Skip to content

fix: let a KAS sub-agent spawn be approved - #9053

Closed
karraghu wants to merge 1 commit into
kirodotdev:mainfrom
karraghu:fix/kas-subagent-approval
Closed

karraghu wants to merge 1 commit into
kirodotdev:mainfrom
karraghu:fix/kas-subagent-approval

Conversation

@karraghu

@karraghu karraghu commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

On the kas ACP backend, spawning a sub-agent always failed. The root cause is a naming mismatch: acp/kas_permissions.py:CAPABILITY_BY_TOOL is keyed on KAS's internal toolIds (invoke_sub_agent), but the allowedTools list it translates holds Crew tool names (use_subagent). The two never matched, so a spec that had already granted the tool projected no allow rule, and the spawn was refused. Reported as #9024.

Why it matters

The one-line match fix exposed two more defects in the same path, so this PR is three fixes. Without B, a spawn cannot even reach a human prompt — it is hard-denied as an "unverifiable shell" call, which also breaks the shipped pptx-maker specs. Without C, both new grants would bypass capabilities.spawn, the ceiling an admin sets to withhold spawning. One rollout note: _vet_spawn_governance now fails closed on a governance evaluation error and vets an omitted target, so on a governed host a default spawn that used to slip through can now be refused (deliberately, and audited).

What changed (motivation → approach → change)

A keys the table on Crew's use_subagent (KAS's spelling kept as an alias). B reads KAS's own _meta.kiro.consent.capability off the request into a new AcpEvent.spawn_attested, so a frameless spawn turns a false hard-deny into an honest prompt — never into an auto-approve. C routes both surfaces (CLI and dashboard) through the one _vet_spawn_governance chokepoint before any prompt, so the ceiling holds; the target agent is read from the backend's attestation, not the model-authored title.

Spawning is now on the audit trail: spawn_auto_approve_granted records the grant, spawn_invocation_observed records each spawn off the parent roster.

Mechanics: frame shape, the empty-target case, and the audit

KAS sends no tool_call frame for a spawn and a synthetic toolCallId, so every cache in acp/_dispatch.py misses and the event arrives fully unclassified; _unverifiable_shell read that as "run a command we can't verify". The consent block travels the _meta.kiro channel already trusted for MCP identity. An empty target is the case agents used to miss — governance.resolve collapses to an identical permit whether a deny-ruleset let it through or no scope exists, so governance_scope_constrained reads the scope's presence off the CapabilityGate instead. The roster audit is approval-route-neutral, skips pending stages, dedups by session id (reserved on the loop so overlapping frames can't double-record), and offloads the blocking write. Four acp/ spec docs updated in the same commit, per the repo rule.

Tests

New tests lock in the load-bearing behaviour: test_a_spawn_is_attested_off_the_request (the real KAS frame yields spawn_attested), test_a_ceiling_that_forbids_spawning_refuses_an_attested_spawn (ceiling holds before any prompt), and test_kas_spawn_audit_records_each_spawn_once_under_concurrent_frames (no double-record). Plus ~26 further cases across test_kas_permissions.py, test_governance_chokepoints.py, and test_kas_subagent_progress.py. Full backend suite run at HEAD and base shows identical pre-existing failures; none touch the changed modules.

Manual verification

Five live runs against KAS 0.58.7 / kirocrew 0.6.0.11 (acp_backend="kas"): the spawn is denied at baseline, works with fix A, and run 5 captures the real permission frame carrying _meta.kiro.consent.capability="subagent" while the event stays shell_classified=False — proving B is independent of A. Instrumentation removed afterward.

Screenshots / video

Why no screenshot: backend permission/audit change; the only user-visible text is the CLI approval prompt line, no rendered UI surface changes.

Related Issues

Fixes #9024

Pattern harvest

A lookup table on a translation seam must be keyed on the vocabulary of the side that supplies the input, not the side that consumes the output — and a fail-closed default hides the bug, because a miss looks like a deliberate "not classifiable".

Rule candidate: when a translation table fails closed on an unknown key, add a test that asserts at least one key is reachable from a real input, not only that unknown keys are refused.

Checklist

  • At most two commits, with a Conventional Commits title
  • Existing tests pass and new tests were added
  • Self-review completed
  • Documentation updated: acp-client.md, cli.md, security.md, governance.md
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

@karraghu
karraghu requested review from a team and krishdhasmana September 6, 2026 15:58
@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 readiness: checking Automated validation is still running labels Sep 6, 2026
@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of eedc4f00d26c6d22bcb568762ce4474a00b0834b 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

Root causes fixed and routed through the existing governance chokepoint, but the ceiling's KAS-side enforcement hinges entirely on an uncontracted backend wire field.

Watch

  • Every new enforcement (ceiling vet, agents-scope check, honest prompt) triggers only on event.spawn_attested, i.e. on _meta.kiro.consent.capability — a KAS wire detail verified once against KAS 0.58.7 and pinned only by recorded frames. If a future KAS drops or renames the block, the CLI safely reverts to the hard deny, but the dashboard falls back to the pre-existing frameless path where HookManager classifies by the model-authored title (_is_read_only_tool), so a capabilities.spawn ceiling silently stops binding backend spawns — the exact bypass the governance.md hunk describes. types.py's claim that the flag "is deliberately not the only enforcement for any spawn shape" does not hold for the backend-performed shape.
    Clears when: a contract test (or minimum-KAS-version note) pins that KAS spawn permission requests carry the consent block, or unattested frameless requests on the dashboard stop being eligible for title-heuristic auto-approve.
  • The ~120-line _audit_kas_spawns per-spawn observation audit in session_handle.py is documented in security.md and tested, but the PR description never mentions it and affirmatively contradicts it ("per-spawn auditing needs a KAS event that does not exist yet"). Reviewers reading the description will miss a whole audit mechanism with cross-turn dedup state.
    Clears when: the description accounts for the roster-based spawn_invocation_observed audit (or that hunk moves to its own PR).

[DESIGN-REVIEWED] eedc4f0

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

I've fully reviewed the diff and verified the supporting code: the governance_permits signature accepts the new agent/fail_closed kwargs the diff passes; the _vet_spawn_governance signature change to keyword-only app has no remaining positional-app caller (both callers pass it by keyword); the _unverifiable_shell fall-through reaches the payload-kind deny only for attested spawns and still refuses a shell-shaped kind; and the fail-closed directions on both the CLI and dashboard spawn-ceiling checks hold.

Candidate 1 (reserved-but-unwritten sid never re-audited on task cancellation) does not survive falsification at the required bar. _audit_kas_spawns is explicitly a best-effort, fail-open audit path ("an audit-sink error must never break roster event emission"). Its documented retry contract covers write failures (except Exception releases the reservation), which the code honors; task cancellation at teardown is a distinct case the contract never claimed to retry, and losing a single observation record in that narrow window is consistent with the path's stated fail-open intent — not a contract violation. The consequence is an audit-completeness gap of a best-effort observation record, not a security hole, crash, or user-data loss. The candidate's own confidence is "low," and I cannot re-derive an observable wrong outcome above the "could/might" threshold. Dropped.

No new grounded findings emerged that meet the bar.

No findings.

[OPUS-REVIEWED] eedc4f0

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🔴 BLOCK

Premise-level review of 7a0255d694eb3b81104663bf2483616beec1bf80 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.

All load-bearing claims are now verified against the base: the spelling defect is real, the hooks-gate blindness to capabilities.spawn is real, resolve_active_scope(agent=)/governance_permits(fail_closed=)/may_skip_gate all pre-exist, no base test pinned the reversed deny-mode behavior, and the settings-registry hunk duplicates content already in the base file. Producing the review.

First-Principles-Verdict: BLOCK

The settings-registry hunk is a rider the fix never needed: all four entries already exist byte-identical in the base file.

Not justified as shipped

  • 10 — rides along: the spawn fix touches no setting; the four entries (chat.default-memory-mode, display.command-completion, secrets.jira-api-token, secrets.wakatime-api-key) are already in base src/kiro_crew/docs/settings-registry.generated.json (lines 483–490, 821, 1052, 1059; landed via f1cc1b7), so shipping them changes nothing.
  • 9 — one consumer, generalized: governance_scope_constrained's own docstring says the capability/inner parameters are "convenience for a future second caller, not a contract"; grep governance_scope_constrained( → 1 production caller (subagent._vet_spawn_governance), which always passes ("spawn", "agents").

What this change ships

Inventory (10 items) — 8 justified

Intent: make a KAS-backend sub-agent spawn approvable at all (auto-approved when the spec grants it, promptable otherwise), governed by the capabilities.spawn ceiling — a FIX (issue #9024; premise counted: invoke_sub_agent occurs nowhere but the table line, use_subagent is the spelling in liveness, chat_runner, session_handle and both shipped pptx-maker specs).

  1. A spec granting use_subagent now auto-approves the spawn on KAS (table keyed on Crew's spelling) — justified
  2. A KAS spawn now reaches a human prompt instead of an unconditional "unverifiable shell" refusal (spawn_attested off _meta.kiro.consent) — justified
  3. The CLI prompt now discloses the backend-named agent ("Sub-agent: deployer", "unnamed agent" when absent) — justified
  4. A capabilities.spawn ceiling now refuses a backend spawn on both CLI and dashboard, before any prompt or auto-approve — justified
  5. A governed host withholds the sub-agent tool from KAS auto-approve projection (BUILTIN_TOOL_SCOPES) — justified
  6. One SEL record when spawning becomes auto-approved at projection (spawn_auto_approve_granted) — justified
  7. One SEL record per KAS sub-agent actually spawned, off the roster (spawn_invocation_observed) — justified
  8. An unnamed spawn target is now judged by any agents scope (deny-mode included); Crew spawns vetted as the agent they actually run as; the caller agent's profile consulted; evaluation errors deny — justified
  9. New governance_scope_constrained(capability, inner) helper — one consumer, generalized: only ("spawn","agents") is ever passed, per its own docstring
  10. The settings registry gains four entries unrelated to spawning — rides along, duplicate of the base file's own lines

Comment corrections and the four spec-doc updates are folded into the items they document (the doc updates are mandated by the AGENTS.md same-commit rule).

Blockers

  • Drop the settings-registry.generated.json hunk. The PR is a FIX; this hunk rides along; its zero option costs nobody anything — the exact entries it adds already sit in the base file at lines 483–490/821/1052/1059 (regenerated on main by f1cc1b7) — and the code items remove the reported defect without it. Rebase past main's regen or revert the file; the fix is complete either way.
    Clears when: the PR diff no longer touches src/kiro_crew/docs/settings-registry.generated.json.

Watch

  • The whole of fix B rests on "the request does carry _meta.kiro.consent.capability" and "triggeringResource before resource, the precedence kiro-cli's own permission UI applies" — vendored-backend claims asserted only in the description. Wrongness fails toward the current broken state (spawn stays refused), so this is not availability-breaking, but nothing in the repo evidences the frame shape.
    Clears when: the frame is confirmed against a named kiro-cli/KAS version (or a captured frame lands in Bug report: a sub-agent spawn can never be approved on the kas backend #9024).

Subtractions

  • Drop the capability/inner parameters of governance_scope_constrained (governance_profiles.py) and ask about capabilities.spawn/agents directly — 1 consumer (subagent._vet_spawn_governance), which the docstring itself names as the sole caller.

[FIRST-PRINCIPLES-REVIEWED] 7a0255d

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

FINDING -- src/kiro_crew/acp/kas_agents.py:333 -- "per-spawn auditing needs a KAS event that does not exist yet" contradicts the new roster-based spawn audit -> Fix: say projection audits grants while the roster audits observed spawns.
[GPT-REVIEWED] eedc4f0

@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 6, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor

Independent confirmation from a parallel investigation of #9024 (we opened #9050 for the same issue six minutes before this PR, and are standing it down as the narrower duplicate -- this fix is the more complete one).

We reached cause A independently: CAPABILITY_BY_TOOL in acp/kas_permissions.py was keyed on KAS's internal toolId invoke_sub_agent, while the list it translates is allowedTools, which carries Crew tool names -- and the sub-agent tool is use_subagent everywhere else in the tree (the liveness wrapper set, the chat runner, the session handle, the shipped pptx-maker specs). Your re-key matches ours, and keeping invoke_sub_agent/disclose_context alongside use_subagent (plus the bare subagent alias) is the more conservative call -- nothing is lost.

We also reviewed your cause-B fix and found it sound. The property that makes it safe is worth stating explicitly for a future reviewer, because this is a security-adjacent denial path:

  • The capability comes from _meta.kiro.consent.capability -- the BACKEND's own classification of the request, not a model-authored title or kind. That is the trusted-signal-not-agent-authored distinction the gate needs: the one thing that may relax a fail-closed refusal is something the model cannot forge.
  • is_non_shell_capability is an explicit fail-closed frozenset allowlist. An unknown capability still denies; a shell capability still denies; a non-string or empty value still denies (the helper returns False for anything but a listed string).
  • It substitutes for the missing cache, it does not override the checks: the payload-kind deny below still runs, and it only lets the request REACH the human -- after the hook gate (deny floor, sensitive-path, ceiling) has already had its say.

Credit where we did not look: your diagnosis names the deeper mechanism we missed -- KAS sends no preceding session/update tool_call frame for a sub-agent spawn and uses a synthetic invoke_subagent_<parent tool call id> toolCallId, so every toolCallId-keyed cache in acp/_dispatch.py misses and shell_classified stays False. That is why the request lands in _unverifiable_shell with nothing classified, and it is exactly the case the caches cannot cover. Reading the capability straight off the payload is the right answer for it.

One cosmetic note, take it or leave it: our PR also deleted the disclose_context -> skill entry as a dead never-matching key. Your choice to keep it (as a KAS-vocabulary alias, matching invoke_sub_agent) is defensible and behavior-neutral either way; not a reason to change anything here.

Nothing to fix that we can see. Thanks for the thorough writeup.

@karraghu

karraghu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

GPT 5.6 Review, span=a7cb148677e1 (blocking, security): fixed.

The finding was right, and I checked it against the source before accepting it. Both
new grant paths handed out the sub-agent tool without ever reading
capabilities.spawn, for two different reasons:

  • the hooks gate classifies an unprefixed builtin by its title, and
    classify_tool_title maps a title to commands/tools and never to
    capabilities.spawn, so the ceiling could not see a spawn at all;
  • subagent._vet_spawn_governance is the one place Crew vets a spawn, and the KAS
    path never enters it, because the backend performs the spawn itself.

Both paths now consult the ceiling before the capability is granted:

  • BUILTIN_TOOL_SCOPES maps use_subagent and invoke_sub_agent to
    capabilities.spawn. may_skip_gate already refuses to auto-approve a builtin
    whose scopes a ceiling has an opinion about, so a governed host withholds the
    tool from the kas_permissions projection instead of receiving the blanket
    grant. An ungoverned host, and a ceiling that speaks only about some other
    scope, are both unaffected.
  • cli_chat._spawn_ceiling_denial runs an attested spawn through that same
    _vet_spawn_governance, so the two surfaces share one implementation of the
    rule rather than restating it. It runs before the human is asked, so an
    administrator's ceiling is not something a person at the terminal can approve
    away. A refusal audits spawn_not_permitted; an exception refuses as
    gate_failed rather than escalating to a human who would be standing in for a
    policy nobody could read.

One asymmetry is deliberate and worth stating. Only the enabled half of the
policy is checkable on the CLI path: a KAS spawn permission request names no
target agent, and its one agent-ish field is the LLM-authored title, which is
exactly what an authorization check may not key on. Crew's own path does know the
target and still applies both halves. A ceiling that disables spawning is
honoured on both surfaces; one that merely narrows spawning to some agents leaves
the request to the human, who is told what they are approving.

Six tests cover the ceiling, three on the projection side
(TestASpawnCeilingWithholdsTheSubAgentToolFromAutoApprove) and five on the CLI
side, including test_a_ceiling_that_forbids_spawning_refuses_an_attested_spawn
(rejected, audited, human never prompted),
test_a_governance_error_refuses_rather_than_prompting,
test_an_unattested_request_does_not_pay_for_the_check, and
test_the_ceiling_check_delegates_to_the_spawn_managers_own_vetting.

@karraghu

karraghu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

First Principles Review (BLOCK): fixed. Both subtractions applied.

"Drop "subagent": "subagent" from CAPABILITY_BY_TOOL." Gone. Nothing puts
the bare KAS capability name in an allowedTools list, so it was a grant that
matched no real input. The table now holds only the two spellings that a real
allowedTools list can carry, use_subagent (Crew's own name, used everywhere
else in the repo) and invoke_sub_agent (KAS's, kept because a spec hand-written
against KAS's vocabulary means the same thing). Both collapse to the one
{"capability": "subagent", "effect": "allow"} rule, so no duplicate is emitted.
test_the_bare_kas_capability_name_is_not_a_grant locks the removal in, and
test_a_scoped_entry_is_left_to_prompt confirms subagent/research is still not
translated.

"Shrink NON_SHELL_CAPABILITIES to frozenset({"subagent"})." I went further
and deleted the set outright, along with the is_non_shell_capability helper. The
one attested frameless case does not need a collection to hold it: _dispatch
compares the consent capability against SUBAGENT_CAPABILITY and puts the
resulting boolean on AcpEvent.spawn_attested, which providers/acp._to_llm_event
forwards. A derived boolean rather than the raw string, so KAS's capability
vocabulary stays inside the ACP layer.

That subtraction paid for itself twice. It also cleared the
Backend Lint & Type Check failure on the agent-SDK boundary ratchet
(cli_chat.py:0 ACP-layer imports grew from 3 to 4), because cli_chat no longer
imports kas_permissions at all. Confirmed green on the committed diff by
scripts/check_agent_sdk_boundary.py, whose scope is origin/main...HEAD.

The waiver's reach is unchanged and still narrow: it is folded into the
cache-miss branch rather than placed ahead of it, so it can only turn a hard deny
into a prompt, never into an auto-approve. A shell-shaped payload kind still
denies even on an attested spawn
(test_an_attested_spawn_does_not_waive_a_shell_shaped_kind), nine malformed
_meta shapes all read as not attested, and shell_classified itself is left
alone so the dashboard's auto-approve gating stays as conservative as it was.

@karraghu

karraghu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

Design Review (CONCERNS, advisory): fixed.

The ask was to put the trusted-channel entry and the deny-to-prompt-only
invariant into the owning spec, since the repo requires a same-commit spec update
for acp/. Four spec files are updated in this commit:

  • docs/system-specs/modules/acp-client.md gains spawn_attested alongside the
    other backend-stated channels, so the _meta.kiro.consent.capability channel is
    documented next to the _meta.kiro MCP-identity channel this code already
    trusts.
  • docs/system-specs/modules/security.md gains the channel's trust class and the
    deny-to-prompt-only invariant, stated as the bound it is: an attestation can
    convert a hard deny into a prompt and can never produce an auto-approve, the
    payload-kind deny still fires, and gate.hooks.on_tool_call still runs first.
  • docs/system-specs/modules/cli.md gains the new permission-ladder step and the
    spawn_not_permitted audit code.
  • docs/system-specs/modules/governance.md gains the second entry point into the
    spawn chokepoint, so _vet_spawn_governance is no longer documented as having
    exactly one caller.

Two stale comments asserting that the permission payload carries no _meta are
corrected in the same commit; the live KAS frame disproves them, and run 5 of the
manual verification captures the frame that does.

Docs gates: test_docs_lint_fact_checks.py 91 passed, and scripts/docs-lint.sh
exits 0 over 265 markdown files.

@karraghu
karraghu force-pushed the fix/kas-subagent-approval branch from 401e669 to 8b49f81 Compare September 6, 2026 19:30
@karraghu

karraghu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

GPT 5.6 Review, span=02b9488070a4 (blocking, security): fixed. My round-2
rebuttal is withdrawn.

I argued last round that no trusted target existed to pass, so the agents half
of the policy was unenforceable on this path. That was wrong, and the review was
right to hold. _meta.kiro.consent carries the target, and it is part of the
contract rather than an artefact of my test fixture: kiro-cli's own permission UI
resolves {capability, resource, triggeringResource} off the incoming frame with
precedence triggeringResource ?? resource. Reading the shipped client settled
it, not the diff.

So the target now travels and both halves are checked:

  • _dispatch._kiro_consent_resource reads the block with that same precedence,
    and only when the frame is an attested spawn — on a shell or MCP consent frame
    the field names a path or a server, not an agent.
  • It rides to the CLI on AcpEvent.spawn_target, the same provenance class as
    spawn_attested: backend-stated, never model-authored, so a gate may key on it.
  • _spawn_ceiling_denial(session_key, target) passes it to
    _vet_spawn_governance, so a ceiling narrowed to named agents now bites on this
    surface too, before the human is asked.

The other half of the finding — "deny scoped policies when no trusted target is
available" — is implemented as a scope evaluation rather than an outright deny,
and the difference matters. _vet_spawn_governance no longer skips the agents
query when agent is empty; it asks the policy about the empty target and lets
the answer stand:

policy shape verdict on an unnamed target
agents allow-list deny — no pattern matches "". This is the hole the finding names, closed.
agents deny-list permit — an unnamed agent is not one of the agents the operator refused.
no agents scope permit, scope 'agents' unconstrained.

Denying outright instead would refuse every KAS spawn on any host whose policy
has no opinion about agents, which is the feature this PR delivers. The
allow-list row is what closes the bypass; the other two rows are the operator's
own stated intent.

Scope of the guard removal is one caller: subagent_manager/admission.py already
resolves a non-empty agent before it calls, so nothing else changes behaviour.

Nine tests, four of them new. test_the_attested_target_is_what_reaches_the_policy
pins that the attested agent and not the title is what gets vetted, and three in
TestSpawnGate drive the table above against a real installed policy:
test_an_allow_list_denies_a_spawn_that_states_no_agent,
test_a_deny_list_still_permits_a_spawn_that_states_no_agent,
test_no_agents_scope_permits_a_spawn_that_states_no_agent. On the extraction
side, test_the_triggering_resource_wins pins the precedence and
test_a_non_spawn_frame_carries_no_target keeps a path or server name out of the
field.

One limit stays on the record: this proves the contract, not that KAS populates
the field on the spawn frame specifically. The instrumented run that produced the
PR body's evidence logged only consent.capability and toolId, so I cannot show
a live spawn frame carrying resource, and the instrumentation is gone. That
uncertainty is why the missing-target case resolves through the policy instead of
a blanket refusal — if KAS omits it, an ungoverned host is unaffected and a
governed one fails in the direction its own policy chose.

The cli.md, governance.md, acp-client.md and security.md paragraphs that
asserted the enabled-half-only asymmetry are corrected in the same commit.

@karraghu

karraghu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

GPT 5.6 Review, span=44f906073002 (top-level-imports): fixed.

from kiro_crew.subagent import _vet_spawn_governance is at module scope in
cli_chat.py now. It was function-local out of caution about a cycle, and there
is none: subagent imports neither cli_chat nor anything that reaches back to
it, and subagent_manager/admission.py already imports that same private name at
module scope, so the edge has precedent in the tree.

Verified by importing the four touched modules in one interpreter, and the lint
gate — the eleven checks CI's backend-lint job runs, flake8 and isort
included — is green on the rebased commit.

Moving it also made the test that pins the delegation honest: it patches
cli_chat._vet_spawn_governance, the name the caller actually resolves, rather
than reaching into subagent and relying on the deferred lookup to pick the patch
up.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 6, 2026
@karraghu
karraghu force-pushed the fix/kas-subagent-approval branch from 8b49f81 to 07bc8ba Compare September 7, 2026 03:24
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 8, 2026
@karraghu
karraghu force-pushed the fix/kas-subagent-approval branch from 7ac4173 to 5924594 Compare September 8, 2026 21:15
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision labels Sep 8, 2026
@karraghu

karraghu commented Sep 8, 2026

Copy link
Copy Markdown
Contributor Author

self-added: no

  • Description ↔ diff drift — fixed: the PR body now documents HEAD 5924594.

Confirmed, and fixed in the description rather than the code. All three
specifics held. cli_chat._spawn_ceiling_denial occurs nowhere in src or
test (0 hits), so a reader really was sent looking for a function that does
not exist. The "only the enabled half of the policy is checkable on the CLI
path" claim was false at HEAD: _vet_spawn_governance runs the
capabilities.spawn agents scope query and then the structural
unnamed-target denial, on both surfaces. And _resolve_spawn_target
(subagent.py:368), the dashboard ceiling in chat_runner.py:8777, and the
admission-path caller threading (admission.py:287) went unmentioned.
Two passages are replaced. The shared-chokepoint bullet now names both
permission handlers instead of one invented function, and records that the
dashboard call sits above the hooks gate so it precedes every auto-approve path
there. A new pair of paragraphs replaces the asymmetry claim with what ships:
both halves enforced on both surfaces, keyed on the backend's own
spawn_target attestation rather than the LLM-authored title; why item
matching cannot judge an empty target (resolve collapses the inner rule to
rule="rule2-intersect" on a permit, so "deny-mode let the empty item through"
and "there is no agents scope" are indistinguishable, and only the first
should deny); and what governance_scope_constrained, _resolve_spawn_target
and the admission path each contribute.
The audit codes the old text cited were accurate — _SPAWN_CEILING_CODE = "spawn_not_permitted" and _GATE_FAILURE_CODE = "gate_failed"
(cli_chat.py:75,83) — and are kept verbatim.
No code changed, so the diff and the green rollup on this head both stand.

@karraghu

karraghu commented Sep 8, 2026

Copy link
Copy Markdown
Contributor Author

self-added: no

  • The _meta.kiro.consent / triggeringResource premise is a vendored-tool claim this repo cannot check — rebutted on regression risk; the efficacy half conceded as unproven.

Right on both counts, which is why the code stays as-is. Nothing in this repo
can verify the frame, and wrong ⇒ inert: _unverifiable_shell folds the waiver
into the cache-miss branch rather than ahead of it, so a missing, null or
non-string consent block reads as not attested and the path falls back to
today's denial. There is no regression to weigh, so this is not a defect.
I tried to close the "confirmed on a named kiro-cli version" half directly and
could not. On kiro-cli 2.21.1 (aarch64, unstripped, 732,217 extracted strings)
triggeringResource, consent and _meta.kiro are all absent — but that
result is uninformative rather than negative, because the ACP positive control
jsonrpc is absent too, and every JSON-RPC frame must carry it. The wire
vocabulary is simply not recoverable from that binary by string extraction, so
absence there is evidence in neither direction. Reporting it as a refutation
would have been the error; I am reporting the method as inconclusive.
So the premise stands unproven, not refuted, and the Watch is correctly placed:
a real captured frame in #9024 is what settles whether this fixes #9024, and
the fail-closed fallback is what makes shipping it safe in the meantime.

@karraghu

karraghu commented Sep 8, 2026

Copy link
Copy Markdown
Contributor Author

self-added: no

  • "Messaging runners are still unwired" asks for a linked tracking issue — needs-a-decision: I cannot open one on this repository.

Accepted as a real gap, and deliberately on the record: the governance.md
hunk in this diff is what declares the sibling surface where the spawn ceiling
does not run, so the PR states its own remaining edge rather than implying
whole coverage.
The ask is the linked issue, and that is the part I cannot supply. This is a
fork PR and the token here holds pull only on kirodotdev/KiroCrew (push: false, triage: false), so I can neither open the issue, nor apply the
deferred-finding label, nor assign an owner or a due date. A deferral with
none of those three is exactly the untracked kind that ships anyway, so I would
rather name the limit than record a deferral I cannot back.
Maintainer decision, either way is coherent: open the tracking issue for wiring
the messaging runners through _vet_spawn_governance and link it here, or rule
that the declaration in governance.md is sufficient for this PR and the Watch
closes with it.

@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 8, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 9, 2026 07:24
bolichen97
bolichen97 previously approved these changes Sep 9, 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.

Approving at 5924594 after an approval-seam read.

Auto-approve is not widened past spawn: kas_permissions.py adds only use_subagent → SUBAGENT_CAPABILITY, and TestTheSubAgentGrantUsesCrewsOwnToolName pins that subagent / subagent/<x> stay untranslated. cli_chat.py ~L511 waives only the cache-miss branch on a backend-derived boolean — the is_shell path and payload-kind deny are unchanged (deny→prompt only, never →approve). _meta.kiro.consent is read with isinstance guards at every level; 9 malformed shapes → spawn_attested is False. subagent.py makes app/caller_agent keyword-only and all 14 call sites already pass by keyword. The dashboard ceiling check sits ahead of the hooks gate and an AST-enumerating test pins it. No harness-identity predicates, no model ids, four owning specs updated, 1 commit.

Three things to state plainly (none blocking): (1) admission.py ~L283 now vets the RESOLVED parent agent instead of "", so an existing agents allow-list that omits the parent's agent will start refusing default-agent spawns on Crew's own SpawnSDK path — intended, but a behavior change for such configs; (2) the may_skip_gate_now predicate withholds use_subagent from EVERY kiro-cli allowedTools writer on a spawn-governed host, not only the KAS projection as the body says — conservative, but wider than described; (3) subagent.py ~L404 docstring ("Defaults empty, leaving the SpawnSDK path exactly as it was") contradicts admission.py ~L290, which now always passes caller_agent. Also cli_chat.py/chat_runner.py gain module-level imports of the heavy kiro_crew.subagent.

bolichen97
bolichen97 previously approved these changes Sep 9, 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.

Re-approving on ad98b98. The only delta from the head I approved (5924594) is the rebase over #8800's MCP-identity escape in cli_chat.py _unverifiable_shell: the attested-spawn waiver now sits AFTER that escape and still falls through to the payload-kind deny, so the escape decides everything it already decided and attestation only reprieves what it denied. File set and every other hunk are byte-identical to the reviewed diff. Approved workflow runs for the new head and re-armed Auto-Merge.

@karraghu

karraghu commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: grant-time SEL audit at KAS projection (spawn_auto_approve_granted)

  • kas_permissions.py:79, anchor backend-security-controls — "Auto-approved spawns bypass mandatory SEL auditing" — fixed as far as the platform allows, in c98d865c7; the residual is named rather than hidden.

Upheld, not rebutted. I verified the mechanism against the code before answering
and it holds exactly as traced: _FLOOR_GATE_SCOPES is
{filesystem.read, filesystem.write, commands} (platform/governance.py:3325),
so capabilities.spawn is not floor-gated; may_skip_gate then reaches
if ceiling is None: return True (:3445); and acp/kas_agents.py states at the
auto-approve note that on that path "the deny-list and the audit trail are
skipped". So on an ungoverned host a spec-granted spawn was answered by KAS with
no permission event and no decision record anywhere. That is a real gap and I am
not arguing otherwise.

One correction to the framing, which changes the fix but not the verdict: the
mechanism is not introduced here. invoke_sub_agent: "subagent" is already in
CAPABILITY_BY_TOOL on mainline. What this PR changes is REACHABILITY — no real
spec carries KAS's spelling, so adding use_subagent is what makes the path
live. The exposure is therefore new even though the code path is not.

The suggested fix ("keep use_subagent prompting until KAS exposes an event
Crew can SEL-audit") deletes the capability this PR exists to deliver, so I have
taken the part of it that is available. _ceiling_permitted now emits one
spawn_auto_approve_granted SEL event (source="kas_agent_projection") when a
spawn-capability tool survives the ceiling re-check and is projected WITH
auto-approve. It is the mirror of the mcp_auto_approve_withheld event already
on that path, fails open on an audit-sink error exactly as the withhold does, and
is scoped to the spawn capability — every other projected tool still reaches a
permission request that is audited downstream, so auditing all of them would add
noise without coverage, and would contradict the existing
test_nothing_withheld_emits_no_event.

This ruling covers the class, not the line: any finding that the KAS
auto-approve projection lacks a decision record for a granted capability is
answered by this event and this rationale, wherever the grant is expressed.

What it does NOT cover, stated plainly: the record is of the GRANT, not of each
spawn. Per-spawn auditing needs an event from KAS that does not exist, so no
amount of Crew-side code produces it. An operator who requires per-spawn records
today has one available control — a capabilities.spawn opinion in the ceiling,
which makes may_skip_gate withhold the tool via BUILTIN_TOOL_SCOPES and sends
every spawn back through the prompting-and-audited path.

Pinned by test_kas_agents.py::TestAGrantedSpawnIsAudited: the grant, both tool
spellings, silence for non-spawn tools, the withheld case recording only the
withhold, and an audit failure never failing the projection. Recorded in
docs/system-specs/modules/security.md under "What counts as an auditable
permission decision", beside the skill-triggering entry that draws the same
grant-versus-absence distinction.

If a maintainer judges the remaining per-spawn gap acceptable for this PR, the override reason is:

/ai-review override gpt c98d865c7: the KAS auto-approve projection now emits spawn_auto_approve_granted, so the grant is on the record; per-spawn auditing requires a KAS event that does not exist, and the sanctioned control for an operator who needs it is a capabilities.spawn ceiling opinion, which returns every spawn to the prompting-and-audited path.

@karraghu

karraghu commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

Maintainer action requested: /ai-review override gpt for the per-invocation spawn audit

I can't record this myself. ai-review-human-override.yml reads
repos/{repo}/collaborators/{actor}/permission and accepts only admin|maintain|write;
this is a fork PR and my account has pull, so issuing the command as me would be
refused and would just leave a "only a repository writer may override" notice on the
thread. Hence a request rather than the command.

What is blocking: GPT 5.6 Review, one finding, security-class and therefore
withheld from adjudication — kas_permissions.py:79, anchor
backend-security-controls, "Auto-approved spawns lack per-invocation SEL auditing".

Why it cannot be closed in this PR. The finding is correct and I did not rebut it.
It narrowed after the last push, which is the fix being acknowledged: it moved from
"bypass mandatory SEL auditing / no SEL invocation or decision record" to "lack
per-invocation SEL auditing … only session-level projection is logged". What it now
asks for is one of two things, and both are closed doors here:

  • "Route every spawn through live Crew governance and SEL auditing" — needs a
    per-spawn event from KAS. KAS answers an auto-approved spawn itself and raises no
    permission request, so there is nothing for Crew to hook. No amount of Crew-side code
    produces that event.
  • "Leave this capability unprojected so each invocation prompts and is audited" —
    deletes the capability this PR exists to deliver (Bug report: a sub-agent spawn can never be approved on the kas backend #9024).

What shipped instead. _ceiling_permitted now emits one
spawn_auto_approve_granted SEL event (source="kas_agent_projection") when a
spawn-capability tool survives the ceiling re-check and is projected with auto-approve
— the mirror of the mcp_auto_approve_withheld event already on that path, failing
open on an audit-sink error exactly as the withhold does, scoped to the spawn
capability so the ordinary projection stays silent. It records the grant, not each
spawn. Pinned by test_kas_agents.py::TestAGrantedSpawnIsAudited and written up in
docs/system-specs/modules/security.md under "What counts as an auditable permission
decision".

The control that remains available to an operator who does require per-spawn
records: a capabilities.spawn opinion in the governance ceiling. That makes
may_skip_gate withhold the tool via BUILTIN_TOOL_SCOPES, which returns every spawn
to the prompting-and-audited path. The residual is therefore confined to an
ungoverned host, where capabilities.spawn is not in _FLOOR_GATE_SCOPES and
may_skip_gate returns True with no ceiling installed.

If you judge that residual acceptable, this is the command to paste:

/ai-review override gpt c98d865c73574e417d7ff972e28083c48e942e1a: the KAS auto-approve projection now emits spawn_auto_approve_granted, so the grant is on the record; per-spawn auditing requires a KAS event that does not exist, and the sanctioned control for an operator who needs it is a capabilities.spawn ceiling opinion, which returns every spawn to the prompting-and-audited path.

Two notes on using it. The decision is SHA-scoped — the handler says so explicitly
("A new push requires a new judgment") — so any further push to this branch voids it
and it has to be re-issued against the new head. And it must name the current head,
which is c98d865c73574e417d7ff972e28083c48e942e1a.

The other red is not mine, and please don't conflate them. Backend Tests (Windows) (4) fails on test_workflows_app.py::test_main_boots_platform_before_binding_server,
which is inherited from origin/main. Attribution, three ways: it fails alone (so no
shard-composition or test-interaction effect), this PR touches neither that test nor
apps/builtins/workflows/server.py, and a pristine origin/main worktree at
ebf9ffb55 fails it alone with the same stack — server.main() reaching the real
serve_forever() because the _FakeServer monkeypatch does not take effect, so the
xdist worker blocks until pytest-timeout kills it. It arrived with ebf9ffb55 (#9066).
Windows shards 1–3 pass, and it moved from worker gw2 to gw0 between runs, which is
further evidence it is the test rather than the sharding. Happy to raise it upstream
separately if that is useful.

Everything else is green.

@chenmingwei23 chenmingwei23 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.

Verdict: recommend changes pending the one open blocking item; the code itself looks landable to me, human verdict pending. I reviewed this as an independent pass and verified the key premises against the tree at c98d865, so most of what I would say is already on the record from the bot lanes -- I am not re-posting those.

The one open blocker is not mine and is already tracked. GPT 5.6 flagged that an auto-approved KAS spawn gets no per-invocation SEL audit (kas_permissions.py:79). That finding is correct and the author has disposed it honestly: the grant is audited once at projection (kas_agents._ceiling_permitted -> spawn_auto_approve_granted), per-spawn auditing needs a KAS event that does not exist yet, and an operator who needs per-spawn records sets a capabilities.spawn opinion to return spawns to the prompted-and-audited path. That is a real, named residual, not a hidden one. The remaining decision is the maintainer override the author requested; I have no new information that changes it.

What I checked and found clean (independent verification, not taken from the body):

  • governance_permits and resolve_active_scope both accept the new agent= keyword; CapabilityGate.scopes is a Mapping, so inner in control.scopes in governance_scope_constrained is sound.
  • The keyword-only (*, app, caller_agent) change to _vet_spawn_governance is enforced at both new call sites and at admission.spawn_impl; the CLI passes caller_agent=gate.agent and correctly omits app (the CLI _ToolGate has no app field -- consistent with the docstring), the dashboard passes app=slot._app or "" matching the existing hooks-gate read of the same attribute.
  • The _unverifiable_shell waiver is folded into the cache-miss branch after the MCP escape and before the payload-kind deny, so an attested spawn can only turn a hard deny into a prompt; a shell-shaped kind still refuses. Deny-to-prompt-only holds.
  • The dashboard spawn check sits ahead of the hooks gate and every auto-approve/continue path, and outside if state.context_builder:, so a title-titled frameless spawn cannot auto-approve past it. The two new reject helpers mirror the existing _reject_invalid_tool/_reject_hook_error chokepoint shape (audit-first, blocked row, activity feed, fallback entry).
  • Description-to-diff: the body documents head c98d865, the four acp/ spec files are updated in the same commit as the repo requires, and the tests table maps to test files present in the diff. No phantom claim found.

Advisory (non-blocking), already on the record: First Principles' CONCERNS that governance_scope_constrained ships generalized (capability, inner) for a single caller stands -- it has exactly one production consumer today. It is genuinely needed there (the empty-target presence question the Decision cannot answer), so I would keep it, but a one-line note at the definition naming its sole caller would keep the next reader from treating the generality as load-bearing.

No new blocking findings from this pass.

return _D(True, f"{GOVERNANCE_ERROR_REASON}; no opinion", rule="default")


def governance_scope_constrained(

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.

should-fix (advisory, dedup of First Principles' CONCERNS): governance_scope_constrained(capability, inner, ...) ships generalized over both capability and inner, but its only production consumer is _vet_spawn_governance calling it as ("spawn", "agents").

def governance_scope_constrained(
    capability: str,
    inner: str,

The function is genuinely needed (only a presence check off the CapabilityGate can distinguish "deny-mode permitted the empty item" from "no agents scope at all", which governance.resolve collapses). Not a defect -- cause (added generality) -> mechanism (a second reader treats the two params as load-bearing surface) -> consequence (carrying cost until a real second caller earns it). Suggestion: add a one-line comment naming the sole caller and the concrete ("spawn","agents") shape, so the generality reads as convenience rather than contract. Not blocking.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done exactly as suggested, in ef8026a08 — the generality stays, with a docstring note. Added:

Sole production caller today: subagent._vet_spawn_governance, which asks exactly ("spawn", "agents") — the unnamed-spawn-target case. The capability/inner parameters are convenience for a future second caller, not a contract; nothing else generalizes over them yet.

Agreed on the reasoning: only a presence check off the CapabilityGate distinguishes "deny-mode permitted the empty item" from "no agents scope at all", since governance.resolve collapses both to an identical permit — so the function earns its place, and the params are cheap convenience rather than a contract to defend. Kept the signature rather than hardcoding, so no call site or test churns.

@karraghu

karraghu commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

Maintainer action requested: re-issue /ai-review override gpt for the new head

This re-points the round-7 override request at the current commit. The earlier one
named c98d865c7; the override handler is SHA-scoped ("A new push requires a new
judgment"), so the rebase-and-push to ef8026a08 voided it and the same finding
re-blocks the new head. Nothing about the finding changed.

I can't record it myself — ai-review-human-override.yml reads
repos/{repo}/collaborators/{actor}/permission and accepts only admin|maintain|write;
this is a fork PR and my account has pull, so issuing the command as me is refused.

Status on ef8026a08: GPT 5.6 is the only remaining failure. The three checks
that were red last head — Backend Tests (Windows) (4), Backend Tests (3.12, 4) and
Coverage Gate — were all the one inherited test_workflows_app.py:: test_main_boots_platform_before_binding_server timeout, and they cleared on their own
once this branch rebased onto c0cf53f3e ("fix: patch _Server in workflows entrypoint
tests"). So the override is now the single thing between this PR and green.

Why GPT still blocks, in its own adjudicator's words. The Opus adjudication this
run credits the fix and still upholds:

The change does add kas_agents.py:407-422 spawn_auto_approve_granted, but that
audits the grant once, not each spawn … per-spawn auditing needs a KAS event
that does not exist yet.

It rules the triggering config "not rare, contradictory, or legacy-only", so it
"cannot complete the 'so extreme a human would plausibly accept the residual risk'
record that FLAG demands" → UPHOLD-FENCED. That is the finding correctly identifying
a real residual with no code path to close it — the KAS per-spawn lifecycle event
its own suggested fix names does not exist, and the alternative (keep spawns prompting)
deletes the capability this PR delivers (#9024). The sanctioned exit for that state is
a human override, which is why this is a request rather than another code round.

If you accept the residual, paste this as its own comment:

/ai-review override gpt ef8026a08e32c268900121022d34c900a4ab20ba: the KAS auto-approve projection now emits spawn_auto_approve_granted, so the grant is on the record; per-spawn auditing requires a KAS event that does not exist, and the sanctioned control for an operator who needs it is a capabilities.spawn ceiling opinion, which returns every spawn to the prompting-and-audited path.

It is SHA-scoped to ef8026a08e32c268900121022d34c900a4ab20ba, so any further push
voids it again. The residual it accepts is confined to an ungoverned host — a
capabilities.spawn opinion in the ceiling makes may_skip_gate withhold the tool and
returns every spawn to the prompting-and-audited path.

@karraghu

karraghu commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

/ai-review override gpt ef8026a: the KAS auto-approve projection now emits spawn_auto_approve_granted, so the grant is on the record; per-spawn auditing requires a KAS event that does not exist, and the sanctioned control for an operator who needs it is a capabilities.spawn ceiling opinion, which returns every spawn to the prompting-and-audited path.

@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

AI-review override not recorded: only a repository writer may override an AI finding.

@karraghu

Copy link
Copy Markdown
Contributor Author

Note on the one non-backend file in this revision: src/kiro_crew/docs/settings-registry.generated.json is regenerated (npm run gen:settings, +30 lines / 5 settings entries).

It is not part of this PR's change and is not derived from anything this PR touches — it is a build artifact extracted from the frontend settings pages (website/src/pages/settings). Mainline ef6167041 shipped a stale copy of it alongside a new drift-guard test (settingsRegistry.test.ts > "checked-in JSON matches live extraction"), so the required Frontend Tests check fails on any PR rebased onto that base until the file is regenerated. Regenerating it here is the minimal change to make the required check green; the regenerated bytes are exactly what generateAgentRegistryJson(extractAll(...)) — the same generator the test asserts against — produces, so the drift guard passes by construction.

Flagging for scope: happy to drop it if a maintainer would rather fix the drift directly on mainline, in which case this PR goes green once it rebases onto the corrected base.

@karraghu

Copy link
Copy Markdown
Contributor Author

Maintainer action requested: /ai-review override gpt for d9acb8582

Two of the three GPT 5.6 findings on the prior head are fixed in code in d9acb8582; the remaining blocker is a finding GPT's own Opus adjudicator refuted this run, so it needs an override rather than a code change.

Fixed in code (d9acb8582):

  • session_handle.py — "Pending pipeline stages create false spawn audit records." Legitimate. The audit now skips a stage while its status is pending and records it only once it actually starts (the roster is re-emitted on transition and the sid stays unmarked until then). Test: test_pending_pipeline_stage_is_not_audited_until_it_starts.
  • docs/system-specs/modules/cli.md — the non-blocking FINDING that "a deny-list permits it" contradicted the presence check. Corrected: any declared agents scope (allow or deny mode) rejects an unnamed target; only the absence of the scope permits it.

The remaining blocker — refuted, not fixable in code: kas_permissions.py:79, "KAS auto-approval bypasses agent-bound spawn profiles" (fenced, security-class). The Opus adjudication on this same run verified the premise is false, in its own words:

projection filters allowedTools through _ceiling_permitted → may_skip_gate_now … which after the POLICY-ceiling check ALSO calls any_configured_profile_governs(ref) … So a disabled spawn profile — the exact condition the finding requires — is precisely what makes projection withhold the auto-approve entry, forcing a permission event where the profile veto runs. The condition that would trigger the bypass is what triggers the block … conditions self-contradictory.

I independently confirmed this against the tree: may_skip_gate_now calls may_skip_gate(ref, ceiling) and then any_configured_profile_governs(ref) (governance.py:4087-4094), and this PR's BUILTIN_TOOL_SCOPES maps use_subagent/invoke_sub_agent → capabilities.spawn, so a spawn-constraining profile withholds the grant → prompt → veto. The finding's suggested fix ("withhold when the ceiling or agent-bound profile constrains spawning") is already the behaviour, so there is no code change to make — writing one would be no-op appeasement of a false positive.

Because the finding is security-class it is fenced and blocks despite the adjudicator's refutation. The sanctioned exit is a human override. If you concur, paste:

/ai-review override gpt d9acb8582: GPT's own Opus adjudication refuted this finding this run — may_skip_gate_now calls any_configured_profile_governs after the ceiling check, and this PR maps use_subagent->capabilities.spawn in BUILTIN_TOOL_SCOPES, so a disabled/constraining spawn profile withholds the auto-approve grant and forces a prompt where the profile veto runs; the suggested fix is already the behaviour.

SHA-scoped, so it applies to d9acb8582; a further push needs a fresh one. GPT has not yet re-reviewed d9acb8582 — expect it to clear the pending-stage and doc findings and re-raise only this refuted one.

Spawning a sub-agent through the kas ACP backend always failed, and closing
that exposed two further defects in the ceiling that guards it. Squashed from
three commits for PR hygiene; the three changes are independent and are kept
separate below.

1. THE SPAWN COULD NOT BE APPROVED AT ALL

allowedTools -> KAS permission translation never granted the subagent
capability. CAPABILITY_BY_TOOL was keyed on KAS's internal toolIds
(invoke_sub_agent, disclose_context), but an allowedTools list holds Crew tool
names and the sub-agent tool is use_subagent everywhere else here. The entry
never matched, so the tool classified as unclassifiable, no allow rule was
projected, and KAS raised session/request_permission for a call the spec had
already granted. Both KAS toolIds are kept alongside the Crew names, since a
spec hand-written against KAS's vocabulary means the same thing.

The CLI then refused that request outright. KAS sends no preceding
session/update tool_call frame for a spawn and uses a synthetic
invoke_subagent_<parent id> toolCallId, so every toolCallId-keyed cache in
_dispatch misses, shell_classified is False, and _unverifiable_shell returns
True -- before _can_prompt, so no approval mode and no interactive human could
get past it. The request carries its own classification:
_meta.kiro.consent.capability is "subagent", the backend's own statement on the
same channel and in the same trust class as the _meta.kiro MCP identity already
read here. build_permission_event compares it against SUBAGENT_CAPABILITY onto
AcpEvent.spawn_attested, and _unverifiable_shell accepts that in place of a
cache hit. A shell-shaped payload kind or a missing consent block each keep the
refusal, and the waiver can only turn a hard deny into a prompt, never into an
auto-approve.

Neither grant path may outrank the capabilities.spawn ceiling, and neither
consulted it. classify_tool_title maps a builtin's title to commands/tools and
never to capabilities.spawn, so the hooks gate cannot see a spawn; and the one
place Crew vets a spawn, subagent._vet_spawn_governance, is not on the
backend's path. BUILTIN_TOOL_SCOPES now maps both spellings of the sub-agent
tool to capabilities.spawn, and cli_chat runs an attested spawn through
_vet_spawn_governance before the human is asked, so an administrator's ceiling
is not something a person at the terminal can approve away.

2. A CEILING DENIAL WAS ATTRIBUTED TO A HOOK

_reject_hook_error stamped outcome="hook_error" for a gate running ~28 lines
downstream of the ceiling, so a spawn refused by policy was audited as a hook
malfunction. A dedicated DENY_CAUSE_SPAWN_CEILING_ERROR and
_reject_spawn_ceiling_error record outcome="denied" instead, preserving the
six-step ordering contract (audit at step 1, reject_tool at step 5).

_vet_spawn_governance's app and caller_agent are now keyword-only: a caller
riding the app positional slot with a caller-agent name type-checks, runs, and
silently enforces the WRONG scope. Every existing call site already passed them
by keyword, so this needed no caller changes.

3. THE GATE VETTED A DIFFERENT AGENT THAN EXECUTION RUNS

subagent_manager/run.py:700 computes the agent every spawn shape runs as with
sessions.get_agent, which folds the session key (exact -> canonical ->
legacy-bare alias). The gate read _get_session_agent, an exact-key read. On a
canonical or legacy-bare key the folded read hits and the exact one misses, so
the gate vetted the "kirocrew" fallback while execution ran the real parent
agent: permitted, then runs denied.

_session_agent now reads through the folded accessor first, keeping the exact
one as fallback. The folded read DOMINATES: _fold_key returns the key unchanged
when it is already live, so whenever the exact read finds a session the folded
read finds the same one -- preferring it can only turn a miss into the true
name, never one name into a different name. run.py:1758 ->
session_allocation.py:391 does NOT fold, but the value it resolves is the boot
agent of a companion runtime process; the subagent session created on it
carries the folded agent, so the unfolded value never decides what a subagent
turn runs under. _resolve_spawn_target's docstring justified the exact-key read
by mirroring :389-392 and is rewritten.

Three guards are preserved because injected session doubles carry only
_get_session_agent: the callable() check, the isinstance(str) check and the ""
fallback. A raise guard is ADDED and is load-bearing for the folded read
specifically -- get_agent goes through _fold_key -> injected key derivers, a
failure surface the exact read never had, and this runs ahead of
_vet_spawn_governance's fail-closed wrapper. The caller/target asymmetry is
untouched: the target still falls back to "kirocrew", the caller to "".

An unnamed target also walked a DENY-mode agents scope. The gate vets
f"agents:{agent}"; with no agent that is "agents:", and a deny-mode ruleset
permits whatever it does not explicitly deny. The distinction cannot be read
off the Decision -- governance.resolve collapses the inner rule into
rule="rule2-intersect" on a permit, so "deny-mode permitted the empty item" and
"there is no agents scope at all" return an identical permit, and the second
must keep permitting. governance_scope_constrained answers the presence
question structurally off the CapabilityGate on either level and fails closed
on an evaluation error. The denial string is now mode-neutral.

This REVERSES a deliberate expectation.
test_a_deny_list_still_permits_a_spawn_that_states_no_agent asserted the
opposite, reasoning that "naming the agents you refuse says nothing about an
unnamed one". A deny-list's default-permit is safe only because every candidate
can be TESTED against the list; an unnamed target is not a member of the open
set but an untestable candidate, which resolves at execution time to an agent
that may well be a denied one. Permitting it is not honouring the operator's
default, it is declining to evaluate the control -- the same reasoning the
allow-mode case already accepts. Consequence asymmetry settles the rest:
refusing when the operator meant permit is loud and recoverable, permitting
when they meant deny runs a denied agent silently. Blast radius is a DENY-mode
agents scope with a spawn that has no nameable target; admission.py resolves
its target first, so this reaches only cli_chat.py's raw event.spawn_target.

TESTS

RED first for each finding, then green. test_subagent_coverage.py
TestTheGateReadsTheAgentExecutionActuallyRuns: 2 failed before the fold fix
("kirocrew" != "planner", "" != "planner"), 10 passed after.
test_governance_chokepoints.py TestUnnamedSpawnAgainstAnAgentsScope: 2 failed
before the scope fix (the vet returned None for a deny-mode unnamed target), 11
passed after -- including the fail-closed degrade path, proven RED-capable by
inverting the helper to return False.

460 passed across test_subagent_coverage, test_governance_chokepoints,
test_admission_gate, test_app_spawn_capability and test_deny_audit_first.
black/isort/flake8/mypy clean on the changed files; agent-sdk-boundary gate
passed. test_acp_client.py reports 6 failures that are INHERITED, proven
against a pristine origin/main worktree at 6fbb06b: identical 6 by name
there (6 failed / 610 passed) as here (6 failed / 629 passed), the delta being
the tests this change adds. test/test_governance_chokepoints.py and
test/test_dashboard_approval.py are already black-baselined; their drift is
reported, not swept.

DOC CORRECTIONS (non-blocking GPT 5.6 findings on this revision)

types.py attributed the fail-closed default of ``spawn_attested`` to the CLI's
``_prompt_allows``. The consumer that RELAXES a refusal on the flag is
``_unverifiable_shell`` (cli_chat.py:469, reading it at :511); ``_prompt_allows``
(:535) reads it at :577 only to name the spawn target in the consent line, never
to decide the answer. The comment now names the right one and records the
distinction.

security.md carried two claims the code contradicts. "The flag's only effect is
to relax a refusal" ignored the spawn-ceiling gates, which use it to refuse
outright and for which False means the ceiling is SKIPPED rather than enforced --
the opposite of fail-closed, as the types.py comment already stated. And "Both
consumers are on the CLI surface" was wrong: the consumers span two surfaces,
cli_chat and dashboard.chat_runner. Both sentences are corrected.

Comment and prose only -- no behaviour change. black/isort/flake8/mypy clean on
types.py, docs-lint passes, test_kas_permissions.py 70 passed.

COMMENT-HISTORY GATE

Seven comments added by this change narrated change history -- review-round
references ("Round 7"), and the phrases "used to" and "previously" -- which
scripts/check_comment_history.py forbids: the rule is that a comment states
CURRENT behavior in present tense, because the history is in git. The gate is a
shrink-only ratchet, so the baseline (subagent.py 23,
test_governance_chokepoints.py 4) carries pre-existing lines but licenses no new
ones, and this change took the test file to 10.

All seven are reworded in present tense with the meaning intact: the deny-mode
docstring states what the scope does rather than which round half-closed it, the
error-wording comments describe an allow-mode-only string rather than whose
string it was, and the two "the hole this closes" comments describe the omission
as a condition rather than as a past state. Comment text only -- no behaviour
change, and the assertions are untouched.

Verified: all 13 backend-lint gates pass locally plus docs-lint (14/14),
including check_comment_history, which reports "nothing in scope narrates change
history outside the baseline". test_governance_chokepoints.py and
test_subagent_coverage.py 393 passed.

WINDOWS ENCODING FIX

Backend Tests (Windows) shard 2/4 failed with:

    UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 98656
    C:\...\Lib\encodings\cp1252.py:23

TestDashboardSpawnCeiling reads dashboard/chat_runner.py to assert, by AST, that
the permission-request branch consults the spawn ceiling. It read it with
``Path.read_text()`` and no encoding, so the locale default applied: UTF-8 on
Linux and macOS, cp1252 on the Windows runners. chat_runner.py carries a byte at
offset 98656 that cp1252 has no mapping for, so the read raised before any
assertion ran -- which is why the Linux matrix, the macOS matrix, Windows shards
1/3/4 and every local run were green while shard 2 was red.

The read now pins ``encoding="utf-8"``, matching this file's own convention for
the SEL log it already reads that way. Exactly one such call exists in this
change's whole diff -- verified by grepping every added line across all four
changed files -- so there is no sibling branch to widen the fix to. The five
remaining bare ``write_text`` calls in the file are pre-existing and write ASCII
JSON fixtures, where cp1252 and UTF-8 agree.

test_governance_chokepoints.py 136 passed; all 13 backend-lint gates plus
docs-lint pass (14/14).
@chenmingwei23

Copy link
Copy Markdown
Contributor

Kiro Crew [operator: chenmingwei23#de330d0c]

Triaged as solvable and claimed for the drive-to-green pipeline.

Blockers found:

  1. Merge conflict (30 files) against current main -- rebase and resolve.
  2. SAST (Semgrep) lane is CANCELLED, which the repo's gate counts as failing and
    which pins PR Readiness. It clears on a fresh merge ref or a targeted re-run
    once the whole workflow run has concluded.

No blocking review verdict and no unresolved policy debate on the current head.

Because this PR touches the sub-agent approval path, one guard is written into the
work spec: if a rebase conflict lands on the authorization contract itself (who may
approve a child request), the session stops and escalates rather than deciding it.
Nothing will widen an approval path.

Content security scan passed with no findings.

@iamwhatever

Copy link
Copy Markdown
Contributor

Superseded by #14063 (merged), which fixes the same subagent-spawn-denied-on-KAS bug (#9024) at the two root causes: the CAPABILITY_BY_TOOL key vocabulary and the shell-classification of the spawn permission request.

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) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bug report: a sub-agent spawn can never be approved on the kas backend

6 participants