Configure
Hooks
A hook runs your own command (or an HTTP endpoint) at a fixed point in a run and hands back a
typed decision the engine acts on. Hooks are configured in a Claude Code settings.json /
hooks.json shape, so a hook you already wrote for Claude Code runs here unchanged.
The ten events
A hook is registered against one of ten events:
| Event | Fires |
|---|---|
PreToolUse | Before a tool runs — can deny it or rewrite its input. |
PostToolUse | After a tool returns. |
Stop | When a turn is about to settle — can continue the run instead. |
PermissionDenied | When a permission check refuses an action. |
UserPromptSubmit | When you submit a prompt — can add context, or block it: nothing is recorded or sent, Ocean TUI puts the prompt back at the front of the queue and opens its blocked-prompt card (Edit · Resend · Discard), and an editor gets a refusal with Not sent: a UserPromptSubmit hook blocked this prompt. and the hook's reason. A blocked prompt names no session; an accepted request's prompt that is blocked withdraws the request. |
SessionStart | When a session opens. |
SessionEnd | When a session closes. |
SubagentStop | When a spawned sub-agent settles. |
PreTide | Before the ledger cuts context out of the window (past the tideline). The old event name PreShelve still fires it as an alias. |
Notification | When a session waits for you (a permission or a question) or has settled — the payload's notification_type says which; a matcher tests it. See Notifications. |
PreToolUse and PostToolUse carry the tool_name, so a handler can scope itself to one tool.
The settings.json shape
Handlers live in a settings.json (or hooks.json) under the same keys Claude Code uses — the
event name maps to a list of hook groups, each group a matcher plus one or more handlers:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "./scripts/guard.sh", "timeout": 10 }
]
}
]
}
}A command handler is run through <shell> -c <command> (shell defaults to sh) in the
project directory, with the event payload as JSON on stdin and these variables on its
environment: OC_HOOK_EVENT (the event name), OC_PROJECT_DIR and CLAUDE_PROJECT_DIR (both
the project directory, so a Claude Code hook script that reads $CLAUDE_PROJECT_DIR works
unchanged). An http handler POSTs the payload to a URL with your headers. Hooks are discovered
as capabilities (see 09 · Capabilities and plugins) and, because they
execute on your behalf, they run only from a trusted source.
The payload is the Claude Code shape: every event object carries hook_event_name and cwd
(inserted only when absent, never overwriting a field the event already set); SessionStart
carries source: "startup", SessionEnd carries reason: "exit". A group's matcher is a
regex tested against tool_name for PreToolUse / PostToolUse / PermissionDenied, against
source for SessionStart, against reason for SessionEnd and against notification_type
for Notification; the other events ignore it.
An absent or empty matcher matches everything. One documented gap: session_id is not available
at the hook seam, so a handler that keys on it sees no such field — Notification is the
exception and carries it.
Notifications
Notification fires when a root session needs you or has stopped, so a hook can reach you
away from the terminal. A sub-agent's permission or question blocks the whole run, so it notifies
under its root session (the root's id, code, title and folder); a sub-agent's finished or stopped
turn never notifies. A turn you cancelled, or one that only yielded to background work it
started, does not notify either. The hook runs in the background and cannot block or change
anything: its exit code and output are ignored. With no Notification hook wired, none of this
work is done. A one-shot oceancode run or goal waits for its last notice before it exits, at
most 5 seconds.
Unlike Claude Code, where idle_prompt fires after about 60 seconds of idleness, here it fires as
soon as a root session's turn finishes, so a Notification hook without a matcher fires after
every turn; use the matcher permission_prompt|elicitation_dialog when you only want to hear when
a session waits for you.
Notification payload
| Field | Value |
|---|---|
notification_type | permission_prompt (a tool waits for your permission), elicitation_dialog (the agent asked you a question), idle_prompt (the turn finished and waits for your next prompt) or blocked (the run stopped on an error, a refusal or a bound). |
message | One line. A permission: the permission and its patterns, bash: git push origin main. A question: its first question. Idle or blocked: the first line of this turn's last reply, at most 300 characters (the … of a cut line included); a blocked turn that wrote no reply gives its stop reason (error, budget, …), never an earlier turn's text. |
session_id | The root session's id (a sub-agent's ask is reported under its root). |
session_code | The last four characters of the id, the code Ocean TUI shows. |
title | The session's title. |
cwd | The session's folder. |
hook_event_name is Notification. On every provider route, the claude CLI one included,
Notification dispatches every loaded hook source (the full table below), not only .oceancode/.
Recipe: Slack incoming webhook
Post every wait and stop to a Slack channel: create an incoming webhook in Slack, export its URL as
SLACK_WEBHOOK_URL in the shell that starts oceancode, and add to ~/.claude/settings.json:
{ "hooks": { "Notification": [ { "matcher": "permission_prompt|elicitation_dialog|idle_prompt|blocked",
"hooks": [ { "type": "command", "command": "jq -c '{text: \"#\\(.session_code) \\(.title): \\(.message)\"}' | curl -s -X POST -H 'Content-type: application/json' --data @- \"$SLACK_WEBHOOK_URL\"" } ] } ] } }jq builds the Slack body from the payload on stdin (#a1b2 Fix login: bash: git push origin main) and escapes it, so a quote in a message cannot break the JSON. Drop idle_prompt from the
matcher to hear only about waits and failures.
Where hooks are read from — and when they run
At boot (and on every reload) oceancode walks every ecosystem's hook files — its own
.oceancode/ and Claude Code's .claude/ — in this order, and merges
their groups per event, so earlier tiers' handlers run first:
| Source | Tier | Runs when |
|---|---|---|
.oceancode/hooks.json in the project | local | always — the local .oceancode/ tier is your machine's own copy, trusted. |
.claude/settings.json, .claude/settings.local.json in the project | repo | only when the project is trusted (oceancode trust repo on, or t in /hooks); otherwise held. |
~/.claude/settings.json | user | always — the user tier is trusted. |
<plugin>/hooks/hooks.json of an installed plugin | plugin | only when the plugin is enabled and trusted; ${CLAUDE_PLUGIN_ROOT} in its commands is replaced with the plugin's root. |
A held source is still parsed and listed — with its handlers — so you can see exactly what
trusting it would enable. The reasons are held: untrusted (repo tier, project not trusted),
held: disabled plugin, unreadable and invalid.
Since 2026-09-10 the three Claude Code settings files are also watched: saving one reloads the
hooks (the same path r in /hooks and POST /hooks/reload take) together with the
Claude Code settings mirror — no reload needed
after editing ~/.claude/settings.json.
On the claude CLI route there is no double firing. When a session's provider route is the
claude command-line protocol, the claude subprocess reads the very same ~/.claude/settings.json,
.claude/settings.json, .claude/settings.local.json and its installed plugins' hooks/hooks.json,
and runs those hooks itself. On that route oceancode therefore dispatches only its own
.oceancode/ hooks (the ocean_code ecosystem, local and user tiers) and leaves every Claude
Code-shared source to Claude Code — a UserPromptSubmit handler in .claude/settings.local.json
fires once per prompt, not twice. Every other route (Anthropic API, OpenAI-compatible, …)
dispatches everything in the table above, since nothing else would. Notification is the one
exception: it comes from oceancode's own notifier, not the turn, and dispatches every source on
every route. /hooks and GET /hooks
still list all sources on every route; the by-source report marks the shared ones
(shared_with_claude_code).
/hooks and oceancode hooks list
In Ocean TUI, /hooks opens the Hooks tab of the capabilities picker (toggle and reload go
through the engine); see 19 · Ocean TUI.
Without a session:
oceancode hooks list # one line per source, then its handlers indented
oceancode hooks list --json # {"repo_trusted": bool, "sources": [...]}
oceancode hooks add PreToolUse --matcher Bash --command ./scripts/guard.sh [--timeout 10] [--scope user|project|local]
oceancode hooks remove PreToolUse --matcher Bash --command ./scripts/guard.sh [--scope user|project|local]list ends with HOOKS_OK sources=<n> handlers=<m> loaded=<k>; add prints HOOK_ADDED <path>
and remove prints HOOK_REMOVED <path> (--scope defaults to project; remove of a handler
that is not there exits 1 with hooks remove: no such handler); --dir <d> and --home <h>
select another project or home. The scope names are Claude Code's: user, project and
local are the three files. Note that both project files — .claude/settings.json and
.claude/settings.local.json — are listed at tier repo: they live in the checkout, so they run
only when the project is trusted. (local the scope is Claude Code's name for the git-ignored
project file; local the tier is .oceancode/, your machine's private copy.) Over HTTP a client reads GET /hooks, reloads with
POST /hooks/reload, toggles repo trust with POST /trust/repo {"on": true|false}, adds with
POST /hooks {event, matcher, command, timeout?, scope} and removes with
POST /hooks/remove {path, event, matcher, target} — every one answers the same
{repo_trusted, sources} document.
The decision contract
A handler communicates back two ways: its exit code and a JSON object on stdout.
| Signal | Meaning |
|---|---|
exit 2 | Deny. On PreToolUse the tool does not run; on Stop it is a deny that does not count toward the Stop cap. |
| any other non-zero, or a spawn / timeout / IO error | No opinion — fail-open, the run proceeds. |
stdout hookSpecificOutput.permissionDecision | An explicit allow / deny / ask. |
stdout updatedInput | Rewrites the tool input before it runs. |
stdout additionalContext | Extra text folded into the model's context. |
stdout stopReason | On Stop, the reason the run should continue rather than settle. |
A handler may also return updatedToolOutput (honoured only for a model-visible copy)
and defer. Everything but an explicit deny fails open: a handler that crashes, times out or
prints garbage never wedges a run.
Only command and http handlers run here, and only the ten events above. A handler of another
type — Claude Code's prompt and agent hooks — or one registered under an event this runner does
not implement (Claude Code's PreCompact, SubagentStart, …) is skipped and
counted (skipped: <n> unsupported handlers beside the source in /hooks), never fatal: the other
handlers in the same file still load.
Continuing a Stop
A Stop handler that wants the run to keep going returns a stopReason — the engine treats that
as a continuation and drains again. To keep a runaway handler from looping forever, at most 8
Stop continuations are honoured per run; past that the run settles. An exit-2 on Stop is a
plain Deny and does not count against those 8.
Provenance and replay
Every hook outcome is recorded with its provenance — which source, which handler, what it
decided — so a run can be replayed and audited: you can see exactly which hook denied a tool or
continued a turn, and from which tier it came. oceancode inspect lists every hook source with
loaded or held beside it.
See also
- 09 · Capabilities and plugins — discovery, tiers, and the trust gate hooks depend on.
- 11 · MCP servers — the other trust-gated capability.
- 02 · Configuration —
OC_HOOK_EVENTandOC_PROJECT_DIR, set on every command handler. - 19 · Ocean TUI —
/hooksin the terminal UI. - 07 · Headless and server —
oceancode hooks listandoceancode trust.