Skip to content

feat(hooks): make SessionLaneChanged an authorable hook event - #7669

Closed
rnoack1 wants to merge 1 commit into
kirodotdev:mainfrom
rnoack1:feat/session-tags-changed-hook
Closed

rnoack1 wants to merge 1 commit into
kirodotdev:mainfrom
rnoack1:feat/session-tags-changed-hook

Conversation

@rnoack1

@rnoack1 rnoack1 commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let someone write a hook that runs when a session's board lane changes, so close-out work can react to the move instead of polling for it.

Nothing server-side reacted to a lane change. A tag write mutated slot.tags, persisted, and called push_slots_update() to tell the browser — with no server-side consumer, so an automation that wanted to act on "this session just entered Done" had to poll the board and diff it itself.

Why it matters

A lane is where a team already expresses "this is finished", so it is the natural trigger for close-out work: file the artefact, post the summary, archive the branch. Reaction is no longer bounded by a poll interval, and the delta is computed once here rather than by every consumer.

It does not retire the polling loop for a subscriber that needs certainty. The RFC's v1 delivery bar does not promise every arrival, so a subscriber doing irreversible work still re-reads the board and gains only latency.

Not a goal

  • Firing on every tag change. The contract is status tags only. chat_auto_tag.maybe_auto_tag writes non-status tags routinely and never writes a status one, so a tag-general event would be chatty for the board-lane case that motivates it while adding nothing. Widening later is a NEW event (SessionTagsChanged), not a redefinition of this one — which is why the name is lane-scoped.
  • A hook that can veto. Exit code 2 blocks a PreToolUse call; this event ignores it. By the time it fires the write is applied and the drag has happened, so a veto would make the board unusable when a hook breaks rather than preventing anything.
  • Every write site. Two writers emit. Folder-tag inheritance is a KNOWN GAP here rather than a designed silence, and channel first-filing plus the single choke point are deferred for a stated reason; both below.
  • Re-entrancy signals. origin and hook_reentry_depth are the RFC's Phase 2.

What changed (motivation → approach → change)

The event is dispatchable (hooks.HOOK_EVENTS) and registrable (validation.ALLOWED_HOOK_EVENTS), and deliberately absent from agent._VALID_HOOK_EVENTS — that is kiro-cli's own closed enum, and a generated agent config naming an event it does not know fails to load at all. A test pins all three memberships with that rationale so the divergence cannot be "fixed" by syncing them.

The two emit sites, both under a dashboard request. api_chat_slot_tags and api_chat_slot_drop (dashboard/chat_tags.py). Because both carry a dashboard request, _lane_dispatch_is_permitted applies to them unchanged and neither needed a new authorization rule.

A known gap, stated rather than claimed closed: folder-tag inheritance does not fire. The inheritance in _read_folder_tags reached from api_chat_slot_create is the site a two-handler design misses: validate_folder_tag_ids screens a folder tag id's shape and vocabulary but not its status field, so an inherited folder status tag puts a session into a lane with nothing firing, and a hook keyed on entering that lane will not see such a session. Its emitter is written and was held out of this PR to bring it under the review size cap; it follows as its own PR once this lands. It needs no new authorization rule either, so the only thing it waits on is the dispatcher reaching main. The spec, the RFC amendment and the RFC index row all state the gap.

Each dispatch runs after its write has CONFIRMED persisted, on the success path only — and two failure shapes are kept silent, not one. A refusal without writing (the session was deleted or rebound) rolls slot.tags back and answers 409 before the dispatch is reached; that branch has its own push_slots_update(), so the success call is identified by the outcome="allowed" SEL row rather than by the broadcast.

A lock timeout or I/O error is the shape a return value cannot report. save_slot_off_loop defaults to best_effort=True, which catches it, marks the slot dirty for the periodic flush and returns True — its own docstring says that return "does NOT prove a committed write". Firing on the strength of it would run close-out work for a lane move that never reached disk, and a restart before the retry then restores the old lane with those side effects already taken. Both handlers therefore persist through _persisted_tag_write, which takes the confirming mode and re-arms that flush itself: the acknowledged edit is still retried and the response is unchanged, so suppressing the hook does not turn a recoverable write failure into a lost edit.

Silent, deliberately. Load-time reconstruction (chat_persistence.py, chat_handlers.py) would replay the whole tag history on every restart and read every existing Done as just-entered. The two slot.tags.append sites in surface_channel_session have no dashboard caller, so what authorizes a fire there is unanswered — that is the RFC's closing-order step 2, and the choke point is step 3 because it inherits that answer. The permit gate is what makes those deferrals rather than holes: a path that cannot be authorized cannot dispatch.

Payload, all keys stamped unconditionally so a hook that always reads one never KeyErrors: slot, added, removed, and cwd like every other event (so a hook that passes Test cannot fail on cwd when it really fires). added/removed are status-only, not the raw set difference — a single edit can bundle a lane change with a plain-label change, and emitting the whole delta would put a non-status id into the matcher context, letting a hook match a tag the firing contract excludes.

