Skip to content

fix: never run a hooks.json hook whose matcher is not text - #38798

Open
bolichen97 wants to merge 1 commit into
mainfrom
fix/37310-inert-non-text-matcher
Open

bolichen97 wants to merge 1 commit into
mainfrom
fix/37310-inert-non-text-matcher

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A hooks.json row whose matcher is not text no longer breaks the hooks around it: its command never runs, a PreToolUse call is refused with a reason that names the row, and every other hook keeps firing.

A row such as {"event": "PreToolUse", "matcher": ["Bash", "Write"], "command": "true"} (or "matcher": 3, or an object) loads as a live hook. From then on every tool call is refused with PreToolUse hook could not run: 'list' object has no attribute 'lower', and the healthy hooks of that event never run. On a message event such as Stop the same row breaks that event's hooks whenever there is text to match.

Why it matters

One malformed row refuses every tool call with a Python error that does not say which row to fix, and it silences every other hook on that event, deny gates included.

Not a goal

  • Reading a list as several matchers: that is a new matcher grammar.
  • Loading a PreToolUse row like this inert: that would drop a deny gate, so the call stays refused (maintainer decision on the issue).
  • Changing a falsy non-text matcher (null, 0, []): it is no matcher, as on main.
  • The Hooks page drawing an object matcher, which it cannot do on main either.

What changed (motivation → approach → change)

A hooks.json row whose matcher is a list, a number or an object no longer crashes the hooks of its event, and its command never runs. On PreToolUse the call is refused with a reason that names the row (bad: hook 'bad' has a matcher that is not text (list); fix it in hooks.json) instead of a Python error, and the event's other hooks run. On every other event the row is skipped. The row loads as written, a load warning names it, and a save keeps the matcher the operator wrote.

The cause: fire() folds a set matcher's case, which raises for a value that is not text, and the raise ended the whole event's fire.

ScriptHookStore.fire (hook_runtime/script_hooks.py) checks a set matcher's type before matching. A matcher it cannot read never reaches the spawn, because running the hook would widen it to every call. On PreToolUse it adds a failed result, which every PreToolUse gate already reads as a block (a gate with no verdict blocks); on other events the hook is skipped. _load_data logs the warning. The Script hooks section of memory-skills-hooks.md states the rule.

Backwards compatibility

Compatible: only a row with a set, non-text matcher behaves differently, and on main that row raised every time its matcher was read. Every text or falsy matcher loads and fires as it does on main.

Reader: src/kiro_crew/hook_runtime/hook_dispatch.py:permission_pre_tool_block -- subagent|cron|channel -- blocks on the row's failed result and returns its reason, where main blocked on the raise; test_non_text_matcher_never_runs_and_blocks_only_pre_tool_use
Reader: src/kiro_crew/dashboard/chat_turn/turn_spec_hooks.py:_fire -- chat -- turns the failed result into a BLOCKED: marker carrying its error (the fail-closed branch for any exit but 0 and 2), where main raised into the hook-error refusal
Reader: src/kiro_crew/hook_runtime/script_hooks.py:ScriptHookStore.fire -- chat|subagent -- a message-event row with such a matcher ran as match-all on main when the event had no text, and raised when it had some; it now never runs; test_non_text_matcher_never_runs_and_blocks_only_pre_tool_use (context="" and "done")
Reader: src/kiro_crew/hook_runtime/hook_dispatch.py:persisted_hook_store -- subagent|cron -- the row loads, so the strict read of the saved hooks is unaffected, as on main
Reader: src/kiro_crew/acp/kas_wire.py:normalize_script_hook -- chat -- already withholds a hook whose matcher is not a string; unchanged
Reader: src/kiro_crew/acp/kas_hook_coverage.py:hook_gated_capabilities -- chat -- already reads such a matcher as covering every tool, so each call reaches Crew's gate, which now refuses it with the named reason; unchanged
Reader: src/kiro_crew/hook_runtime/hook_dispatch.py:_run_one_lane_hook -- chat -- a SessionLaneChanged row with such a matcher already never ran (its own task raised); unchanged

Tests

test/test_hook_validation_parity.py::TestStoreLoadResilience::test_non_text_matcher_never_runs_and_blocks_only_pre_tool_use (list, number and object matcher): writes a PreToolUse row and a Stop row with that matcher beside a healthy Bash PreToolUse row, then checks that permission_pre_tool_block refuses Bash with the named reason, that Stop fires with and without text return nothing, that only the healthy hook runs, and that both rows keep their matcher in hooks.json after a save.

