Repository navigation
fix(kas): gate auto-approved calls and subagent tools on spec hooks - #14066
Conversation
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Hook gating rests on KAS resolving WatchThe whole item-1 guarantee is a behavioral property of an external engine. The projection adds an unscoped Suggestions
[DESIGN-REVIEWED] 06f70bd |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: a user-authored PreToolUse hook on KAS actually sees and can block every call it covers — chat, subagent, and task-runner alike — and unrunnable
[FIRST-PRINCIPLES-REVIEWED] 06f70bd |
Security Scope Review -- 🟡 CONCERNSWhich legitimate operations does Verdict basis: the reviewer's own judgement; no confirmed regression. Security scope review -- adjudicated candidates
No candidate flipped from allowed to refused. Scope-Verdict: CONCERNS TIGHTENING: The KAS agent projection now withholds auto-approval for every capability a PreToolUse hook's matcher covers -- "the KAS projection adds an ADJUDICATED: 12 candidates, 0 confirmed newly-refused No confirmed rows were handed back at review time. The candidates probe the touched area's daily operations (the standalone PLATFORM COVERAGE: Candidates were written in all three spellings: UNADJUDICATED: The entire tightening lives outside the tool-call deny composite the classifier adjudicates. The guard is the KAS permission projection plus the script-hook permission gate; the call path an input takes: agent spec
The honest verdict over a guard nothing could classify is CONCERNS, not PASS. [SCOPE-REVIEWED] 06f70bd |
9cce2df to
29ac79f
Compare
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsAdvisory only — nothing blocks: with a wildcard FINDING — src/kiro_crew/dashboard/chat_runner.py:16217 — one enabled PreToolUse hook with an empty or [OPUS-REVIEWED] 06f70bd Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
29ac79f to
ade06a4
Compare
eb502df to
beeb6e8
Compare
ae93af1 to
a842f6a
Compare
a842f6a to
e8ffafe
Compare
e8ffafe to
2ef1acc
Compare
2ef1acc to
68e9db8
Compare
68e9db8 to
fe42ba8
Compare
|
/ai-review override scope 0835d26: prior attempt's CONCERNS verdict (0 newly refused, no confirmed regression; run 36305445798 attempt 1) failed only to publish on the App rate limit; the rerun classified clean |
Human judgment recorded@iamwhatever marked the scope AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Maintainer sweep (2026-09-27, on behalf of @bolichen97): not merging yet, although every gate is green on 0835d26. The intent -- make a user's own PreToolUse hooks actually run for auto-approved and subagent calls -- is right, and the extra prompts for hook authors are the point, not a regression. What holds it is the GPT finding on this head: standalone |
|
/ai-review override scope 9090055: Fable produced zero candidate rows on three consecutive runs (two heads + a full rerun); the validator fails closed on an empty corpus by design, and this diff changes spec-hook gating on KAS sessions, not the shell denylist, so there is no newly refused operation to measure. |
Human judgment recorded@iamwhatever marked the scope AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
Three gaps left after agent spec hooks started running from Crew on KAS (refs #13926, items 1, 2 and 5): - A PreToolUse hook runs on Crew's permission path, which an auto-approved KAS call never takes. The KAS projection now adds an `ask` rule for each auto-approvable capability a PreToolUse hook's matcher covers (the spec's own hooks and Hooks-page hooks), and records each one in the security event log. KAS resolves the most restrictive match, so `ask` outranks every `allow` on that capability and the call comes back as a permission request (confirmed in a live KAS session). A live session keeps the batch it registered, so the runtime records what that batch auto-approves on the session handle. Before a turn claims the session it is reset when a PreToolUse hook now covers one of those capabilities, and because that reset is declined for a session another turn holds, the decision is made again on the claimed session under its lease: a stale one is reset and re-claimed, and one still stale after two resets refuses the turn (both confirmed live). `LLMProvider` declares `kas_auto_approved_capabilities`. - A `confirm: true` spec hook is skipped because Crew cannot ask for the confirmation. A new KAS session now gets one notice naming how many were skipped. - On KAS, subagent and task-runner turns gate each permission request on their PreToolUse hooks (`hooks.permission_pre_tool_block`: the Hooks page's and their own agent's spec hooks together, matched on the event's canonical tool name before its title; exit 2 or no verdict refuses the call; an unreadable spec refuses every call), and skip the informational tool-call fire, which KAS sends before the permission request. Keyed on the turn's own provider's `crew_fires_spec_hooks`, so a kiro-cli subagent under a KAS parent is not gated and gets no spec hooks, and nothing fires twice. A subagent also passes the spec hooks to PostToolUse.
Problem / Motivation
Goal: On KAS, an agent's PreToolUse hooks see and can block every tool call they cover, on chat, subagent and task-runner turns alike, and
confirm: truehooks that cannot run say so.Three gaps from #13926 (items 1, 2 and 5):
permissionsauto-approves never reaches Crew's permission path, so neither a spec hook nor a Hooks-page PreToolUse hook sees it.confirm: trueis skipped silently.Why it matters
A PreToolUse deny hook is a user-authored gate. On KAS it was silently bypassed for every auto-approved call and for every subagent or task-runner turn, so a user who wrote a hook to block a tool got no block and no warning.
Not a goal
confirm: truehooks: Crew cannot ask for the confirmation, so they stay skipped and get a notice.What changed (motivation → approach → change)
Item 1: an auto-approved KAS call now meets a PreToolUse hook. A PreToolUse hook runs on Crew's permission path. A KAS call that the projected
permissionsauto-approves never takes that path, so neither a spec hook nor a Hooks-page hook saw it. The KAS projection now adds an unscopedaskrule for each auto-approvable capability that a PreToolUse hook's matcher covers (kas_permissions.withhold_hook_gated_auto_approval). KAS resolves the most restrictive matching rule (deny over ask over allow), so oneaskoutranks everyallowon that capability: the ones derived fromallowedToolsand any the author's ownpermissionsblock relayed. The call comes back as a permission request, the hook runs, and Crew's own approval decides as for any other request. Adenystill wins.kas_agents.pre_tool_hook_matcherslists the spec's own PreToolUse hooks and the Hooks-page store's, read when the session's agent batch is built.set_modeactivates, it re-sends nothing), so the runtime records what that batch auto-approves on the session handle (kas_auto_approved, fromkas_agents.projected_auto_approved, on bothsession/newandsession/load). Before a chat turn, a kept subagent claim or a task step claims the session,spec_hooks.invalidate_stale_kas_sessioncompares it with what the PreToolUse hooks cover now; on an overlap it resets the session (skip_if_busy), and the claim registers a fresh batch. An unreadable spec also resets. That pre-claim reset is declined for a session another turn holds (it answersbusy, notfresh), and the claim may have waited for exactly that turn, sospec_hooks.reproject_claimed_sessiondecides again on the session the claim holds, under its lease and before any tool runs: a stale one is reset and re-claimed, and one still stale after two resets refuses the turn (StaleProjectionError, lease handed back).LLMProviderdeclareskas_auto_approved_capabilitieswithNonemeaning "no batch registered". The re-claim adopts its new permit (sessions.adopt_turn), so a task step'sreleaseafter a reset unlocks the session it now holds.kas_projected_agent, declared onLLMProvideras""), andspec_hooks.session_agentreads it only when the turn names no agent (an agent the turn names, including one an in-turn switch moved to, always wins); a KAS mode switch (current_mode_update) moves the recorded agent too. With no agent known at all, a KAS turn fails closed (every permission request refused)._tool_matches: an empty matcher or*covers everything; a literal Crew tool name covers its capability (or nothing forexecute_bash/fs_*, which are never auto-approved here); a literal MCP tool name (@server/tool,mcp__server__tool) covers MCP; any other literal covers everything, since it may be a harness's own name for a built-in; a glob covers the built-ins it matches plus MCP. If the hooks cannot be listed, every auto-approval is withheld.KAS_TOOL_IDS_BY_KIRO_TOOLtable; there is no second kiro-cli -> KAS table here.allowfrom the author's block; anaskcovers both.auto_approve_toolscovers it, the user sees a prompt. Each withheld capability is written to the security event log through the projection's own permission audit (mcp_auto_approve_withheld). That is the price of the hook seeing the call, and the same trade the shell and filesystem families already make on KAS.Item 2:
confirm: truespec hooks get a notice. They are still skipped, since Crew cannot ask for the confirmation. A new KAS session now gets one notice row through the same channel as thetoolsSettings/slashCommandnotice: "Agent X has 2 hooks ask to be confirmed before running. This backend cannot ask, so they do not run in this session." The count comes from the cached conversion, so it costs no extra read and no extra audit.Item 5: subagent and task-runner turns gate on their PreToolUse hooks.
spec_hooks.turn_spec_hooks(provider, agent)answers for a turn outside the chat loop, keyed on that turn's OWN agent and provider. On KAS, each permission request runshooks.permission_pre_tool_block: the Hooks page's PreToolUse hooks and the agent spec's together, as the chat loop runs them, matched on every name the call is known by: its title (what the chat loop matches), its canonicaltool_name, and for an MCP call the@server/toolandmcp__server__toolforms built from the trustedmcp_server_name(ScriptHookStore.fire(tool_match_names=...)). Exit 2 or no verdict refuses the call, and an unreadable spec refuses every call. Such a turn skips the informational tool-call fire: KAS sends a call's tool-call frame before its permission request (seen in the live probe), and item 1 sends every call a PreToolUse hook covers to the gate, so firing on both would run each hook twice. A Hooks-page hook added mid-session reaches these turns through the re-projection above. Item 1 makes every call such a hook covers arrive as a permission request, so the gate sees it. A subagent also passes the spec hooks to PostToolUse. A process that registers no hook store (the standalonekirocrew runtask runner) reads the saved Hooks-page hooks from disk (hooks.persisted_hook_store), for the projection and for the gate, so a saved deny hook still gates a standalone KAS task. That read is strict, runs in a worker thread when the gate calls it, and reads the file once under the writers'hooks.json.lock, validating and loading that one snapshot: ahooks.jsonthat cannot be read or parsed, or holds an entry the store could not load, raises, and both consumers fail closed (the gate refuses the call, the projection withholds every auto-approval). An agent switch is a projection change too: KAS'sset_modeactivates an entry of the batch the session already registered, so the handle re-reads what the switched-to agent auto-approves (kas_agents.switched_auto_approved; a mode the batch does not carry counts as approving everything), and if that agent's hooks cover any of it the turn is cancelled and refused (spec_hooks.refuse_stale_switch), since those calls would never reach the permission request; the next claim finds the session stale and re-projects it for the new agent. A switch to a KAS built-in mode with no spec on disk (vibe) carries no spec hooks (kas_agents.agent_spec_absent), so only the Hooks page's hooks decide; a spec that exists but cannot be read still fails closed. On chat the refusal runs before the switch is recorded, so a refused switch never leaves the slot on the switched-to agent. A subagent's session on its parent's shared runtime is created per run, sospec_hooks.replace_stale_shared_sessionchecks it right after creation and replaces a stale one (refusing the run if it stays stale); the dedicated-process fallback goes through the same claim-time re-check as the dedicated arm. A kiro-cli subagent under a KAS parent is not gated here and its spec is not read.KAS writes its own tool id only in the permission request's
_meta.kiro.toolId(titleFetch URL, idweb_fetch, empty canonicaltool_name). Rebased on #14065, the subagent and task gate reads it (harness_tool_idthroughspec_hook_tool_names, one table): a spec hook matches that id's names and the trusted identity, never the title, and a Hooks-page hook matches the title and those names both. The chat turn loop builds the same names through the one helper (hooks.pre_tool_match_names), so an@server/toolormcp__server__toolhook meets a KAS MCP call there too, and on a backend where Crew fires the spec's hooks the chat's informational tool-call fire is skipped, as on the subagent loop: the permission request is where the hooks run, so each runs once.hook_gated_capabilitiesreads the sameKAS_TOOL_IDS_BY_KIRO_TOOL/KIRO_TOOL_ALIASES, soremote_web_searchcoversweb_searchandrun_commandcovers nothing auto-approved.Docs:
agent-spec-fields.md(hooksrow) andagent-host-contract.mdstate the new behaviour.Backwards compatibility
Compatible: nothing main accepts is rejected, renamed or removed. On KAS, a call a PreToolUse hook covers now reaches Crew's approval instead of being silently auto-approved; kiro-cli sessions are untouched (the projection bookkeeping is recorded by the KAS harness's
record_session_projectionseam; the base harness's default records nothing, so the shared runtime has no KAS branch).Tests
test/test_kas_spec_hook_gaps.py(124 tests): matcher coverage cases, including a glob that matches no name the table spells (Fetch*) covering everything;askadded and input untouched; no hook or no policy changes nothing; the projection and the built batch withhold what a spec hook covers; Hooks-page listing skips disabled, command-less and PostToolUse hooks; listing failure withholds everything; confirm notice once per new KAS session, singular copy, none on kiro-cli or without confirm hooks;turn_spec_hookson kiro-cli returns nothing and reads no spec; on KAS returns the agent's own hooks and cwd, or flags an unreadable spec; the gate runs stored and spec hooks, blocks on exit 2, 1 and -1, matches the canonical tool name over the title, a KASweb_fetchrequest titled "Fetch URL" with_meta.kiro.toolId=web_fetchmeets aweb_fetchdeny hook (spec and Hooks page) and is rejected, and blocks with no store only when spec hooks were loaded; a KAS subagent denies on its permission request (reject, no approve) with no second PreToolUse fire, and passes the spec hooks to PostToolUse; a Hooks-page deny alone also denies; an unreadable spec denies; a kiro-cli subagent is not gated and gets no spec hooks; the same for a KAS and a kiro-cli task step; with no hook store registered (standalonekirocrew run) the saved Hooks-page hooks are read from disk and still withhold auto-approval and deny at the gate, and a corrupthooks.json(unparseable, wrong root, non-list hooks, unloadable entry) makes the gate refuse and the projection withhold everything; a KAS subagent or task step switched to another agent mid-run is gated by that agent's hooks, and so is a task step retried on a session an earlier attempt switched (the loop carries the switched-to agent across attempts andspec_hooks.running_agentprefers what the session records; a step that switches A to B, fails, and retries meets B's deny hook); a switch re-reads what the session auto-approves (the switched-to agent's registered entry, or everything for a mode the batch does not carry), and a switch to an agent whose deny hook covers an auto-approved capability stops the turn (chat, subagent, task) so the next claim resets the session and the rebuilt batch asks for the call, which the hook then denies. Re-projection: what a projected policy auto-approves (allow, unscoped/scoped ask, meta, deny), the active agent's entry, the provider read-through, stale on a new Hooks-page or spec hook only for an auto-approved capability, not stale off KAS or without a batch, stale on an unreadable spec, a hook added mid-session resets the session and the rebuilt batch asks for it, a chat turn checks before it claims and again under the lease before its tools run, a turn refused as stale hands its lease back,busyis told apart fromfresh, a turn that waited behind a busy stale session re-projects before running, and one that stays stale is refused. Mutation sweeps (fire again on the tool call in either loop, match on the title, pass with no store, drop the audit, drop the chat check, never stale, ignore an ask, no read-through, drop the claim-time re-check in chat or in the helper, drop the final refusal, answerfreshfor busy, drop the lease hand-back, drop the base declaration, drop the unknown-glob widening, dropharness_tool_idat the subagent gate, drop the id's names for a Hooks-page hook or a spec hook, drop the table lookup in coverage, fire the chat's informational hook on KAS, drop the chat's MCP identity, keep the old projection on a switch, treat an unknown mode as approving nothing, skip the stale-switch check in chat, subagent or task loop, drop the saved-hooks fallback in the gate or the projection, make the saved-hooks read fail-soft again, drop the KAS harness's projection record on create or load, record a projection in the base harness, gate a retried task step with its original agent, read the saved hooks without the lock or twice, read them on the event loop) are caught each time.test_acp_runtime.pyfails 53 tests on unmodifiedorigin/mainon this host (reader loop "attached to a different loop"), and 52 on this branch; it is not a signal here.test_crew_fired_spec_hooks.py,test_acp_session_provider.py,test_kas_session_teardown.py,test_kas_permissions.py,test_kas_agents.py,test_fire_tool_hooks.py,test_acp_harness_contract.py,test_harness_parity.py,test_subagent.py,test_subagent_component_globals.py,test_script_hooks.py, the taskrunner suites, and the doc suites that read both docs. All pass.origin/mainbe067a3503locally:test_spawn_approval_channel_delivery_2381.py::...test_it_registers_no_wait_so_the_window_is_never_spentandtest_sandbox_protected_name_holds.py::...test_leaf_only_count_has_not_grown.Manual verification
Live KAS probes on this host, below.
Live KAS probe
kiro-cli 2.24.1,
acp --agent-engine v3, Crew's own projection (build_kas_custom_agentson this branch), prompt "fetch https://example.com with your web fetch tool". Both agents setallowedTools: ["web_fetch"].permissionsweb_fetch: allowweb_fetchweb_fetch: allow,web_fetch: asktoolId=web_fetch, titleFetch URL)So
askoutranksallowon the live engine, and the session starts with both rules.Hook added mid-session (same host,
live_probe_reproject.py): one KAS process, agent withallowedTools: ["web_fetch"]and no hook.web_fetchaddedhook_projection_stale= True_kiro/session/delete), claim re-projectsweb_fetch: allow+web_fetch: ask; stale = FalsetoolId=web_fetch), hook ran onceBusy-session race (
live_probe_busy_race.py, realreproject_claimed_sessionover one KAS process):busy(reset declined)A second probe (
probe_variants.py) shows which KAS operations take a new batch: a NEW session on the same process does (1 request), andsession/loadon a NEW process does (1 request);session/loadof a session the same process still holds does not, which is why the fix ends the session instead of re-loading it in place. The probe fired Crew's spec-hook path matching on_meta.kiro.toolId, the input #14065 matches on; the title (Fetch URL) alone does not matchweb_fetch, which is the item-3 gap #14065 closes.Related Issues
Refs #13926 (items 1, 2 and 5). Builds on #14065.
Pattern harvest
Rule candidate: review-prompt
Pattern: a hook or gate that runs on a permission request is blind to whatever the backend auto-approves; when adding a gate there, also take away the auto-approval for what it covers, and wire every fire site (chat, subagent, task runner) at the permission request, not only at the informational tool-call event.
Checklist