Skip to content

fix(agent): gate generated spec permissions by CLI version - #12919

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
jeeshofone:fix/12897-generated-spec-permissions-gate
Sep 23, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
jeeshofone:fix/12897-generated-spec-permissions-gate

Conversation

@jeeshofone

Copy link
Copy Markdown
Contributor

Problem / Motivation

Generated conductor and worker agent specs always wrote a derived permissions field. Older kiro-cli releases use strict unknown-field rejection and do not accept that field, so they can reject the whole generated spec and fall back to broader default grants. Generated configs can also inherit a user-configured permissions value before the writer runs.

Why it matters

Users running an older or unrecognized kiro-cli can lose the intended generated agent spec instead of receiving a compatible spec with its existing allowedTools grants.

What changed (motivation → approach → change)

In src/kiro_crew/agent.py, centralized generated permissions writes in _write_derived_permissions, using the existing installed-version capability probe. The default seed plus conductor, ledger-conductor alias, pipeline conductor, security conductor, and worker paths now share that gate. Accepting versions replace any inherited value with a fresh derivation; refusing or unknown versions remove any inherited value. The default-spec seed still preserves an existing hand-written block before calling the helper.

Updated src/kiro_crew/docs/agent-spec-fields.md to document the generated-writer gate, inherited-value replacement/removal, and default-seed preservation behavior.

Backwards compatibility

Compatible: supported kiro-cli versions receive the same freshly derived policy; unsupported versions receive a spec without a field they cannot parse, while existing user-owned default-spec blocks remain untouched.

Tests

  • Added accepting, refusing, and unknown-version coverage through the real conductor, ledger alias, pipeline conductor, security conductor, and worker writers.
  • Each generated-writer test injects an inherited deny policy, verifies accepting versions replace it with the exact policy derived from allowedTools, and verifies refusing/unknown versions remove it without removing allowedTools.
  • Existing default-seed tests verify a hand-written block remains unchanged.
  • 497 writer/seed tests pass.
  • The five generated-writer regressions all fail at pytest call phase when overlaid on exact origin/main production code.
  • Black, isort, flake8, full mypy, documentation lint, comment-history, brand-name, agent-SDK-boundary, async-I/O, and diff-integrity gates pass.

Manual verification

N/A — real writer entry points and all installed-version outcomes are covered by automated tests.

Screenshots / video

N/A — backend-only generated agent-spec behavior; no user-visible frontend change.

Related Issues

Fixes #12897

Pattern harvest

Rule candidate: review-prompt
Pattern: when version-gating an optional generated field, remove an inherited copy on the closed gate instead of only skipping the direct write.

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

@jeeshofone
jeeshofone requested review from a team and krishdhasmana September 22, 2026 21:50
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Intent: Ensure every generated conductor and worker agent spec is accepted by the installed kiro-cli: emit freshly derived permissions only when supported, and remove inherited copies otherwise.
Not a goal: Change the permissions schema, doctor diagnostics, publication alignment rules, or user-owned default-spec blocks.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Maintainer action requested: please approve the fork workflow runs for this head when GitHub presents the approval banner. The branch is locally green and exact-head GPT/Opus reviews found no blocking issues.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Sep 22, 2026
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 5108f56

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

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

Design-Verdict: PASS

Verify a version probe that fails once (cached None per binary identity) can't strip permissions for the whole gateway lifetime on an accepting kiro-cli.

[DESIGN-REVIEWED] 5108f56

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

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

Premise-level review of 5108f562d9ee8b08814f44d35077ab8865e4f750 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

One sibling writer stays ungated: agent_capabilities.py:396 (_align_permissions) still writes permissions into a forked spec whenever the base carries a matching block — confirm an old kiro-cli host can't reach it.

I grepped derived_agent_permissions across src/: 6 write sites, 5 fixed here, the sixth fires only when a hand-written block on the base spec exactly equals the fresh derivation — narrow, and outside the defect #12897 scopes, so it is a verify-before-merge, not a finding.

