Skip to content

feat(acp): answer the KAS hooks list and sessionStart requests, read-only - #13174

Merged
iamwhatever merged 1 commit into
mainfrom
feat/acp-hooks-list-readonly
Sep 24, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
feat/acp-hooks-list-readonly

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A hook a user writes in the Hooks UI cannot reach a KAS session. The projected agent has no hooks slot 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/list for the hooks matching a trigger, _kiro/hooks/sessionStart for 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 autoApprove and 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.py can now build both read-only answers from Kiro Crew's own hook store. Nothing reaches the backend yet, on purpose.

request main this PR
_kiro/hooks/list 🟦 unknown request → -32601 🟩 Kiro Crew's hooks for that trigger
_kiro/hooks/sessionStart 🟦 unknown request → -32601 🟩 answered, buffer empty
_kiro/hooks/executeHook 🟦 unknown request → -32601 🟦 unknown request → -32601
the record of what was listed 🟦 none 🟦 none — it ships with the execute path
handshake hooks: {enabled: true} 🟦 not announced 🟦 not announced
what the backend asks for 🟦 nothing 🟦 nothing
a NON-KAS backend sending either 🟦 unknown request → -32601 🟦 unknown request → -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 them userPromptSubmit, stop and agentSpawn. 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: includeDisabled is the tree view's request, and display data. enabled must 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_hooks gate, deliberately. That gate decides whether a hook may run, keyed by the owning Kiro Crew session; an AcpSessionHandle holds 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, in run_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 AcpSessionHandle does not hold. The obligation is written into the spec instead of half-built here.

sessionStart answers 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/main at 5c23469f7e, and the diff is two files.

normalize_script_hook is 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

file what it now says
docs/system-specs/modules/agent-host-contract.md the KAS deferral is scoped to hook EXECUTION, with the three properties that hold the surface shut
docs/system-specs/modules/acp-client.md both read-only methods are in the inbound-request inventory
src/kiro_crew/agent_sdk/backends.py ACP_BACKENDS_HOOKS_LIST and its disposition row
src/kiro_crew/acp_backends.py, src/kiro_crew/acp/types.py re-export that set, never a copy
src/kiro_crew/agent_sdk/backend_cards.py classifies it off-card, with the reason
docs/system-specs/modules/harness-onboarding.md its Stage 2 row, which that table's own rule requires

Investigation — 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.initialize reads the client meta from initialize's clientCapabilities._meta.kiro and branches:

  • hooks.enabled with hooks.v2 === true → it builds a HooksModuleCache and logs v2 hooks cache initialized (hooks load at session start). That cache is the disk path: createHooksModule per workspace-root set, globalHookDirs wired to <homeDir>/.kiro/hooks plus 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.enabled without v2 → it wires the ACP providers and logs v1 ACP hook providers wired: the hooks provider whose extractHooks calls _kiro/hooks/list and whose extractPrecomputedResults calls _kiro/hooks/sessionStart (acp-hooks-provider.ts:39-74), plus pre/post-tool-use providers that call _kiro/hooks/list with toolId and toolTags. No HooksModuleCache is constructed on this branch.

