Bug: Windows 11: hook's process-snapshot PowerShell flashes a visible terminal window despite windowsHide:true (Windows Terminal default-terminal delegation)

[Schlaflied]

Symptom

A blank PowerShell/terminal window flashes on screen intermittently while working in Claude Code with Clawd on Desk installed. Unlike #586/#605 (taskbar-icon-only, fixed by #587), this is an actual visible console window. #596 may be the same root cause showing as a milder symptom.

Environment

• Windows 11 Home 10.0.26200, default terminal application = "Let Windows decide" (i.e. Windows Terminal on current Win11 builds — HKCU\Console\%%Startup absent)
• Clawd on Desk build installed 2026-07-01, Claude Code CLI, hooks registered per the standard install
• Node.js v25.5.0 (C:\nodejs → nvm junction)

Forensics (Windows 4688 process-creation audit, command line included)

Every Claude Code hook event fires clawd-hook.js, which calls getWindowsProcessSnapshot() in hooks/shared-process.js — one PowerShell spawn per resolve:

22:05:11  powershell.exe  PARENT: claude.exe        CMD: ...node clawd-hook.js PreToolUse     ← hidden, fine
22:05:12  powershell.exe  PARENT: node.exe (hook)   CMD: powershell -NoProfile -NonInteractive -Command "...ClawdWin32 typedef + Get-CimInstance Win32_Process..."   ← THIS one flashes

Over 48h of normal use this snapshot spawn fired 600+ times.

Root cause

shared-process.js correctly passes { windowsHide: true } (→ CREATE_NO_WINDOW) to execFileSync. But on Windows 11, when the OS-level default terminal application delegates console hosting to Windows Terminal, WT's takeover path does not always honor CREATE_NO_WINDOW — the spawned conhost/WT window becomes briefly visible (timing/cold-start dependent, which is why it's intermittent rather than every event). This is a known WT-side behavior (microsoft/terminal delegation issues), so Clawd's code is technically correct and still flashes.

Confirmed on this machine: the flash correlates 1:1 with the snapshot spawn timestamps in the 4688 log, not with the Electron hit-window path fixed in #587.

Suggested fixes (any of these would do)

1. Reuse a long-lived helper instead of a cold PowerShell per hook event — the comment in shared-process.js already notes the ~270 ms PS cold-start dominates; a persistent resolver (or short-TTL snapshot cache shared across consecutive hook events) would fix both the flash exposure and the perf issue tracked in follow-up #331: state hook reliability, startup sync deferral, Windows PID resolution perf #350.
2. Move the snapshot into the compiled sidecar (cc-connect-clawd already ships as a native exe) — a GUI-subsystem or truly windowless native binary can't flash regardless of WT delegation.
3. At minimum, document the workaround: setting Windows' default terminal application back to "Windows Console Host" makes CREATE_NO_WINDOW honored again and the flashes disappear.

Happy to test a patched build on this machine — the 4688 audit setup here makes before/after verification easy.

[Schlaflied]

