[FEATURE] UserInputChange hook — real-time input buffer events for live prompt tooling

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code's hook system covers the full session lifecycle — but there is a gap between session start and prompt submission: the moment the user is actively composing a prompt.

The existing UserPromptSubmit hook fires only after the user presses Enter. There is no hook that fires while the user is typing. This gap prevents an entire class of real-time input tooling that would otherwise be straightforward to implement.

Related prior request #11550 (closed) was scoped to pre-transmission preprocessing for privacy/sanitization. This request is distinct: it targets real-time, in-session input feedback while the prompt is being composed.

Proposed Feature

A new hook event: UserInputChange

Fires while the user is composing a prompt in the TUI input field, delivering the current input buffer contents to a user-defined handler.

Payload (stdin JSON)

{
  "hook_event_name": "UserInputChange",
  "session_id": "abc123",
  "input": "how do I refcator this functon",
  "cursor_position": 30,
  "change_type": "insert"
}

Handler output (stdout)

The hook can return structured JSON to influence the TUI:

{
  "suggestion": "how do I refactor this function",
  "annotation": "Did you mean: refactor, function?",
  "block": false
}

---

Implementation Options

Three delivery modes — pick one or make it configurable:

Option A — Debounced (recommended)

Fire after N milliseconds of typing inactivity. Default: 500ms, configurable.

"UserInputChange": {
  "command": "~/.claude/hooks/input-watch.sh",
  "debounce_ms": 500
}

Tradeoffs: Low overhead, feels natural, adequate for most use cases. Won't fire mid-word.

---

Option B — Per-word

Fire on each whitespace/punctuation boundary.

"UserInputChange": {
  "command": "~/.claude/hooks/input-watch.sh",
  "trigger": "word"
}

Tradeoffs: Natural breakpoints for NLP-based tools. More frequent than debounce but bounded by word rate.

---

Option C — Configurable (most flexible)

Expose trigger: "debounce" | "word" | "keystroke" and let users choose. Default to debounce to avoid performance issues.

"UserInputChange": {
  "command": "~/.claude/hooks/input-watch.sh",
  "trigger": "debounce",
  "debounce_ms": 300
}

Tradeoffs: Maximum flexibility. keystroke mode should be opt-in with a performance warning in docs.

---

Use Cases

1. Autocorrect / spell correction

Catch and suggest fixes for typos before submit. Technical terms and code identifiers can be allowlisted. The UserPromptSubmit hook can handle it post-submit, but real-time feedback is significantly better UX.

2. Live token / character counting

Display a running token estimate in an annotation as the user types. Helps users who are cost-conscious or working near context limits craft appropriately-sized prompts.

3. Sensitive data detection

Flag API keys, passwords, PII, or internal hostnames as they're typed — before they ever reach the network. Earlier than UserPromptSubmit and without requiring the user to submit first.

4. Prompt template expansion

Detect shorthand triggers (!debug, !pr, !explain) and expand them to full prompt templates inline, similar to text expanders — but context-aware and project-specific.

5. Live prompt quality feedback

Warn in real time when a prompt is likely too vague, missing file context, or doesn't match expected patterns (e.g. "you may want to @-mention a file"). Reduces the round-trip of submitting an underspecified prompt.

6. Dynamic autocomplete beyond / and @

Power custom autocomplete UIs — ticket IDs from Linear/Jira, function names from the current file, recent error strings from logs — surfaced as the user types.

7. Input history and fuzzy search

Build richer prompt history UX: fuzzy-search previous prompts as the user types, surface similar past prompts as suggestions.

8. Accessibility / input assistance

Assistive tools for users who benefit from real-time rewriting, word prediction, or input normalization.

---

Why this fits the existing hook architecture

• UserPromptSubmit already establishes that hooks can intercept user-generated content
• This is the natural earlier-in-lifecycle companion to that event
• It follows the same stdin JSON / stdout JSON pattern
• Debounced delivery means it doesn't require changes to the per-keystroke render path
• Handlers are user-supplied scripts — Anthropic doesn't need to ship any autocorrect logic itself

---

Priority

Medium — enables a class of tooling that currently has no viable native path.

Feature Category

Hooks / developer extensibility