Three further reads confirm the exclusivity rather than inferring it from the two branches:

  • KiroAgent.buildSessionHooks uses the v2 module only if (this.v2HooksCache && workspacePaths.length > 0), and otherwise returns this.v1SessionHooks ?? SessionHooks.disabled. One or the other, never both.
  • KiroAgent.registerAgentProfileHooks returns immediately when there is no v2HooksCache. So agent-profile hooks are inert on the ACP branch too — not only the .kiro/hooks/*.json files.
  • 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} without v2 makes Kiro Crew the only hook provider for that session. The user's .kiro/hooks/*.json files 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 KiroClientMetaHooksExtension declares only {enabled: true}; v2 is 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. And hooks.enabled also 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.ts and packages/kiro-agent/src/hooks/hooks-module-cache.ts at the line numbers above; the four KiroAgent methods 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 for agent.ts are not cited because that file is not in the published source set; the symbol names are KiroAgent.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.

  • the emitted trigger set is exactly the seven, each Crew event resolves to its spelling, a profile alias selects nothing, and a trigger outside the seven serves nothing;
  • a list answer is filtered by trigger and by toolId through 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;
  • disabled hooks are excluded by default and included with includeDisabled, includeDisabled has to be the boolean, and a hook answered for a tree view is not recorded;
  • a tool matcher is withheld when the request names no tool, a context matcher is withheld on a non-tool trigger, and a matcherless hook is answered in both places;
  • enabled is only ever the literal boolean: "false", "", 0, 1, None and "true" all read as off;
  • the route predicate answers per backend and per method, so removing the membership clause fails it (checked by reverting the clause and re-running);
  • an oversized command, name or id is withheld, while one exactly at the bound is served;
  • a matcher that cannot be READ withholds the hook, because an empty matcher means no restriction — while a name that cannot be read falls back to the id, which restricts nothing;
  • the two read-only methods are routed and answered, and a malformed params object is still answered;
  • host-supplied shapes degrade to absent rather than raising; toolTags and workspacePaths do not narrow; no store answers empty;
  • the handshake meta carries no hooks, on the constant and on the harness — this test fails if someone flips the flag without the execute path;
  • _kiro/hooks/executeHook classifies 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.

@iamwhatever
iamwhatever requested review from a team and CrysisDeu September 23, 2026 20:26
@iamwhatever

Copy link
Copy Markdown
Contributor Author

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.
Not a goal: _kiro/hooks/executeHook — no command runs from this change. Announcing hooks: {enabled: true} at the handshake, so the backend still never asks. Wiring the answers into the inbound dispatch. Serving agent-spec hooks as a second source.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the announce pin does hold: adding hooks: {enabled: true} to KAS_CLIENT_CAPABILITIES must fail test_kas_hooks_acp.py, since that pin alone keeps this surface shut.

Suggestions

  • When the flag flips, surface (not just log) that a context-matcher hook is withheld on this channel — a hook that works on kiro-cli and silently never fires on KAS is a parity gap the hook's author cannot see today.

[DESIGN-REVIEWED] 3a54bc7

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 3a54bc7b6760dc0a1a57b167bde5e0361bbefad5 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3a54bc7

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

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ human override accepted

@iamwhatever overrode this lane for 3a54bc7b6760dc0a1a57b167bde5e0361bbefad5 via /ai-review override (this commit only).

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@iamwhatever
iamwhatever force-pushed the feat/acp-hooks-list-readonly branch from 9e17423 to 0ed2032 Compare September 23, 2026 21:24
@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=4a899333ab3d
self-added: yes
mechanism: ListedHookStore.record skips a disabled hook even when the answer carried it

  • fixed: includeDisabled no longer puts a switched-off hook into the record

Correct as reported, and taken the first of the two exits you named rather than the second.
record() now skips any hook whose enabled is false, so the tree view's own request cannot
make an id the user turned off indistinguishable from one they left on. The answer still
RETURNS it, because display data is what that request is for.
Also narrowed the claim the docstring was making, since a fix to one direction does not earn
the wider sentence: a hit is now stated as a NECESSARY condition and never a sufficient one,
and the two things an execute path must still re-read from the live store — enabled and the
command — are named there.
Pinned by test_a_disabled_hook_listed_for_a_tree_view_is_not_recorded and
test_the_list_answer_still_returns_what_it_does_not_record.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=6e679bbb337c
self-added: yes
mechanism: the record's contract now states that the live store owns the command, not the record

  • fixed: the record no longer claims the command is authoritative

Agreed on the mechanism and disagreed on where it belongs. Confirming the hook still exists is
an execute-time read, and there is no execute path in this change to put it in, so the fix here
is the contract that makes the omission impossible to inherit silently.
ListedHookStore's docstring now says a hit is necessary and never sufficient, and names the
two reads it does not answer: enabled and the command, both of which belong to the live store
because a user can edit or switch off a hook between the two calls.
So the recorded command is the id's PROVENANCE, not the text to run. Stated in the class
docstring and in the body, which is what the execute path is written against.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=fd70011655e2
self-added: yes
mechanism: AcpSessionHandle routes both methods to the builders before classification

  • fixed: the two answers have a dispatch route, so the title is now true

Took your exit exactly: the route lands in this change. AcpSessionHandle tests
_KAS_HOOKS_METHODS before _classify, and answers through
_answer_kas_hooks_request with send_response.
Routed in the session loop only, deliberately. The shared classifier is also read by the
single-session client, which serves no hooks surface — naming an action there that only one loop
handles would leave the request UNANSWERED on the other path rather than refused.
_kiro/hooks/executeHook is absent from that set, so it still classifies as an unknown server
request and is answered -32601.
Pinned by test_only_the_read_only_methods_are_routed,
test_a_list_request_is_answered_with_crews_hooks and the sessionStart sibling.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=471f97086f32
self-added: yes
mechanism: forget is called from AcpRuntime.unregister_session; record is called by the list answer

  • fixed: the store's write and its teardown both have production callers

Partly your subtraction and partly a rebuttal, split by method rather than taken as one.
forget had no caller and now has the right one: AcpRuntime.unregister_session, so a departing
session takes its record with it and a reused session id starts with nothing executable instead
of inheriting the previous occupant's set. That is a correctness gain in THIS change, not a
promise about a later one.
record already had a production caller — the list answer is the only writer, which is what
makes "was this id minted for this session" answerable at all.
lookup is the store's only read, and deleting it would leave a write-only structure whose
effect no test could assert. Keeping a one-line accessor is smaller than keeping an unassertable
record.
Also bounded the record by the same literal that bounds one answer, since they describe the same
population.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=5a1e12452b98
self-added: yes
mechanism: _CREW_EVENT_TO_ACP_TRIGGER holds one key per HOOK_EVENTS member and nothing else

  • fixed: the nine unreachable keys are deleted

Checked your evidence rather than taking it, and it holds on both write paths: create refuses an
event outside HOOK_EVENTS through validate_hook_fields, and the loader raises on one and
skips the entry. So a stored hook could never carry a camelCase spelling or either
TaskExecution spelling, and nine of the fourteen keys were unreachable.
The map is now exactly the five. A wider trigger vocabulary arrives with the source that can
carry it, which is the change that widens HOOK_EVENTS.
ACP_HOOK_TRIGGERS keeps all seven, because that is the REQUEST vocabulary, not the hook
vocabulary: a request naming either task trigger is accepted and answered with an empty list.
Pinned by test_the_map_holds_exactly_the_stores_event_vocabulary and
test_a_trigger_with_no_crew_event_answers_empty.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Opus 5 lane: findings recovered from the job log, and answered

The lane failed on its own summary step (Opus 5 validation, outcome=failure), so its nine candidates were never posted. Recovered from the job log and ruled on each — head 0ed2032ad6465f073427b51b5a82b9871ff040e0:

# candidate ruling
1 includeDisabled resurrects disabled hooks into the executable record fixed — record() skips a disabled hook (also the Design lane's watch item)
2 the answer never consults capabilities.script_hooks fixed — a denial answers the whole request with no hooks, reason logged
3 the tool-matcher check is skipped when toolId is omitted fixed — a tool matcher with no named tool now WITHHOLDS the hook
4 a context-scoped hook is listed unconditionally fixed — same rule: a matcher this request cannot evaluate withholds the hook
5 a recorded hook keeps authorizing an old command fixed as contract — a hit is necessary, never sufficient; the live store owns command + enabled
6 params is not shape-guarded, so a params-less request raises fixed — guarded at the sink (_params_object), not only at the route
7 two literals bound the same population; truncation is silent fixed — the record's per-session cap IS HOOKS_LIST_MAX, and a truncated answer logs what it withheld
8 the "listed for THAT session" guarantee rests on a host-chosen session id rebutted — see below
9 the docstring says these requests are answered, but nothing routes them fixed — the route lands in this change

On candidate 8: the session id is the backend's, and Crew cannot mint it — the same id is what routes every session/update and every permission request for that session, so the whole transport already rests on it. What the record adds is that a hook id must have been listed for the id the request names, which narrows the set an execute path will accept from "any id the host invents" to "an id Crew minted on this connection for this session". A host that can forge another session's id can already impersonate that session on the transport, so this cannot be the layer that fixes it. The record is also dropped on unregister_session, so a reused id starts empty.

On candidate 2 specifically: the gate is consulted with an empty session key, because an AcpSessionHandle holds no Crew session key (the same reason its SEL audits pass session_key=""). That asks the capability gate's own enabled flag, which is the question a policy that forbids script hooks answers. A gate that cannot be resolved counts as a denial.

Re-running the whole lane so a fresh verdict lands on this head.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 3a54bc7b6760dc0a1a57b167bde5e0361bbefad5 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 3a54bc7

Verdict parsed from the review's SHA-scoped output markers for commit 3a54bc7b6760dc0a1a57b167bde5e0361bbefad5.

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

@iamwhatever
iamwhatever force-pushed the feat/acp-hooks-list-readonly branch from 0ed2032 to a66474d Compare September 23, 2026 22:03
@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=19934bb5ba3d
self-added: yes
mechanism: the list answer is built with asyncio.to_thread, and the docstring's in-memory claim is gone

  • fixed: the list answer no longer resolves governance on the event loop

Correct, and my own docstring was the thing asserting otherwise. It said "reading the hook store is
an in-memory dict copy, so it stays on this loop" — true of ScriptHookStore.list_all, and false of
the governance gate the same round added underneath it.
_answer_kas_hooks_request now builds the list answer with
await asyncio.to_thread(kas_wire.hooks_list_response, params, session_id=...), and the docstring
names the fingerprint/reload walk as the reason rather than the store.
The sessionStart answer stays inline on purpose: it reads nothing and returns a constant, so a
thread hop there would buy nothing and hide that fact.
The loop this was blocking demuxes every multiplexed session's frames, which is why it is a stall
and not a slow answer.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=a66be8a8e997
self-added: yes
mechanism: the decision is SEL-audited under the asking session, and the record is keyed by the session the handle owns

  • fixed in part, rebutted in part: the audit lands; the Crew session key does not exist here

Audit half taken as reported. script_hooks_forbidden(session_id) now calls
_audit_governance_hook_decision on BOTH outcomes, under acp:<session id>, with scope
capabilities.script_hooks — so a listed set and a refused one each leave a record naming which
session asked. Pinned by test_both_outcomes_are_audited_under_the_asking_session.
Key half rebutted with the code: an AcpSessionHandle has no Crew session key to pass. Its
constructor takes a backend session_id and a crew_agent, and _emit_tool_interrupted_sel says
so in as many words while passing session_key="" for the same reason. A key invented here
resolves no profile while LOOKING like an identity, which is worse than an honest empty one.
So the empty key is deliberate and now documented with its cost: a denial scoped to a Crew session
is unreachable from this surface, and the capability gate's own flag is what answers. Pinned by
test_the_question_is_asked_on_an_empty_key.
Separately took the identity point where it IS actionable: the record is now keyed by
self._session_id, never by the request's sessionId, so one session's request cannot write
another's executable set.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=7549aeb9d2a0
self-added: yes
mechanism: enabled=getattr(hook, "enabled", True) is True

  • fixed: enabled is the literal boolean, not truthiness

Verified the premise at the store rather than taking it: ScriptHook.from_dict takes
data.get("enabled", True) with no coercion, and validate_hook_fields does not check the field,
so a hand-edited hooks.json carrying "enabled": "false" reaches this code as that string. Your
fix is the right one and it is applied: anything that is not True is off.
Pinned by test_enabled_must_be_the_literal_boolean over "false", "", 0, 1, None and
"true" — note 1 and "true" read as OFF too, which is the same direction: only the boolean
means on.
One pre-existing sibling, reported and not fixed here: ScriptHookStore.fire tests
if not hook.enabled, so the same string would fire there. That is the store's own read on a path
this PR does not touch, and coercing the field at from_dict would change firing behaviour for
every existing consumer — a separate change with its own blast radius, not a rider on a read-only
surface.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=9f6ed7c59b5d
self-added: yes
mechanism: both owning specs record the channel, the unannounced capability and the record's contract

  • fixed: the two specs no longer contradict the code

Both claims you named were false as of that head, and both are now true.
agent-host-contract.md said "hooks are not wired for it". It now scopes that deferral to hook
EXECUTION and states the three properties that hold the surface shut: the handshake does not carry
hooks: {enabled: true}, _kiro/hooks/executeHook has no handler and is answered -32601, and
ListedHookStore is a necessary-not-sufficient record keyed by the session the handle owns. It also
records that listing consults capabilities.script_hooks, audits the decision, and asks the
question on an empty key with the cost of that stated.
acp-client.md's inbound inventory said session/request_permission is the only inbound request
Kiro Crew implements. It now says that of AcpClient specifically, names the two read-only methods
AcpSessionHandle serves, and gives the reason they are matched in that handle's own loop ahead of
the shared classifier: naming an action the client path has no branch for would leave the request
unanswered there instead of refused.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=7c4263542252
self-added: yes
mechanism: none — the split is a recorded maintainer decision, and this lane's exit needs a human

  • needs-a-decision: whether this ships read-only or waits to merge with the announcing change

Your reading of the state is exact: the handshake does not announce hooks, this PR's own
TestTheCapabilityIsNotAnnounced pins that, so on merge nothing asks either method.
That is not an oversight, it is the instruction this work was given: the flag stays OFF in this PR,
the execute path is a separate item, and no command may run from this change. The reason is the
hazard the execute path carries — a hook's payload is an arbitrary shell command, so it needs the
deny floor, the sensitive-path check and the ceiling wired before the surface is announced.
So both exits you offer are outside what I may decide: announcing is forbidden here, and merging
the two together is the split being rejected.
Question for a maintainer, not an issue: keep the read-only half merging on its own, or hold it
until the execute path lands and merge both at once? If the former, the line to paste is
/ai-review override first-principles a66474deaf40c3f3c6126f79a5fc94b28b818050: read-only half of a deliberate two-PR split; the capability stays unannounced until the execute path is gated.
Not self-authorizing it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=e735a3326aeb
self-added: yes
mechanism: record and forget have product callers; lookup is the read that makes the record assertable

  • rebutted: deleting the only read leaves a write-only structure nothing can verify

Your grep is right about the three call sites, and I read it the same way: record() from the list
answer, forget() from unregister_session, lookup() from tests only.
The write and the teardown are what the record IS: the list answer is the only writer, which is what
makes "was this id minted for this session" a fact at all, and the teardown is why a reused session
id starts empty instead of inheriting the previous occupant's set. Both are behaviour in THIS change.
lookup is one line and it is the only way to observe either. Delete it and the record becomes a
structure whose entire behaviour — keyed by owner, excludes disabled, evicts oldest-first, dropped on
unregister — has no assertable surface, so the tests that hold those properties go with it. That is a
worse trade than one unused accessor.
Disproportional rather than wrong, and it is a spelling of the same staging question as span
7c4263542252 — answered there with a maintainer question rather than a change.

@iamwhatever
iamwhatever force-pushed the feat/acp-hooks-list-readonly branch from a66474d to ddb5916 Compare September 23, 2026 22:20
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Round 4: two reds on a66474deaf, one mine and one not

Backend Lint & Type Check (3.12) was mine, and it was a self-inflicted one worth naming: a whole-file black run on src/kiro_crew/acp/kas_wire.py collapsed one PRE-EXISTING block (STEERING_KINDS), which made that baseline-exempt file black-clean and tripped the gate's graduated-entry check — 1 baselined file(s) are now black-clean.

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 ddb5916e62. src/kiro_crew/acp/kas_wire.py deletions are now the module docstring and one import line, nothing else.

Backend Tests (Windows) (7) — test/test_runtime_cleanup_windows.py::test_windows_failed_owner_drain_recovers_after_owner_drop, assert {6104, 7080, 8176} <= {6104}. Not this diff: that file exercises runtime.kill's Windows process-tree teardown through platform_compat and session_pid, with an injected transient discovery failure; it never reaches unregister_session, kas_wire or any hook path. The assertion is a PID-discovery timing shape.

The earlier .github/black-baseline.txt line (test/test_knowledge.py) stays pruned — that entry graduated on main, and the check is whole-tree, so it blocks every PR until someone removes it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

/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 hooks: {enabled: true} without v2, KAS builds no HooksModuleCache, so the user's .kiro/hooks/*.json AND their agent-profile hooks stop loading and Kiro Crew becomes the session's only hook provider. Announcing that before an execute path exists would take a user's working disk hooks away and put nothing in their place. So the flag flips in the 3d PR, together with _kiro/hooks/executeHook and its deny-floor, sensitive-path and ceiling wiring — which is also why the unannounced capability is pinned here by TestTheCapabilityIsNotAnnounced and by the spec text in docs/system-specs/modules/agent-host-contract.md.

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."

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Sep 23, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=3aca38367e44
self-added: yes
mechanism: none — same cause as its sibling span, same standing ruling

  • rebutted: the observer arrives with the flag, and the flag arrives with the execute path

Correct that the distinction it draws — "implemented, nothing buffered" versus "not implemented" — has
no observer until announce day. That is the same cause as span 19516e1c5439, and the same maintainer
ruling covers it.
The reason to ship it with its sibling rather than after it: the change that flips the capability is the
change that fills this buffer, and a method answering -32601 on the day the handshake advertises the
capability would contradict the advertisement. Adding it then means announcing and implementing in one
step; adding it now means announcing only.
Also the work item's own scope names both read-only methods together, so one of two is not the
deliverable — that is why this is a scope question rather than my preference.
Cost, stated plainly so the trade is visible: eleven product lines and one test class. Its false harm
claim — the one that said an unanswered request parks the turn — was deleted three heads ago when you
caught it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

/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 hooks: {enabled: true} without v2, KAS builds no HooksModuleCache, so the user's .kiro/hooks/*.json AND their agent-profile hooks stop loading and Kiro Crew becomes the session's only hook provider. Announcing that before an execute path exists would take a user's working disk hooks away and put nothing in their place. So the flag flips in the 3d PR, together with _kiro/hooks/executeHook and its deny-floor, sensitive-path and ceiling wiring — which is also why the unannounced capability is pinned here by TestTheCapabilityIsNotAnnounced and by the spec text in docs/system-specs/modules/agent-host-contract.md.

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."

@github-actions

Copy link
Copy Markdown
Contributor

AI-review override not recorded: keep the reason to 500 characters or fewer.

@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 24, 2026
@iamwhatever
iamwhatever force-pushed the feat/acp-hooks-list-readonly branch from 5a6627e to 8048ee4 Compare September 24, 2026 06:10
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 24, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

/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 hooks: {enabled: true} without v2 makes KAS build no HooksModuleCache, so a user's disk and profile hooks stop loading and Crew becomes the only provider — the flag flips in the 3d PR with _kiro/hooks/executeHook and its deny-floor. Pinned by TestTheCapabilityIsNotAnnounced.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@iamwhatever marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 8048ee4cd14bd8ea7d57b0a6f5eb69759659bc8d.

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 hooks: {enabled: true} without v2 makes KAS build no HooksModuleCache, so a user's disk and profile hooks stop loading and Crew becomes the only provider — the flag flips in the 3d PR with _kiro/hooks/executeHook and its deny-floor. Pinned by TestTheCapabilityIsNotAnnounced.

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

@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 24, 2026
…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.
@iamwhatever
iamwhatever force-pushed the feat/acp-hooks-list-readonly branch from 8048ee4 to 3a54bc7 Compare September 24, 2026 06:54
@iamwhatever

Copy link
Copy Markdown
Contributor Author

/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 hooks: {enabled: true} without v2 makes KAS build no HooksModuleCache, so a user's disk and profile hooks stop loading and Crew becomes the only provider — the flag flips in the 3d PR with _kiro/hooks/executeHook and its deny-floor. Pinned by TestTheCapabilityIsNotAnnounced.

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

Copy link
Copy Markdown
Contributor

Human judgment recorded

@iamwhatever marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 3a54bc7b6760dc0a1a57b167bde5e0361bbefad5.

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 hooks: {enabled: true} without v2 makes KAS build no HooksModuleCache, so a user's disk and profile hooks stop loading and Crew becomes the only provider — the flag flips in the 3d PR with _kiro/hooks/executeHook and its deny-floor. Pinned by TestTheCapabilityIsNotAnnounced.

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

@iamwhatever

Copy link
Copy Markdown
Contributor Author

span=22da22f1c24b
self-added: no
mechanism: deferred to the 3d PR, which owns the surface this suggestion needs

  • accepted as scope for 3d, not for this PR

Right about the parity gap, and the lane names the precondition itself: "when the flag flips". Today no
KAS agent asks for a hook list at all, because this PR deliberately does not announce
hooks: {enabled: true} — so a withheld context-matcher hook has no observer to surface anything to,
and there is no author-visible KAS run to be inconsistent with kiro-cli.

The surface it asks for also does not exist here. This PR's whole diff is the two read-only answers plus
their spec text; it adds no page, no card and no status cell. Building one now would be the one thing
the work item's fence forbids, and it would ship a dormant indicator for a channel nothing uses — the
same shape a sibling PR (#13193) is currently blocked on.

Where it goes instead: the 3d PR flips the announce flag and adds _kiro/hooks/executeHook, so it is
the first head on which a hook can be withheld from a real request, and the first one that can show the
author why.

What this PR does leave 3d to build on, stated precisely so the obligation is not overclaimed: the
withhold RULE — a matcher this request cannot evaluate withholds the hook, rather than failing open —
lives in src/kiro_crew/acp/kas_wire.py (select_hooks, and the log lines around it) and is pinned by
test_a_tool_matcher_is_withheld_when_no_tool_is_named and
test_a_context_matcher_is_withheld_on_a_non_tool_trigger. Today the reason reaches a LOG only, which
is exactly the gap this item names. The spec record next to it in
docs/system-specs/modules/agent-host-contract.md is the execute-path obligation, not this one — so 3d
carries the surface as new work rather than inheriting a written promise.

Nothing in this PR changes for it: a SUGGESTIONS item on a PASS verdict, answered as accepted-and-moved
rather than rebutted.

@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 24, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Ready for review. Head 3a54bc7b6760dc0a1a57b167bde5e0361bbefad5, rebased onto origin/main 1fb8c9e. 93 checks pass, 0 failing, mergeable. All four reviewer lanes answered on this head: Design PASS (its SUGGESTIONS span deferred to the 3d PR), GPT and Opus with no blocking lines, First Principles overridden with the recorded scope/ordering justification. Only a human approval remains.

@iamwhatever
iamwhatever enabled auto-merge (squash) September 24, 2026 16:57

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

Approve. The "read-only" claim holds on 3a54bc7b:

  • _KAS_HOOKS_METHODS (acp/session_handle.py:178) routes only hooks/list and hooks/sessionStart, KAS-backend only; executeHook still answers -32601.
  • The list answer is store.list_all() (an in-memory copy); sessionStart always returns {"results": []}. The only side effect is send_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.

@iamwhatever
iamwhatever merged commit 831bdd7 into main Sep 24, 2026
93 of 94 checks passed
@iamwhatever
iamwhatever deleted the feat/acp-hooks-list-readonly branch September 24, 2026 17:20
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 24, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
…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>
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.

2 participants