Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

User hooks

A hook is a handler you configure to look at a tool call, a prompt or a moment in the life of a session. Hooks are how you add your own checks, rewrite arguments, keep a record and feed the agent context without changing Fontaine. They follow Claude Code’s hooks: the event arrives as JSON, the answer is JSON, and exit code 2 blocks. A hook can add context or block; it can never widen a permission, and a repository can only tighten.

A handler is a shell command, an http endpoint or a prompt put to the guardian’s model. Not every event takes every handler.

EventWhenWhat it can doHandlers
pre_tool_useAt the start of the pipeline, before the floor.Deny, ask or allow the call, rewrite its arguments, add a note for the guardian.command, http, prompt
post_tool_useAfter the tool ran and succeeded, in the result pipeline.Add a note to the result the agent reads.command, http, prompt
post_tool_use_failureAfter the tool failed.Add a note to the error the agent reads.command, http, prompt
permission_deniedWhen the pipeline denied the call.Say the agent may retry a call the guardian denied.command, http, prompt
task_createdBefore board_update creates a task.Block the create.command, http, prompt
task_completedBefore board_update completes a task.Block, keeping the task open.command, http, prompt
teammate_idleWhen an agent’s turn ends while it holds a task in progress on its parent’s board.Block, keeping the agent working.command, http, prompt
session_startWhen a session starts, after /clear and after a compaction.Add context for the next prompt.command
session_endWhen the session ends and before /clear.Nothing: it is told.command, http
user_prompt_submitWhen you send a prompt.Block the prompt, or add context to it.command, http, prompt
stopWhen the main agent’s turn ends with an answer.Keep the agent working.command, http, prompt
stop_failureWhen the main agent’s turn ends in an error.Nothing: it is told.command, http
subagent_startBefore a subagent first runs.Add context ahead of its task.command, http
subagent_stopWhen a subagent finishes a run.Keep the subagent working.command, http, prompt
pre_compactWhen a compaction is about to ask the model for a summary.Block it, or add focus to the summary.command, http
post_compactAfter a compaction saved its summary.Nothing: it is told.command, http
notificationWhen an approval or a question waits for you in the terminal UI.Nothing: it is told.command, http
elicitationWhen an MCP server asks for input, before any dialog, on every surface.Accept, decline or cancel the request.command, http
activity_changedWhen the session’s activity changes between active, waiting and idle.Nothing: it is told.command, http

In the terminal UI, /hooks lists the configured hooks by event with their type and scope, marks the ones that do not run and why, and names the events that have none.

Configuring hooks

[[hooks.pre_tool_use]]
matcher = "shell(git *)"
command = "/home/me/.config/fontaine/hooks/git-guard.sh"
timeout_secs = 10

[[hooks.post_tool_use]]
matcher = "edit"
command = "/home/me/.config/fontaine/hooks/format.sh"
KeyMeaningDefault
typecommand, http or prompt.command
matcherWhat the hook runs for; see Matchers.none: every call or every time
commandcommand hooks: the command line, run by the shell: sh -c (through Git Bash on Windows, found the same way as for the shell tool, including FONTAINE_GIT_BASH_PATH); the command reaches Git Bash as written, including every \\. On Windows without Git Bash it runs in PowerShell instead, and a pre_tool_use hook then fails closed: one that exits with anything other than 0 or 2, cannot start or times out denies the call with a reason saying so. Required for command.none
urlhttp hooks: the endpoint the event is POSTed to. Required for http.none
headershttp hooks: a table of extra request headers. $VAR and ${VAR} in a value expand only for variables named in allowed_env_vars; any other name becomes empty.none
allowed_env_varshttp hooks: the environment variables headers may read. It may not name a variable the shell tool’s scrub removes (an API-key variable of an account, a telemetry key, …): that is a startup error.none
promptprompt hooks: the question put to the model. $ARGUMENTS stands for the event; without it the event is appended. Required for prompt.none
timeout_secsAt least 1. A command hook that takes longer is cut off: its process tree is stopped, not just the shell (on Windows, a descendant started before the command joins its Job Object can escape).30; session_end has 1.5 seconds

