Repository navigation
feat(acp): answer the KAS hooks list and sessionStart requests, read-only - #13174
Conversation
|
Intent: Let a hook a user authored in Kiro Crew reach a KAS session, by answering the two READ-ONLY requests of the backend's ACP hooks channel from Kiro Crew's own hook store, and by recording which hook ids were listed per session so a later execute path can refuse an id Kiro Crew never minted. |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the announce pin does hold: adding Suggestions
[DESIGN-REVIEWED] 3a54bc7 |
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) — ✅ human override accepted@iamwhatever overrode this lane for |
9e17423 to
0ed2032
Compare
|
span=4a899333ab3d
|
|
span=6e679bbb337c
|
|
span=fd70011655e2
|
|
span=471f97086f32
|
|
span=5a1e12452b98
|
|
Opus 5 lane: findings recovered from the job log, and answered The lane failed on its own summary step (
On candidate 8: the session id is the backend's, and Crew cannot mint it — the same id is what routes every On candidate 2 specifically: the gate is consulted with an empty session key, because an Re-running the whole lane so a fresh verdict lands on this head. |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
0ed2032 to
a66474d
Compare
|
span=19934bb5ba3d
|
|
span=a66be8a8e997
|
|
span=7549aeb9d2a0
|
|
span=9f6ed7c59b5d
|
|
span=7c4263542252
|
|
span=e735a3326aeb
|
a66474d to
ddb5916
Compare
|
Round 4: two reds on
Restored the block rather than pruning the baseline entry. The file's own formatting is not this PR's business, and keeping it out means the diff carries no unrelated reformat. Head
The earlier |
|
/ai-review override first-principles ddb5916: Scope and ordering override, recorded by the maintainer who set the scope — not a security override. This PR is the read-only half of a deliberate split (3a–3c ship together; the handshake flag waits for 3d, the gated execute path). The ordering is the safety argument, and it comes from this PR's own investigation: the moment a client announces Answering spans 7c4263542252 and e735a3326aeb. Posted on the maintainer's explicit instruction, quoted: "keep the read-only half merging on its own … post the first-principles override yourself, with exactly that justification and a pointer that the flag flips in the 3d PR; it is a scope/ordering override, not a security override, and the scope was set by the maintainer." |
|
span=3aca38367e44
|
|
/ai-review override first-principles 5a6627e: Scope and ordering override, recorded by the maintainer who set the scope — not a security override. This PR is the read-only half of a deliberate split (3a–3c ship together; the handshake flag waits for 3d, the gated execute path). The ordering is the safety argument, and it comes from this PR's own investigation: the moment a client announces Answering spans 19516e1c5439 and 3aca38367e44. Posted on the maintainer's explicit instruction, quoted: "keep the read-only half merging on its own … post the first-principles override yourself, with exactly that justification and a pointer that the flag flips in the 3d PR; it is a scope/ordering override, not a security override, and the scope was set by the maintainer." |
|
AI-review override not recorded: keep the reason to 500 characters or fewer. |
5a6627e to
8048ee4
Compare
|
/ai-review override first-principles 8048ee4: Scope/ordering override from the maintainer who set the scope, not a security override. This is the read-only half of a deliberate split. Announcing |
Human judgment recorded@iamwhatever marked the first-principles 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. |
…only
The second ACP backend can delegate hook extraction to its client: it asks
`_kiro/hooks/list` for the hooks matching a trigger and `_kiro/hooks/sessionStart`
for results computed before the turn. Kiro Crew had no answer for either, so a
hook a user authored in the Hooks UI could not reach a KAS session at all.
`kas_wire` now answers both from Kiro Crew's own hook store, and the session
dispatch routes the two methods to it:
- the seven trigger spellings this channel uses (`preToolUse`, `postToolUse`,
`promptSubmit`, `agentStop`, `preTaskExecution`, `postTaskExecution`,
`sessionStart`) rather than the agent-profile aliases, which are a different
spelling of three of the same events;
- a `NormalizedHook` interface the reader consumes, so selection, projection and
the id record are independent of how a hook was written;
- selection by trigger, with a matcher this request cannot evaluate WITHHOLDING
the hook: on a tool trigger a named tool decides it through Kiro Crew's own
tool matcher, and on any other trigger a context matcher has no subject here;
- disabled hooks excluded unless the request asks for them, never recorded even
then, and `enabled` read as the literal boolean because the store persists that
field uncoerced;
- named bounds on the three strings a hook puts on the wire — its command, its name
and its id — with an oversized hook withheld rather than truncated, because a
truncated command is a different command;
The route is gated on `ACP_BACKENDS_HOOKS_LIST`, a new capability set holding
only the KAS id: the dispatch loop it lives in is shared by every backend the
runtime demuxes, and the answers carry operator-authored hook commands, so a
backend that never defined the channel is answered `-32601` like any other method
it does not serve. The gate is a named predicate, `_is_kas_hooks_request`, so a
test drives it per backend and fails if the membership clause is removed —
asserting the set's own contents cannot catch a deleted check.
The ids are Kiro Crew's own, and an execute path may only run one this surface
listed for the session that asks — but the RECORD that answers it is not kept here.
Nothing in this build reads it, and the change that adds execution is the one that
can key it by the owning Kiro Crew session, which an `AcpSessionHandle` does not
hold. The obligation is recorded in `agent-host-contract.md` beside the governance
one rather than half-built here.
Neither answer consults the `capabilities.script_hooks` governance gate, and the
placement is deliberate rather than an omission. That gate decides whether a hook
may RUN and it is keyed by the owning Kiro Crew session; an `AcpSessionHandle`
holds no such key, so asked from a list answer it resolves the policy ceiling
alone and never the surface-bound profile that denies the capability — a gate
keyed wrongly claims a protection it does not provide. The spawn is already gated
where the key exists: `run_script_hook` consults it before starting the process.
An execute path added over this surface owes the same check on a REAL owning key,
threaded from `AcpRuntime.create_session(session_key=…)`. Both answers therefore
read one in-memory dict and stay on the dispatch loop.
Read-only on purpose. `_kiro/hooks/executeHook` is the method that spawns a
command and nothing here implements it: an inbound request naming it stays an
unknown server request answered `-32601`. The handshake does not announce
`hooks: {enabled: true}` either, so the backend does not learn the surface
exists and keeps its current behaviour; a test fails if that flag is flipped
without the execute path. Zero commands run from this change.
`sessionStart` answers with an empty buffer for every trigger, which is the true
answer rather than a stub: a precomputed result is a hook's output, every hook
this surface can serve carries a command, and no command runs. Serving it rather
than leaving it refused keeps two facts apart — "implemented and nothing
buffered" is not "not implemented" — on the day the capability is announced.
The records that own the claims follow: the KAS parity list scopes its deferral to
hook EXECUTION and states where the governance gate lives, the inbound-request
inventory names both read-only methods, and the new capability set carries its
disposition row, its off-card classification and its Stage 2 onboarding row.
8048ee4 to
3a54bc7
Compare
|
/ai-review override first-principles 3a54bc7: Scope/ordering override from the maintainer who set the scope, not a security override. This is the read-only half of a deliberate split. Announcing |
Human judgment recorded@iamwhatever marked the first-principles 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. |
|
span=22da22f1c24b
|
|
Ready for review. Head |
buluoray
left a comment
There was a problem hiding this comment.
Approve. The "read-only" claim holds on 3a54bc7b:
_KAS_HOOKS_METHODS(acp/session_handle.py:178) routes onlyhooks/listandhooks/sessionStart, KAS-backend only;executeHookstill answers-32601.- The list answer is
store.list_all()(an in-memory copy); sessionStart always returns{"results": []}. The only side effect issend_response. test/test_kas_hooks_acp.py: 90 passed.
Non-blocking: the listed hooks come from the global store with no per-session scoping, and the route is only wired into the multiplexed in-turn loop. Both matter once the capability is announced and executeHook lands.
…only (kirodotdev#13174) The second ACP backend can delegate hook extraction to its client: it asks `_kiro/hooks/list` for the hooks matching a trigger and `_kiro/hooks/sessionStart` for results computed before the turn. Kiro Crew had no answer for either, so a hook a user authored in the Hooks UI could not reach a KAS session at all. `kas_wire` now answers both from Kiro Crew's own hook store, and the session dispatch routes the two methods to it: - the seven trigger spellings this channel uses (`preToolUse`, `postToolUse`, `promptSubmit`, `agentStop`, `preTaskExecution`, `postTaskExecution`, `sessionStart`) rather than the agent-profile aliases, which are a different spelling of three of the same events; - a `NormalizedHook` interface the reader consumes, so selection, projection and the id record are independent of how a hook was written; - selection by trigger, with a matcher this request cannot evaluate WITHHOLDING the hook: on a tool trigger a named tool decides it through Kiro Crew's own tool matcher, and on any other trigger a context matcher has no subject here; - disabled hooks excluded unless the request asks for them, never recorded even then, and `enabled` read as the literal boolean because the store persists that field uncoerced; - named bounds on the three strings a hook puts on the wire — its command, its name and its id — with an oversized hook withheld rather than truncated, because a truncated command is a different command; The route is gated on `ACP_BACKENDS_HOOKS_LIST`, a new capability set holding only the KAS id: the dispatch loop it lives in is shared by every backend the runtime demuxes, and the answers carry operator-authored hook commands, so a backend that never defined the channel is answered `-32601` like any other method it does not serve. The gate is a named predicate, `_is_kas_hooks_request`, so a test drives it per backend and fails if the membership clause is removed — asserting the set's own contents cannot catch a deleted check. The ids are Kiro Crew's own, and an execute path may only run one this surface listed for the session that asks — but the RECORD that answers it is not kept here. Nothing in this build reads it, and the change that adds execution is the one that can key it by the owning Kiro Crew session, which an `AcpSessionHandle` does not hold. The obligation is recorded in `agent-host-contract.md` beside the governance one rather than half-built here. Neither answer consults the `capabilities.script_hooks` governance gate, and the placement is deliberate rather than an omission. That gate decides whether a hook may RUN and it is keyed by the owning Kiro Crew session; an `AcpSessionHandle` holds no such key, so asked from a list answer it resolves the policy ceiling alone and never the surface-bound profile that denies the capability — a gate keyed wrongly claims a protection it does not provide. The spawn is already gated where the key exists: `run_script_hook` consults it before starting the process. An execute path added over this surface owes the same check on a REAL owning key, threaded from `AcpRuntime.create_session(session_key=…)`. Both answers therefore read one in-memory dict and stay on the dispatch loop. Read-only on purpose. `_kiro/hooks/executeHook` is the method that spawns a command and nothing here implements it: an inbound request naming it stays an unknown server request answered `-32601`. The handshake does not announce `hooks: {enabled: true}` either, so the backend does not learn the surface exists and keeps its current behaviour; a test fails if that flag is flipped without the execute path. Zero commands run from this change. `sessionStart` answers with an empty buffer for every trigger, which is the true answer rather than a stub: a precomputed result is a hook's output, every hook this surface can serve carries a command, and no command runs. Serving it rather than leaving it refused keeps two facts apart — "implemented and nothing buffered" is not "not implemented" — on the day the capability is announced. The records that own the claims follow: the KAS parity list scopes its deferral to hook EXECUTION and states where the governance gate lives, the inbound-request inventory names both read-only methods, and the new capability set carries its disposition row, its off-card classification and its Stage 2 onboarding row. Co-authored-by: Joe Guo <zejiangg@amazon.com>
Problem / Motivation
A hook a user writes in the Hooks UI cannot reach a KAS session. The projected agent has no
hooksslot on that wire, so the hook is simply not there.There is a channel for it. The backend can ask its ACP client for hooks instead of loading its own:
_kiro/hooks/listfor the hooks matching a trigger,_kiro/hooks/sessionStartfor results computed before the turn. Kiro Crew answered neither, so the channel was unusable.Why it matters
The channel is the only one of four where Kiro Crew spawns the hook's command. Every other route ends with the backend spawning a shell command Kiro Crew never saw, which is exactly what the existing refusals to relay
autoApproveand to translate shell tools exist to prevent. A hook's payload is an arbitrary shell command, so it is the worst thing to hand to a process outside the deny floor.This change is the read-only half: the answers exist, nothing runs.
What changed (motivation → approach → change)
src/kiro_crew/acp/kas_wire.pycan now build both read-only answers from Kiro Crew's own hook store. Nothing reaches the backend yet, on purpose._kiro/hooks/list-32601_kiro/hooks/sessionStart-32601_kiro/hooks/executeHook-32601-32601hooks: {enabled: true}-32601-32601🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged
The trigger names are this channel's seven —
preToolUse,postToolUse,promptSubmit,agentStop,preTaskExecution,postTaskExecution,sessionStart— not the profile aliases, which spell three of themuserPromptSubmit,stopandagentSpawn. Crew events map onto five; either task trigger is answered empty, because no Crew hook can carry it.The reader consumes a
NormalizedHook, so another source would be one adapter.A matcher this request cannot evaluate withholds the hook. On a tool trigger a named tool decides it through Kiro Crew's own matcher; without one, answering would let the hook run for a tool its author excluded. On any other trigger it is a context matcher with no subject here. A matcherless hook is unrestricted and always answered.
A disabled hook is withheld unless asked for, and never recorded even then:
includeDisabledis the tree view's request, and display data.enabledmust be the literal boolean, because the store persists it uncoerced —"enabled": "false"is a string, and truthiness reads "off" as "on". A hook past its named command, name or id bound is withheld, not truncated: a truncated command is a different command.The route is gated on
ACP_BACKENDS_HOOKS_LIST, holding only the KAS id: that loop is shared by every backend the runtime demuxes. The gate is a named predicate, so a test drives it per backend and fails if the clause is deleted.Neither answer consults the
capabilities.script_hooksgate, deliberately. That gate decides whether a hook may run, keyed by the owning Kiro Crew session; anAcpSessionHandleholds no such key, so asked here it resolves the policy ceiling and never the surface profile that denies the capability — a gate keyed wrongly claims a protection it lacks. The spawn is gated where the key exists, inrun_script_hook. So both answers read one in-memory dict and stay on the loop.The ids are Kiro Crew's own, and an execute path may only run one this surface listed for the session that asks — but the record that answers it is not kept here. Nothing in this build reads it, and the change that adds execution is the one that can key it by the owning Kiro Crew session, which an
AcpSessionHandledoes not hold. The obligation is written into the spec instead of half-built here.sessionStartanswers an empty buffer for every trigger — the true answer, not a stub: a precomputed result is a hook's output, every hook here carries a command, and no command runs. Serving it keeps "implemented, nothing buffered" apart from "not implemented" for announce day.What a user sees when this merges: nothing. The capability is not announced, so the backend keeps loading its own hooks and never asks. The flag flips in the execute-path change, which is the one that adds a way to run anything.
Stacking
Nothing here is imported from another branch: the single commit's parent is
origin/mainat5c23469f7e, and the diff is two files.normalize_script_hookis not the spec-shape normalizer. Its input is one entry of Kiro Crew's hook store and its output is the wire hook this channel sends; the spec-shape normalizer converts an agent spec's object-of-arrays to and from hook documents, which is a different input and a different output. The two do not overlap, and this PR does not read an agent spec at all.Records kept in step with the code
docs/system-specs/modules/agent-host-contract.mddocs/system-specs/modules/acp-client.mdsrc/kiro_crew/agent_sdk/backends.pyACP_BACKENDS_HOOKS_LISTand its disposition rowsrc/kiro_crew/acp_backends.py,src/kiro_crew/acp/types.pysrc/kiro_crew/agent_sdk/backend_cards.pydocs/system-specs/modules/harness-onboarding.mdInvestigation — which provider the backend uses when a client announces hooks
Asked and answered before the flag is flipped: when a client announces hooks, does the backend stop loading its own disk hooks, or do both providers run?
They are mutually exclusive, chosen at handshake, and the sub-flag decides which.
KiroAgent.initializereads the client meta frominitialize'sclientCapabilities._meta.kiroand branches:hooks.enabledwithhooks.v2 === true→ it builds aHooksModuleCacheand logsv2 hooks cache initialized (hooks load at session start). That cache is the disk path:createHooksModuleper workspace-root set,globalHookDirswired to<homeDir>/.kiro/hooksplus a cloud replica's hooks dir when one exists, and a file watcher that reloads on change (hooks-module-cache.ts:99-107,:124-174,:190-222). The ACP providers are NOT wired on this branch.hooks.enabledwithoutv2→ it wires the ACP providers and logsv1 ACP hook providers wired: the hooks provider whoseextractHookscalls_kiro/hooks/listand whoseextractPrecomputedResultscalls_kiro/hooks/sessionStart(acp-hooks-provider.ts:39-74), plus pre/post-tool-use providers that call_kiro/hooks/listwithtoolIdandtoolTags. NoHooksModuleCacheis constructed on this branch.Three further reads confirm the exclusivity rather than inferring it from the two branches:
KiroAgent.buildSessionHooksuses the v2 module onlyif (this.v2HooksCache && workspacePaths.length > 0), and otherwise returnsthis.v1SessionHooks ?? SessionHooks.disabled. One or the other, never both.KiroAgent.registerAgentProfileHooksreturns immediately when there is nov2HooksCache. So agent-profile hooks are inert on the ACP branch too — not only the.kiro/hooks/*.jsonfiles.KiroAgent.handleHooksList(the same method name in the opposite direction, agent answering a client) throws_kiro/hooks/list is not available when v2Hooks is disabled.So for the execute-path change the answer is: announcing
hooks: {enabled: true}withoutv2makes Kiro Crew the only hook provider for that session. The user's.kiro/hooks/*.jsonfiles and their agent-profile hooks stop being loaded — which is a real behaviour change for anyone who has them, and belongs in the decision to flip the flag rather than in this PR.Two notes for that work. The covenant's
KiroClientMetaHooksExtensiondeclares only{enabled: true};v2is a sub-flag the shipped agent branches on and the covenant type does not mention, so the shape to announce is the covenant's one. Andhooks.enabledalso gates the agent's infrastructure-safety monitor on the same branch, so flipping it turns on more than hooks.Evidence:
packages/kiro-agent/src/acp/acp-hooks-provider.tsandpackages/kiro-agent/src/hooks/hooks-module-cache.tsat the line numbers above; the fourKiroAgentmethods read out of the shipped bundle at~/.local/share/kiro-cli/kas/2.23.1-*/node_modules/@kiro/agent/dist/server/acp-server.js, which is the artifact the relay actually runs (grep -o 'v2 hooks cache initialized' / 'v1 ACP hook providers wired' / 'not available when v2Hooks is disabled'locates all three branch points). Source line numbers foragent.tsare not cited because that file is not in the published source set; the symbol names areKiroAgent.initialize,KiroAgent.buildSessionHooks,KiroAgent.registerAgentProfileHooks,KiroAgent.handleHooksList.Backwards compatibility
Compatible: nothing that works today stops working. The handshake is byte-identical, no method that was answered is answered differently, and the two new answer builders have no caller on the wire.
Tests
test/test_kas_hooks_acp.py, 80 cases, no server stood up — the store is driven against a tmp directory, and the route is driven through the answer method with a handle stub that records what its runtime was sent.toolIdthrough Kiro Crew's matcher; a matcher is not applied when no tool is named, and not applied as a tool filter off the two tool triggers;includeDisabled,includeDisabledhas to be the boolean, and a hook answered for a tree view is not recorded;enabledis only ever the literal boolean:"false","",0,1,Noneand"true"all read as off;toolTagsandworkspacePathsdo not narrow; no store answers empty;hooks, on the constant and on the harness — this test fails if someone flips the flag without the execute path;_kiro/hooks/executeHookclassifies as an unknown server request, the answer is-32601, and the product names no constant for the method;Manual verification
N/A — unit coverage sufficient: the route cannot be reached from a live session, because the capability that would make the backend call it is not announced.
Related Issues
no linked issue: this is one work item of a planned round of KAS support, tracked outside the issue tracker.