Skip to content

fix(hooks): open no windows hook console, document v2 prompt hooks - #33833

Merged
bolichen97 merged 1 commit into
mainfrom
fix/sweep-g6-spec-hooks
Nov 9, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/sweep-g6-spec-hooks

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On Windows no hook Kiro Crew runs opens a console window, whatever console the gateway has, and the hooks docs tell a user that on kiro-cli's v2 engine an agent spec's userPromptSubmit hook reads the whole prompt Kiro Crew sends, and what to use instead.

This PR bundles two hook fixes from one sweep.

1. A Windows hook's console window depended on how the gateway was started (defect 2 of #33527). run_script_hook spawned every hook with CREATE_NEW_PROCESS_GROUP only, and cmd.exe is a console program. A gateway that has a console (the desktop app, kirocrew restart, a terminal) hands it down, so no window opens. A gateway with no console (started by pythonw, or by a launcher that passes DETACHED_PROCESS) makes Windows create a new console for each hook. On the shell spawn only CPython's SW_HIDE hint hides it. The argv spawn, used once a sandbox wrapper wraps the hook, passes no such hint, so its window would show and could take the focus.

2. On kiro-cli's v2 engine an agent spec's userPromptSubmit hook does not get the typed message (#33821). kiro-cli runs that hook itself, on the whole text block Kiro Crew sends the model. On a session's first message that block holds the agent prompt, the critical rules, memory and session context: in the repro below the hook's prompt was 12,634 characters for a 51-character message. A hook Kiro Crew fires gets the message. The docs said none of this.

Why it matters

  • A PreToolUse hook fires on every tool call, so a console window per hook would flash, and could steal the focus, many times in one turn. With the flag, "no window" holds under any gateway launch and either spawn form, instead of resting on an inherited console or a show-window hint.
  • A user whose userPromptSubmit hook checks prompt (a keyword guard, a logger) on a Kiro CLI choice still on v2 matches text they never typed, and no doc explains why or names the fix.

Not a goal

What changed (motivation → approach → change)

Fix Change
Windows hook console (hook_runtime/script_hooks.py) no hook opens a console window under any gateway launch: both spawn forms pass CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW (platform_compat._SUBPROCESS_NO_WINDOW, 0 on POSIX)
kiro-cli v2 userPromptSubmit (steering-and-hooks.md, agent-spec-fields.md, the memory-skills-hooks spec) a user learns where a hook's prompt is their own message, where it is the whole prompt, and what to use instead

Windows. A hook Kiro Crew runs never opens a console window, however the gateway was started. A hook is a console program, so without a flag its window follows the gateway's own console. CREATE_NO_WINDOW gives cmd.exe a console with no window, which its own console children share, whatever console the gateway has. stdin stays the event-JSON pipe, and the process group keeps the hook tree reapable with taskkill /T. This covers every hook run_script_hook spawns: Hooks-page hooks, agent spec hooks Kiro Crew fires, and the dashboard's hook test. POSIX is unchanged. The spec's script-hook section says the same.

Docs. A user can tell from the hooks docs what a userPromptSubmit hook's prompt holds, and what to use when it is not their message; behaviour is unchanged. Under What a hook runs, steering-and-hooks.md says that in a dashboard chat, and on a channel turn that runs the Hooks page's hooks, prompt is the user's message with none of the agent prompt, rules or memory, and it names the two exceptions. Under kiro-cli hooks that survive an update it says when a session runs on v2, quoting the gateway's log line. It says what the spec hook reads on a first message, after a compaction and later, and gives the two remedies: a Hooks-page hook, or kiro-cli update so a Kiro CLI choice runs on KAS. The hooks row of agent-spec-fields.md and the memory-skills-hooks spec carry the same facts with their code paths.

Backwards compatibility

Compatible: _SUBPROCESS_NO_WINDOW is 0 on POSIX, so the spawn there is unchanged; a Windows hook keeps its stdin pipe, output, exit code, timeout and process group and only runs without a console window; the doc edits change no behaviour.

Removes nothing: no key, record, path or public function is removed; a Windows hook loses only a console window, which under the desktop app and kirocrew restart it already had hidden.

Tests

  • test_a_windows_hook_spawn_opens_no_console_window[shell] and [wrapped-argv] (test/test_script_hooks.py) give run_script_hook the platform view it has on win32, on any OS. They assert that each spawn form passes CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW, keeps stdin a pipe and delivers the event JSON.
  • TestKiroCliV2PromptHook (4 tests, test/test_steering_and_hooks_doc.py) pins the new paragraphs of steering-and-hooks.md. It checks that the quoted log line is in platform.bootstrap.KAS_CLI_FLOOR_KIRO_NOTICE, and that kiro-cli stays out of ACP_BACKENDS_CREW_FIRES_SPEC_OBSERVER_HOOKS, since the paragraph is true only while it does.

Runs on a Linux host at head 3fa112fac92b:

  • Changed test files, test/test_script_hooks.py and test/test_steering_and_hooks_doc.py: 80 passed.
  • Determinism (testing-conventions D12) for the six new tests: 20/20 green at -n0; 10/10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test/test_crew_fired_spec_hooks.py and test/test_kas_user_hook_files.py; and once in a seeded shuffled order of all 80 ids of the two files (seed 21705).
  • Related set, at -n 4 --dist loadgroup --max-worker-restart=2: 95 test files (every hook and spec-hook test, the tests that read the three docs, the flake-pattern ratchet, brand-name and file-line-cap tests), 3774 passed, 6 skipped.
  • Gates: black, isort and flake8 on the changed .py files, check_comment_history.py, check_brand_name.py, scripts/docs-lint.sh and test/test_flake_pattern_ratchet.py: all exit 0.
  • The full backend and frontend suites run in CI.
  • Rebased onto main after review; git range-diff shows the patch unchanged; related tests re-run on a DevSpace: at head 75d54ca8ff73, the 47 test files that exercise script hooks, spec hooks or the three changed docs, plus test/test_flake_pattern_ratchet.py, at -n 4 --dist loadgroup --max-worker-restart=2: 2011 passed; prove.py re-run at the same head: PROVEN.

Member repros, on the same host:

  • Windows hook console, on head 3fa112fac: a harness runs run_script_hook through its win32 code path and applies the documented Win32 console rules. Both spawn forms got creationflags=0x08000200 (CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP), stdin stayed a pipe and the event JSON was echoed, with no console window for a gateway with a hidden console, a terminal's console or none. Exit 0, CHECK: PASS.
  • kiro-cli v2 prompt hook, docs only, so the repro still reports the v2 behaviour (exit 1, as intended) on the group commit 99e684591: on v2, kiro-cli's own spec hook got a 12,634-character prompt holding [AGENT SYSTEM PROMPT] and [CRITICAL RULES]; on KAS the spec hook Kiro Crew fired got the 51-character message, and the Hooks-page hook got it on both engines. That is what the new docs describe.

Proof: PROVEN test/test_script_hooks.py::TestRunScriptHookSpawnForm::test_a_windows_hook_spawn_opens_no_console_window[shell], test/test_script_hooks.py::TestRunScriptHookSpawnForm::test_a_windows_hook_spawn_opens_no_console_window[wrapped-argv], test/test_steering_and_hooks_doc.py::TestKiroCliV2PromptHook::test_the_kiro_cli_section_states_what_the_hook_reads, test/test_steering_and_hooks_doc.py::TestKiroCliV2PromptHook::test_the_quoted_log_line_is_the_one_the_gateway_logs, test/test_steering_and_hooks_doc.py::TestKiroCliV2PromptHook::test_kiro_cli_is_still_the_one_running_the_spec_hook (head 75d54ca)

Manual verification

  • No Windows host was available. The win32 spawn is checked by the test above on every OS, and by the repro's harness, which applies the documented Win32 console rules. A run on real Windows is still open.
  • kiro-cli v2: observed in an isolated gateway with its own KIROCREW_HOME, bound to 127.0.0.1, on a Linux host, as in the repro above.

Screenshots / video

N/A: no frontend file changes; the diff changes a Windows spawn flag and docs.

Related Issues

Part of #33527
Fixes #33821

Sibling sweep

Swept: git grep -n "run_script_hook(" -- src/kiro_crew
Sibling: src/kiro_crew/hook_runtime/script_hooks.py:349 -- changed here
Sibling: src/kiro_crew/acp/kas_wire.py:924 -- not affected -- it runs the hook through run_script_hook, so the flag above applies
Sibling: src/kiro_crew/hook_runtime/hook_dispatch.py:519 -- not affected -- it runs the hook through run_script_hook, so the flag above applies
Sibling: src/kiro_crew/dashboard/handlers/hooks_scripts.py:352 -- not affected -- the hook test runs through run_script_hook, so the flag above applies
Swept: git grep -n "creationflags=platform_compat.CREATE_NEW_PROCESS_GROUP," -- src/kiro_crew
Sibling: src/kiro_crew/cli_server_restart.py:388 -- not affected -- the 42 console helpers that pass only CREATE_NEW_PROCESS_GROUP inherit the console every Kiro Crew launch gives the gateway (hidden from the desktop app and from this restart, #32087; the terminal's otherwise), and none of them runs a user's command on every tool call
Swept: git grep -n -i "userPromptSubmit" -- src/kiro_crew/docs docs/system-specs docs/guides
Sibling: docs/system-specs/modules/messaging.md:225 -- not affected -- it already says a spec UserPromptSubmit gets the prompt the backend receives and that kiro-cli runs the spec's hooks itself
Sibling: docs/system-specs/modules/agent-host-contract.md:721 -- not affected -- it lists which backend runs the spec's hooks, not what a hook's prompt holds

Pattern harvest

Not generalizable: the console-window class already has its chokepoint (#32087 gives the gateway Kiro Crew restarts a hidden console, and platform-compat.md names the flag), so a lint over the 42 helpers would flag sites that inherit that console; the docs gap is one engine's behaviour, which ends when kiro-cli removes v2.

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

- Windows: run_script_hook adds CREATE_NO_WINDOW to both spawn forms,
  so no hook Kiro Crew fires opens a console window that can take the
  focus, whatever console the gateway was started with.
- Docs: on kiro-cli's v2 engine an agent spec's userPromptSubmit hook
  reads the whole prompt Kiro Crew sends, not the typed message. The
  hooks docs and spec now say when that happens and name the remedies.
  Behaviour is unchanged.

Part of #33527
Fixes #33821
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 9, 2026 11:12
@bolichen97
bolichen97 requested a review from Zedmor November 9, 2026 11:12
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/hook_runtime/script_hooks.py

  • @buluoray: missing the ## Sensitive change review heading

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: 75d54ca8ff73159808b1374ded9363d58848b657
- 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 added the readiness: checking Automated validation is still running label Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 75d54ca8ff73159808b1374ded9363d58848b657 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 9, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 75d54ca8ff73159808b1374ded9363d58848b657 — 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 Windows flag reuses the existing platform_compat._SUBPROCESS_NO_WINDOW at the one spawn site that lacked it. The docs describe a defect the PR reproduces (#33821).

Not checked: how Win32 consoles behave for a gateway with no console of its own (Windows only).

Notes

  • Item 5 — oversized: TestKiroCliV2PromptHook asserts the absence of phrases the docs never shipped, such as "short Kiro Crew block" not in body, "never Kiro Crew's context" not in para and "the first after a compaction, carries the full" not in para. They pin wording from earlier review rounds and guard no shipped text. Subtraction: delete the five not in assertions and keep the positive sentence pins.

What this change ships

Inventory (5 items) — 4 justified

Intent: stop Windows hooks from opening console windows, and tell users that a kiro-cli v2 userPromptSubmit hook gets the whole prompt, not their typed message. FIX.

  1. On Windows, a hook spawned by either spawn form (shell or wrapped argv) no longer opens a console window, however the gateway was started — justified
  2. The steering-and-hooks "What a hook runs" section now says what prompt holds in a dashboard chat and on channel turns — justified
  3. The kiro-cli section now explains v2 userPromptSubmit behaviour, gives the log line that identifies v2, and names the two remedies — justified
  4. The hooks row of agent-spec-fields and the memory-skills-hooks spec now carry the same facts — justified
  5. Doc-pinning tests check exact sentences and also assert that rejected wordings are absent — oversized: the absence checks guard text that never shipped

[FIRST-PRINCIPLES-REVIEWED] 75d54ca

Description read

[DESCRIPTION-READ] 5cd9b222dd417ea11b88219266cb6e48210010649623f2363e0fbd7ab0b4f994

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 9, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the change reuses the repo's existing _SUBPROCESS_NO_WINDOW idiom on both hook spawn forms and leaves POSIX untouched. The doc additions describe behaviour without changing it.

Notes

  • The Windows repro ran on Linux and applied the Win32 console rules by hand. Running one real Windows hook once, with stdin piped and a gateway that has no console, would confirm CREATE_NO_WINDOW combined with cmd.exe children.

[DESIGN-REVIEWED] 75d54ca

Description read

[DESCRIPTION-READ] 4662dc7db05701653e9a6da4bf742eeb8d59bac7aba3235fc55f9be54c62ce24

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 9, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 75d54ca

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

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

@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 75d54ca

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 9, 2026 11:17
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Security Scope Review -- ✅ PASS

Which legitimate operations does 75d54ca8ff73159808b1374ded9363d58848b657 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): 7 classified, 0 newly refused, 7 still allowed.
  • ubuntu-latest (platform posix): 7 classified, 0 newly refused, 7 still allowed.
  • windows-latest (platform windows): 7 classified, 0 newly refused, 7 still allowed.

No candidate flipped from allowed to refused.

Scope-Verdict: PASS

Reason: Nothing in this change tightens the tool-call deny composite. The only code edit adds CREATE_NO_WINDOW to the Windows creation flags of the two hook spawns in run_script_hook, so a hook no longer opens a visible console window. That flag is 0 on POSIX. The rest of the diff is documentation and doc-pinning tests. None of the three shell tiers (sensitive-bash, exfil, deny-rules) changes, so no shell operation can newly be refused. The Windows spawn behaviour itself cannot be classified as a shell command and is named under UNADJUDICATED.

TIGHTENING: None in the deny composite. The only behaviour change is a Windows process-creation flag on hook spawns, not a refusal rule -- creationflags=platform_compat.CREATE_NEW_PROCESS_GROUP | no_console_window, in src/kiro_crew/hook_runtime/script_hooks.py. It refuses no operation; the issue it fixes is a console window that shows, and can take the focus, when the gateway has no console of its own.

ADJUDICATED: 14 candidates, 0 confirmed newly-refused

PLATFORM COVERAGE: The diff's only platform assumption is Windows, where the flag takes effect on both the cmd.exe shell spawn and the argv fall-through. On POSIX it is a no-op. I wrote paired posix and windows rows for the operations around this area:

  • reaping and inspecting a hook's process tree (taskkill /T against ps/killpg)
  • the dashboard hook test's trivial command (cmd /c against plain echo)
  • reading a standalone hook file (%USERPROFILE%\ with \ separators against ~/)
  • the kiro-cli update remedy (with the .exe name on Windows)
  • the gateway-log check for the v2 engine (findstr against grep)
  • running the new pytest pins (.venv\Scripts\python.exe against .venv/bin/python)

No row is marked any, because each one carries a path or an executable name. I could write a candidate for every platform the diff assumes.

UNADJUDICATED: The guard is the Windows hook spawn in hook_runtime/script_hooks.run_script_hook. Hooks-page hooks, an agent spec's extra_hooks and the dashboard's hook test all reach it. Both asyncio.create_subprocess_shell (the shell form) and sandbox.create_subprocess_limited (the argv form, when a wrapper changed the argv) now get CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW. This is a spawn flag, not a refusal, so the classifier cannot judge it. These are the inputs I would have submitted:

  • A Windows hook that expects a visible window. A hook command that opens its own console window (cmd /c start "" notepad.exe, or a console program meant to show the user output) would now run in a windowless console. GUI programs started with start still get their own window, so the likely loss is limited to hooks that relied on an inherited, visible console. That reliance only worked when the gateway itself was started from a visible terminal.
  • A hook that reads interactive console input. A hook that calls pause or set /p was already fed the event-JSON pipe on stdin, and the diff leaves stdin unchanged, so nothing new is lost there.

I cannot demonstrate a lost legitimate operation along this call path, so this is named rather than blocking.

[SCOPE-REVIEWED] 75d54ca

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

Approving. Both Windows hook spawn forms now pass CREATE_NEW_PROCESS_GROUP | _SUBPROCESS_NO_WINDOW, so hooks no longer flash a console window. The flag is 0 on POSIX, so POSIX is unchanged (hook_runtime/script_hooks.py:331, 356, 367; test/test_script_hooks.py:968). This follows the platform-compat.md rule for console helpers. The v2 userPromptSubmit doc additions change no behavior and are pinned by tests. Sensitive Change Review still needs the author's template.

@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 Nov 9, 2026
@bolichen97
bolichen97 merged commit bbfddbc into main Nov 9, 2026
108 of 110 checks passed
@bolichen97
bolichen97 deleted the fix/sweep-g6-spec-hooks branch November 9, 2026 12:29
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 9, 2026
bolichen97 added a commit that referenced this pull request Nov 9, 2026
…33833)

- Windows: run_script_hook adds CREATE_NO_WINDOW to both spawn forms,
  so no hook Kiro Crew fires opens a console window that can take the
  focus, whatever console the gateway was started with.
- Docs: on kiro-cli's v2 engine an agent spec's userPromptSubmit hook
  reads the whole prompt Kiro Crew sends, not the typed message. The
  hooks docs and spec now say when that happens and name the remedies.
  Behaviour is unchanged.

Part of #33527
Fixes #33821

Backport note: doc-only conflicts. memory-skills-hooks.md takes the
two new paragraphs without main's KIROCREW_SESSION_MODEL paragraph
(unreleased), and names release's drain_pending_context, which main
renamed take_turn_context. steering-and-hooks.md takes the v2 engine
paragraph without main's kiro-cli exit-code paragraph (unreleased).
agent-spec-fields.md adds main's one sentence to release's hooks row.
The script_hooks.py change and both tests apply as on main.

(cherry picked from commit bbfddbc)
bolichen97 added a commit that referenced this pull request Nov 9, 2026
…33833)

- Windows: run_script_hook adds CREATE_NO_WINDOW to both spawn forms,
  so no hook Kiro Crew fires opens a console window that can take the
  focus, whatever console the gateway was started with.
- Docs: on kiro-cli's v2 engine an agent spec's userPromptSubmit hook
  reads the whole prompt Kiro Crew sends, not the typed message. The
  hooks docs and spec now say when that happens and name the remedies.
  Behaviour is unchanged.

Part of #33527
Fixes #33821

Backport note: doc-only conflicts. memory-skills-hooks.md takes the
two new paragraphs without main's KIROCREW_SESSION_MODEL paragraph
(unreleased), and names release's drain_pending_context, which main
renamed take_turn_context. steering-and-hooks.md takes the v2 engine
paragraph without main's kiro-cli exit-code paragraph (unreleased).
agent-spec-fields.md adds main's one sentence to release's hooks row.
The script_hooks.py change and both tests apply as on main.

(cherry picked from commit bbfddbc)
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.

kiro-cli v2 runs a spec userPromptSubmit hook on the whole model prompt, and the hooks docs do not say so

2 participants