Repository navigation
fix(hooks): open no windows hook console, document v2 prompt hooks - #33833
Conversation
- 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
Sensitive Change ReviewSensitive files changed:
How to clear this check:
Only the author's comment counts this way. A reviewer can instead |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The Windows flag reuses the existing Not checked: how Win32 consoles behave for a gateway with no console of its own (Windows only). Notes
What this change shipsInventory (5 items) — 4 justifiedIntent: stop Windows hooks from opening console windows, and tell users that a kiro-cli v2
[FIRST-PRINCIPLES-REVIEWED] 75d54ca Description read[DESCRIPTION-READ] 5cd9b222dd417ea11b88219266cb6e48210010649623f2363e0fbd7ab0b4f994 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change reuses the repo's existing Notes
[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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Security Scope Review -- ✅ PASSWhich legitimate operations does Verdict basis: adjudicated, zero confirmed regressions. Security scope review -- adjudicated candidates
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 TIGHTENING: None in the deny composite. The only behaviour change is a Windows process-creation flag on hook spawns, not a refusal rule -- 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
No row is marked UNADJUDICATED: The guard is the Windows hook spawn in
I cannot demonstrate a lost legitimate operation along this call path, so this is named rather than blocking. [SCOPE-REVIEWED] 75d54ca |
buluoray
left a comment
There was a problem hiding this comment.
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.
…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)
…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)
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
userPromptSubmithook 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_hookspawned every hook withCREATE_NEW_PROCESS_GROUPonly, 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 bypythonw, or by a launcher that passesDETACHED_PROCESS) makes Windows create a new console for each hook. On the shell spawn only CPython'sSW_HIDEhint 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
userPromptSubmithook 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'spromptwas 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
userPromptSubmithook checksprompt(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
CREATE_NEW_PROCESS_GROUP(the update check, app backends, builds). They inherit the gateway's console, and fix: give the restarted windows gateway a hidden console #32087 gives a restarted gateway a hidden one.call_toolarguments), which is a separate fix.What changed (motivation → approach → change)
hook_runtime/script_hooks.py)CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW(platform_compat._SUBPROCESS_NO_WINDOW,0on POSIX)userPromptSubmit(steering-and-hooks.md,agent-spec-fields.md, the memory-skills-hooks spec)promptis their own message, where it is the whole prompt, and what to use insteadWindows. 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_WINDOWgives 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 withtaskkill /T. This covers every hookrun_script_hookspawns: 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
userPromptSubmithook'spromptholds, and what to use when it is not their message; behaviour is unchanged. Under What a hook runs,steering-and-hooks.mdsays that in a dashboard chat, and on a channel turn that runs the Hooks page's hooks,promptis 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, orkiro-cli updateso a Kiro CLI choice runs on KAS. Thehooksrow ofagent-spec-fields.mdand the memory-skills-hooks spec carry the same facts with their code paths.Backwards compatibility
Compatible:
_SUBPROCESS_NO_WINDOWis0on 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 restartit already had hidden.Tests
test_a_windows_hook_spawn_opens_no_console_window[shell]and[wrapped-argv](test/test_script_hooks.py) giverun_script_hookthe platform view it has on win32, on any OS. They assert that each spawn form passesCREATE_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 ofsteering-and-hooks.md. It checks that the quoted log line is inplatform.bootstrap.KAS_CLI_FLOOR_KIRO_NOTICE, and that kiro-cli stays out ofACP_BACKENDS_CREW_FIRES_SPEC_OBSERVER_HOOKS, since the paragraph is true only while it does.Runs on a Linux host at head
3fa112fac92b:test/test_script_hooks.pyandtest/test_steering_and_hooks_doc.py: 80 passed.-n0; 10/10 at-n 4 --dist loadgroup --max-worker-restart=2besidetest/test_crew_fired_spec_hooks.pyandtest/test_kas_user_hook_files.py; and once in a seeded shuffled order of all 80 ids of the two files (seed 21705).-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..pyfiles,check_comment_history.py,check_brand_name.py,scripts/docs-lint.shandtest/test_flake_pattern_ratchet.py: all exit 0.75d54ca8ff73, the 47 test files that exercise script hooks, spec hooks or the three changed docs, plustest/test_flake_pattern_ratchet.py, at-n 4 --dist loadgroup --max-worker-restart=2: 2011 passed;prove.pyre-run at the same head: PROVEN.Member repros, on the same host:
3fa112fac: a harness runsrun_script_hookthrough its win32 code path and applies the documented Win32 console rules. Both spawn forms gotcreationflags=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.99e684591: on v2, kiro-cli's own spec hook got a 12,634-characterpromptholding[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
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
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)