Proof: PROVEN test/test_hook_validation_parity.py::TestStoreLoadResilience::test_non_text_matcher_never_runs_and_blocks_only_pre_tool_use[matcher0], test/test_hook_validation_parity.py::TestStoreLoadResilience::test_non_text_matcher_never_runs_and_blocks_only_pre_tool_use[3], test/test_hook_validation_parity.py::TestStoreLoadResilience::test_non_text_matcher_never_runs_and_blocks_only_pre_tool_use[matcher2] (head f47ead078679)

Determinism: the new test 20/20 at -n0; the whole file 10/10 at -n 4 --dist loadgroup; the whole file once in a seeded shuffled order (seed 37310, 74/74). On the base source the new test fails all three cases: the list and the object on the .lower error, the number on argument of type 'int' is not iterable.

Manual verification

Reproduced and smoke-tested on Linux (Ubuntu 24.04.5 LTS, kernel 7.0, Python 3.12.3) in an isolated KIROCREW_HOME, on main 6911319 without and with this change. A driver wrote hooks.json (a bad PreToolUse row, a bad Stop row with the same matcher, then a healthy Bash PreToolUse row), built ScriptHookStore() and called permission_pre_tool_block(store, (), None, "Bash") and store.fire("Stop", ...). Each bad row's command writes a marker, so the table shows whether it ran. The healthy hook ran through the real sandboxed spawn: namespace backend, its own mount namespace, seccomp on, exit 0. The hooks HTTP routes ran against an isolated gateway on 127.0.0.1. No model is signed in on that host, so no chat turn was driven.

