The hook entry point

How a session tells the daemon what it is doing. A hook runs one small command that writes a few named fields to disk and exits, whatever happens.

On this page

What a hook is #

Claude Code runs commands of your choosing at fixed points in a session: when it starts, when you send a prompt, when it stops to ask permission, when a turn ends. It hands each command a JSON description of the event on standard input.

nucleated hook is the command Nucarium registers at those points. It does three things and nothing else:

  1. Reads the event.
  2. Writes one small file to the spool, built from a fixed list of fields.
  3. Exits 0.

It does not talk to the network and does not need the daemon. The daemon sends the note later, from the spool. So a hook costs a session a few milliseconds, and a dead daemon or an unreachable Watch costs it nothing.

Register the hooks #

Print the block:

Boxas agent
nucleated hooks print
Output
{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "nucleated hook SessionStart", "async": true, "timeout": 5 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "nucleated hook UserPromptSubmit", "async": true, "timeout": 5 }] }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt|agent_needs_input|elicitation_dialog|elicitation_url_dialog|elicitation_complete|elicitation_response",
        "hooks": [{ "type": "command", "command": "nucleated hook Notification", "async": true, "timeout": 5 }]
      }
    ],
    "PostToolUse": [
      { "hooks": [{ "type": "command", "command": "nucleated hook PostToolUse", "async": true, "timeout": 5 }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "nucleated hook Stop", "async": true, "timeout": 5 }] }
    ],
    "StopFailure": [
      { "hooks": [{ "type": "command", "command": "nucleated hook StopFailure", "async": true, "timeout": 5 }] }
    ],
    "SessionEnd": [
      { "hooks": [{ "type": "command", "command": "nucleated hook SessionEnd", "timeout": 5 }] }
    ]
  }
}

Merge that hooks block into the user settings of the login the environment uses: ~/.claude/settings.json, or settings.json in the folder that login's CLAUDE_CONFIG_DIR names. Keep any hooks already there. nucleate's worktree hooks live in a different file, in the nucleus, and are not affected.

Then restart the agent server so new sessions pick the hooks up. Sessions already running keep the hooks they started with.

Boxas agent
systemctl --user restart agent-server@client-a.service

Every hook is a command hook, on purpose. An http hook would post the whole event to a URL, and some events carry content: a Stop event includes the agent's reply. A command hook lets nucleated choose what to keep before anything is written, let alone sent.

What each event becomes #

Claude Code event Sent as The session becomes
SessionStart session_start Idle
UserPromptSubmit user_prompt_submit Working
Notification · permission_prompt permission_prompt Needs input
Notification · idle_prompt, agent_needs_input input_prompt Needs input
Notification · elicitation_dialog, elicitation_url_dialog elicitation_prompt Needs input
Notification · elicitation_complete, elicitation_response activity Working
PostToolUse activity, only when the session was not already working Working
Stop stop Idle
StopFailure stop_failure, with the kind of error Failed
SessionEnd session_end Ended

Three rows need a word.

idle_prompt is how an agent that stopped to ask you something becomes a session that needs you. Claude Code raises it about a minute after a turn ends, if nobody has typed since. A turn that ends is Idle; a turn that ended a minute ago with nobody answering is Needs input. Watch never learns what the agent said, only that it finished and is waiting.

PostToolUse is how a session leaves "needs input" after you grant a permission in the vendor's app: the tool ran, so the agent is working again. It fires on every tool call, and the hook writes each one down, but the daemon forwards a note only when it changes the session's status. A busy session sends nothing extra.

SessionStart also fires when a session compacts its context. That is not a new session, so it is sent as activity.

What is kept from an event #

From everything Claude Code passes, the entry point keeps these and discards the rest:

Sent as From
event_id Made on the box when the note is written.
env_id The environment's name in the config.
session_id The hook's session_id.
bridge_session_id The CLAUDE_CODE_BRIDGE_SESSION_ID environment variable, when the agent sets it. This is the vendor's own id for the session.
type The table above.
repos The session's repos, as owner/name from each remote, or the folder name where there is no such remote.
branch The session's branch.
error_kind The hook's error, for StopFailure only, and only when it is a short fixed word such as rate_limit.
client_ts The box's clock.

Each value is checked against the shape Watch accepts before it is written down. One that does not fit is left out.

The hook's cwd is read to find the session's repos and branch, and goes no further. Never read, never written to disk, never sent: prompt, message, title, last_assistant_message, tool_input, tool_response, transcript_path, compaction summaries, error details, and every other field. They are not removed from a copy of the event. The note is built field by field from the list above, so they are never in it.

A test proves it on every release. It feeds every hook event a payload with a sentinel string in every content-bearing field, in the working directory's path and in the environment, and fails if a sentinel is in the spool, in the daemon's records, or in any request the daemon makes.

The environment #

A hook has to know which environment it belongs to. It works that out in order:

  1. --env NAME on the command line, if you registered it that way (nucleated hooks print --env client-a writes it into every command).
  2. The environment whose config_dir matches the CLAUDE_CONFIG_DIR the hook was run with.
  3. The environment whose root holds the session's folder.
  4. The only environment configured.

A hook that matches no environment does nothing and exits 0.

How it fails #

It doesn't, as far as the session can tell.

  • Any error (no config, a full disk, an event it does not understand) ends in exit code 0 and nothing printed.
  • It gives up after two seconds. Nothing in it should take that long, but a hung disk can.
  • The hooks are registered as async, so Claude Code does not wait for them. SessionEnd is the exception: it runs as the session is closing, when an async hook might not get to run, and the entry point is fast enough to finish in the short time Claude Code allows there.

Try one by hand #

You can feed the entry point an event yourself. Stop the daemon first, so the note stays where you can read it. This event carries a sentinel where a prompt would be:

Boxas agent
systemctl --user stop nucleated.service
printf '%s' '{"session_id":"test-1","hook_event_name":"UserPromptSubmit","cwd":"/home/agent/workspace/.worktrees/fix-login/web","prompt":"SENTINEL-DO-NOT-FORWARD"}' | nucleated hook UserPromptSubmit; echo "exit $?"
Output
exit 0

Read the note it wrote:

Boxas agent
cat ~/.local/state/nucleated/spool/*.json
Output
{
  "event": {
    "event_id": "019ab3f2-6d1c-7e4a-9b0f-3c2d1e0f4a5b",
    "env_id": "client-a",
    "session_id": "test-1",
    "type": "user_prompt_submit",
    "repos": ["your-org/web", "your-org/api"],
    "branch": "workspace/fix-login",
    "client_ts": "2026-11-19T02:41:07.120Z"
  },
  "at_ms": 1795056067120,
  "workspace": "fix-login"
}

The sentinel is not there. event is what is sent. The other two stay on the box: at_ms orders the notes, and workspace is the session folder's name, which nucleated status shows and Watch never receives. Delete the test note and start the daemon again:

Boxas agent
rm ~/.local/state/nucleated/spool/*.json
systemctl --user start nucleated.service

Other agents #

The workspace model and the event envelope are the same for every agent. What differs is the hook names and how they are registered, and that lives in one adapter per agent. agent = "claude-code" in an environment's config selects the adapter, and <event> on the command line is always that agent's own name for the event.