Skip to content

fix(agent): gate the forked spec's permissions block by CLI version too - #13070

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:claude/deep10-caps-perm-gate-20260923
Sep 23, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:claude/deep10-caps-perm-gate-20260923

Conversation

@leonlaiyc

Copy link
Copy Markdown
Contributor

Problem / Motivation

kiro-cli validates agent specs with serde deny_unknown_fields, so a release
below SPEC_PERMISSIONS_MIN_VERSION (2.23.0) refuses the whole file when it
carries a permissions block — dropping every Crew MCP server the spec mounts
and falling back to broader default grants. #12919 answered that with one shared
gate, _write_derived_permissions, documented as "the one version gate every
generated spec writer shares"
, and routed agent.py's five generated writers
through 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_permissions kept its own write and never reached
that gate:

if "permissions" in base:
    prior = derived_agent_permissions(base.get("allowedTools"), str(base.get("name", "")))
    if base["permissions"] != prior:
        raise CapabilityError("alternate_permissions_require_review")
    spec["permissions"] = derived_agent_permissions(       # <- no version gate
        spec.get("allowedTools"), str(spec.get("name", ""))
    )

It is a generated-spec writer like the other five: CapabilityService.put and
CapabilityService.publish atomic_write the projected spec into the kiro
agents directory and bind the member to it (document["agents"][member] ["kiro_agent"] = target). So on a below-floor or unknown release, the fork and
publish funnel wrote exactly the file the gate exists to prevent.

Why it matters

The two losses are not symmetric, which is why spec_permissions_supported
already reads an unknown version as False: withholding the field costs the KAS
mode 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 --version is refused, times
out or is unparseable; the version cache is keyed on the binary's path and
mtime
, so a kiro-cli update that swaps the binary re-probes. A member spec
that already carries a derived block — written while an accepting release was
installed, or seeded by _seed_kas_permissions — then re-publishes that block
through the fork funnel onto a release that refuses it. The development box this
was measured on has a real kiro-cli at 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
permissions on a CLI that refuses it. The cause is a sixth write path that
predates the shared gate. The change routes that one write through the same
gate:

_write_derived_permissions(spec, spec.get("allowedTools"), str(spec.get("name", "")))

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:

  1. Governance — was the source block hand-edited away from its derivation?
    That is a question about the template, answered the same way whatever binary
    happens to be installed. docs/agent-spec-fields.md states it
    unconditionally, and the alternate_permissions_require_review comparison is
    therefore left exactly where it was, before the gate.
  2. Compatibility — may the target spec carry the field for this installed
    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_permissions already owns exactly this pair of behaviours
including removal of an inherited value. agent_capabilities already imports
private names from kiro_crew.agent function-locally on this path
(_conflicting_spec_for, _MANAGED_MCP_SERVERS), so the import adds no new
edge; scripts/check_agent_sdk_boundary.py passes with the diff in scope.

Docs deliberately untouched. docs/agent-spec-fields.md already states the
rule this path now obeys — "Crew WRITES this derived from allowedTools … only
when 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 docstring
said "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_permissions call
derived_agent_permissions(allowed_tools, name) and assign the result to
spec["permissions"], and the [accepts] test arm passed before this
change 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_supported documents 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 never
withheld, and that is asserted on every arm.

Tests

test/test_agent_capabilities.py, driven through the real service entry points
(CapabilityService.preview + put, and reset) and asserting on the spec
as written to disk, not on _align_permissions in isolation:

  • test_a_fork_writes_permissions_only_where_the_installed_cli_accepts_them
    — parametrized over accepts / refuses / unknown. The parent carries a
    block 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. allowedTools is 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 not
    move: a block the derivation would not produce still raises
    alternate_permissions_require_review on a release that cannot carry the
    field, and the member's own spec is left intact.
  • _pin_spec_permissions_cli + an autouse accepts fixture, the same helper
    and 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 a
    direct demonstration of the fix working against this box's real 2.22.1.

RED on 2fdadc71a, before the production change:

FAILED test_a_fork_writes_permissions_only_where_the_installed_cli_accepts_them[refuses]
        AssertionError: a refuses CLI must get no block
FAILED test_a_fork_writes_permissions_only_where_the_installed_cli_accepts_them[unknown]
        AssertionError: a unknown CLI must get no block
2 failed, 3 passed

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:

Suite Result
test_agent_capabilities.py (whole module) 486 passed
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.py 496 passed, 1 skipped
test_cli_doctor.py, test_agent_sdk_capabilities.py, test_capability_manager.py, test_capability_ledger.py 316 passed, 1 skipped
test_agent_fork_endpoint.py, test_agent_publish_endpoint.py, test_agent_state.py, test_capability_agents_plugins.py 128 passed
test_agent_spec_fields_doc.py, test_docs_lint_fact_checks.py, test_connections_kiro_spec_fields.py 128 passed, 5 skipped