A hook has exactly the fields of its type, and the event must take its type: anything else is a load error naming the key.

A hook without a matcher runs for every call and counts as broad, which matters for allow in auto (below). A tool matcher is matched the way a deny or ask rule is, failing toward matching, so a hook meant to tighten runs for every call it could concern; the commands run in the primary workspace root.

Matchers

EventsThe matcher selects on
pre_tool_use, post_tool_use, post_tool_use_failure, permission_deniedThe tool, in the Tool(specifier) rule form.
session_startstartup, resume, fork, clear or compact.
session_endclear, resume, prompt_input_exit or other.
stop_failureThe error kind: rate_limit, overloaded, authentication_failed, oauth_org_not_allowed, account_on_hold, billing_error, invalid_request, model_not_found, server_error, max_output_tokens, cloud_credential_error or unknown.
subagent_start, subagent_stopThe agent type name.
pre_compact, post_compactmanual (/compact) or auto (the threshold).
notificationpermission_prompt (an approval) or elicitation_dialog (a question).
elicitationThe MCP server’s name.
activity_changedThe new state: active, waiting or idle.
user_prompt_submit, stop, task_created, task_completed, teammate_idleNothing: a matcher is a load error.

Outside the tool events a matcher is a |-separated list of exact names; an omitted matcher, "" and * match everything. A name outside the event’s set is a load error; the agent type and MCP server name lists are open, so any non-empty names load.

Hooks come from any scope. Hooks of different scopes are all kept; the same hook defined twice is kept once, under the scope with more trust. No setting in a scope turns off the hooks of another.

What the hook receives

One JSON object on standard input:

FieldValue
session_idThe session id.
cwdThe primary workspace root.
hook_event_nameThe event’s name as Claude Code writes it: PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied, SessionStart, Stop, …
tool_nameFontaine’s tool name (shell, read, mcp__github__create_issue, …).
tool_inputThe call’s arguments.
tool_use_idThe model’s id for the call, when there is one.
agent_idroot, or the id of the subagent that made the call.
permission_modeThe mode the call is judged under, by its Fontaine name (manual, acceptEdits, dontAsk, auto).
workspace_rootsEvery workspace root, including the session’s scratch directory, which comes after the startup roots and before any /add-dir root.
tool_responsepost_tool_use only: {"is_error": false, "output": "..."}.
errorpost_tool_use_failure only: the error text the agent reads.
reason, tierpermission_denied only: why, and which part of the pipeline denied it.
mcp_server_name, message, mode, url, elicitation_id, requested_schemaelicitation only: the server, its message (untrusted text), form or url, the link (URL mode), the request id, and the form’s JSON schema (form mode).
reason, previous_state, activityactivity_changed only: why the snapshot changed, the state of the last snapshot delivered, and the complete activity object.

The task-board events send only session_id, cwd, hook_event_name and agent_id (for task_completed, the agent completing the task, which is not always its owner), plus their own field (see below): they carry no tool. The other lifecycle events send session_id, cwd, hook_event_name, agent_id, permission_mode and workspace_roots, plus their own fields (see Lifecycle events). An http hook gets the same object as the request body, and a prompt hook as data inside an untrusted block.

There is no transcript_path: Fontaine keeps no transcript file. The environment variable FONTAINE_PROJECT_DIR holds the primary root.

The hook runs with the same scrubbed environment as the shell tool: the variables named by api_key_env of any account, [telemetry] api_key_env, [guardian] scanner_hf_token_env, the MICROMEGAS_* family and the OTLP header variables are not passed. The entries of [env] are set on it, after that scrub and before FONTAINE_PROJECT_DIR.

What the hook answers