⚠️ Warning to readers + @rullerzhou-afk: the comment above from rogamusa40 (no prior activity in this repo, posted ~1 minute after the issue opened) attaches an unsolicited zip (clawd_fix_v2.zip). Do not download it. This is the second time today one of my issues got hit by this exact pattern — a fresh account replies within minutes with an LLM-generated message that paraphrases the issue text (here it even rewords my own suggested fix #1 as "I already implemented this") plus a zip payload. Same campaign hit a career-ops issue earlier today (santifer/career-ops#1684) from a different throwaway account with the same naming pattern.

I've reported the account to GitHub. @rullerzhou-afk please consider deleting the comment so nobody grabs the file — and given this repo's size, a pinned note telling users to never download zip attachments from unknown accounts in issues might be worth it. Real fixes come as PRs, not zips.

[rullerzhou-afk]

Thank you for this — it's one of the most useful reports I've gotten. The 4688 process-creation audit with command lines is exactly the evidence that makes this diagnosable, and cleanly separating it from #586/#605/#587 (the taskbar-icon path) and pinning it to the snapshot spawn rather than the Electron hit-window path saved me a lot of triage.

I went through the code and can confirm your root cause end to end:

• getWindowsProcessSnapshot() (hooks/shared-process.js) does spawn powershell.exe per resolve, and it does pass windowsHide: true — so the code is technically correct and the flash is on the Windows Terminal side, exactly as you described.
• That snapshot runs once per resolve(), and resolve() is called for every hook event in the non-remote path (hooks/clawd-hook.js). The resolver's cache (_cached) only lives inside a single Node process, and every hook event is a fresh node clawd-hook.js process — so the cache never survives across events. PreToolUse/PostToolUse are registered with an empty matcher (= every tool call), so that's one cold PowerShell per tool call. Your "600+ in 48h" is fully consistent.
• Your 4688 also matches the code on the two-spawn structure: the outer powershell.exe (parent claude.exe) is Claude Code's own hook wrapper (shell: "powershell"), and the inner one (parent node.exe) is this snapshot. Your data showing the outer one staying hidden and only the inner one flashing lines up — and the inner one is the part this repo can actually fix.

Direction I'm taking: your suggestion #1 — collapse the per-event spawns with a cross-process cache in the shared resolver. That's the right lever because it also closes the ~270 ms cold-start cost tracked in #350, and because the same resolver is shared by every agent integration (Cursor, Copilot, Gemini, Codex, Kimi, …), so one fix covers all of them rather than Claude Code alone.

Two refinements I hit while scoping it, in case they're useful to you too:

• The cache can't reuse the whole resolve() result. pid_chain isn't stable across events: because the hook is launched through that per-event powershell.exe wrapper, and powershell.exe is itself in the terminal-name set, the ephemeral wrapper PID lands in pid_chain (and can even shift source_pid when no outer terminal is matched). So the cache has to keep only the stable parts (agent PID, terminal PID, detected editor), key by session, invalidate on session start/end, and re-verify the cached PID's identity before trusting it — a bare kill(pid, 0) reachability check can't tell you the PID wasn't reused. The high-frequency events (PreToolUse/PostToolUse/Stop) then read the cache and don't spawn at all; UserPromptSubmit still needs a live foreground-window read, but that's low-frequency.

On your other two suggestions:

• Moving it into cc-connect-clawd (feat: add macOS platform support #2): I don't think that one fits. That sidecar is the Telegram/IM approval bridge — a long-lived process alongside the Electron app, not something the hook invokes per event, and it has no line into the hook's own process ancestry. The instinct (compute it in a windowless native process) is right, but that particular binary is the wrong vehicle.
• conhost.exe --headless: I looked at this as a smaller targeted patch and tested it locally — it returns 0 but doesn't forward the command's stdout (only VT control sequences come back), and the snapshot needs to JSON.parse that stdout, so it isn't a drop-in wrapper for the spawn. Whether it even bypasses the WT default-terminal delegation would still need real-machine verification. So I'm not pursuing it as the quick fix.
• Documenting the "default terminal = Windows Console Host" workaround (feat: add macOS support (Intel x64 + Apple Silicon arm64) #3): good interim, and it's actually half-there already in docs/guides/known-limitations.md (currently framed around tab focus). I'll sharpen it to cover the flash.

One thing I'd like to confirm with your rig once I have a build: that after the inner-snapshot fix the flash is fully gone. Your 4688 already suggests the outer CC wrapper stays hidden, but your before/after setup is the cleanest way to be sure there's no residual. I'll ping you with a patched build to test — thank you for offering.

Thanks again. This was a genuinely great report.

[rullerzhou-afk]

Fixed — PR #630.

I went with your suggestion #1 (the cross-process cache). The process tree is stable within a session, so the snapshot now runs once on the always-fresh events (SessionStart / UserPromptSubmit) and the high-frequency events (PreToolUse/PostToolUse/Stop) read a per-session cache instead of cold-starting PowerShell. The tool-call burst — which was the main surface of the flash — no longer spawns at all, and it also closes the ~270 ms cold-start cost in #350.

A few things that came out of review and are worth noting, since they shaped the final shape:

• The cache stores only the stable subset (terminal PID, agent PID, editor). It deliberately does not cache pid_chain — its head is that per-event ephemeral PowerShell wrapper — and the server merges a missing pid_chain (keeps the last one), so omitting it on cached events is safe.
• It only caches a non-degraded snapshot: the resolver now reports whether the Windows snapshot actually succeeded, so a transient snapshot failure can't poison the whole session's cache.
• On a cache hit, the PID that becomes source_pid is liveness-checked (a zero-spawn kill(pid, 0)), so a stale/reused PID falls back to a fresh resolve rather than shipping downstream.

It's Windows-only; mac/linux are untouched.

This isn't in a release yet — I'll ping you here once it ships so you can run the before/after on your 4688 rig and confirm the flash is fully gone (your audit setup is the cleanest way to be sure there's no residual from the outer CC wrapper). Keeping this open until then.

Thanks again — the forensic report made this straightforward to land.