Problem

There's no reliable built-in way to know when Claude Code finishes working — in either the VS Code extension or the terminal CLI. The Notification hook with idle_prompt matcher — which should be the canonical "done and waiting" signal — does not fire in VS Code (documented in #8985, #11156, #16114, #28774) and has been reported as unreliable in the terminal CLI as well (#8320, closed as NOT_PLANNED). This forces users to build fragile notification systems on top of the Stop hook, which fires on every response turn, not just genuine completions.

What users are building (and why it's painful)

The community has converged on increasingly complex workarounds:

• Time-based debouncing (sleep 3s, check if another Stop fires) — arbitrary, unreliable
• Transcript JSONL parsing in Stop hooks to find recent tool_use timestamps and suppress mid-loop notifications
• Shared cooldown files between Stop and TaskCompleted hooks to prevent double-tap notifications during agent team runs
• Regex content filters on last_assistant_message — fragile, can't anticipate every mid-workflow message
• LLM-as-classifier via type: "prompt" Stop hooks — adds latency and API cost per turn

Multiple repos exist just to solve this: ADAPT-Chase/claude-stop-hook, felipeelias/claude-notifier, dazuiba/CCNotify, wyattjoh/claude-code-notification. The OpenCode ecosystem has 3+ competing notification plugins. This is a gap in the core product.

Terminal CLI — additional pain points

For terminal users (our primary environment), the problems are compounded:

• No AskUserQuestion tool in CLI mode. When Claude has a question, it just outputs text ending with ? and the Stop hook fires. There's no distinct signal — you have to regex-match the last line to guess if it's a question vs a statement. The VS Code extension has the AskUserQuestion PreToolUse hook for this, but terminal users get nothing.
• Notification:idle_prompt was closed as NOT_PLANNED (60-Second Idle Notifications Not Triggering in Notification Hook #8320) for the terminal CLI. The 60-second idle timeout never fires. This means terminal users have zero first-class "Claude is done" signals — only the noisy Stop hook.
• No native terminal notification integration. Users must install third-party tools (terminal-notifier, notify-send) and wire them up manually. Other CLI tools like Aider have --notifications as a built-in flag that auto-detects the platform and sends native notifications. Claude Code could do the same.
• Agent team runs are especially noisy in terminal. With TaskCompleted and Stop both firing in rapid succession, and no visual distinction between a teammate status update and a genuine "I need your input" moment, terminal users end up building dedup logic with cooldown files just to avoid notification spam.
• Bell character (\a) would be a zero-dependency option. Many terminal emulators (iTerm2, kitty, WezTerm, Windows Terminal) can be configured to show a notification or bounce the dock icon on bell. Emitting \a when Claude genuinely finishes would require zero user setup and work across all platforms.

Proposed solution

1. Fix Notification:idle_prompt everywhere. Make it fire reliably in both the VS Code extension and the terminal CLI. This is the most impactful single change — the hook exists, the payload is designed, it just doesn't fire. If it worked, most of the workaround ecosystem would be unnecessary.

2. Add a completion_type field to the Stop hook payload that distinguishes:

   • "end_turn" — Claude finished and is waiting for user input (genuine idle)
   • "tool_pause" — Claude paused between tool calls in an agentic loop
   • "agent_update" — a teammate/subagent sent a status update

   This single field would eliminate the need for transcript parsing, debouncing, and cooldown files.

3. Built-in --notify flag for the CLI (like Aider's --notifications). Auto-detect platform, send native notification when Claude finishes or needs input. No hooks, no third-party tools. For terminal users this would be the simplest path.

4. Emit bell character (\a) on genuine completion. Zero-dependency, works with existing terminal emulator notification features (iTerm2 dock bounce, tmux monitor-bell, etc.). Could be behind a --bell flag or a setting.

5. Built-in notification support in the VS Code extension — a simple toggle in settings that sends a native VS Code notification when Claude finishes or needs input. No hooks, no scripts, no terminal-notifier. Cursor's community has been requesting this too (forum threads #32835, #56793, #100843).

6. Give terminal CLI a distinct signal for questions. Either fire a specific hook event when Claude's response ends with a question/prompt for the user, or add a needs_input boolean to the Stop hook payload. Currently terminal users have to regex-guess from last_assistant_message.

Environment

• Claude Code terminal CLI (primary) and VS Code extension
• macOS (but the Notification hook bug also affects Linux per 60-Second Idle Notifications Not Triggering in Notification Hook #8320)
• Using agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)