The defect has checkable provenance: the base agent-spec-fields.md:528 itself pins it — "That derivation is not yet behind the kiro-cli version gate the default spec's seed takes … ([#12897])" — and this diff deletes that sentence by fixing it. The fix sits at cause level (one shared gate instead of five independent writers), the doc updates in the same commit as AGENTS.md mandates, no new public surface, no default a non-broken install loses, no deleted pin.

What this change ships

Inventory (5 items) — 5 justified

Intent: FIX — stop generated conductor and worker specs carrying a permissions field an older or unknown kiro-cli rejects wholesale (#12897).

  1. Conductor, ledger-alias, pipeline, security, and worker specs withhold permissions on a refusing/unknown kiro-cli — justified
  2. A refusing/unknown kiro-cli also removes an inherited permissions value instead of only skipping the write — justified
  3. Five writers now share one internal gate, _write_derived_permissions (5 counted consumers) — justified
  4. agent-spec-fields.md rewritten: known-gap sentence removed, gate behavior documented — justified
  5. Accepting/refusing/unknown test coverage across all five writers, plus an accepting-CLI autouse pin in test_worker_agent.py — justified

[FIRST-PRINCIPLES-REVIEWED] 5108f56

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

The candidate hinges on the no-new-work-on-gateway-boot-path rule. That rule is blocking: true, but its file-patterns are slack/gateway.py, dashboard/server.py, dashboard/handlers/**, and cli.py — none of which this PR touches (it changes only agent.py and tests). So the rule cannot make this BLOCKING.

As a standalone defect it also fails the bar. installed_kiro_cli_version() is bounded (5s timeout) and cached by (binary, mtime) at module level. Before this PR the seed already probed the version on the common (no-block-on-disk) boot, warming that shared cache; the writers reuse it. The candidate's scenario (a permissions block already on disk, so the seed early-returns without probing) yields at most one cached ≤5s probe that previously didn't happen — a narrow, one-time latency delta, not a crash, data loss, security hole, or removed guard. The candidate's own (b) is admittedly unverified ("could not verify whether ... already caches"), which is a drop under Step 1.

The refactor itself is correct: _seed_kas_permissions still guards an on-disk block before delegating (so hand-written seeds are untouched), while the generated conductor/worker writers now pop an inherited block on a refusing/unknown release — the intended #12897 fix — and the doc and tests match that behavior. No new grounded defect found in Step 2.

No findings.

[OPUS-REVIEWED] 5108f56

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Sep 22, 2026
@jeeshofone
jeeshofone force-pushed the fix/12897-generated-spec-permissions-gate branch from e40dc30 to 949a130 Compare September 22, 2026 23:30
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 22, 2026
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Maintainer action requested for rebased head 949a13080743300fc3dc9f1706671c0186a461d8: please approve the fork workflow runs when GitHub presents the approval banner. The conflict was documentation-only with merged #12899; its doctor/version-floor guidance was preserved and combined with this PR's generated-writer behavior. The patch is range-diff identical after the final non-overlapping rebase, 497 tests and the full static/docs floor pass, and exact local GPT/Opus reviews found no findings.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Sep 22, 2026
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Current-head CI attribution: Backend Tests (3.12, shard 7) fails only on the new main ratchet tracked in #12939. I reproduced the exact node locally; it reports the same two issue_radar/backend/crew_store.py exc_info sites. Both that source file and test/test_crew_log_exc_info_sites.py are byte-identical to origin/main, and this PR changes neither. This is inherited main red, not a generated-spec regression, so I am keeping the branch scoped and not repushing.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@jeeshofone
jeeshofone force-pushed the fix/12897-generated-spec-permissions-gate branch from 949a130 to 5108f56 Compare September 23, 2026 01:10
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Maintainer action requested for healed-main head 5108f562d9ee8b08814f44d35077ab8865e4f750: please approve the fork workflow runs when GitHub presents the banner. This rebase includes merged #12943, so the inherited Linux/Windows shard-7 #12939 failure is fixed and the new head clears the cancelled lint run. The branch patch is range-diff identical; its five gate tests, the previously failing main ratchet, body, and static guards pass.

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Sep 23, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Sep 23, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after verified readiness: passed, PR Readiness success on this head, mergeable, no open change requests. [operator: bolichen97 batch review 2026-09-23]

@bolichen97
bolichen97 merged commit cdeab00 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
@jeeshofone
jeeshofone deleted the fix/12897-generated-spec-permissions-gate branch September 23, 2026 04:41
bolichen97 pushed a commit that referenced this pull request Sep 23, 2026
…oo (#13070)

#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 #13014, so
it is left untouched here.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
iamwhatever added a commit that referenced this pull request Oct 2, 2026
…-cli

`side_readonly_spec` publishes `~/.kiro/agents/<agent>--readonly.json` on
every side turn -- into the registry kiro-cli loads its selectable agents
from -- and rewrites the inherited KAS policy to an empty one:

    if "permissions" in spec:
        spec["permissions"] = {"rules": []}

It is a generated-spec writer like the five in `agent.py`, but it never
reached the shared version gate #12919 centralized. kiro-cli validates
specs with serde `deny_unknown_fields`, and it is the KEY's presence,
not its value, that a release below SPEC_PERMISSIONS_MIN_VERSION refuses
-- an empty policy is still a policy. So a base spec carrying a
`permissions` block, on a below-floor or unknown release, produced a
derived file that release refuses whole.

What is lost when it is refused is this module's entire reason to exist.
The derived spec is the side turn's read-only isolation: `allowedTools`
emptied, no `autoApprove`, no `toolsSettings` grants, no
`includeMcpJson`, no lifecycle hooks -- so that every call raises a
permission request the READ_ONLY gate judges instead of being approved
by the backend unattended.

Routed through `_write_derived_permissions`, which on an accepting
release derives `{"rules": []}` from the emptied grants -- byte-identical
to what this line wrote -- and on a refusing or unknown one removes the
inherited value. The `if "permissions" in spec` guard stays: the gate
decides whether the field may be CARRIED, not whether to add one, and
its mere presence is what makes KAS load a spec at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Co-authored-by: iamwhatever <12429733+iamwhatever@users.noreply.github.com>
chenmingwei23 pushed a commit that referenced this pull request Oct 2, 2026
…-cli (#16086)

`side_readonly_spec` publishes `~/.kiro/agents/<agent>--readonly.json` on
every side turn -- into the registry kiro-cli loads its selectable agents
from -- and rewrites the inherited KAS policy to an empty one:

    if "permissions" in spec:
        spec["permissions"] = {"rules": []}

It is a generated-spec writer like the five in `agent.py`, but it never
reached the shared version gate #12919 centralized. kiro-cli validates
specs with serde `deny_unknown_fields`, and it is the KEY's presence,
not its value, that a release below SPEC_PERMISSIONS_MIN_VERSION refuses
-- an empty policy is still a policy. So a base spec carrying a
`permissions` block, on a below-floor or unknown release, produced a
derived file that release refuses whole.

What is lost when it is refused is this module's entire reason to exist.
The derived spec is the side turn's read-only isolation: `allowedTools`
emptied, no `autoApprove`, no `toolsSettings` grants, no
`includeMcpJson`, no lifecycle hooks -- so that every call raises a
permission request the READ_ONLY gate judges instead of being approved
by the backend unattended.

Routed through `_write_derived_permissions`, which on an accepting
release derives `{"rules": []}` from the emptied grants -- byte-identical
to what this line wrote -- and on a refusing or unknown one removes the
inherited value. The `if "permissions" in spec` guard stays: the gate
decides whether the field may be CARRIED, not whether to add one, and
its mere presence is what makes KAS load a spec at all.

Co-authored-by: Leon <leon.lai.yc@gmail.com>
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 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.

Conductor and worker specs still write permissions on a kiro-cli that refuses it

2 participants