Matcher grammar, direction-tagged, id only: added:<id>; and removed:<id>;. Direction is in the grammar because the motivating case is "a session entered Done", which an untagged context cannot express — a bare <id> would fire on leaving too. Matching is whole-string fnmatch, so a bare lane id matches nothing; the selectors are *added:<id>;*, *removed:<id>;*, and *:<id>;* for either. Both bounds are load-bearing and neither is forgeable: : and ; are outside the id allowlist (\A[a-z0-9_.-]+\Z), so no id can contain either, and an id the allowlist refuses is skipped with a warning rather than escaped.

Net additive, and measured as such: 24 files, 1348 insertions, 70 deletions against the base (git diff --numstat against the merge base, excluding the two committed PNG frames, which GitHub counts as binary). An earlier revision of this PR shipped the vocabulary with no emitter and carried refusal machinery to contain it, and later revisions took that back out -- but none of it ever reached main, so against the base there is nothing of the sort to remove. Read this as what it is: the event, its emitter and its matcher grammar arriving together. The only subtraction visible from the base is small and local -- HOOK_EVENTS_UNFIRED is gone, because with the emitter landed it was literally HOOK_EVENTS_KAS_ONLY under a second name, and its seven readers use the original name again.

The Hooks page change is the minimum needed to select the event, per the maintainer's split: the event picker offers SessionLaneChanged and the table gives it the same style and badge as its siblings. Help for writing a lane matcher is not in this PR. A lane's tag id is what the matcher keys on and no surface shows one, so a picker that fills it in, a grammar line under the field and their screenshots belong to the separate Hooks-page UX PR. Until then the grammar is documented in the user doc and the system spec.

Test isolation, two host-independence fixes in one autouse fixture per new module.

The process-global hook store is reset around every test. Each module binds one rooted at its own tmp_path; left bound, a later test on the same xdist worker that moves a status tag would reach the dispatcher, find that store, and recreate an already-deleted tmp_path to write hooks.json into it -- a side effect outside the running test's own directory, arriving or not depending on test order.

The capabilities.script_hooks gate is permitted explicitly. It defaults to OFF, so with no config a hook is blocked before its subprocess spawns and writes nothing. These tests passed locally only because this developer host enables it, and failed on CI's shards 2 and 3 with expected exactly one fire, got [] -- the fire assertions were reading the host rather than the code. Reproduced by driving the gate directly: permitted passes, denied reproduces CI's exact signature. The denial path now has its own test, which also pins that the gate is asked about dashboard:s1 -- the firing session's surface-qualified key -- rather than the empty key that would resolve the wrong scope.

One rider, declared so it is not undeclared scope. The "unparseable hook entry" warning now names the row id and its event, so an operator can find the row to rename. An earlier revision also respelled the dormant-event check, churned its comments and suppressed an empty tooltip; the first-principles lane showed those were no-ops against the base, and they have been reverted.

One pre-existing finding, reported and not fixed here. The spec's deferral paragraph claims both async call sites "await ONE seam, _script_hooks_capability_denied_async". That symbol does not exist — each site calls await asyncio.to_thread(_script_hooks_capability_denied, sk) inline, which is the per-caller hop the paragraph says was avoided. It is present in this PR's base and untouched here; it wants its own docs: change rather than riding inside a feature PR.

The matcher builder lives beside its only caller. _session_lane_matcher_context is in hook_runtime/hook_dispatch.py, so the hooks.py facade gains no definition and test_hooks_composition_contract.py keeps main's count of 94. The _TOKEN_ALLOWED allowlist stays on the facade with the rest of the module state, which the same contract requires.

Backwards compatibility

Additive for anything already working. A hook stored against this name before the emitter loaded, rendered and edited, and still does — it now also arms and accepts a matcher, which it could not before. A row naming an event outside HOOK_EVENTS_ALL is still not loaded but not erased: _load keeps it in _unparsed_hook_entries and _save writes it back, so it returns if the name does.

The event is absent from agent._VALID_HOOK_EVENTS and stays absent, so no generated agent config changes.

