Repository navigation
fix(agent): gate the forked spec's permissions block by CLI version too - #13070
Conversation
kirodotdev#12919 made `_write_derived_permissions` "the one version gate every generated spec writer shares" and routed agent.py's five writers through it: a kiro-cli below SPEC_PERMISSIONS_MIN_VERSION, or one whose version cannot be established, gets no `permissions` block and any inherited value removed. `agent_capabilities._align_permissions` kept its own write. It is the sixth generated-spec writer -- `CapabilityService.put` and `publish` atomic_write the projected spec into the kiro agents directory and bind the member to it -- so on a below-floor or unknown release the fork funnel published exactly the file the gate exists to prevent. kiro-cli validates specs with serde `deny_unknown_fields`, so that release refuses the WHOLE file and drops every Crew MCP server with it, falling back to broader default grants. Two questions share that call site and only the second is the binary's. Whether the SOURCE block was hand-edited away from its derivation is a governance question about the template, so the `alternate_permissions_require_review` comparison stays unconditional; only the target write moves behind the gate. Both are pinned. Reuses the existing gate rather than adding a sixth spelling of the version check: `agent_capabilities` already imports private names from `kiro_crew.agent` function-locally on this path. `docs/agent-spec-fields.md` already states the rule this path now obeys ("Crew WRITES this ... only when the installed kiro-cli accepts the field"), and its `permissions` row is being rewritten by open kirodotdev#13014, so it is left untouched here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsFINDING -- src/kiro_crew/agent_capabilities.py:402 -- function-local |
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS The gate's removal half never runs on non-tools edits: a prompt-only fork/publish still republishes an inherited Watch
[DESIGN-REVIEWED] 2493a56 |
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify What this change shipsInventory (5 items) — 5 justifiedIntent: FIX — make forked/published member specs loadable on kiro-cli releases that refuse the
Evidence: [FIRST-PRINCIPLES-REVIEWED] 2493a56 |
Opus 5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNothing blocks; the new removal is one-way — a fork that loses its FINDING — src/kiro_crew/agent_capabilities.py:410 — FINDING — src/kiro_crew/docs/agent-spec-fields.md:350 — the owning [OPUS-REVIEWED] 2493a56 |
…oo (kirodotdev#13070) kirodotdev#12919 made `_write_derived_permissions` "the one version gate every generated spec writer shares" and routed agent.py's five writers through it: a kiro-cli below SPEC_PERMISSIONS_MIN_VERSION, or one whose version cannot be established, gets no `permissions` block and any inherited value removed. `agent_capabilities._align_permissions` kept its own write. It is the sixth generated-spec writer -- `CapabilityService.put` and `publish` atomic_write the projected spec into the kiro agents directory and bind the member to it -- so on a below-floor or unknown release the fork funnel published exactly the file the gate exists to prevent. kiro-cli validates specs with serde `deny_unknown_fields`, so that release refuses the WHOLE file and drops every Crew MCP server with it, falling back to broader default grants. Two questions share that call site and only the second is the binary's. Whether the SOURCE block was hand-edited away from its derivation is a governance question about the template, so the `alternate_permissions_require_review` comparison stays unconditional; only the target write moves behind the gate. Both are pinned. Reuses the existing gate rather than adding a sixth spelling of the version check: `agent_capabilities` already imports private names from `kiro_crew.agent` function-locally on this path. `docs/agent-spec-fields.md` already states the rule this path now obeys ("Crew WRITES this ... only when the installed kiro-cli accepts the field"), and its `permissions` row is being rewritten by open kirodotdev#13014, so it is left untouched here. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Problem / Motivation
kiro-clivalidates agent specs with serdedeny_unknown_fields, so a releasebelow
SPEC_PERMISSIONS_MIN_VERSION(2.23.0) refuses the whole file when itcarries a
permissionsblock — dropping every Crew MCP server the spec mountsand falling back to broader default grants. #12919 answered that with one shared
gate,
_write_derived_permissions, documented as "the one version gate everygenerated spec writer shares", and routed
agent.py's five generated writersthrough it: an accepting release gets the fresh derivation, a below-floor or
unknown one gets no block and any inherited value removed.
agent_capabilities._align_permissionskept its own write and never reachedthat gate:
It is a generated-spec writer like the other five:
CapabilityService.putandCapabilityService.publishatomic_writethe projectedspecinto the kiroagents directory and bind the member to it (
document["agents"][member] ["kiro_agent"] = target). So on a below-floor or unknown release, the fork andpublish funnel wrote exactly the file the gate exists to prevent.
Why it matters
The two losses are not symmetric, which is why
spec_permissions_supportedalready reads an unknown version as
False: withholding the field costs the KASmode listing for that agent, while writing it on a refusing release costs the
whole spec — no MCP servers, no tools, no Kiro Crew agent at all.
The trigger needs no exotic setup.
installed_kiro_cli_version()answers"unknown" whenever there is no pinned binary, or
--versionis refused, timesout or is unparseable; the version cache is keyed on the binary's path and
mtime, so a
kiro-cli updatethat swaps the binary re-probes. A member specthat already carries a derived block — written while an accepting release was
installed, or seeded by
_seed_kas_permissions— then re-publishes that blockthrough the fork funnel onto a release that refuses it. The development box this
was measured on has a real
kiro-cliat 2.22.1, one minor below the floor,so the defect reproduced against a genuine installed binary rather than a stub.
What changed (motivation → approach → change)
Symptom → cause → change. The symptom is a forked or published spec carrying
permissionson a CLI that refuses it. The cause is a sixth write path thatpredates the shared gate. The change routes that one write through the same
gate:
Two questions share that call site and only the second one is the binary's.
This was the design question worth being explicit about, and it is resolved
against the repository's own authority rather than by preference:
That is a question about the template, answered the same way whatever binary
happens to be installed.
docs/agent-spec-fields.mdstates itunconditionally, and the
alternate_permissions_require_reviewcomparison istherefore left exactly where it was, before the gate.
release? That is the CLI's question, and only that write moves behind the
gate.
Both halves are pinned by tests, so a later change cannot quietly trade one for
the other.
No sixth spelling of the version check. The controller-preferred shape was
to reuse the existing authority rather than re-implement
spec_permissions_supported(installed_kiro_cli_version())locally, and_write_derived_permissionsalready owns exactly this pair of behavioursincluding removal of an inherited value.
agent_capabilitiesalready importsprivate names from
kiro_crew.agentfunction-locally on this path(
_conflicting_spec_for,_MANAGED_MCP_SERVERS), so the import adds no newedge;
scripts/check_agent_sdk_boundary.pypasses with the diff in scope.Docs deliberately untouched.
docs/agent-spec-fields.mdalready states therule this path now obeys — "Crew WRITES this derived from
allowedTools… onlywhen the installed kiro-cli accepts the field" — so the fix makes the existing
sentence true rather than needing a new one. That row is also being rewritten by
open #13014, and this PR does not contend for it. The one prose correction that
this diff does make is in
test/test_conductor_agent.py, whose helper docstringsaid "The five spec writers share one gate"; after this change that count is
wrong, so it now reads "The generated spec writers".
Backwards compatibility
Compatible. On an accepting release the behaviour is byte-identical: both
the old line and
_write_derived_permissionscallderived_agent_permissions(allowed_tools, name)and assign the result tospec["permissions"], and the[accepts]test arm passed before thischange as well as after. What changes is only the below-floor and unknown cases,
where the field is now withheld instead of written — the direction the shared
gate already takes for the five sibling writers, and the direction
spec_permissions_supporteddocuments as the smaller loss.Nothing is rejected, renamed or removed: no new required field, no stricter
validator, no narrowed type.
allowedTools— the governed ceiling — is neverwithheld, and that is asserted on every arm.
Tests
test/test_agent_capabilities.py, driven through the real service entry points(
CapabilityService.preview+put, andreset) and asserting on the specas written to disk, not on
_align_permissionsin isolation:test_a_fork_writes_permissions_only_where_the_installed_cli_accepts_them— parametrized over
accepts/refuses/unknown. The parent carries ablock equal to its own fresh derivation (so the governance comparison
succeeds), a grant is added through the funnel, and the published spec must
carry the derived block on an accepting release and no block on the other
two.
allowedToolsis asserted intact on all three.test_a_hand_edited_block_still_blocks_a_fork_on_a_refusing_cli— parametrized over
refuses/unknown. Pins the half that must notmove: a block the derivation would not produce still raises
alternate_permissions_require_reviewon a release that cannot carry thefield, and the member's own spec is left intact.
_pin_spec_permissions_cli+ an autouseacceptsfixture, the same helperand the same rationale the five writers' suites already use: without it the
host's own binary decides the assertions. That fixture is load-bearing and was
measured as such — disabling it fails exactly the two pre-existing tests that
assert a derived block is present (
KeyError: 'permissions'), which is also adirect demonstration of the fix working against this box's real 2.22.1.
RED on
2fdadc71a, before the production change:The
[accepts]arm and both governance arms were green before the change too —they are the regression guard, not the repro.
GREEN after, plus adjacent suites:
test_agent_capabilities.py(whole module)test_kas_permissions.py,test_worker_agent.py,test_conductor_agent.py,test_pipeline_conductor_agent.py,test_security_conductor_agent.py,test_ledger_conductor_agent.pytest_cli_doctor.py,test_agent_sdk_capabilities.py,test_capability_manager.py,test_capability_ledger.pytest_agent_fork_endpoint.py,test_agent_publish_endpoint.py,test_agent_state.py,test_capability_agents_plugins.pytest_agent_spec_fields_doc.py,test_docs_lint_fact_checks.py,test_connections_kiro_spec_fields.pyStatic gates on the committed diff:
black --check,isort --check-only,flake8,mypy --platform linux,git diff --check,scripts/check_black_formatting.pyandscripts/check_agent_sdk_boundary.py(both run after committing, so their
origin/main...HEADscope is the real4→3 changed files and not a vacuous zero).
Manual verification
N/A — unit coverage sufficient: the assertions read the spec file this path
actually writes to the agents directory, under all three version verdicts the
gate distinguishes, so the observable a user would check by hand is the one the
tests already read.
Related Issues
Follow-up to #12919, which introduced the shared gate and converted the five
agent.pywriters. No issue filed.Pattern harvest
Rule candidate:
review-promptPattern: a new centralized runtime-version (or capability) gate is only central
once every mutation path is enumerated — a sibling writer that predates the
gate keeps its own write and silently defeats it. When a PR introduces a shared
gate and says "every writer", grep the whole tree for other assignments to the
same field rather than only the writers that PR touched.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
🤖 Generated with Claude Code