Skip to content

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.

name: safe-migration
description: Generate SQL with guardrails
nodes:
- 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"

Each hook matcher has three fields:

  • matcher (optional): Regex pattern to filter by tool name. Omit to match all tools.
  • response (required): The SDK SyncHookJSONOutput returned 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 () => response

No 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.

You needUseOwned by
A fixed response the workflow author can read in the YAML: deny Bash, add a reminder after every ReadYAML hooks: on the nodeThe workflow
Logic that inspects the hook input at runtime: allow git status but block git push, lint the file a Write just touchedA native Claude hook in .claude/settings.json or ~/.claude/settings.jsonClaude configuration
A deterministic step in the workflow: run tests, parse JSON, decide whether a later node runsA bash: or script: node, gated with when: on its outputThe 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.

The node’s settingSources controls which Claude settings files load, and so which native hooks run:

settingSourcesSettings file loadedNative hooks that run
['project', 'user'] (default)<cwd>/.claude/settings.json and ~/.claude/settings.jsonProject and user hooks
['project']<cwd>/.claude/settings.jsonProject hooks only
['user']~/.claude/settings.jsonUser hooks only
[]NeitherNone

<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-fix
description: Fix a bug with the project's Bash guard active
provider: claude
nodes:
- 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.

EventFires WhenMatcher Filters On
PreToolUseBefore a tool executesTool name (e.g. Bash, Write, Read)
PostToolUseAfter a tool succeedsTool name
PostToolUseFailureAfter a tool failsTool name
NotificationSystem notificationNotification type
StopAgent stopsN/A
SubagentStartSubagent spawnedAgent type
SubagentStopSubagent finishesAgent type
PreCompactBefore context compactionTrigger (manual/auto)
SessionStartSession beginsSource (startup/resume/clear/compact)
SessionEndSession endsExit reason
UserPromptSubmitUser prompt submittedN/A
PermissionRequestPermission prompt would appearTool name
SetupSDK initializationTrigger (init/maintenance)
TeammateIdleAgent teammate goes idleN/A
TaskCompletedBackground task finishesN/A
ElicitationMCP server requests user inputN/A
ElicitationResultElicitation response receivedN/A
ConfigChangeSettings/config file changedSource (user_settings/project_settings/etc.)
WorktreeCreateGit worktree createdWorktree name
WorktreeRemoveGit worktree removedWorktree path
InstructionsLoadedCLAUDE.md/instructions loadedMemory type (User/Project/Local/Managed)

Tool names: Bash, Read, Write, Edit, Glob, Grep, WebFetch, Agent, plus MCP tools as mcp__<server>__<action>.

The response object supports these fields:

FieldTypeEffect
hookSpecificOutputobjectEvent-specific response (see below)
systemMessagestringInject a message visible to the model
continuebooleanfalse stops the agent
decision'approve' / 'block'Top-level approve/block
stopReasonstringReason when stopping
suppressOutputbooleanSuppress output emission
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 context
hookSpecificOutput:
hookEventName: PostToolUse
additionalContext: "..." # Text injected after tool result
updatedMCPToolOutput: ... # Override what model sees from tool
hookSpecificOutput:
hookEventName: PostToolUseFailure
additionalContext: "..." # Context after tool failure
hookSpecificOutput:
hookEventName: Elicitation
action: accept | decline | cancel # Respond to MCP elicitation
content: { ... } # Form field values
hookSpecificOutput:
hookEventName: ElicitationResult
action: accept | decline | cancel # Override elicitation result
content: { ... } # Modified response values
hooks:
PreToolUse:
- matcher: "Bash"
response:
hookSpecificOutput:
hookEventName: PreToolUse
permissionDecision: deny
permissionDecisionReason: "Shell access not allowed in this node"
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"
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."
hooks:
PostToolUse:
- matcher: "Read"
response:
hookSpecificOutput:
hookEventName: PostToolUse
additionalContext: "You just read a file. Do NOT modify it — analysis only."
hooks:
PreToolUse:
- matcher: "Bash"
response:
continue: false
stopReason: "Emergency halt — shell access attempted"
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"
name: safe-code-review
description: Review code with guardrails
nodes:
- 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: []
Featureallowed_tools/denied_toolshooks
Block a tool entirelyYesYes
Inject contextNoYes (additionalContext, systemMessage)
Modify tool inputNoYes (updatedInput)
Override tool outputNoYes (updatedMCPToolOutput)
Stop the agentNoYes (continue: false)
React after tool useNoYes (PostToolUse)

Use allowed_tools/denied_tools for simple include/exclude. Use hooks when you need context injection, input modification, or post-tool-use reactions.

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.

  • 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: or script: node and gate downstream nodes with when:.
  • Claude only — other providers warn and ignore hooks:.

Refer to the Anthropic Claude Agent SDK documentation for the authoritative SyncHookJSONOutput type, hook event reference, and matcher patterns.