Tests

  • test/test_session_lane_changed_emitter.py (new, 15 tests): the two tag routes driven through a real TestClient. A lane change fires once carrying the status-only delta with the plain label excluded; a drag fires with both directions, because the drop route's mutual-exclusion strip makes one drag a two-direction transition; a refused persist (409) fires nothing; a swallowed save failure fires nothing while still answering 200 and leaving the slot dirty for retry; a plain label alone fires nothing; an agent caller does not fire the operator's hook; a denied governance capability fires nothing; with no registered hook there is no dispatch at all; a *added:<id>;* hook runs only on entering the lane and a *removed:<id>;* hook only on leaving it, through the real route and matcher; and the permit gate denies each non-person signal alone (internal transport, app claim, crew member) while permitting the person.
  • test/test_session_lane_changed_event.py (new, 23 tests): the event's standing in the store. It arms like any other fired event and accepts a matcher, while the six Kiro Agent triggers still refuse one — the control proving the store's activation contract is intact for the events that are genuinely unfired, rather than loosened across the board to let this one through.
  • The emitter test asserts through the dispatcher's own spawn seam, not through a file a real hook writes — and the module needs no windows-collect-ignore.txt entry. Recording through a spawned hook's file write makes the test depend on the sandbox and on the runner's filesystem view: measured, a real-spawn version passed locally, where wrap_argv returns the argv unchanged because no sandbox backend exists, and ALL THREE fire assertions came back got [] on CI's Linux shards 2 and 5 while every absence assertion passed — the signature of nothing firing at all, read as a pass. Mocking the spawn removes both dependencies, and takes the POSIX-shell-body assumption with them, so the module is collected on every platform instead of being skipped on Windows.
  • Negative controls, nine breakages each applied alone and reverted before the next: a handler that never dispatches, a dispatch not gated on the confirmed persist, the save left in the swallowing best_effort mode, ids never resolved against the live vocabulary, the whole delta instead of status-only, Test sending no lane payload, the matcher filter removed, the grammar's directions swapped, and the live cwd dropped. Each reddens the suite; all restored byte-identical and green. The runner aborts when a breakage's anchor does not match rather than reporting a pass, because one of these controls had already gone vacuous that way once when an edit moved its anchor. The swallowed-save control is why the failure is injected at the inner write rather than by replacing save_slot_off_loop: a mock raising in its place raises whatever mode the caller asked for, so the test would have passed with the swallowing default restored and proved nothing about the mode.
  • The website tests pin the event's presence: HooksPage.eventPicker.test.tsx asserts the picker offers SessionLaneChanged by name and in order, and HooksPage.rowActions.test.tsx asserts a lane hook's switch is live and not marked dormant.
  • The Test button sends the lane payload the live fire sends. api_hook_test built a payload for UserPromptSubmit and Stop only and passed None for every other event, so a valid hook reading json.load(sys.stdin)["added"] raised KeyError on Test and then worked when it actually fired. A third branch supplies slot, added and removed; test/test_api_hook_test_stop_payload.py (6 tests) pins all three branches.
  • Totals: 45,095 backend tests pass across 820 dependent test files, discovered by grepping the test tree for this change's own module paths rather than hand-picked. 61 failures and errors remain, and all 61 are INHERITED: the same test ids fail identically on a pristine worktree of the upstream tip 455e8ecbf1 (test_cli_manifest_signature 34 errors, test_onboarding_import_refactor_contract, test_cron_secret_env, and six singletons), with the pristine tip failing one MORE than this branch rather than fewer. 1089 website tests pass across 56 files (the i18n tree plus every HooksPage suite). This PR adds no catalog values. The repo's own baselined gates pass (check_black_formatting diff-scoped, check_file_line_cap, check_subprocess_encoding, check_acp_frame_host_data, check_agent_sdk_boundary), as do isort/flake8/mypy src/kiro_crew//tsc/eslint --max-warnings 0.

Manual verification

Built the website and drove the Hooks page in a headless browser against a stubbed API, with a twelve-row fixture.

The shape bug a passing test hid, twice. slot.tags holds tag ids, while the status field that makes an id a lane lives on the tag object in state._tags; and store._hooks is a dict keyed by id, so iterating it yields id strings. The first cut got both wrong and every test still passed, because each fixture supplied the shape the code expected rather than the shape production holds. mypy caught the second one. The fixtures now resolve ids through the live vocabulary and build their hook through store.create(...), the real write path, and one test carries the mistake as its own control: dicts where ids belong must fire nothing.

Measured on this revision, one build, four fixtures. At 1440px the LAST RUN column must not overlap the sticky right-0 ACTIONS column, and it does not: overlap 0. The lane row is 77px against a 57px neighbour, inside the 1.5× bound. At 900px the eleven-row baseline is 518px and the twelve-row board is 525px, so this change's contribution to the narrow-viewport overlap is +7px — down from +19px on the previous cut, because the lines that explained a disabled switch are gone.

A measurement artifact, named so it is not mistaken for a regression. A first capture showed 27px of overlap at 1440px. The cause is matcher width, not this change: on the eleven-row harness with no lane row at all, a 13-character matcher produces 20px of overlap, while the lane row carrying no matcher produces 0. The measurement therefore used *:done;*, the spec's own "any movement" selector, which is the same width as the harness's existing fs_write.

Screenshots / video

Two frames of this head are committed under temp-screenshots/session-lane-changed/, where .github/scripts/pr-committed-evidence.sh puts them in front of the review lanes. Each claim below was asserted by the capture script before its shot was taken.

  • temp-screenshots/session-lane-changed/hooks-table-lane.png: the hooks table with a SessionLaneChanged row carrying its badge, an ordinary live switch and the *added:done;* matcher. The row carries no not fired yet / never fires mark.
  • temp-screenshots/session-lane-changed/hooks-event-picker-lane.png: the event picker open on SessionLaneChanged, directly after Stop and with no dormant mark, above the six Kiro Agent triggers that keep theirs.

Help for writing a lane matcher, and its screenshots, belong to the separate Hooks-page UX PR.