Static gates on the committed diff: black --check, isort --check-only,
flake8, mypy --platform linux, git diff --check,
scripts/check_black_formatting.py and scripts/check_agent_sdk_boundary.py
(both run after committing, so their origin/main...HEAD scope is the real
4→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.py writers. No issue filed.

Pattern harvest

Rule candidate: review-prompt
Pattern: 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

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>
@leonlaiyc
leonlaiyc requested review from a team and pepmach September 23, 2026 12:41
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 2493a56aea4b8af18dca4180804932c6b920fa7a via the fork AI-review pipeline; updated in place on each push.

Review details

FINDING -- src/kiro_crew/agent_capabilities.py:402 -- function-local from kiro_crew.agent import _write_derived_permissions violates top-level-imports -> Fix: move this import to module scope.
[GPT-REVIEWED] 2493a56

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of 2493a56aea4b8af18dca4180804932c6b920fa7a via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The gate's removal half never runs on non-tools edits: a prompt-only fork/publish still republishes an inherited permissions block a refusing CLI rejects.

Watch

  • _align_permissions sits behind the guard at agent_capabilities.py:947 (reset_parent or tools/allowedTools/autoApprove touched), and _materialize deep-copies base — permissions included — into the projected spec. So on a below-floor or unknown CLI, a prompt-only edit to a member carrying a previously-derived block re-atomic_writes that block untouched, and the funnel keeps emitting "exactly the file the gate exists to prevent" (the PR's own words). The fix heals only the tools-changed paths; neither new test covers a non-tools edit under a refusing pin (the second test's prompt save runs under the autouse "accepts" fixture, and its reset takes the reset_parent arm).
    Clears when: the removal half runs on every publish of the projected spec (e.g. pop/gate spec["permissions"] unconditionally, keeping the governance comparison and fresh derivation behind the existing guard), with a [refuses] test for a prompt-only edit — or a stated rationale that non-tools publishes deliberately preserve the on-disk block.

[DESIGN-REVIEWED] 2493a56

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 2493a56aea4b8af18dca4180804932c6b920fa7a via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify side_readonly_spec.py:224 truly needs no gate — it preserves a permissions key on a spec it publishes into ~/.kiro/agents/, though only when the parent spec is already refused.

What this change ships

Inventory (5 items) — 5 justified

Intent: FIX — make forked/published member specs loadable on kiro-cli releases that refuse the permissions field, by routing the sixth generated-spec writer through the shared version gate.

  1. Forking/publishing on a below-floor or unknown kiro-cli now withholds/removes the spec's permissions block instead of writing a file that CLI refuses whole — justified
  2. A hand-edited parent block still refuses the fork (alternate_permissions_require_review) on every CLI version — justified
  3. Docstring on _align_permissions recording the governance/compatibility split — justified
  4. test_conductor_agent.py helper docstring count corrected ("five" → "generated") — justified
  5. New parametrized tests plus an autouse accepts-pin fixture in test_agent_capabilities.py — justified

Evidence: _write_derived_permissions (agent.py:4116, "the one version gate every generated spec writer shares") has exactly 5 prior call sites (grep _write_derived_permissions, 5 in agent.py); base _align_permissions wrote the field unconditionally, so the new [refuses]/[unknown] arms fail on base by reading; the withheld-when-unsupported rule is a documented invariant (src/kiro_crew/docs/agent-spec-fields.md, permissions row). Grep \["permissions"\] = across src/: the other assignment sites are wire projections, Claude settings, session state, or app manifests — not kiro agent spec writers — except side_readonly_spec.py:224, whose kept key only survives when the source spec is already refused, so no independent harm counted. Function-local private imports from kiro_crew.agent already exist in this module (lines 74, 789, 982) — no new edge.

[FIRST-PRINCIPLES-REVIEWED] 2493a56

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 2493a56aea4b8af18dca4180804932c6b920fa7a via the fork AI-review pipeline; updated in place on each push.

Review details

Nothing blocks; the new removal is one-way — a fork that loses its permissions block never gets it back.

FINDING — src/kiro_crew/agent_capabilities.py:410 — _write_derived_permissions(spec, ...) pops an inherited block on a refusing/unknown kiro-cli, but the unchanged if "permissions" in base: above it means the next save's base = _ordinary_parent(snap["spec"], …) reads the now-blockless fork spec, so the guard is False forever and no writer re-materializes it (_seed_kas_permissions only touches AGENT_FILENAME, and _refresh_forked_templates_locked routes enrolled forks to the no-op reconcile_member_capabilities) — after kiro-cli is installed/upgraded above the floor the fork permanently lacks the field KAS needs to load the profile by name, unlike the five agent.py writers that re-run each boot, and only reset() repairs it by discarding every local capability choice → Fix: let the write also run when the source block is absent — thread the parent spec's block into _align_permissions so an accepting release re-derives what a refusing one removed (needs a signature/call-site change, hence advisory).

FINDING — src/kiro_crew/docs/agent-spec-fields.md:350 — the owning permissions row still scopes the shared gate to "Generated conductor and worker writers" and describes fork/publish as the path that only "does read it", so it never records that _align_permissions now removes an inherited block on an older or unknown release, while AGENTS.md requires the owning spec updated in the same commit → Fix: extend the row to name _align_permissions as a gated writer that removes an inherited block, noting the hand-edit comparison stays unconditional.

[OPUS-REVIEWED] 2493a56

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@bolichen97
bolichen97 merged commit c4bd38c into kirodotdev:main Sep 23, 2026
95 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 23, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants