Skip to content

fix: honour the parent agent spec's availableAgents at the spawn gate - #13683

Merged
bolichen97 merged 2 commits into
mainfrom
fix/spawn-respect-available-agents
Sep 27, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/spawn-respect-available-agents

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

An operator wrote toolsSettings.subagent.availableAgents (and trustedAgents) on their custom agent spec to say "delegate only to these three agents", and a Kiro Crew session running that agent still spawned other installed agents. Reproduced against main: with an orchestrator spec declaring availableAgents: [agent1, agent2, agent3], spawn_run(agent="rogue") was ADMITTED, and the spawn_run tool description listed rogue under "Valid names right now".

Why it matters

This is an authorization boundary, not a missing feature. A field that looks like a security control and does nothing is worse than no field: every configuration that relied on it for isolation was false safety. kiro-cli enforces the key for its own built-in subagent tool, but Kiro Crew's sub-agents go through spawn_run / spawn_sub_agents, whose admission never opened the parent's spec.

What changed (motivation → approach → change)

Piece What it does now
src/kiro_crew/subagent.py (_vet_parent_available_agents, parent_spawn_allowlists, spawn_allowlist, agent_matches_allowlist) Reads the CALLING session's agent spec (read_session_execution(...).template_id, resolved in ~/.kiro/agents like agent_spec_path does) and refuses a child whose effective template matches none of the declared availableAgents globs
subagent_manager/admission/gate.py Calls it right after _vet_spawn_governance, before the row is persisted; refusal carries error_code=agent_not_available (subagent.AGENT_NOT_AVAILABLE_CODE) and is audited as denied
subagent.parent_spawn_policy, spawn_async, subagent_manager/admission/pump.py, dashboard/handlers/messaging.py (api_spawn) The parent's declaration is a blocking read (session record + agents-directory snapshot), so every event-loop entry point resolves it through asyncio.to_thread and hands it to spawn_impl as _parent_spawn_policy; the gate scans nothing on the loop. spawn_async derives the template from the parent record it already reads off-loop, /api/spawn from the parent_execution it admitted, the durable pump re-resolves before each drained row's re-check, and the in-memory queue's synchronous drain re-enters with the policy admitted with the row (stored in queue_params, dropped from the durable row by taskq_build_record); the synchronous spawn() computes it inline for callers that are not on the loop
mcp_tools/spawn.py "Valid names right now" and spawn_list's roster drop the names the parent's declaration forbids and say why; the wave short-circuit recognises the new code
docs/system-specs/modules/subagent.md, governance.md, src/kiro_crew/docs/agent-spec-fields.md Document the gate, the omit-allows-all rule, the intersection with governance, and what is not covered

Root cause: _validate_agent only asked "does this agent exist" and _vet_spawn_governance only read Kiro Crew's own capabilities.spawn.scopes.agents; nothing read the parent spec. The target checked is the EFFECTIVE child template (explicit agent, the inherited parent template, or a crew= member's kiro_agent), so the list cannot be routed around by omitting the name. Matching is fnmatch on the glob. Only when the VERIFIED calling app (execution.app) spawns its own <app>--<name> is the bare <name> tried too, the name the app's spec lists; a -- inside any other installed name is just a name, so rogue--reviewer never satisfies a reviewer-only list. The parent's spec is resolved the way agent_spec_path resolves a name: a spec whose declared name matches wins, the filename stem is the fallback, and if two specs declare the same name both lists apply (tightest wins). If no readable spec declares the parent's name and its own <template>.json/.md is present but unreadable (invalid JSON, oversized, symlink to a sensitive target), the answer is unknown and the gate refuses rather than failing open; a broken spec under any other filename refuses nothing. An agents directory that exists but cannot be scanned is unknown too (refused); an absent one declares nothing. The check is an intersection with governance: both gates must admit, and it never widens a governance denial.

trustedAgents is not read as an allowlist: upstream it means "run without permission prompts".