Related Issues

Follow-ups deferred from this PR, each tracked on its own:

Implements #7663. RFC: docs/request-for-change/rfc-session-tag-change-event.md (in-review; its amendment and the README's implementation-state column are updated here, its status: is not — the first-principles lane reads that from the base sha so a PR cannot move its own RFC's review state). Tracking: #13865.

Checklist

  • Tests added and passing
  • Lint and type checks clean
  • Docs updated (user doc, system spec, RFC amendment and README row)
  • Screenshot evidence committed
  • Backwards compatible

@rnoack1
rnoack1 requested review from a team and cixuuz September 1, 2026 15:53
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 1, 2026
@rnoack1
rnoack1 force-pushed the feat/session-tags-changed-hook branch from 56fbd26 to edb18bc Compare September 1, 2026 17:58
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 1, 2026
@rnoack1
rnoack1 force-pushed the feat/session-tags-changed-hook branch from edb18bc to 3b8c1f3 Compare September 1, 2026 21:20
@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 1, 2026
@github-actions

github-actions Bot commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 6d692e2ad655013a1043b123245b6173063cf3c1 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the event fires only after a confirmed persist, only for a dashboard user, and the gaps that remain are written down and pinned.

Notes

  • Hooks fire only when a person moves a session, so a lane change made by a conductor or chat_tag_assign runs nothing. Close-out hooks will miss sessions that agents move to Done. The user doc says so; the spec section should say it in the same plain words.
  • acp/kas_wire.py:242 still says "One key per member of HOOK_EVENTS", which is now false. Fix that comment in this PR, because the changed test in test_kas_hooks_acp.py relies on it being accurate.

[DESIGN-REVIEWED] 6d692e2

Description read

[DESCRIPTION-READ] 439ed221f5a0b8eb5daa97d6ddea000acea9c1ac410f75c005d94c4a9189fe8d

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 6d692e2ad655013a1043b123245b6173063cf3c1 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The event is opt-in: nobody gets anything until they write a hook for it. So it is not a product-shape change, even though its RFC is still in-review on the base.

Notes

  • Item 1 — symptom-level (accepted, deferred): the PR names the gap itself: "folder-tag inheritance does not fire". With the channel first-filing writers (2 sites in surface_channel_session), that leaves 3 writers that can move a session into a lane without the event firing. The description states this and defers it, so it is a note, not a demand.
  • Item 1 — second spelling: _run_one_lane_hook re-does the match → run_script_hook → _persist_current steps that ScriptHookStore.fire (hook_runtime/script_hooks.py:816) already runs. fire has no way to carry slot/added/removed, so the two are meaningfully different. Subtraction: let fire take a payload and drop the duplicated loop when the choke-point step lands.

What this change ships

Inventory (9 items) — 7 justified

Intent: let an operator run a hook when a dashboard user moves a session between board lanes, instead of polling the board. This is an ADDITION.

  1. A new hook event, SessionLaneChanged, fires when a dashboard user edits or drags a session's status tags — justified
  2. The Hooks page picker offers the new event, and the table shows it with a badge — justified
  3. The hook Test button sends a placeholder lane payload — justified
  4. A lane matcher grammar (added:<id>;, removed:<id>;) where tag ids are allowlisted and bad ids are skipped — justified
  5. Only a dashboard user's move fires the hook; an agent's move does not, and each decision writes an audit (SEL) row — justified
  6. A failed tag save is now detected and the hook is held back, while the periodic flush still retries the save — justified
  7. The load error for an unparseable hook now names the row's id and event — undeclared, harmless rider
  8. User doc, spec and RFC amendment updated to say "six events" and to list the known gaps — justified
  9. Two screenshot PNGs committed under temp-screenshots/ — rides along, follows the repo's evidence convention

[FIRST-PRINCIPLES-REVIEWED] 6d692e2

Description read

[DESCRIPTION-READ] 477cc2c190fc9218c85de6c8e6ca0c7448197b4c21de4de1da1df917e62dd534

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 6d692e2

@github-actions

github-actions Bot commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6d692e2

@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 1, 2026
@rnoack1
rnoack1 force-pushed the feat/session-tags-changed-hook branch from 3b8c1f3 to b521748 Compare September 2, 2026 00:03
@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 2, 2026
@rnoack1
rnoack1 force-pushed the feat/session-tags-changed-hook branch from b521748 to a47c047 Compare September 2, 2026 00:39
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 2, 2026
@rnoack1

rnoack1 commented Sep 13, 2026

Copy link
Copy Markdown
Contributor Author

@bolichen97 — one narrow factual update on your review, and nothing else.

The branch no longer conflicts with main. At head cd59585baabd294ddf4f3641265a79b3a4ab4429 GitHub
reports the pull request as mergeable, and a local three-way merge against the current main tip resolves
with no conflicts. The conflict you saw was against the sha your review is pinned to; it is not present at
this head.

I am deliberately not responding here to the split you asked for — that decision is still being made, and I
do not want to pre-empt it in a comment.

@rnoack1