Every handler answers in the same shape. A command hook exits 0 and writes nothing (no opinion), one JSON object or, for the events that take it, plain text; an http hook answers 2xx with an empty body or one JSON object; a prompt hook is asked for a verdict. The object’s hookSpecificOutput holds the answer; hookEventName, when present, must name the event.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "no pushes on Fridays",
    "updatedInput": { "command": "git push --dry-run" },
    "guardian_context": "the user runs this hook to keep Friday releases quiet"
  }
}
EventFields
pre_tool_usepermissionDecision (allow, deny or ask), permissionDecisionReason, updatedInput (an object that replaces the call’s arguments), guardian_context (a note for the guardian).
post_tool_use, post_tool_use_failureadditionalContext, a string added after the tool’s result or error.
permission_deniedretry, a boolean. A command or http hook only; a prompt hook’s answer is discarded.
elicitationaction (accept, decline or cancel) and, for a form accept, content: an object of field values. See Elicitation.
the other eventsSee Lifecycle events.

Any handler can also block with {"decision": "block", "reason": "..."}. Exit code 2 blocks too, with the hook’s standard error as the reason. A pre_tool_use block is a deny; for post_tool_use the reason is added to the result, since the call already ran. Any other exit code, a non-2xx status, a connection error or an unreadable answer is a non-blocking error: the hook decides nothing and the call goes on through the normal pipeline.

A systemMessage string in the answer is shown to you as a warning, on every event except notification, session_end, stop_failure, pre_compact and post_compact. The fields continue, stopReason, suppressOutput and terminalSequence are ignored: a hook never ends the turn.

Text a hook adds for the model (additionalContext, plain standard output, a block reason fed back to the agent) is cut at 10,000 characters with a marker, where Claude Code saves the rest to a file.

Elicitation

An elicitation hook runs when an MCP server asks for input (see Requests for input), before any dialog, in the terminal UI, headless runs and AFK mode alike; with none configured nothing changes. A hook answers accept (with content for a form), decline or cancel; exit code 2 and {"decision": "block"} decline.

[[hooks.elicitation]]
matcher = "my-server"
command = "/home/me/.config/fontaine/hooks/answer.sh"
{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": { "name": "Ada" }
  }
}
  • Several hooks combine as cancel beats decline beats accept. A hook that fails, times out or answers something unreadable decides nothing and is reported as a warning, so the request goes on to the dialog (or, unattended, to cancel).
  • A hook from the repository or a plugin can decline or cancel, but its accept is ignored with a warning: only your own config can answer for you.
  • A hook never accepts a URL-mode request. The link opens only after you confirm it in the terminal UI; a hook’s decline and cancel are honored.
  • A form answer is still checked against the server’s schema; one that does not fit is sent as decline.
  • Requests a subagent’s call causes, and links that are not http or https, are handled before the hook and never reach it.

How hooks compose and where they sit

  • pre_tool_use runs first. If several hooks answer, deny beats ask beats allow. The last updatedInput in configured order wins, and the rewritten call is what every later step judges: the floor, the pre-classifier, the rules, the guardian and the audit log, which records the digest of the original arguments too.
  • A matcher is checked against the call the model made. A read-only shell command such as cat src/private/x does not run a hook matching read(...), ls or grep; instead any such hook takes shell reads off the pre-classifier fast path, so they reach the allow rules and the mode (an allow rule in dontAsk, a prompt in manual mode, the guardian in auto).
  • deny denies the call. ask forces the human prompt like an ask rule (a denial in dontAsk and headless runs).
  • allow is an allow rule, no more. It acts after the floor and never past it: a deny rule, an ask rule or a protected path still stands. It also only counts where an allow rule’s matcher would match, so a shell(git *) hook does not allow ls && git push. In auto a hook with a narrow matcher skips the guardian, and a hook with a broad one (no matcher, or one that is a suspended allow rule) is suspended and the guardian decides; Claude Code honors a broad hook, so this is stricter. An allow stands only for the arguments the hook saw: if a later hook rewrites the call with updatedInput, the allow is dropped and the call takes the normal path (a hook that rewrites and allows in one reply allows its own rewrite).
  • guardian_context is shown to the guardian inside an untrusted block, as a note and never as an instruction.
  • post_tool_use runs last in the result pipeline, after anything that screens tool results, and its additionalContext lands after the tool’s output. It fires only for a call that succeeded; a failed call fires post_tool_use_failure, which adds to the error the agent reads. Background job output reaches them like any result.
  • permission_denied runs for every denial the pipeline makes, whatever the mode. A hook’s retry: true makes the denied call run once if the agent sends exactly the same call again, as /denied followed by r does, and the agent is told so. It can only do that for a call the guardian denied: the floor and the mode have no retry to give, so for them the hook only gets to hear about it.