Variant main this PR
matcher ["Bash", "Write"], PreToolUse PreToolUse hook could not run: 'list' object has no attribute 'lower'; the healthy hook never runs bad: hook 'bad' has a matcher that is not text (list); fix it in hooks.json; the healthy hook runs; the bad command never runs
matcher 3 / {"tool": "Bash"} the same, with argument of type 'int' is not iterable / 'dict' the same, with (int) / (dict)
the same matcher on a Stop row with text: raises; with no text: the bad command runs both fires return nothing; the bad command never runs
GET /api/hooks, toggle good off and on lists all three rows; matchers kept lists all three rows; matchers kept; the load warning names each bad row
controls: matcher "Write", `"Write Bash", null, event FutureEvent` Write fires only for Write; `Write

Gates, on that host for this change on main 6911319: 65 of the project's 66 profile gates green, including the related-test runner's backend shard (1,184 passed) and its frontend shard (15,840 vitest tests), mypy, flake8 and isort; plus 673 tests across the eight hook test files, the flake-pattern ratchet (75 passed) and semgrep (0 findings). The one red, the bundle-size check, fails the same way on main itself (#39726, fix open in #39727); this PR changes no website/ file. This head sits on a later main, whose added commits change none of this PR's code or test files.

Real-machine verification

Machine: EC2 m7i.2xlarge, Ubuntu 24.04.5 LTS x86_64, 8 vCPU / 32 GiB, Python 3.12.3; a disposable verification host with no inbound rules, about 35 minutes for this job (about $0.23 on-demand)
Before (main 6911319): PYTHONPATH=<tree>/src KIROCREW_HOME=<fresh mktemp -d home> python drive.py <dir> V1 (the driver under Manual verification, list matcher) -> PreToolUse hook could not run: 'list' object has no attribute 'lower'; the healthy Bash hook never runs; fire("Stop", context="done") raises AttributeError and context="" runs the bad Stop row's command
After (this change on main 6911319): the same command -> bad: hook 'bad' has a matcher that is not text (list); fix it in hooks.json; the healthy hook runs in its own mount namespace under a seccomp filter and exits 0; both Stop fires return []; neither bad command runs. V2 (3) and V3 (an object) give the same with (int) and (dict)
Cleanup: the isolated homes, markers and the test gateway (stopped by its own PID, port closed) were removed; no key pair was made (session access only); the host is a pooled verification host still serving other jobs, which the pool terminates once idle

Related Issues

Closes #37310

Sibling sweep

Swept: git grep -nE "_tool_matches(hook.matcher|_context_matches, hook.matcher" -- src/kiro_crew
Sibling: src/kiro_crew/hook_runtime/script_hooks.py -- changed here
Sibling: src/kiro_crew/hook_runtime/hook_dispatch.py -- not affected -- _run_one_lane_hook evaluates one lane hook in its own task, so such a hook already never runs and the other lane hooks do
Sibling: src/kiro_crew/acp/kas_wire.py -- not affected -- normalize_script_hook withholds a hook whose matcher is not a string before select_hooks matches it
Sibling: src/kiro_crew/agent_sdk/spec_hooks.py -- not affected -- an agent spec hook with an invalid matcher is dropped at conversion

Pattern harvest

Not generalizable: every other reader of a hand-edited matcher already keeps such a hook from running (the agent spec loader and the KAS projection withhold it, and the lane dispatcher's per-hook task fails alone); this was the one reader whose raise took the whole event down.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 17, 2026 22:39
@bolichen97
bolichen97 requested a review from CrysisDeu November 17, 2026 22:39
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/hook_runtime/script_hooks.py

  • @bolichen97 comment: does not name the current head b5eb0d5; post it again for this head

How to clear this check:

  1. The PR author posts the template below as a PR comment, with
    every field filled (N/A needs a reason). Keep the
    Head commit line: it must name the current head SHA.
  2. The check turns green within a minute, with no push.
  3. A new push resets this check: post it again for the new head.

Only the author's comment counts this way. A reviewer can instead
paste the filled template into an "Approve" review on this head.
Merging still needs a reviewer's approval.

## Sensitive change review
- Head commit: b5eb0d5e7d703e1c66cac48b7ba3b7a75250a653
- What rule changed:
- Before -> after (what was allowed/blocked, now):
- Worst case if wrong (breaks commands / leaks secret / locks user out):
- Evidence checked (which sandbox result proves it):
- No regression:
  - Tools still work (which tools/commands were run, result):
  - Backward compatible (old config / old data / old callers still work, how checked):
  - Existing tests (which suites passed on this head):
- How to undo:

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision b5eb0d5e7d703e1c66cac48b7ba3b7a75250a653 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b5eb0d5e7d703e1c66cac48b7ba3b7a75250a653 — 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

The guard sits where the crash happens, in ScriptHookStore.fire. It keeps the deny gate fail-closed and doesn't affect the other hooks on the same event.

What this change ships

Inventory (5 items) — 5 justified

Intent: a hand-edited hooks.json row with a list, number or object matcher should stop breaking every tool call and silencing the other hooks on its event. This is a FIX.

  1. A PreToolUse row with a non-text matcher now refuses the call with a reason that names the row, instead of a Python error — justified
  2. The other hooks on that event run again — justified
  3. A non-PreToolUse row with a non-text matcher is skipped and never runs, including the no-text Stop fire that ran it as match-all on main — justified
  4. Loading the file logs a warning naming each such row; the row stays in the file and survives a save — justified
  5. The Script hooks spec section states the rule — justified

[FIRST-PRINCIPLES-REVIEWED] b5eb0d5

Description read

[DESCRIPTION-READ] 24b6454321e495c1f7a85fa1f97dfed081ea215ddd1c2f7b611de9ad7a0b7af4

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 Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b5eb0d5e7d703e1c66cac48b7ba3b7a75250a653 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The fix sits at the one place the event's fire raised, and failing closed on PreToolUse follows the maintainer decision cited in the description.

Notes

  • A PreToolUse row with a non-text matcher still refuses every tool call, now with a reason that names the row. The Hooks page cannot draw an object matcher, so a later change could show the load warning in the UI, so the operator can find the row without reading logs.

[DESIGN-REVIEWED] b5eb0d5

Description read

[DESCRIPTION-READ] 3369241a4b27c272c258b254eb4bf0046cccabee40a5a32fcb2e0e87c506116a

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 Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] b5eb0d5

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable b5eb0d5e7d703e1c66cac48b7ba3b7a75250a653 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of b5eb0d5e7d703e1c66cac48b7ba3b7a75250a653 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b5eb0d5

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b5eb0d5e7d703e1c66cac48b7ba3b7a75250a653 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- ✅ PASS

Which legitimate operations does b5eb0d5e7d703e1c66cac48b7ba3b7a75250a653 newly refuse? Updated in place on each push. A script-confirmed regression blocks; the model proposes candidates and never decides a refusal.

Verdict basis: adjudicated, zero confirmed regressions.

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 6 classified, 0 newly refused, 6 still allowed.
  • ubuntu-latest (platform posix): 6 classified, 0 newly refused, 6 still allowed.
  • windows-latest (platform windows): 5 classified, 0 newly refused, 5 still allowed.

No candidate flipped from allowed to refused.

Scope-Verdict: PASS

Reason: The tightening affects only stored script hooks whose matcher is truthy and not a string. Every matcher a person writes in the Hooks page, and every matcher the update path saves through str(...), is a string, so nothing it newly refuses is a legitimate operation I could name. The guard sits in ScriptHookStore.fire / load, not in the shell deny composite, so the classifier cannot measure it. That gap is named under UNADJUDICATED.

TIGHTENING: ScriptHookStore.fire used to match on any truthy matcher. It now refuses to run any hook whose matcher is truthy but not text, and a PreToolUse hook of that kind now blocks the tool call. The threat it refuses: a hand-edited hook that, run anyway, would apply to every call — if not isinstance(hook.matcher, str): ... if event == HOOK_EVENT_PRE_TOOL_USE: error = (f"hook {str(hook.id)[:64]!r} has a matcher that is not text " ...) results.append(ScriptHookResult(hook.id, hook.name, event, error=error)); continue.

ADJUDICATED: 11 candidates, 0 confirmed newly-refused

PLATFORM COVERAGE: The diff makes no assumption about paths, separators, interpreters or argv. It checks the type of a JSON value. I wrote posix rows (~/.kiro/crew/hooks.json reads, a validate, a jq lookup, a backup, the .venv/bin/python pytest run, a piped ls | wc -l) and matching windows rows (%USERPROFILE%\.kiro\crew\hooks.json with type/copy/python -m json.tool, .venv\Scripts\python.exe with \ test paths, dir /b | find /c /v ""). These rows only check that the operations an operator runs to find and fix a flagged row are still allowed by the unchanged shell gate. No platform's spelling is assumed by the guard and left unprobed.

UNADJUDICATED: The guard is the non-text-matcher check in src/kiro_crew/hook_runtime/script_hooks.py, in ScriptHookStore.fire with a matching warning at load.

  • Call path: ~/.kiro/crew/hooks.json → ScriptHookStore.__init__/load → ScriptHook.from_dict (keeps the raw matcher type) → fire(event, ...). On PreToolUse, the result goes to permission_pre_tool_block and becomes a block on every tool call.
  • Inputs I would have submitted, as prose:
    • A PreToolUse hook whose matcher is a list of tool names (["Bash", "Write"]), which someone used to another tool's hook format might write. It is now refused on every call, not just for the named tools.
    • The same shape on PostToolUse or Stop, which is now skipped silently apart from the load warning.
    • A matcher of JSON true, which is truthy and not a string, so it blocks every PreToolUse call.
    • A falsy non-text matcher (null, 0, [], {}), which is treated as no matcher and still runs on every call, exactly as before.
  • Narrowing to consider, not confirmed: one hand-edited PreToolUse row now stops every tool call in every session that loads the store. The narrower option would block only calls that one of the row's list entries would have matched, but that reads the list as alternatives, which the PR deliberately refuses to do.
  • Also not measurable here: the dashboard update path (matcher=str(data.get("matcher", hook.matcher) or "")) turns a list into its Python repr string. After an edit, the row stops blocking and quietly matches nothing.

[SCOPE-REVIEWED] b5eb0d5

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

Copy link
Copy Markdown
Contributor Author
  • span=c9eb4aef77b0 Superseding product decisions require explicit maintainer override

Rebutted: not a defect in this PR. git diff --name-only d15505809e1...9c1d626644b3 lists only docs/system-specs/modules/memory-skills-hooks.md, src/kiro_crew/hook_runtime/script_hooks.py and test/test_hook_validation_parity.py; nothing under website/ or docs/decisions/ changes.
The cited mateThreads = liveMateThreads(slots) (website/src/store/personSlots.ts:51 on the 26b0ee3 base the lane read) and the Bot-session, quiet-turn and conductor decisions reached main after this head's base through other PRs (#37713 and #37915 among them), so they are main's lines, not this diff's.
The lane's own adjudication flagged the same: this PR adds, edits or supersedes no decision entry, so there is nothing here for the supersession override gate to approve.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/37310-inert-non-text-matcher branch from 9c1d626 to 1997b4f Compare November 19, 2026 16:45
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/memory-skills-hooks.md and src/kiro_crew/hook_runtime/script_hooks.py since this head went green (d155058 -> 27cd6ac); CI re-running.

The change itself is unchanged: the new head 1997b4f carries the same patch as 9c1d626, with no conflict. The rebase also answers the earlier GPT 6.1 finding at website/src/store/personSlots.ts: those lines and the decisions it cited reached main after the old base, so they now sit in the base instead of being read as this diff. On the new head the hook tests and the backend related tests pass, mypy, black, isort and flake8 are clean, and the new test still fails with the fix reverted.

[operator: bolichen97]

@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 Nov 19, 2026
@bolichen97
bolichen97 force-pushed the fix/37310-inert-non-text-matcher branch from 1997b4f to 39b9b07 Compare November 19, 2026 20:11
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/memory-skills-hooks.md since this head went green (27cd6ac -> 983fd61); CI re-running.

The change itself is unchanged: the new head 39b9b07 carries the same patch as 1997b4f, with no conflict. The two Windows reds on the old head were main's flakes, and their fixes reached main after the old base: #39516 runs the Windows backend shards with 4 workers again and #39545 makes that test file's poll helpers wait on the lost-run bound (test_the_pass_fix_is_exported_to_the_pr_queue, #39485), and #39505 stubs the hook scan in the code-channel bar suite (test_the_bar_is_resent_only_when_its_items_change, #39566). Since the old base, main has changed none of this PR's code or test files; on the new head black, isort, flake8 and semgrep are clean on the changed files.

[operator: bolichen97]

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 20, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

Sensitive change review

  • Head commit: 39b9b07
  • What rule changed: a stored script hook in hooks.json whose matcher is set and is not text (a hand-edited list, number or object) never runs its command. On PreToolUse it refuses the call with a reason naming the row (a gate with no verdict blocks); on every other event it is skipped. The row still loads as written, with a load warning naming it, and a save keeps it. Text matchers and falsy matchers (null, 0, []) are unchanged.
  • Before -> after (what was allowed/blocked, now): ScriptHookStore.fire runs an event's hooks one at a time, in hooks.json order. Before, such a row made it raise when it reached that row: on PreToolUse and PostToolUse with an AttributeError on .lower, and on any other event fired with text with an AttributeError on .lower in the default glob mode, an AttributeError on .split in contains mode, or a TypeError in regex mode. A matching hook listed before the row had already run its command, no hook listed after it ran, deny hooks included, and the raise discarded every result. So every PreToolUse call was refused, through permission_pre_tool_block as PreToolUse hook could not run: 'list' object has no attribute 'lower'. Any other event fired with no text never checked the matcher, so the bad row's command ran as match-all. After, every PreToolUse call is still refused, now as bad: hook 'bad' has a matcher that is not text (list); fix it in hooks.json, the other hooks on the event run, and the bad row's command never runs on any event. Nothing that was refused becomes allowed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): an observer hook (Stop, PostToolUse, ...) with a non-text matcher that a user expected to run stays silent apart from the load warning. A PreToolUse row with a non-text matcher keeps refusing every tool call until the row is fixed, exactly as main does today, but with a reason that names the row. The change never runs the bad row's command. The only commands that newly run are the event's other configured hooks listed after the bad row (stored rows, then an agent spec's own hooks), which the raise had been skipping on PreToolUse, PostToolUse and any other event fired with text. So PostToolUse and Stop hooks listed after the row receive their tool output or event text again, and the fire's run bookkeeping is saved to hooks.json as on any fire that runs a hook. Those hooks go through the same matcher, governance checks and spawn as they do on main with no bad row in the file, so nothing outside the configured hooks gets a payload.
  • Evidence checked (which sandbox result proves it): on a disposable Ubuntu 24.04.5 LTS x86_64 host (Python 3.12.3), an isolated data home and a driver outside the tree wrote hooks.json with a bad PreToolUse row first, then a bad Stop row and a healthy Bash PreToolUse row, then called permission_pre_tool_block(store, (), None, "Bash") and store.fire("Stop", ...) with nothing patched. On the base the healthy hook, listed after the bad row, never ran and the call was refused with the .lower error; the Stop fire with text raised, and without text ran the bad Stop command. With this change (the same patch as this head, git patch-id identical), for a list, a number and an object matcher, the call is refused with the named reason, both Stop fires return nothing, neither bad command runs, and the healthy hook ran through the real sandboxed spawn (namespace backend, standard mode) in its own mount namespace, a different one from the driver's, with seccomp on (Seccomp: 2, one filter), and exited 0.
  • No regression:
    • Tools still work (which tools/commands were run, result): controls on the same host and driver gave identical results on base and with the change: a "Write" matcher fires only for Write, a null matcher fires as match-all, and a row with an unknown event is skipped and kept. Against an isolated gateway on 127.0.0.1, GET /api/hooks listed all three rows (200) and toggling the healthy hook off and on answered 200 twice, with the bad rows' matchers kept in the file.
    • Backward compatible (old config / old data / old callers still work, how checked): no row is dropped or converted at load or save (the bad rows' matchers were read back unchanged from hooks.json after a save); text and falsy matchers follow the unchanged path, pinned by the controls above.
    • Existing tests (which suites passed on this head): in CI on 39b9b07: Backend Tests (3.12, 8 shards), Backend Tests (Windows, 8 shards), Backend Tests (macOS, 8 shards), Backend Tests (namespace sandbox), Backend Tests (crew container), Backend Tests (IPv6, ubuntu and windows), Backend Lint & Type Check, Frontend Tests (4 shards), E2E (stub ACP backend; private member namespace), Integration (in-process gateway), E2E Gateway Boot (ubuntu, windows), Denial Differential and Security scope adjudication (ubuntu, macOS, windows), SAST (Semgrep), Flake Pattern Ratchet, New-test stability (ubuntu, windows) and Coverage Gate all passed. On the test hosts, the same patch passed 620 tests across the eight hook test files and every project gate.
  • How to undo: revert the single commit; there is no data or config migration. The change adds no conversion of hooks.json: it only logs a warning at load and has fire refuse (PreToolUse) or skip (any other event) the row, and a bad row's matcher stays as written through load and save.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 20, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 3: merge conflict.

ScriptHookStore.fire now checks for a set, non-text matcher before matching. On PreToolUse it adds a failed result with exit code -1 and from_spec=False, so pre_tool_blocks is True. Both gates refuse on it: permission_pre_tool_block blocks with the row-naming reason, and turn_spec_hooks._fire fails closed through its "exit not 0 or 2" branch. On other events the row is skipped, and because touched is not set, no hooks.json rewrite happens. The row still loads as written and a save keeps its matcher. Spec hooks cannot reach the new branch because conversion sets a non-text matcher to "". The new parametrised test fails on main and covers the block reason, that the healthy sibling hook still runs, the Stop skip with and without text, and save preservation. The docs are updated. I found no regression, fail-open path or missing test.

Tier: 3, held for a person: merge conflict.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 39b9b075f9 · 55 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

A hand-edited hooks.json row whose matcher is a list, a number or an
object loaded as a live hook, and fire() raised when it folded the
matcher's case. On PreToolUse the dispatcher turned that raise into a
block for every tool call with a Python error, and on any event the
raise stopped that event's other hooks.

Such a hook now loads as written, with a warning naming it, and a save
keeps the value the operator wrote. Its command never runs, since
running it would widen it to every call. On PreToolUse it blocks the
call with a reason that names the row, because a gate with no verdict
blocks; on every other event it is skipped. The event's other hooks
run.

Closes #37310
@bolichen97
bolichen97 force-pushed the fix/37310-inert-non-text-matcher branch from 39b9b07 to b5eb0d5 Compare November 20, 2026 01:52
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/memory-skills-hooks.md and src/kiro_crew/hook_runtime/script_hooks.py since this head went green (983fd61 -> ae93f16); CI re-running.

GitHub reported this PR as conflicting: main's #38686 (| matcher alternatives) rewrote the same spec paragraph and the matcher code right after this fix's check. The conflict was in that paragraph only, and both sentences are kept. The code and test hunks are unchanged, and the non-text check still runs before every matcher read, _hook_matcher_alternatives included. On a verification host, for this change on main 6911319: 65 of the 66 profile gates are green (the related backend tests, 1,184, and frontend tests, 15,840, among them), 673 tests across the hook test files pass, the proof re-ran PROVEN, and the smoke gives the same before and after. The one red there, the bundle-size check, fails on main too (#39726, a fix is open in #39727); this PR changes no website/ file, and its CI skips that lane.

[operator: bolichen97]

@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: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 20, 2026

This branch has not been deployed

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

Labels

readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

a hooks.json row with a non-text matcher blocks every tool call

2 participants