rnoack1 commented Sep 13, 2026

Copy link
Copy Markdown
Contributor Author

Requesting the allow-fork-workflow-change label so CI can run on this PR.

Current state: PR Readiness reports 4 workflow(s) awaiting maintainer approval; none has run yet, and only 5 checks have ever run on this head. No tests, lint, build or AI-review lane has executed, so there is no signal on the change itself — every push so far has produced the same held state rather than a verdict.

Why the guard fires: the only path under .github/ this PR touches is .github/black-baseline.txt, and only to DELETE lines — the entries for test files this PR reformats to be black-clean. No workflow file is added or modified. The deletions are a consequence of the reformat rather than an independent change, so dropping them is not a clean workaround: the files would be black-clean while still listed as exempt.

Precedent: the same label was applied on #7068 to clear this guard for a trusted .github/** path touch, which is the same situation here.

I do not have write access on this repository, so I cannot apply the label myself — hence the request. Happy to restructure the baseline change instead if you would prefer that to the label.

@aniruddhaadak80

Copy link
Copy Markdown
Contributor

Coordination note from the #7843 side (per the 09-08 relationship audit): my PR reworks ScriptHook/ScriptHookResult/ScriptHookStore for PreToolUse deny on subagent/task-runner paths while this one rewrites the same store read path and fire() loop. Happy to land in whichever order you prefer - mine is small and rebases cleanly, so I can go second after this lands if that is easier. Just say the word.

Copy link
Copy Markdown
Contributor

PR triage (2026-10-05) — REBASE + MERGE-DISCUSSION with #10931

Code-level audit of head 8aa8855 against origin/main a97659d (merge base 529a8f5, 1,610 commits behind).

Relationship: OVERLAPPING with open PR #10931 (same author, not a duplicate). Both add HOOK_EVENT_SESSION_LANE_CHANGED = "SessionLaneChanged" to src/kiro_crew/hooks.py, the "SessionLaneChanged" entry to ALLOWED_HOOK_EVENTS in validation.py, and the picker entry in website/src/pages/hookEventWireValues.ts. The two models disagree. #10931 puts it in a new HOOK_EVENTS_PENDING group inside HOOK_EVENTS_DORMANT, so the hook is saved disabled and can't take a matcher. This PR adds it to the firing HOOK_EVENTS tuple, where it is enabled and takes a matcher. Only this PR carries the dispatcher (dispatch_session_lane_changed_bulk, the queue and worker, _session_lane_matcher_context). Neither PR has a writer that calls it: chat_tags.py / chat_handlers.py are not in this diff, even though the description's "What changed" table lists them. Please agree which model lands, and in what order, before rebasing. If #10931 lands first, this PR has to move the name from HOOK_EVENTS_PENDING into HOOK_EVENTS. If this PR lands first, #10931's dormant gating is moot.

REBASE needed (heavy conflicts). git merge-tree reports conflicts in hooks.py, validation.py, memory-skills-hooks.md, docs/feature-map/README.md, test/test_api_hook_test_stop_payload.py and website/eslint.i18n.config.js. Main has moved under this diff:

No new P0 and no breaking change found. The concern that the event is selectable but never fires has already been raised: by the Design, First-Principles and UX reviews (BLOCK), the GPT finding, and the maintainer's CHANGES_REQUESTED. I'm not filing a duplicate request. The enabled fail-closed coercion and the Hook-Test governance binding are tightenings, and the description discloses both.

Recommendation: REBASE, settle the order with #10931, and ship the chat_tags.py emission in the same PR as the move into HOOK_EVENTS (or keep the event dormant until then).

@rnoack1

rnoack1 commented Oct 20, 2026

Copy link
Copy Markdown
Contributor Author

The split you asked for has landed. At d7177a925e this PR is 24 files, +270/−46, down from 72 files and +10,299/−197. The branch no longer conflicts with main.

In it: the SessionLaneChanged constant, its ALLOWED_HOOK_EVENTS row, the wire-values export, the minimal HooksPage change needed to select it, the spec section, and the backend tests.

Out of it: the lane-matcher picker, draft save/restore across navigation, deep links, the tag-manager hand-off and the capture harness. None of those files appear in the diff. That is the second PR.

Two places this differs from your item 1, so you are not reading it from the diff:

  • The event is not in HOOK_EVENTS. Since your review, main grew HOOK_EVENTS_KAS_ONLY — six triggers that are authorable and that nothing fires — and the comment above HOOK_EVENTS now states that membership there carries a promise something calls fire. This cut has no emitter, so the event sits in ALLOWED_HOOK_EVENTS and outside HOOK_EVENTS, and a hook saved on it is stored switched off, the same contract those six carry.
  • The chat_tags.py emission is not here. src/kiro_crew/hooks.py has gone from 5322 to 1723 lines since this branch was cut, with the dispatch machinery moved into src/kiro_crew/hook_runtime/, so the emission is a port rather than a lift.

The first-principles review lane now blocks on that second point.

@rnoack1

rnoack1 commented Oct 27, 2026

