Per-Node Hooks
DAG workflow nodes support a hooks field that attaches Claude Agent SDK hooks
to individual nodes. Hooks fire during the node’s AI execution and can control
tool behavior, inject context, modify inputs, and more.
Claude only — other providers warn and ignore hooks: (see the
capability matrix).
These YAML hooks are one of three places hook-like logic can live. See Choosing where hook logic lives before reaching for them.
Quick Start
Section titled “Quick Start”name: safe-migrationdescription: Generate SQL with guardrailsnodes: - id: generate prompt: "Generate a database migration for $ARGUMENTS" hooks: PreToolUse: - matcher: "Bash" response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: "No shell access during SQL generation"How It Works
Section titled “How It Works”Each hook matcher has three fields:
matcher(optional): Regex pattern to filter by tool name. Omit to match all tools.response(required): The SDKSyncHookJSONOutputreturned when the hook fires.timeout(optional): Seconds before the hook times out (default: 60).
At runtime, each YAML hook is wrapped in a trivial callback:
async () => responseNo custom DSL — response IS the SDK type, passed through unchanged.
Important: When using hookSpecificOutput, you must include a hookEventName
field that matches the event key (e.g., hookEventName: PreToolUse inside a
PreToolUse hook). This is an SDK requirement — it uses this field to determine
which event-specific fields to process.
Choosing where hook logic lives
Section titled “Choosing where hook logic lives”| You need | Use | Owned by |
|---|---|---|
A fixed response the workflow author can read in the YAML: deny Bash, add a reminder after every Read | YAML hooks: on the node | The workflow |
Logic that inspects the hook input at runtime: allow git status but block git push, lint the file a Write just touched | A native Claude hook in .claude/settings.json or ~/.claude/settings.json | Claude configuration |
| A deterministic step in the workflow: run tests, parse JSON, decide whether a later node runs | A bash: or script: node, gated with when: on its output | The workflow |
YAML hooks: are deliberately static. Each response is returned unchanged
every time its matcher fires, so the engine and anyone reading the workflow can
see exactly what the node will do. Workflow YAML has no executable hook types
(command:, http:, prompt:, agent:) by design: computation
belongs in a node body, not in the YAML. The
workflow language constitution
explains that boundary.
When a hook has to compute something from its input, write it as a native Claude hook. Claude Code runs it inside the node’s session, and Archon decides which settings files that session reads.
Native Claude hooks and settingSources
Section titled “Native Claude hooks and settingSources”The node’s settingSources controls which Claude settings files load, and so
which native hooks run:
settingSources | Settings file loaded | Native hooks that run |
|---|---|---|
['project', 'user'] (default) | <cwd>/.claude/settings.json and ~/.claude/settings.json | Project and user hooks |
['project'] | <cwd>/.claude/settings.json | Project hooks only |
['user'] | ~/.claude/settings.json | User hooks only |
[] | Neither | None |
<cwd> is the node’s working directory, the run’s worktree when it has one, so
project hooks come from the checked-out branch. Archon never loads
.claude/settings.local.json. settingSources also controls CLAUDE.md, skills,
commands, and agents discovery; see
settingSources.
A project hook that inspects every Bash command, in .claude/settings.json:
{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-bash.sh" } ] } ] }}A workflow that runs the project hook in one node, keeps the operator’s user hooks out, and runs another node with no native hooks at all:
name: guarded-fixdescription: Fix a bug with the project's Bash guard activeprovider: claudenodes: - id: fix prompt: "Fix the bug described in $ARGUMENTS" settingSources: ['project'] # project hooks run; ~/.claude hooks do not
- id: test bash: "bun run test" depends_on: [fix]
- id: summarize prompt: "Summarize the fix and the test result: $test.output" depends_on: [test] settingSources: [] # no settings files, so no native hooks hooks: # YAML hooks still apply PreToolUse: - matcher: "Write|Edit" response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: "Summary node is read-only"Omitting settingSources inherits assistants.claude.settingSources from
.archon/config.yaml, and then the ['project', 'user'] default. YAML hooks:
run whatever settingSources says, alongside any native hooks that load. See
Claude Code hooks for the
native hook format.
Supported Hook Events
Section titled “Supported Hook Events”| Event | Fires When | Matcher Filters On |
|---|---|---|
PreToolUse | Before a tool executes | Tool name (e.g. Bash, Write, Read) |
PostToolUse | After a tool succeeds | Tool name |
PostToolUseFailure | After a tool fails | Tool name |
Notification | System notification | Notification type |
Stop | Agent stops | N/A |
SubagentStart | Subagent spawned | Agent type |
SubagentStop | Subagent finishes | Agent type |
PreCompact | Before context compaction | Trigger (manual/auto) |
SessionStart | Session begins | Source (startup/resume/clear/compact) |
SessionEnd | Session ends | Exit reason |
UserPromptSubmit | User prompt submitted | N/A |
PermissionRequest | Permission prompt would appear | Tool name |
Setup | SDK initialization | Trigger (init/maintenance) |
TeammateIdle | Agent teammate goes idle | N/A |
TaskCompleted | Background task finishes | N/A |
Elicitation | MCP server requests user input | N/A |
ElicitationResult | Elicitation response received | N/A |
ConfigChange | Settings/config file changed | Source (user_settings/project_settings/etc.) |
WorktreeCreate | Git worktree created | Worktree name |
WorktreeRemove | Git worktree removed | Worktree path |
InstructionsLoaded | CLAUDE.md/instructions loaded | Memory type (User/Project/Local/Managed) |
Tool names: Bash, Read, Write, Edit, Glob, Grep, WebFetch,
Agent, plus MCP tools as mcp__<server>__<action>.
Response Format (SDK SyncHookJSONOutput)
Section titled “Response Format (SDK SyncHookJSONOutput)”The response object supports these fields:
| Field | Type | Effect |
|---|---|---|
hookSpecificOutput | object | Event-specific response (see below) |
systemMessage | string | Inject a message visible to the model |
continue | boolean | false stops the agent |
decision | 'approve' / 'block' | Top-level approve/block |
stopReason | string | Reason when stopping |
suppressOutput | boolean | Suppress output emission |
PreToolUse hookSpecificOutput
Section titled “PreToolUse hookSpecificOutput”hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny | allow | ask # Control whether tool runs permissionDecisionReason: "..." # Why (shown in logs) updatedInput: # Modify tool arguments file_path: "/sandbox/output.ts" additionalContext: "..." # Text injected into model contextPostToolUse hookSpecificOutput
Section titled “PostToolUse hookSpecificOutput”hookSpecificOutput: hookEventName: PostToolUse additionalContext: "..." # Text injected after tool result updatedMCPToolOutput: ... # Override what model sees from toolPostToolUseFailure hookSpecificOutput
Section titled “PostToolUseFailure hookSpecificOutput”hookSpecificOutput: hookEventName: PostToolUseFailure additionalContext: "..." # Context after tool failureElicitation hookSpecificOutput
Section titled “Elicitation hookSpecificOutput”hookSpecificOutput: hookEventName: Elicitation action: accept | decline | cancel # Respond to MCP elicitation content: { ... } # Form field valuesElicitationResult hookSpecificOutput
Section titled “ElicitationResult hookSpecificOutput”hookSpecificOutput: hookEventName: ElicitationResult action: accept | decline | cancel # Override elicitation result content: { ... } # Modified response valuesExamples
Section titled “Examples”Deny a tool entirely
Section titled “Deny a tool entirely”hooks: PreToolUse: - matcher: "Bash" response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: "Shell access not allowed in this node"Deny tools with a reason message
Section titled “Deny tools with a reason message”hooks: PreToolUse: - matcher: "Write|Edit" response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: "Only read operations are allowed — do not modify files"Inject context before tool use (without blocking)
Section titled “Inject context before tool use (without blocking)”Note: this does NOT block the tool — it adds guidance the model sees before the tool runs.
hooks: PreToolUse: - matcher: "Write|Edit" response: hookSpecificOutput: hookEventName: PreToolUse additionalContext: "Only write to files in the src/ directory"Redirect file writes (modify tool input)
Section titled “Redirect file writes (modify tool input)”hooks: PreToolUse: - matcher: "Write" response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: allow updatedInput: file_path: "/sandbox/output.ts"Inject steering instructions after every tool call
Section titled “Inject steering instructions after every tool call”hooks: PostToolUse: - response: systemMessage: "Check: is this output relevant to the task? If not, stop and explain why."Inject context after reading files
Section titled “Inject context after reading files”hooks: PostToolUse: - matcher: "Read" response: hookSpecificOutput: hookEventName: PostToolUse additionalContext: "You just read a file. Do NOT modify it — analysis only."Emergency stop on shell access
Section titled “Emergency stop on shell access”hooks: PreToolUse: - matcher: "Bash" response: continue: false stopReason: "Emergency halt — shell access attempted"Multiple hooks on one node
Section titled “Multiple hooks on one node”hooks: PreToolUse: - matcher: "Bash" response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: "No shell" - matcher: "Write|Edit" response: hookSpecificOutput: hookEventName: PreToolUse additionalContext: "Only write to files in src/" PostToolUse: - response: systemMessage: "Verify output before continuing"Full workflow example
Section titled “Full workflow example”name: safe-code-reviewdescription: Review code with guardrailsnodes: - id: fetch-diff bash: "git diff main...HEAD"
- id: review prompt: "Review this diff for bugs and security issues: $fetch-diff.output" depends_on: [fetch-diff] hooks: PreToolUse: - matcher: "Bash" response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: "Code review should not execute commands" - matcher: "Write|Edit" response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: "Code review is read-only" PostToolUse: - matcher: "Read" response: hookSpecificOutput: hookEventName: PostToolUse additionalContext: "Focus on security issues in this file"
- id: summarize prompt: "Summarize the review findings from $review.output" depends_on: [review] allowed_tools: []Hooks vs allowed_tools/denied_tools
Section titled “Hooks vs allowed_tools/denied_tools”| Feature | allowed_tools/denied_tools | hooks |
|---|---|---|
| Block a tool entirely | Yes | Yes |
| Inject context | No | Yes (additionalContext, systemMessage) |
| Modify tool input | No | Yes (updatedInput) |
| Override tool output | No | Yes (updatedMCPToolOutput) |
| Stop the agent | No | Yes (continue: false) |
| React after tool use | No | Yes (PostToolUse) |
Use allowed_tools/denied_tools for simple include/exclude. Use hooks when you
need context injection, input modification, or post-tool-use reactions.
Hook events in the run record
Section titled “Hook events in the run record”When a native Claude hook runs (a command, http, or MCP-tool hook from a
settings file), Archon records a hook provider event when it starts and another
when it ends. The end event carries the hook’s name, the event that fired it
(such as PreToolUse), a status of succeeded, failed, or cancelled, and the
exit code when there is one. Like other provider events, they are saved with the
node, streamed live, served by GET /api/workflows/runs/{runId}/provider-events,
and written by archon workflow logs, whose --format text view prints only
failed and cancelled hooks. The console’s run stream shows each hook event beside
tool calls, with its name, triggering event, status, and exit code when present.
Hook events remain visible when tool calls or system messages are hidden, and
follow the selected node filter.
YAML hooks: record no hook events. They are in-process SDK callbacks, and the
Claude Agent SDK emits lifecycle events only for hooks it executes itself.
Archon does not record hook_progress output, which Claude emits only for async
native hooks.
Limitations
Section titled “Limitations”- Static responses only in YAML — hooks return the same response every time.
For input-aware hook logic, use a native Claude hook.
For workflow logic, use a
bash:orscript:node and gate downstream nodes withwhen:. - Claude only — other providers warn and ignore
hooks:.
SDK Reference
Section titled “SDK Reference”Refer to the Anthropic Claude Agent SDK documentation for the authoritative SyncHookJSONOutput type, hook event reference, and matcher patterns.
Related
Section titled “Related”- Per-Node MCP Servers —
mcp:field for external tool access - Per-Node Skills —
skills:field for domain knowledge injection
