Hooks reference changedhooks
Nearest release: v2.1.321, published 2 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 9 Nov 2026 21:50 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 9 Nov 2026 22:07 UTC.
Upstream edited
Recorded here
Lines+13added
Lines−5removed
From line
1,085
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits136to this page, all time
#### Get terminal notifications inside tmux or GNU screen
The whole hunk
from line 1085, old and new numbered
/
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 1085
10851085
10861086#### Emit terminal notifications
10871087
1088Hooks run without a controlling terminal, so writing escape sequences directly to `/dev/tty` fails. Instead, return the escape sequence in the `terminalSequence` field and Claude Code emits it for you through its own terminal write path. This is race-free, works inside tmux and GNU screen, and works on Windows where there is no `/dev/tty`.
1088Hooks run without a controlling terminal, so writing escape sequences directly to `/dev/tty` fails. Instead, return the escape sequence in the `terminalSequence` field and Claude Code emits it for you through its own terminal write path. This is race-free and works on Windows where there is no `/dev/tty`.
10891089
10901090The field accepts a string of one or more allowlisted escape sequences:
10911091
from line 1097
10971097
10981098Sequences may be terminated with BEL or with ST. Anything outside the allowlist, including CSI cursor and color sequences, OSC palette sequences, OSC 8 hyperlinks, OSC 52 clipboard writes, and OSC 1337, is rejected and the field is ignored.
10991099
1100Claude Code writes the sequence itself when it processes your hook's output, so the field works on events that discard `systemMessage` and `continue`, such as `Notification` and `StopFailure`. It has two limits:
1100Claude Code writes the sequence itself when it processes your hook's output, so the field works on events that discard `systemMessage` and `continue`, such as `Notification` and `StopFailure`. It has some limits:
11011101
1102* Claude Code writes the sequence only in an interactive session, and only while its interface is on screen. In non-interactive mode with the `-p` flag and in the Agent SDK, it ignores the field.
1102* Claude Code writes the sequence only in an interactive session, and only while its interface is open. In non-interactive mode with the `-p` flag and in the Agent SDK, it ignores the field.
1103* The field works only from a hook that doesn't run in the [background](#run-hooks-in-the-background), so leave `async` and `asyncRewake` off.
11031104* A `WorktreeCreate` command hook can't return JSON, because Claude Code reads its stdout as the worktree path. An HTTP `WorktreeCreate` hook returns JSON and can include the field.
11041105
1105The example below fires a desktop notification from a `Notification` hook. The escape sequence is built with `printf` octal escapes so the control bytes never appear on the shell command line, and `jq -n --arg` builds the JSON output so quotes, backslashes, and newlines in the notification message are escaped correctly:
1106If you use tmux or GNU screen, complete [the setup for them](#get-terminal-notifications-inside-tmux-or-gnu-screen) first. The example below fires a desktop notification from a `Notification` hook in a terminal that reads OSC `777`, such as Ghostty or Warp. The script's `jq -nc --arg` call builds the JSON output and escapes any quotes, backslashes, and newlines in the notification message:
11061107
11071108```bash theme={null}
11081109#!/bin/bash
from line 1117
11161117
11171118The `{ "terminalSequence": "..." }` shape is the same from any shell or language.
11181119
1120#### Get terminal notifications inside tmux or GNU screen
1121
1122When Claude Code runs inside tmux or GNU screen, OSC sequences need the following to reach your terminal application:
1123
1124* **tmux 3.3 or later**: add `set -g allow-passthrough on` to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` from a shell. The option applies to every program in those panes, not only Claude Code. With `on`, only panes tmux is showing can send them. To let other panes in a session you're attached to send them too, use `all` in place of `on`, on tmux 3.4 or later.
1125* **GNU screen**: keep Claude Code's window showing in screen, because sequences from a background window don't reach your terminal application
1126
11191127#### Add context for Claude
11201128
11211129The `additionalContext` field passes a string from your hook into Claude's context window. Claude Code wraps the string in a [system reminder](https://code.claude.com/docs/en/glossary.md#system-reminder) and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it doesn't appear as a chat message in the interface.
from line 3725
37173725}
37183726```
37193727
3720This output declines a request:
3721
3722```json theme={null}
3723{
3724 "hookSpecificOutput": {
3725 "hookEventName": "Elicitation",
3726 "action": "decline"
3727 }
3728}
3729```
3730
3731In the dialog, selecting **Decline** sends `decline` and pressing `Esc` sends `cancel`, so return the one you want the server to see.
3732
3733For a URL-mode request, a hook that returns `accept` skips the dialog, so the URL never opens.
3734
3735Claude Code discards `reason`, `systemMessage`, and `continue` from an Elicitation hook's JSON output, whichever `action` you return.
3736
3737#### Other ways to decline an elicitation
3738
3739Your hook can also decline in these ways. The server receives the same `decline` as for `"action": "decline"`:
3740
3741* **Exits with code 2**: Claude Code ignores a `hookSpecificOutput` printed by the same hook
3742* **Prints a top-level `"decision": "block"`**: the block overrides an `action` in the same output
3743
3744When several hooks match the sam
3728This output declines a re
No line in this hunk matches that.