Copy link
Copy Markdown
Contributor Author

@bolichen97 the split landed. Head 0038d48ddb is 42 files, +1,488/-69, down from the 72 files and +10,299/-197 you reviewed.

PR 1 keeps everything on your list: the SessionLaneChanged entry in HOOK_EVENTS, the chat_tags.py emission, hookEventWireValues.ts, the HooksPage change needed to select the event, the spec update in docs/system-specs/modules/memory-skills-hooks.md, and the backend tests (7 files under test/).

Of the six things you moved to PR 2, four are gone: draft save/restore across navigation, deep links, the tag-manager hand-off, and the capture harness. I checked that against the diff's added lines rather than the touched files, so a pre-existing sibling key does not read as present.

Two are still here, and a review lane required each of them after you wrote your review:

  • The lane-matcher picker. UX Review returned BLOCK at 7f6723ddf: the matcher keys on a tag id, and no dashboard surface displays one, so anyone who renames a lane or creates their own writes a selector that silently never matches. Its fix asked for a control that picks a lane by name and inserts the id. Opus 5.5 then blocked the first version, one button per lane, and asked for a single dropdown, which is what ships now.
  • The five screenshots, which are that lane's evidence requirement.

I could not drop either without re-opening a block. If you still want both in PR 2, say so and they come out. That is your call rather than mine.

The conflict you mentioned is resolved: GitHub reports MERGEABLE.

All six AI lanes are green at this head, and 92 checks pass. The one remaining red is Sensitive Change Review, which cannot be cleared from here. It refuses any fork PR touching a sensitive path before it looks at a template at all, and this one touches src/kiro_crew/hooks.py and src/kiro_crew/hook_runtime/. Its own message asks a maintainer to take the branch over on a branch of this repository, keeping the author with Co-authored-by:. That step needs one of you.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 7077f6b.

What would clear it:

  • @bolichen97's change request from 2026-09-10 (asking for the split) is still active. The author reports the split is done, so it needs a fresh review or a dismissal from that reviewer.
  • PR Policy fails because the description has no screenshot of the changed Hooks page (job). The UX lane asks for the same thing: the event picker option and the table badge.
  • Sensitive Change Review fails for this fork head (job). A maintainer has to take it over, as its message says.
  • This adds a new trigger for operator script hooks and an identity gate that decides who may fire them (hook_dispatch.py L274-L320). That is reserved for a human reviewer.
  • Three deferred items need linked issues: the folder-tag inheritance emitter, the Hooks-page matcher help (UX lane asks for it to be linked), and the docs fix for the nonexistent _script_hooks_capability_denied_async seam. docs: the merged SessionLaneChanged spec makes three claims #7669 no longer backs #13865 is closed and does not cover them.

I found no defect in the code I read. The dispatch runs only after a confirmed persist (chat_tags.py L368-L374), and a swallowed save failure re-arms the flush without firing (L91-L122). All AI lanes pass on this head.

AI findings judged non-blocking:

  • Design: agent-driven moves never fire; this should be stated in the user doc. Wording only.
  • Design: the HOOK_EVENTS header and _CREW_EVENT_TO_ACP_TRIGGER comments are now inaccurate. Comment accuracy, no runtime effect.
  • First Principles item 2: dispatch_session_lane_changed_bulk could take a single move. Simplification only.

— crew-pr-reviewer (r136)

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 3cccea1.