Every subagent tool call runs the same hooks.

Task boards: task_created, task_completed and teammate_idle

These three events are quality gates for task boards and exist only while [agents] teams is on (the default). They are configured like the others, without a matcher, which is rejected at load because the events have no tool name:

[[hooks.task_completed]]
command = "/home/me/.config/fontaine/hooks/tests-green.sh"

[[hooks.teammate_idle]]
command = "/home/me/.config/fontaine/hooks/anything-left.sh"
timeout_secs = 20
EventFiresExtra inputA block
task_createdBefore board_update create takes the board lock.task (the task object without id, which the create assigns), and Claude Code’s task_subject, task_description and teammate_name.The task is not created and the reason is the error the agent reads.
task_completedBefore board_update complete takes effect on any board, with no board lock held.task: the task object (id, title, description, status, owner, blocked_by, created_by).The task stays in progress and the reason is the error the owner reads.
teammate_idleAfter an agent’s turn ends while it owns an in-progress task on its parent’s board, before it is marked idle and before its report is delivered. It never fires for an agent holding no such task.teammate_name (the agent’s name).The agent is resumed with the reason as feedback instead of going idle. It is a gate on unfinished work and never hands out new work.

The answer is Claude Code’s: exit code 2 (or decision: "block", or a prompt hook’s ok: false) blocks and the reason is what the agent reads. A hook has no allow answer; nothing it says can loosen anything, it can only add work, and a JSON answer of allow is ignored. Several hooks run in configured order and the first to block decides.

  • A failing gate does not block. A hook that cannot start, exits with another code, or runs past its timeout warns you once and blocks nothing: these are quality gates, not security gates, and one that failed closed forever would wedge the agents.
  • A gate that always blocks is bounded. A teammate_idle block resumes an agent at most three times in a row without the board that holds its task changing (a create, claim, complete or release on it resets the count), then it goes idle with a warning.
  • Where they may come from. Your user config, --settings and plugins can define both. A repository’s task_completed hook loads like its other hooks (after workspace trust, and it counts in the trust prompt) and can only keep a task open. A repository’s teammate_idle hook is ignored with a warning, because forcing more model calls is spend, not tightening. A plugin’s hooks.json names the events TaskCreated, TaskCompleted and TeammateIdle; a matcher on them is ignored.

Handler types

Command handlers

The default. The command runs with the event on standard input and answers with exit code and standard output, as above.

HTTP handlers

[[hooks.session_end]]
type = "http"
url = "https://hooks.example.com/fontaine"
headers = { Authorization = "Bearer $HOOK_TOKEN" }
allowed_env_vars = ["HOOK_TOKEN"]

The event is POSTed as the JSON body with Content-Type: application/json and your headers, on a client that follows [network]. Only the variables named in allowed_env_vars expand in a header value; any other $NAME becomes the empty string, so a hook cannot read the rest of your environment. A 2xx answer with an empty body has no opinion, and one with a JSON object is the answer. Any other status, a connection error, a timeout or a body that is not a JSON object is a failure that decides nothing. An http hook sends session data off your machine, so a repository cannot define one (see below).

Prompt handlers

[[hooks.stop]]
type = "prompt"
prompt = "Did the agent run the tests after its last edit? $ARGUMENTS"

A prompt hook is one question to the guardian’s model, so it forces model spend and a repository cannot define one. $ARGUMENTS in the prompt is replaced by the event, as data in an untrusted block that the model is told never to obey; without it the event is appended. The model answers { "ok": bool, "reason": string, "impossible": bool }. ok: false blocks, with the reason, through the event’s usual block path; ok: true has no opinion and never allows anything. For stop and subagent_stop, impossible: true lets the agent stop: what the prompt asks cannot be met by more work. The usage counts with the guardian’s. A model that is unavailable, slow or unreadable is a failure that decides nothing. There is no model key: it runs on the guardian’s model.

Lifecycle events

Context a hook adds is delivered as a harness note, [Hook context from <event>, not the user's words: ...], in the next model request. It is never recorded as something you said, so a hook can never become the intent the guardian reads.

EventFiresExtra inputA hook can
session_startAfter the session starts, after /clear (clear) and after a compaction that saved (compact). The source is startup, resume, fork, clear or compact.source, modelWrite additionalContext or plain standard output: it goes ahead of the next prompt. After an automatic compaction it is added to the very request that triggered it.
session_endWhen the terminal UI ends (prompt_input_exit, or resume when it switches session), before /clear (clear), and when a headless run ends (other).reasonNothing. It has 1.5 seconds. On a quit it starts after the session’s work has been cancelled and shares the two-second exit budget with the rest of the cleanup, so it can be cut off earlier than its own timeout.
user_prompt_submitWhen you send a prompt: typed, a skill line, /goal <condition>, /init, the first /loop iteration, or a headless -p prompt.promptBlock (the prompt is not sent and nothing is recorded; the reason is shown to you), or add context with additionalContext or plain standard output.
stopWhen the main agent’s turn ends with an answer, before a /goal evaluation.stop_hook_active, last_assistant_messageBlock, or add additionalContext: the agent works on, with the reason as a harness note.
stop_failureWhen the main agent’s turn ends in an error.error (the kind), error_details, last_assistant_message (always empty: Fontaine has no answer text for a failed turn)Nothing.
subagent_startBefore a subagent’s first run, with agents on or off.agent_typeWrite additionalContext: it goes ahead of the subagent’s task.
subagent_stopWhen a subagent finishes a run, after its mail is read and before teammate_idle.stop_hook_active, agent_type, last_assistant_messageBlock or add additionalContext: the subagent is resumed with the reason.
pre_compactWhen a compaction has something to summarize, just before the model is asked. Nothing fires when the conversation is under the threshold.trigger, custom_instructions (the /compact focus, or null)Block (the compaction is skipped, with a warning), or write plain standard output, which is added to the summary request as Additional focus: ....
post_compactAfter the summary was saved.trigger, compact_summaryNothing.
notificationWhen an approval or a question starts waiting for you in the terminal UI, whatever [tui] notify is set to. It runs in the background.message, title, notification_typeNothing.
activity_changedWhen the session becomes active, waiting or idle; see below. It runs in the background.reason, previous_state, activityNothing.

A user_prompt_submit hook does not fire for turns Fontaine starts itself (a scheduled task, a subagent’s report, a goal or stop continuation), for text you steer a running turn with, for text typed to a subagent, or for the free-text “Other” answer to a question.

In a headless run, a blocked user_prompt_submit ends the run before any model call with exit code 0 and a success result: the block message followed by Original prompt: <the prompt>.

Session activity: activity_changed

stop fires when the model’s turn ends, which is not when the instance is idle: a twenty-minute background test may still run. activity_changed fires when the session’s activity changes, so a program that schedules work can tell the two apart. It is a new, Fontaine-only event with no Claude Code equivalent, and, like notification, observational: it takes command and http handlers, decides nothing and its output is ignored. It runs in the background, never delaying the turn or the job that changed the state.

Every payload carries the complete snapshot in activity, so a consumer needs no history:

FieldMeaning
session_idThe session id.
seqIncreases with every published change. A gap between two deliveries means snapshots in between were skipped.
stateactive, waiting or idle; the matcher selects on it.
turn_runningA root turn, its end-of-turn work (the stop hooks, a goal evaluation) or a turn on a notification is under way.
waiting_on_humanThe main agent is blocked on a permission prompt, an ask_user_question dialog or an MCP elicitation, or a running subagent is blocked on a permission prompt.
running_agentsSubagents whose status is running, those waiting on a permission prompt included.
running_background_jobsBackground shells and monitors still running.
running_monitorsThe monitors among them.
pending_notificationsNotes some surface will deliver and none has yet.
queued_promptsMessages you typed (or a connected host sent) that wait behind the running turn.

A dialog you opened yourself, such as a login or a plugin command, counts as active, not waiting: only a prompt that blocks an agent sets waiting.

waiting when waiting_on_human: some agent cannot progress until a person answers, which a scheduler must tell from busy. It wins over active even while jobs run. Otherwise active when any of turn_running, running_agents, running_background_jobs, pending_notifications or queued_prompts is non-zero, and idle when none is. A run with nobody to answer (plain -p, or AFK mode) never reports waiting: a question there resolves to a denial.

Not counted: an idle subagent (its turn ended; mail for it counts as pending), a scheduled task or wake-up that has not fired, and a goal waiting between check-ins. Notes no surface will deliver are not pending either: while AFK mode is stopped or paused by the denial breaker, held notes stay out of the count and return to it when AFK resumes. The terminal UI starts a turn on a job’s note by itself, so the session stays active until that turn ends. A headless -p run, Agent SDK mode and an embedded Session read a note with the next message instead, so a note that arrives between messages leaves the state idle.

The payload also carries reason, the cause of the transition: waiting_changed, turn_started, turn_ended, agent_started, agent_ended, job_started, job_ended, notification_queued, notification_delivered, queue_changed, clear (a /clear or a conversation /rewind) or shutdown; and previous_state.

Deliveries are serial and latest-wins: one hook run at a time, and while it runs only the newest snapshot waits, so a slow hook never reorders or backs up and the last state is always delivered. Intermediate states can be skipped. reason and previous_state are relative to the last snapshot delivered, not the last one published, and a skipped snapshot’s reason is dropped (a clear survives a skip). A burst of changes that returns to the state it started from delivers nothing.

When the session ends, one more delivery with reason shutdown goes out before session_end, after the agents and jobs were stopped, so the final snapshot reads idle. It is always delivered, even when nothing differs, and waits for any delivery in flight. It has at most 1.5 seconds (a slice of the exit’s budget on a quit), so a slow hook cannot delay session_end. A callback an Agent SDK host registered misses this transition when the session ends by the host closing stdin, since the host cannot be called back by then.

# Tell a scheduler the instance is free.
[[hooks.activity_changed]]
matcher = "idle"
type = "http"
url = "http://localhost:8080/instances/main/idle"

A repository may define a command hook for it, as for any event that forces no model calls. A plugin can register it, and so can an SDK callback as ActivityChanged. The terminal UI’s custom status line receives the same object as activity.

Loop bounds

A stop or subagent_stop hook that keeps blocking is let go after 8 continuations in a row, with a warning, and the turn or the agent ends. An agent that made tool calls since the previous stop is working, not looping, and starts the count again; so does a prompt you send. The input field stop_hook_active is true on every continuation after the first.

On a turn’s end the stop hooks run first; only when none blocks does a goal evaluation run.

Failure never loosens

A hook that cannot start, exits with a code other than 0 or 2, runs past its timeout, or writes anything but the JSON above decides nothing. It cannot make a call run that would not have. The failure of a pre_tool_use, post_tool_use, post_tool_use_failure or permission_denied hook is only logged to the debug file; the failure of any other event’s hook warns you. Hooks are your own processes, so the pipeline does not gate them, and they are not tool calls.

Hooks a repository defines

Hooks in .fontaine/settings.toml or .fontaine/settings.local.toml are executables the repository chose:

  • In the terminal UI they start only after you trust the workspace; see Workspace trust. A headless run loads them without asking, as Claude Code’s -p does, unless [headless] require_trust = true and the workspace is not trusted.
  • They can only tighten. A repository hook’s allow and its retry are ignored; its deny, ask, updatedInput, guardian_context and additionalContext work as for any hook. An untracked settings.local.toml of a trusted root is your own file, and its hooks’ allow counts.
  • http and prompt hooks and the events that force model calls are ignored. A repository’s http or prompt hook, and its stop, subagent_stop and teammate_idle hooks, are ignored with a warning at startup: they send session data off your machine or spend model calls, and a repository may only tighten. Claude Code loads them.
Where the hook is definedcommandhttp, promptstop, subagent_stop, teammate_idle
Your user config, --settingsrunsrunsruns
An untracked settings.local.toml of a trusted rootrunsrunsignored
.fontaine/settings.tomlafter workspace trustignoredignored
A pluginrunsrunsruns

activity_changed forces no model call, so a repository’s command hook for it loads like any other event’s; its http hook is ignored, like every repository http hook.

Hooks a plugin defines

A plugin’s hooks/hooks.json loads as hooks and starts without the workspace-trust gate: install approved them, http and prompt hooks included. They can only tighten, like a repository’s hooks: their allow and retry never count, while deny, ask, updatedInput, guardian_context and additionalContext work as usual. Claude Code’s matchers over tool names map to Fontaine rules where they can; an un-mappable matcher skips its hook entry with a warning. Plugins lists what loads and what is skipped.

A plugin’s hooks are a layer of their own: /plugin install, /plugin update, /plugin enable and /reload-plugins in a running session load, replace or remove them for every event, without a restart, while your own and your project’s hooks stay as they were at startup. The floor order is unchanged, and a plugin hook’s allow and retry still never count. A plugin loaded this way does not run its session_start hooks, since that event already happened in this session; they run at the next session. See Plugins.

SDK callback hooks

An application using Agent SDK mode registers hooks as callbacks in initialize. Fontaine runs one by sending hook_callback with the JSON a command hook gets on stdin, and reads the reply as a command hook’s output. A Claude matcher such as Write|Edit is split on |, each name mapped to a Fontaine tool; a name that cannot be mapped fails initialize, and an empty or * matcher runs for every call. The timeout is the matcher’s, or the command-hook default. When a callback fails or times out, onFailure: block denies the call, with a reason that says so; otherwise it is a non-blocking error.

ActivityChanged registers like any other event, with an optional active, waiting or idle matcher.

Callbacks only tighten, like a repository’s hooks: deny, ask and updatedInput count, and an allow is ignored, unlike Claude Code’s PreToolUse allow. Events with no equivalent here fail initialize, naming the event. A callback cannot be declared in a settings file.

What is not built

  • Events: PermissionRequest (an allow there would answer the human prompt, a second way to loosen next to pre_tool_use), Setup, UserPromptExpansion, PostToolBatch, MessageDisplay, InstructionsLoaded, ConfigChange, CwdChanged, DirectoryAdded, FileChanged, WorktreeCreate, WorktreeRemove, PreModelSwitch, PostModelSwitch and ElicitationResult. A plugin that names one loads with a warning.
  • Handler types: agent and mcp_tool. An mcp_tool hook would call a tool outside the per-call gate. A plugin hook of those types is skipped with a warning.
  • Handler fields: args, if and shell: "powershell" skip a plugin’s hook with a warning; async, asyncRewake, onFailure, statusMessage and once are ignored.

Spans

Each run of a hook is a fontaine.hook span with the hook_event, the hook_type and whether it succeeded. The tool events’ spans sit under the fontaine.permission span of the call; the lifecycle events have no such parent. See Telemetry.