Existing-user visible behaviour

  • Unchanged for every session whose agent spec does not declare toolsSettings.subagent.availableAgents: no parent, no spec, or an omitted key is "allow all" exactly as before. No shipped Kiro Crew agent spec declares the key (the two pptx_maker specs that do use kiro-cli's own use_subagent tool, not spawn_run, and their bare name still matches). The spawn_run roster and spawn_list output are byte-identical for those sessions.
  • Changed, only for a session whose spec DOES declare the key — the behaviour the operator asked for by writing it:
    1. spawn_run / spawn_sub_agents targeting an agent outside the globs is refused with agent_not_available and a message naming the parent, the key and the allowed globs.
    2. Omitting agent inherits the parent's own template; if that template is not in the list, the spawn is refused too (the effective template is what is checked).
    3. The tool description's roster and spawn_list list only the allowed names, with a note that the list is restricted.
    4. A declared value that is not a list of strings is treated as an empty list (declared, nothing allowed) rather than allow-all; an empty list is announced in the roster instead of silently listing nothing.
    5. If the declaring parent's own spec file becomes unreadable, spawns from it are refused (fail-closed) until the file is fixed or removed; a parent whose execution record exists but cannot be read is refused the same way at the pump's re-check (a caller with no session at all stays unrestricted).

Backwards compatibility

Compatible: nothing that works today on a spec without the key stops working; the gate is a no-op unless toolsSettings.subagent.availableAgents is present, and no shipped spec presents it on a spawn_run path. POST /api/spawn gains one more value in the existing code field, which clients already treat as an open set (spawn_rejected for anything they do not know).

Tests

test/test_spawn_parent_available_agents.py (all 35 fail on main, pass here):

  • The triage fixture as a regression test: orchestrator declaring availableAgents: [agent1, agent2, agent3] plus agent1..3, an out-of-list rogue, an undeclared plain parent and a trust-only parent.
  • rogue refused with AGENT_NOT_AVAILABLE_CODE through the real SubagentManager.spawn; no slot taken, no row persisted, one denied audit record.
  • agent1 admitted; the inherited (omitted) template is vetted too.
  • No-regression controls: plain and trust-only parents admit rogue exactly as before; an unknown parent and an empty parent admit everything.
  • trustedAgents alone is not an allowlist; omitted key is None, malformed value is (); kiro-cli glob semantics; <app>--<agent> matches its bare name only for the verified app, never for rogue--reviewer.
  • An unreadable parent spec is unknown and refused; a resembling filename (sprint-planner.json for planner) or a declaring spec under another filename refuses nothing; queued params carry the admitted policy and the durable row does not; the roster announces an empty allowlist and leaves an unreadable parent alone.
  • The gate consumes a supplied _parent_spawn_policy without an inline scan; spawn_async resolves the declaration on a worker thread, never on the loop thread.
  • test/test_agent_spec_hardened_reads.py: the parsed_agent_specs call-site label ratchet lists the gate's spawn_available_agents/subagent read. test/test_subagent_execution_capture_async.py: a caller supplying the execution supplies the policy beside it, so the parent record is still read once.
  • Roster: filtered for a declaring parent, unfiltered for an undeclared or unknown one; wave short-circuit recognises the code.

Related existing suites (test_agent_roster_shared, test_spawn_agent_roster, test_governance_chokepoints, test_subagent_cwd, test_subagent_continuable, test_error_code_contract) and the diff-related set (scripts/local-gate.py, 37,943 tests) pass.

Manual verification

N/A — unit coverage sufficient: the gate test drives the real SubagentManager.spawn admission path with the same spec files kiro-cli would read.

Related Issues

no linked issue: reported in an internal channel; there is no GitHub issue for this defect.

Pattern harvest

Rule candidate: review-prompt
Pattern: "a kiro-cli spec field that reads like a security control is silently unread on a Kiro Crew path that replaces the kiro-cli tool it configures" — when Kiro Crew replaces a kiro-cli built-in with its own MCP tool, list the toolsSettings.<tool> keys of the replaced tool and decide each one explicitly (honour, or refuse loudly).

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

@bolichen97
bolichen97 requested review from a team and iamwhatever September 25, 2026 04:30
@bolichen97

Copy link
Copy Markdown
Contributor Author

Intent: Make spawn_run / spawn_sub_agents honour the calling agent spec's toolsSettings.subagent.availableAgents (kiro-cli semantics: declared = glob allowlist, omitted = allow all), so a declared allowlist is enforced at the spawn gate and advertised truthfully, with zero change for any spec that does not declare it.
Not a goal: Reading trustedAgents as an allowlist, adding a governance scope, honouring a project-scope parent spec, or warning when the key is declared but unreachable.

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 061c206197c62fd005a18a5f585fb1b717ef6105 — 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 on a real install that a pptx_maker session still spawns its composer: the only shipped declaring specs now cross this gate via the verified-app bare-name alias.

What this change ships

Inventory (9 items) — 9 justified

Intent: FIX — make the operator's toolsSettings.subagent.availableAgents declaration actually restrict spawn_run/spawn_sub_agents, as reproduced against main and pinned by 35 new tests.

  1. Spawning an agent outside the parent spec's declared globs is now refused (agent_not_available) — justified
  2. The effective/inherited child template is what's checked, so omitting agent can't route around the list — justified
  3. spawn_run's roster and spawn_list drop forbidden names and say the list is restricted — justified
  4. A declared non-list value is an empty allowlist (nothing allowed), announced in the roster — justified
  5. Unreadable parent spec, unreadable execution record, or unscannable agents dir refuses fail-closed, cost disclosed — justified
  6. POST /api/spawn and spawn responses gain the agent_not_available code; the wave short-circuit honours it — justified
  7. Retained globs bounded (256 patterns, 64 chars), overflow dropped fail-closed and logged — justified
  8. The gate reads the directory fresh through the existing AgentsDirMemo revision pin, off-loop at every entry point — justified
  9. Owning specs (subagent.md, governance.md, agent-spec-fields.md) updated in the same commit — justified

[FIRST-PRINCIPLES-REVIEWED] 061c206

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ human override accepted

Human judgment by @bolichen97 overrides the GPT 5.6 finding for 061c206197c62fd005a18a5f585fb1b717ef6105; the recorded reason is authoritative for this commit.

[GPT-OVERRIDE] 061c206

This comment is updated in place on each push.

The model was not re-run because an authorized human decision supersedes it.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 061c206197c62fd005a18a5f585fb1b717ef6105: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 061c206197c62fd005a18a5f585fb1b717ef6105 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

PR description and the new taskq_bridge comment describe a carry-the-policy-with-the-row design the code deliberately doesn't implement.

Watch

  • The description says the in-memory drain re-enters "with the policy admitted with the row (stored in queue_params…)" and "the gate scans nothing on the loop", and the new taskq_bridge.py comment says the policy is "kept in the in-memory queue so its synchronous drain scans nothing on the loop" — but gate.py's queue_params comment says "Deliberately NOT queued", and test_queued_params_do_not_carry_the_admitted_policy pins that. The real design (re-read fresh at every drain, via the gate's inline blocking fallback — a scandir when the memo pins, a full spec-directory parse when it can't) is the better one and the module spec states it correctly, but a maintainer reading the taskq_bridge comment will believe no I/O can run at drain time and budget the drain path accordingly.
    Clears when: the taskq_bridge.py comment and the PR description are corrected to the pinned re-read-at-drain design.

  • A parent spec living only in a project's .kiro/agents still has its availableAgents silently ignored — the exact "field that looks like a security control and does nothing" harm this PR's motivation names, now harder to spot because docs say the key is honoured. The gap is acknowledged only in the module spec, which the operator writing the project spec never reads.
    Clears when: a follow-up issue tracks project-scope resolution or a loud non-enforcement signal (log/roster note) when a project-scope spec declares the key.

[DESIGN-REVIEWED] 061c206

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ human override accepted

Reviewed 061c206197c62fd005a18a5f585fb1b717ef6105 — this comment is updated in place on each push.

Human judgment by @bolichen97 overrides the Opus 5 finding for 061c206197c62fd005a18a5f585fb1b717ef6105; the recorded reason is authoritative for this commit.

[OPUS-OVERRIDE] 061c206

Verdict recorded from an authorized human decision for commit 061c206197c62fd005a18a5f585fb1b717ef6105.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 061c206197c62fd005a18a5f585fb1b717ef6105: <one-sentence reason>

@bolichen97
bolichen97 enabled auto-merge (squash) September 25, 2026 05:12
@bolichen97
bolichen97 force-pushed the fix/spawn-respect-available-agents branch from b1c4aed to 5bc2d1d Compare September 25, 2026 05:46
@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 25, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: bare-name alias for app-namespaced agents

  • span=599ab81e58eb Unverified bare-name aliases bypass the parent allowlist — fixed in 5bc2d1d

The bare half is now tried only when the VERIFIED calling app (execution.app, bound by the SpawnSDK and re-proved by _validate_app_agent_ownership) is spawning its own <app>--<name>; agent_matches_allowlist takes app explicitly and never parses a prefix out of the target name.
rogue--reviewer against a reviewer-only list is pinned refused with and without an unrelated app identity (test_app_namespaced_agent_matches_its_bare_name_only_for_the_verified_app).

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: parent-spec allowlist resolver

  • span=599ab81e58eb Unreadable parent specs fail open — fixed in 5bc2d1d

parent_spawn_allowlists now answers UNKNOWN (None) when a file that can be the parent's spec by filename (<template>.json/.md, or the package-installed <package>-<template> shape) is present but did not parse under the hardened reader, or when the directory cannot be scanned; _vet_parent_available_agents refuses on UNKNOWN with agent_not_available naming the unreadable file.
Only the parent's own candidates are checked, so an unrelated broken spec refuses nothing it never governed; pinned by test_unreadable_parent_spec_is_unknown_not_allow_all, test_unreadable_package_shaped_candidate_is_unknown, test_unrelated_unreadable_spec_does_not_refuse and the gate-level test_gate_refuses_when_the_parent_spec_is_unreadable.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: off-loop parent spawn policy (_parent_spawn_policy)

  • span=599ab81e58eb Agent-spec scanning blocks the gateway event loop — fixed in 5bc2d1d

The declaration is now resolved off-loop by every event-loop entry point and handed to spawn_impl as _parent_spawn_policy: spawn_async derives the template from the parent record it already reads via to_thread and reads the allowlist in a thread, /api/spawn does the same from the parent_execution it admitted, and the pump resolves parent_spawn_policy via to_thread before each drained row's re-check. The gate consumes the supplied policy and scans nothing on the loop; only the synchronous spawn() (non-loop callers) computes it inline.
Pinned by test_a_precomputed_policy_is_consumed_without_an_inline_scan and test_spawn_async_resolves_the_policy_off_the_loop (asserts the resolver ran on a non-loop thread).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=6a3a78cb8f4d function-local imports (fnmatch, parsed_agent_specs, read_session_execution) — fixed in 5bc2d1d

All three moved to module scope in subagent.py and mcp_tools/spawn.py (no import cycle: execution_context imports only validation at top level); the _kiro_agents_dir import moved up as well.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=78333a2bd813 empty declared allowlist suppresses the restriction notice — fixed in 5bc2d1d

_agent_roster_hint now returns an explicit "allows none of the installed agents" notice when restricted is true and nothing remains, and spawn_list prints its restriction line whether or not any name survives; pinned by test_empty_allowlist_still_announces_the_restriction.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: off-loop parent spawn policy (_parent_spawn_policy)

  • span=aedc5864b93f synchronous agents-directory walk and session-record read on the gateway event loop — fixed in 5bc2d1d

Both reads now run off-loop at every event-loop entry point: spawn_async takes the parent template from the record it already reads through to_thread and reads the allowlist in a thread (one record read, as test_async_spawn_captures_parent_off_loop_before_policy_gates still pins), /api/spawn passes the policy from the parent_execution it admitted, and the pump's _dispatch_async_impl resolves parent_spawn_policy via to_thread before each drained row's re-check. spawn_impl consumes the supplied _parent_spawn_policy and scans nothing; the inline fallback serves only the synchronous spawn() callers that are not on the loop.
cached_agent_specs was not used on purpose: it serves empty rows cold, which would fail this gate open. Pinned by test_a_precomputed_policy_is_consumed_without_an_inline_scan and test_spawn_async_resolves_the_policy_off_the_loop.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=e20707424d7b matching the EFFECTIVE child template also governs the inherited/default template and a member with no kiro_agent — rebutted

This is the intended semantics, and it is what the reporting operator asked for: kiro-cli's key is "the agents this agent can spawn", and an omitted agent or a crew= member with no kiro_agent still RUNS a template — the parent's own, or the full kirocrew default. Matching only the requested name would let spawn_run(crew=X) run the default agent past a list that excludes it, which is exactly the "started subagents that are not allowed" the PR fixes, and kiro-cli's own subagent tool has no unnamed spawn to exempt.
Nothing moves for a spec that omits the key; a spec that declares it and wants its own template or the default may list them (kirocrew, its own name, or a glob). The PR body declares this under "Existing-user visible behaviour: changed" item 2 and the module spec records it.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=c27b95d3e4d6 gate honours only the user-level agents directory; a project-scope parent spec's declaration is silently not honoured — accepted-and-deferred

Correct as stated and out of this PR's scope: the gate has no handle on the parent SESSION's project directory today (_pool_cwd is the gateway's), so honouring the project scope is a plumbing change through the session record, not a spawn-gate edit. Tracked as #13697 (label deferred-finding, assignee bolichen97, Due line in the body), which also asks for the loud surfacing this Watch item names.
Nothing here is worse than main: on main NO declaration was honoured; this PR honours the user-level one and records the residual in the module spec.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=1fbbb6c59d58 duplicate-name spec handling undeclared in the description — fixed

The PR body's "What changed" now states the resolution rule in full: declared name wins, filename stem is the fallback, and two specs declaring the same name both apply (tightest wins); no code change was needed.

@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 25, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=6bff14db2323 project-scope parent spec's declaration not resolved by the gate — accepted-and-deferred

Same residual as span c27b95d3e4d6 on the previous head, and this lane's own "Clears when" accepts a linked follow-up: it is tracked in #13697 (label deferred-finding, assignee bolichen97, Due line), which asks for project-dir resolution through the session record and, until then, an operator-visible warning when a declaring project-level spec exists for the parent template.
Out of this PR's scope because the gate has no handle on the parent SESSION's project directory today (_pool_cwd is the gateway's); on main no declaration at all was honoured, so this PR narrows the gap and records the remainder in the module spec.

@bolichen97
bolichen97 force-pushed the fix/spawn-respect-available-agents branch from 5bc2d1d to 1e51e79 Compare September 25, 2026 06:27
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: parent spawn policy resolver (parent_spawn_policy / ParentRecordUnreadable)

  • span=599ab81e58eb Unreadable parent execution fails open — fixed in 1e51e79

_parent_template_for_spawn no longer folds a read failure into "no parent": it raises ParentRecordUnreadable, parent_spawn_policy answers ("", None), and _vet_parent_available_agents refuses that with agent_not_available ("the parent session's execution record could not be read"). A caller with no session, or a session with no record, stays ("", ()) (parentless, unrestricted) — the two facts are kept apart at the pump's re-check too.
Pinned by test_unreadable_parent_record_is_unknown_not_parentless.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=65f335fcf785 parentless /api/spawn uses the synthesized child template as its parent — fixed in 1e51e79

api_spawn now derives _parent_spawn_policy from parent_execution only when one was resolved (the caller's execution or the parent record read off-loop) and passes the literal ("", ()) when no parent execution exists, before the synthesized ExecutionContext is built from the requested agent, so a child's own restrictive spec is never read as its parent's.

@bolichen97

bolichen97 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _parent_spawn_policy carried in queue_params (process-local)

  • span=28d6714545d6 the gate's inline fallback still runs on the loop for the in-memory queue's synchronous drain — fixed in 1e51e79

The policy admitted with a row is now stored in its queue_params beside _execution_context, so _drain_queue_sync_impl's spawn(**params, _from_queue=True) re-enters with it and the gate scans nothing; taskq_build_record drops it from the durable row (added to _PROCESS_LOCAL_PARAMS, like _agent_prevalidated) and the durable pump re-resolves it off-loop before each re-check, popping any stored copy first. The inline fallback is now reached only by the synchronous spawn() callers that are not on the loop.
Pinned by test_queued_params_carry_the_admitted_policy (in-memory params carry it, the durable record does not) beside the existing off-loop tests.

@bolichen97

bolichen97 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=88a3825dcf3c resembling filenames counted as the parent's unreadable spec — fixed in 1e51e79

parent_spawn_allowlists now checks only agent_spec_candidates(agents_dir, parent_template) — the exact <template>.json/.md paths agent_spec_path resolves — and only when no parsed row declares the name; the endswith("-<template>") match is gone, so a broken sprint-planner.json beside a healthy planner.json refuses nothing, and a readable spec under another filename that declares the name wins over a broken candidate.
Pinned by test_a_resembling_filename_is_not_the_parents_candidate and test_a_declaring_spec_under_another_filename_wins_over_a_broken_candidate.

@bolichen97
bolichen97 force-pushed the fix/spawn-respect-available-agents branch from 7d294e0 to 8fb2053 Compare September 26, 2026 22:57
@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 26, 2026
@bolichen97
bolichen97 force-pushed the fix/spawn-respect-available-agents branch from 8fb2053 to 9af4cb8 Compare September 26, 2026 23:01
@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 26, 2026
@bolichen97
bolichen97 force-pushed the fix/spawn-respect-available-agents branch from 9af4cb8 to 6b119b2 Compare September 26, 2026 23:54
@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 26, 2026
Comment thread src/kiro_crew/subagent.py Fixed
@bolichen97
bolichen97 force-pushed the fix/spawn-respect-available-agents branch 2 times, most recently from 78c8148 to f2406af Compare September 27, 2026 00:31
Comment thread src/kiro_crew/subagent.py Fixed
Comment thread src/kiro_crew/subagent.py Fixed
@bolichen97

Copy link
Copy Markdown
Contributor Author

@buluoray -- thank you for the review; your reproduction was exactly right and it is fixed on 481e625455.

🔴 Plain non-spec .md refused every spawn -- fixed. _scan_parent_spawn_allowlists now skips a markdown file whose head has no opening frontmatter fence through agent_discovery.plain_markdown_document, the same rule the KAS projection and the tool-policy read already apply, so the file joins the ._ sidecar as "not a spec" rather than "unreadable" and the path.stem == parent_template fallback is reached. Your rebuttal is what the code comment now says: a fence-less document cannot carry a name kiro-cli would resolve, so it can hide no declaration and the fail-closed rationale does not reach it. A FENCED .md that fails to parse still counts as unreadable.

Mutation-verified from both sides, as you asked:

  • test_a_plain_markdown_document_is_not_an_unreadable_spec -- your case verbatim (planner.json with no name, README.md beside it): () before and after the README appears, _vet("planner", "agent1") admits. Fails on the previous head (None, refuse all).
  • test_a_fenced_markdown_spec_that_does_not_parse_still_refuses -- a fenced .md with broken YAML, and one whose fence never closes: still None, still refused. Fails against an over-broad mutation that skips every .md.

The arms in your "Verified clean" section (LookupInconclusive / ParentRecordUnreadable / unscannable directory, the os.scandir probe ordering, the bare-name alias gating, intersect-not-replace) are untouched; the whole file plus the spawn/admission suites pass locally (684).

🟡 Memo turns itself off above 4096 entries -- not fixed here, tracked in #14335 with your measurements. Both defeats (_AGENTS_DIR_REVISION_MAX_ENTRIES and the racy window) live in the shared agents_dir_revision from #13067 and are the pin for two other readers as well; changing either changes their cache semantics, and the racy window is the deliberate freshness rule that keeps a cp -p rewrite from serving a stale permissive allowlist. That is a design decision for the memo, not a one-liner inside this PR, so it is filed rather than dropped. The per-spawn read stays off-loop as you noted.

Also in this push, unrelated to your review: GPT flagged that the refusal strings and the warning log in _vet_parent_available_agents echoed the caller-supplied agent / parent_template names unredacted; they now go through redact_via_context like the glob roster beside them.

w added 2 commits September 27, 2026 04:06
kiro-cli defines toolsSettings.subagent.availableAgents for its built-in
subagent tool: the glob list of agents an agent may spawn, omit = allow
all. Kiro Crew's sub-agents come through spawn_run / spawn_sub_agents,
whose admission only checked that the target agent exists plus Kiro
Crew's own governance scope, so an operator's declared allowlist was
silently ignored and the spawn tools advertised every installed agent as
valid (reproduced against main: an out-of-list agent was ADMITTED).

The gate now resolves the calling session's template, reads its spec's
availableAgents from the user-level agents directory, and refuses a
target whose EFFECTIVE template (explicit, inherited or a member's)
matches no glob, with error_code=agent_not_available. It runs right
after the governance check and is an intersection with it. Only a spec
that DECLARES the key changes anything: no parent, no spec or an omitted
key is allow-all, so every existing session keeps its admission.
trustedAgents keeps its upstream meaning and is not read as a list.

spawn_run's "Valid names right now" roster and spawn_list drop the names
the parent's declaration forbids and say so; the wave short-circuit
recognises the new code.
…y at every drain; redact refusals

Three review findings on the parent-spec allowlist gate.

A frontmatter-less .md in ~/.kiro/agents (a README, a shared prompt
fragment) is returned by iter_agent_spec_files and refused by the hardened
reader, so _scan_parent_spawn_allowlists kept it as UNREADABLE and the
fail-closed arm fired before the filename-stem fallback could run: a parent
whose spec declares no name lost every spawn, and the refusal blamed a file
that was never a spec. Such a file cannot carry a name kiro-cli would
resolve, so it can hide no declaration; it is now skipped through
plain_markdown_document, the same rule the KAS projection and the
tool-policy read apply. A FENCED .md that fails to parse still refuses.
Tests pin both sides with the planner.json + README.md reproduction.

The queued entry no longer stores the policy it was admitted under. A row
waits on capacity, so the wait is unbounded in time and the declaration may
be tightened while it waits; the in-memory queue's synchronous drain
re-entered with the stored copy and the gate re-reads only when none is
passed, so a target the operator had since excluded still started. Every
drain now reads the declaration fresh: the durable pump off-loop (unchanged)
and the synchronous drain through the gate's inline fallback, a memo-pinned
directory read. Test parks a spawn on capacity, tightens the declaration,
drains, and asserts the refusal.

_vet_parent_available_agents hands its refusal back to the caller through
info.error before _validate_agent has vetted the target, so the agent and
parent-template names get the same redact_via_context pass the glob roster
next to them already had, in both refusals and the warning logged beside
them. Tests pin each site with a credential-shaped name.
@bolichen97

Copy link
Copy Markdown
Contributor Author

@buluoray -- ready for re-review at 061c206197 (your review is pinned to 9dd77209f2, several heads back). Everything since, in one read:

Your 🔴 (plain .md refuses every spawn) -- fixed, mutation-verified both directions. _scan_parent_spawn_allowlists skips a fence-less .md via agent_discovery.plain_markdown_document, so the stem fallback is reached.

  • test_a_plain_markdown_document_is_not_an_unreadable_spec: your planner.json (no name) + README.md case answers () and agent1 is admitted. Fails on the pre-fix head (None, refuse all).
  • test_a_fenced_markdown_spec_that_does_not_parse_still_refuses: a fenced .md with broken YAML, and one whose fence never closes, still answer None and still refuse. Fails against an over-broad mutation that skips every .md.

Your 🟡 (memo defeats above 4096 / inside the racy window) -- tracked in #14335 with your measurements; not changed here, since the cap and the window belong to the shared agents_dir_revision that pins two other readers.

One finding you did not raise, also closed: GPT flagged that the in-memory queue stored _parent_spawn_policy at enqueue and the synchronous drain re-entered with that copy, so a declaration tightened while a spawn sat on capacity was not re-read. The queued entry no longer stores the policy; every drain reads it fresh (durable pump off-loop as before, sync drain through the gate's inline memo-pinned read). test_sync_drain_honours_a_declaration_tightened_while_queued parks a spawn on capacity, tightens the declaration, drains, and asserts the refusal; it fails with the stored key restored. Cost weighed: a scandir when the memo pins; a full parse only at the scale in #14335.

Also: the refusal strings and warning log in _vet_parent_available_agents now redact the caller-supplied names (GPT security-class finding). Your "Verified clean" arms are untouched; 1375 tests across the spawn/admission/queue suites pass locally.

@bolichen97

Copy link
Copy Markdown
Contributor Author

/ai-review override gpt 061c206: With one twin unreadable the gate answers exactly as agent_spec_path and spec_by_declared_name do -- the readable declaring twin is the spec kiro-cli resolves as live -- so honouring its declaration is not fail-open, and an actor able to corrupt the restrictive twin could equally rewrite it permissive.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for 061c206197c62fd005a18a5f585fb1b717ef6105.

With one twin unreadable the gate answers exactly as agent_spec_path and spec_by_declared_name do -- the readable declaring twin is the spec kiro-cli resolves as live -- so honouring its declaration is not fail-open, and an actor able to corrupt the restrictive twin could equally rewrite it permissive.

This decision applies only to this commit. A new push requires a new judgment.

@bolichen97

Copy link
Copy Markdown
Contributor Author

@buluoray one more thing on the record for your re-review, since it touches a decision from your round.

GPT raised a finding on 061c206197 at _scan_parent_spawn_allowlists (subagent.py:676): when two specs declare the parent's name and the restrictive twin is the one the hardened reader refuses, unreadable is never consulted (it is checked only inside if not declared), so the readable permissive twin's declaration stands. Its remedy is to return UNKNOWN whenever any spec in the directory is unreadable -- the wider refusal your round narrowed, and it flips test_a_declaring_spec_under_another_filename_wins_over_a_broken_candidate (span=88a3825dcf3c), which pins "a readable declaring spec beats a broken candidate".

We kept your shape and overrode the finding instead (override on gpt, pinned to 061c206197). The ground for the override: with one twin unreadable, the gate answers exactly as agent.agent_spec_path and agent_discovery.spec_by_declared_name do -- both skip a file the reader refuses and resolve the readable declaring twin as the live spec -- so honouring that twin's declaration honours the spec kiro-cli would load rather than failing open, and an actor able to corrupt the restrictive twin could equally rewrite it permissive. For accuracy: the resolvers raise AmbiguousAgentSpecError only when two readable specs declare the name, so that refusal does not reach this scenario and the override does not rely on it. The residual case is a twin kiro-cli parses but the hardened reader refuses (oversized, symlink), where the restrictive twin is not demonstrably the live one either.

If you want the wider refusal after all, it is your change and we implement it immediately -- say so and I will flip that test and the fail-closed branch. Nothing here touches your CHANGES_REQUESTED; that is still yours to clear.

@bolichen97

Copy link
Copy Markdown
Contributor Author

/ai-review override fable 061c206: The same site was downgraded as a disproportionate remedy in the GPT lane's own adjudication, and both proposed remedies are the queue_params staleness fail-open this PR deliberately removed and an off-loop dispatch redesign outside its scope -- the memo-pinned read is a scandir in the ordinary case, with the large-directory cost tracked in #14335.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 marked the fable AI finding as false positive, not applicable, or explicitly accepted for 061c206197c62fd005a18a5f585fb1b717ef6105.

The same site was downgraded as a disproportionate remedy in the GPT lane's own adjudication, and both proposed remedies are the queue_params staleness fail-open this PR deliberately removed and an off-loop dispatch redesign outside its scope -- the memo-pinned read is a scandir in the ordinary case, with the large-directory cost tracked in #14335.

This decision applies only to this commit. A new push requires a new judgment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants