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.
| Event | When | What it can do | Handlers |
|---|---|---|---|
pre_tool_use | At 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_use | After the tool ran and succeeded, in the result pipeline. | Add a note to the result the agent reads. | command, http, prompt |
post_tool_use_failure | After the tool failed. | Add a note to the error the agent reads. | command, http, prompt |
permission_denied | When the pipeline denied the call. | Say the agent may retry a call the guardian denied. | command, http, prompt |
task_created | Before board_update creates a task. | Block the create. | command, http, prompt |
task_completed | Before board_update completes a task. | Block, keeping the task open. | command, http, prompt |
teammate_idle | When 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_start | When a session starts, after /clear and after a compaction. | Add context for the next prompt. | command |
session_end | When the session ends and before /clear. | Nothing: it is told. | command, http |
user_prompt_submit | When you send a prompt. | Block the prompt, or add context to it. | command, http, prompt |
stop | When the main agent’s turn ends with an answer. | Keep the agent working. | command, http, prompt |
stop_failure | When the main agent’s turn ends in an error. | Nothing: it is told. | command, http |
subagent_start | Before a subagent first runs. | Add context ahead of its task. | command, http |
subagent_stop | When a subagent finishes a run. | Keep the subagent working. | command, http, prompt |
pre_compact | When a compaction is about to ask the model for a summary. | Block it, or add focus to the summary. | command, http |
post_compact | After a compaction saved its summary. | Nothing: it is told. | command, http |
notification | When an approval or a question waits for you in the terminal UI. | Nothing: it is told. | command, http |
elicitation | When an MCP server asks for input, before any dialog, on every surface. | Accept, decline or cancel the request. | command, http |
activity_changed | When 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"
| Key | Meaning | Default |
|---|---|---|
type | command, http or prompt. | command |
matcher | What the hook runs for; see Matchers. | none: every call or every time |
command | command 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 |
url | http hooks: the endpoint the event is POSTed to. Required for http. | none |
headers | http 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_vars | http 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 |
prompt | prompt hooks: the question put to the model. $ARGUMENTS stands for the event; without it the event is appended. Required for prompt. | none |
timeout_secs | At 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
| Events | The matcher selects on |
|---|---|
pre_tool_use, post_tool_use, post_tool_use_failure, permission_denied | The tool, in the Tool(specifier) rule form. |
session_start | startup, resume, fork, clear or compact. |
session_end | clear, resume, prompt_input_exit or other. |
stop_failure | The 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_stop | The agent type name. |
pre_compact, post_compact | manual (/compact) or auto (the threshold). |
notification | permission_prompt (an approval) or elicitation_dialog (a question). |
elicitation | The MCP server’s name. |
activity_changed | The new state: active, waiting or idle. |
user_prompt_submit, stop, task_created, task_completed, teammate_idle | Nothing: 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:
| Field | Value |
|---|---|
session_id | The session id. |
cwd | The primary workspace root. |
hook_event_name | The event’s name as Claude Code writes it: PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied, SessionStart, Stop, … |
tool_name | Fontaine’s tool name (shell, read, mcp__github__create_issue, …). |
tool_input | The call’s arguments. |
tool_use_id | The model’s id for the call, when there is one. |
agent_id | root, or the id of the subagent that made the call. |
permission_mode | The mode the call is judged under, by its Fontaine name (manual, acceptEdits, dontAsk, auto). |
workspace_roots | Every workspace root, including the session’s scratch directory, which comes after the startup roots and before any /add-dir root. |
tool_response | post_tool_use only: {"is_error": false, "output": "..."}. |
error | post_tool_use_failure only: the error text the agent reads. |
reason, tier | permission_denied only: why, and which part of the pipeline denied it. |
mcp_server_name, message, mode, url, elicitation_id, requested_schema | elicitation 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, activity | activity_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"
}
}
| Event | Fields |
|---|---|
pre_tool_use | permissionDecision (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_failure | additionalContext, a string added after the tool’s result or error. |
permission_denied | retry, a boolean. A command or http hook only; a prompt hook’s answer is discarded. |
elicitation | action (accept, decline or cancel) and, for a form accept, content: an object of field values. See Elicitation. |
| the other events | See 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
acceptis 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
declineandcancelare 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
httporhttps, are handled before the hook and never reach it.
How hooks compose and where they sit
pre_tool_useruns first. If several hooks answer, deny beats ask beats allow. The lastupdatedInputin 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
shellcommand such ascat src/private/xdoes not run a hook matchingread(...),lsorgrep; 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 indontAsk, a prompt in manual mode, the guardian inauto). denydenies the call.askforces the human prompt like anaskrule (a denial indontAskand headless runs).allowis 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 ashell(git *)hook does not allowls && git push. Inautoa 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. Anallowstands only for the arguments the hook saw: if a later hook rewrites the call withupdatedInput, 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_contextis shown to the guardian inside an untrusted block, as a note and never as an instruction.post_tool_useruns last in the result pipeline, after anything that screens tool results, and itsadditionalContextlands after the tool’s output. It fires only for a call that succeeded; a failed call firespost_tool_use_failure, which adds to the error the agent reads. Background job output reaches them like any result.permission_deniedruns for every denial the pipeline makes, whatever the mode. A hook’sretry: truemakes the denied call run once if the agent sends exactly the same call again, as/deniedfollowed byrdoes, 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
| Event | Fires | Extra input | A block |
|---|---|---|---|
task_created | Before 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_completed | Before 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_idle | After 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_idleblock 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,
--settingsand plugins can define both. A repository’stask_completedhook loads like its other hooks (after workspace trust, and it counts in the trust prompt) and can only keep a task open. A repository’steammate_idlehook is ignored with a warning, because forcing more model calls is spend, not tightening. A plugin’shooks.jsonnames the eventsTaskCreated,TaskCompletedandTeammateIdle; 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.
| Event | Fires | Extra input | A hook can |
|---|---|---|---|
session_start | After the session starts, after /clear (clear) and after a compaction that saved (compact). The source is startup, resume, fork, clear or compact. | source, model | Write 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_end | When the terminal UI ends (prompt_input_exit, or resume when it switches session), before /clear (clear), and when a headless run ends (other). | reason | Nothing. 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_submit | When you send a prompt: typed, a skill line, /goal <condition>, /init, the first /loop iteration, or a headless -p prompt. | prompt | Block (the prompt is not sent and nothing is recorded; the reason is shown to you), or add context with additionalContext or plain standard output. |
stop | When the main agent’s turn ends with an answer, before a /goal evaluation. | stop_hook_active, last_assistant_message | Block, or add additionalContext: the agent works on, with the reason as a harness note. |
stop_failure | When 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_start | Before a subagent’s first run, with agents on or off. | agent_type | Write additionalContext: it goes ahead of the subagent’s task. |
subagent_stop | When a subagent finishes a run, after its mail is read and before teammate_idle. | stop_hook_active, agent_type, last_assistant_message | Block or add additionalContext: the subagent is resumed with the reason. |
pre_compact | When 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_compact | After the summary was saved. | trigger, compact_summary | Nothing. |
notification | When 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_type | Nothing. |
activity_changed | When the session becomes active, waiting or idle; see below. It runs in the background. | reason, previous_state, activity | Nothing. |
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:
| Field | Meaning |
|---|---|
session_id | The session id. |
seq | Increases with every published change. A gap between two deliveries means snapshots in between were skipped. |
state | active, waiting or idle; the matcher selects on it. |
turn_running | A root turn, its end-of-turn work (the stop hooks, a goal evaluation) or a turn on a notification is under way. |
waiting_on_human | The 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_agents | Subagents whose status is running, those waiting on a permission prompt included. |
running_background_jobs | Background shells and monitors still running. |
running_monitors | The monitors among them. |
pending_notifications | Notes some surface will deliver and none has yet. |
queued_prompts | Messages 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
-pdoes, unless[headless] require_trust = trueand the workspace is not trusted. - They can only tighten. A repository hook’s
allowand itsretryare ignored; itsdeny,ask,updatedInput,guardian_contextandadditionalContextwork as for any hook. An untrackedsettings.local.tomlof a trusted root is your own file, and its hooks’allowcounts. httpandprompthooks and the events that force model calls are ignored. A repository’shttporprompthook, and itsstop,subagent_stopandteammate_idlehooks, 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 defined | command | http, prompt | stop, subagent_stop, teammate_idle |
|---|---|---|---|
Your user config, --settings | runs | runs | runs |
An untracked settings.local.toml of a trusted root | runs | runs | ignored |
.fontaine/settings.toml | after workspace trust | ignored | ignored |
| A plugin | runs | runs | runs |
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(anallowthere would answer the human prompt, a second way to loosen next topre_tool_use),Setup,UserPromptExpansion,PostToolBatch,MessageDisplay,InstructionsLoaded,ConfigChange,CwdChanged,DirectoryAdded,FileChanged,WorktreeCreate,WorktreeRemove,PreModelSwitch,PostModelSwitchandElicitationResult. A plugin that names one loads with a warning. - Handler types:
agentandmcp_tool. Anmcp_toolhook would call a tool outside the per-call gate. A plugin hook of those types is skipped with a warning. - Handler fields:
args,ifandshell: "powershell"skip a plugin’s hook with a warning;async,asyncRewake,onFailure,statusMessageandonceare 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.