Since our r136 hold at 7077f6b the code is unchanged. The new head adds the two Hooks-page screenshots, which clears the PR Policy failure. I found no defect: the lane dispatch runs only after a confirmed persist and past the rollback branch (chat_tags.py#L92-L123). All six AI lanes pass.

What would clear it:

  1. Active change request. @bolichen97's 2026-09-10 review asking for the split is still CHANGES_REQUESTED. The author reports the split is done; that reviewer needs to re-review or dismiss it.
  2. Sensitive Change Review fails for this fork head (job). A maintainer has to take the branch over, as its message says.
  3. Human review of the identity gate. This adds a new trigger for operator script hooks, and _lane_dispatch_is_permitted decides which caller may fire them. That is reserved for a person.
  4. Deferred items still have no issue. Please open one issue each and link it in the description: the folder-tag inheritance emitter, the Hooks-page matcher help (the UX lane's note that a bare lane id matches nothing), and the docs fix for the nonexistent _script_hooks_capability_denied_async seam. No event fires when a session's tags change, so nothing can react to a lane transition #7663 and docs: the merged SessionLaneChanged spec makes three claims #7669 no longer backs #13865 are closed and do not cover them.

AI findings judged non-blocking:

  • Design: per-writer firing instead of one choke point. The gap is documented in the RFC and spec, and no current writer misfires.
  • Design: the matcher grammar becomes a compatibility surface. Advice for the follow-up; the id allowlist keeps : and ; unforgeable.
  • First Principles item 2: the bulk dispatcher only ever gets one move. Simplification only.
  • First Principles item 8: unused re-export in chat_handlers.py. One import line, no behaviour.
  • Security Scope: a tag id outside [a-z0-9_.-] never matches. A deliberate fail-closed choice, logged with a warning.

I read the interdiff from 7077f6b, the emit sites, the dispatch gate and every lane body. I did not run tests.

— crew-pr-reviewer (r144)

@bolichen97

Copy link
Copy Markdown
Contributor

Holding this PR at 3cccea1. Sensitive Change Review is red on this head, and the log gives a real reason, not a flaky run: this is a fork PR that changes a sensitive path (the hook runtime and hook scripts handler), and there is no reasoning template for this head. A fork PR cannot pass that gate.

It needs a maintainer security review before it can move. The gate's own path for this is for a maintainer to take it over on a branch of this repository, keeping the author with Co-authored-by: and writing Supersedes #7669, then run the real sandbox and drive that PR green. I am not approving it until that happens.

@bolichen97

Copy link
Copy Markdown
Contributor

Thanks for this PR. On head 3cccea1 the only red check is Sensitive Change Review. Its log says: "Sensitive path changed without a reasoning template for this head."

Could you add the sensitive change reasoning template for this head (a PR comment in the format the check describes, including the Before -> after section)? The check re-runs once it is posted. Everything else on this head is green.

@rnoack1

rnoack1 commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

@bolichen97 Thanks. A reasoning template can't clear this check for a fork PR. In .github/scripts/sensitive_change_review.py on main, decide() returns the fork refusal at line 334 (if is_fork(pr):, commented "No approval can clear this") before it reaches the author-template check at line 360. So a template on this head would leave the check red. The path the gate names is the one in your earlier comment: a maintainer takes the branch over on this repository, with Co-authored-by: and Supersedes #7669.

Separately, the three deferred items @iamwhatever asked about are now #31614, #31615 and #31616, linked in the description.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 3cccea1. The code is unchanged since r144.

Cleared since r144: the description now links #31614, #31615 and #31616, and each covers its deferred item (folder-tag inheritance emitter, Hooks-page matcher help, the spec's nonexistent seam).

Still blocking:

  1. @bolichen97's 2026-09-10 change request is still active.
  2. Sensitive Change Review failed on this head for a fork changing a sensitive path. A rerun is queued; it needs the reasoning template or a maintainer takeover.
  3. Human review of the new script-hook trigger and its identity gate, _lane_dispatch_is_permitted.

I found no defect; dispatch runs only after a confirmed persist (chat_tags.py#L92-L123).

— crew-pr-reviewer (r148)

@rnoack1

rnoack1 commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

@bolichen97 I have write access to this repository, so I can move this change onto a branch here myself instead of waiting for a takeover: same commit, a new PR with Supersedes #7669, and I post the sensitive-change reasoning template for that head as its author.

That clears the gate's fork refusal, but it would not replace the security review you asked for on the hook runtime and _lane_dispatch_is_permitted. Would you be OK with me doing that, and reviewing the new PR? Or would you rather a maintainer take it over as you described?

@rnoack1

rnoack1 commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

@bolichen97 the split you asked for on 09-10 is done. This PR is now the event part only, rebased on current main. The UI part is in #10931. Could you re-review? Also, Sensitive Change Review says a fork PR can't pass when it touches hooks.py and hook_runtime/. Could a maintainer take it over on a repo branch, keeping me as co-author?

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks for the split into a focused event PR. One problem must be fixed before this can merge.

  1. test/test_hooks_composition_contract.py:497: the facade definition count is wrong once this branch is merged with current main.
    • Trigger: merge this head (3cccea1) into current main, then run test/test_hooks_composition_contract.py.
    • Outcome: test_every_base_definition_is_in_exactly_one_place fails with assert (13 + 82) == 94.
    • Cause: #27745 on main also changed this line from == 93 to == 94, for unattended_turn. Git merges the two identical edits without a conflict. The merged tree then has 95 definitions against a pin of 94.
    • The CI on this head ran before #27745 landed, so the green checks do not cover current main.
    • Smallest fix: move _session_lane_matcher_context into hook_runtime/hook_dispatch.py, its only caller, and drop its _FACADE_DEFS entry and the count edit. Main's 94 then stays correct.
    • Other fix: rebase, set the count to 95, and add the reason for the facade entry to the "What stays in hooks.py" list in memory-skills-hooks.md.

Optional:

  • No test dispatches a lane hook that has a real matcher. You can delete the matcher filter in hook_dispatch.py, or change the direction:id; grammar, and every test stays green. A route-level test for *added:<id>;* and *removed:<id>;* would pin it.
  • _lane_dispatch_is_permitted is denial-tested on the internal-secret transport only. You can parametrize the denial over the app-claim and member: principals too.
  • The live SessionLaneChanged payload has no cwd, but the Test payload has one. A hook that passes Test can then fail when it really fires.

Related: #10931 (same author) models this event differently. Whichever PR lands second must reconcile the two.

Nothing server-side reacted to a lane change, so the board could not trigger
anything. The event now fires from the two tag writers that run under a
dashboard request, `api_chat_slot_tags` and `api_chat_slot_drop`, carrying the
status-only delta as added/removed tag ids.

The matcher is direction-tagged, `added:<id>;` and `removed:<id>;`, because the
motivating case is a session having ENTERED a lane and an untagged context
cannot express it. Matching is whole-string, so the selectors are
`*added:<id>;*` and `*removed:<id>;*`; a bare tag id matches nothing.

The Hooks page change is the minimum needed to select the event: the picker
offers it and the table styles it like its siblings. Help for writing a lane
matcher -- a picker that fills in a lane's id, and a grammar line -- is held
for the separate Hooks-page UX change the maintainer asked for, together with
its screenshots.

A dispatch needs a CONFIRMED persist, not just a return value.
`save_slot_off_loop` defaults to `best_effort=True`, which catches a lock
timeout or I/O error, marks the slot dirty for the periodic flush and returns
`True` -- its own docstring says that return does not prove a committed write.
Both handlers now persist through `_persisted_tag_write`, which takes the
confirming mode and re-arms that flush itself, so the acknowledged edit is
still retried and the response is unchanged while a hook no longer runs
close-out work for a transition that is not on disk.

Folder-tag inheritance on slot create is a KNOWN GAP here, not a designed
silence: an inherited folder status tag puts a session into a lane with nothing
firing. Its emitter is written and was held out of this change to bring it
under the review size cap; it follows as its own PR once this lands, and needs
no new authorization rule. The spec, the RFC amendment and the RFC index row
all state the gap rather than claiming three emit sites.

`HOOK_EVENTS_UNFIRED` goes with this change. With the emitter landed it was
literally `HOOK_EVENTS_KAS_ONLY` under a second name, so its seven readers use
the original name again.

The emitter test asserts through the dispatcher's own spawn seam, not through a
file a real hook writes. A sandboxed spawn drops that write, and the module's
absence assertions cannot tell it apart from a dispatcher that correctly stayed
silent, so the file-channel version read GREEN on a shard where nothing fired at
all. Mocking the spawn takes the platform assumption with it, so the module
needs no windows-collect-ignore.txt entry.
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Thanks for the split. The event change is now focused (24 files), and this review found no blocking defect on head 6d692e2.

Earlier requests:

  • Split into an event PR and a Hooks page UX PR (09-10): done. The UI part is in feat(hooks): gloss SessionLaneChanged in the Hooks page #10931.
  • Facade definition count in test_hooks_composition_contract.py (11-07): fixed. _session_lane_matcher_context now lives in hook_dispatch.py, and the pin stays at 94 as on main.
  • Optional items from 11-07: all addressed. A route-level test now covers *added:<id>;* and *removed:<id>;*. The permit gate is tested on the internal transport, app claim and member: legs. The live payload now carries cwd.

A maintainer still has to act before this can merge:

  • This is a fork PR that changes hooks.py and hook_runtime/. Sensitive Change Review always refuses that from a fork, so the change has to come in on a repository branch. A maintainer will answer your two questions from 11-07 about how.
  • A board move now runs operator shell hooks. The new gate _lane_dispatch_is_permitted needs a security read by a human.
  • The PR edits the RFC index (docs/request-for-change/README.md) and the RFC itself, which need a maintainer's sign-off.
  • Internal Content Scan reported no verdict. That looks like an infrastructure failure, so it needs a rerun.

To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

What the review checked on this head:

  • A refused or swallowed save fires no hook.
  • The permit gate denies by default.
  • The matcher token set cannot carry glob characters.
  • The regex matcher runs off the event loop.
  • No Kiro CLI agent spec gains a key.

Done well: _persisted_tag_write keeps the old retry and response on a failed save and still tells the caller whether the write landed. A test injects the failure at the inner write to prove it.

Optional:

  • Some docs this PR edits still contradict the head. rfc-session-tag-change-event.md lines 346 to 354 name _lane_dispatch_queue(), which does not exist. They also say the dispatcher has no request parameter and that "none emits yet". The README row and the RFC front matter say "not merged". memory-skills-hooks.md says a test pins the _VALID_HOOK_EVENTS absence, but none does, and it says deleting a status tag records a row. The HOOK_EVENTS comment in hooks.py says every event has a ScriptHookStore.fire call site, and kas_wire.py:242 says the map has one key per HOOK_EVENTS member. Fixing them all in one push avoids repeating docs: the merged SessionLaneChanged spec makes three claims #7669 no longer backs #13865.
  • hook_dispatch.py:432 writes an allowed SEL row before the prior == now filter runs. So a plain label edit records a lane decision even though no lane changed. Logging after the moves are computed would fix this.
  • steering-and-hooks.md:152 says "a dashboard user" fires the event. A shared-crew teammate's move is denied on purpose, and the doc could say so.

Related: #10931 models this event as pending and dormant. Whichever PR lands second has to reconcile the two.

@bolichen97

Copy link
Copy Markdown
Contributor

Continuing this in #32962; thanks for the start.

@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you for this work! As noted in the thread, it continued in #32962, which has now merged. Closing this one as superseded by #32962.

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

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants