Hooks

Run shell commands at various points during agent execution for deterministic control over behavior.

Overview

Hooks allow you to execute shell commands or scripts at key points in an agent’s lifecycle. They provide deterministic control that works alongside the LLM’s behavior, enabling validation, logging, environment setup, and more.

Hook Types

docker-agent dispatches the following hook events:

Configuration

agents:
  root:
    model: openai/gpt-4o
    description: An agent with hooks
    instruction: You are a helpful assistant.
    hooks:
      # Run before specific tools
      pre_tool_use:
        - matcher: "shell|edit_file"
          hooks:
            - type: command
              command: "./scripts/validate-command.sh"
              timeout: 30

      # Run after all tool calls
      post_tool_use:
        - matcher: "*"
          hooks:
            - type: command
              command: "./scripts/log-tool-call.sh"

      # Run when session starts
      session_start:
        - type: command
          command: "./scripts/setup-env.sh"

      # Run when session ends
      session_end:
        - type: command
          command: "./scripts/cleanup.sh"

      # Run when agent is waiting for user input
      on_user_input:
        - type: command
          command: "./scripts/notify.sh"

      # Run when the model finishes responding
      stop:
        - type: command
          command: "./scripts/log-response.sh"

      # Run on agent errors and warnings
      notification:
        - type: command
          command: "./scripts/alert.sh"

Built-in Hooks

In addition to shell command hooks, docker-agent ships a small library of built-in hooks — in-process Go functions that run without spawning a subprocess. They’re invoked with type: builtin, where command is the builtin’s registered name and args are passed through as the builtin’s parameters.

hooks:
  turn_start:
    - type: builtin
      command: add_date
    - type: builtin
      command: add_prompt_files
      args:
        - GUIDELINES.md
        - PROJECT.md
  session_start:
    - type: builtin
      command: add_environment_info
  before_llm_call:
    - type: builtin
      command: max_iterations
      args: ["50"]

Built-ins are typically zero-config and faster than equivalent shell hooks because they don’t fork a process. They cover the common “inject context into every turn / session” patterns out of the box.

Available built-ins

A minimal snapshot wiring looks like this:

hooks:
  turn_start:
    - type: builtin
      command: snapshot
  turn_end:
    - type: builtin
      command: snapshot
  session_end:
    - type: builtin
      command: snapshot

The shadow repository stores tree objects only; it never writes commits or touches the source repository’s .git directory. The source repository’s .gitignore and info/exclude rules are mirrored before each capture so ignored files do not appear in snapshots. The built-in only records undo checkpoints when files changed, so a final no-op model response does not hide the last changed snapshot.

You can also enable snapshots globally for every agent with user config:

settings:
  snapshot: true

Omit snapshot or set it to false to leave automatic snapshots off; manually configured snapshot hooks still run.

Matcher Patterns

The matcher field uses regex patterns to match tool names:

Hook Input

Hooks receive JSON input via stdin with context about the event:

{
  "session_id": "abc123",
  "cwd": "/path/to/project",
  "hook_event_name": "pre_tool_use",
  "tool_name": "shell",
  "tool_use_id": "call_xyz",
  "tool_input": {
    "cmd": "rm -rf /tmp/cache",
    "cwd": "."
  }
}

Common Fields

Every hook event carries:

Per-Event Extra Fields

In addition to the common fields, each event ships its own payload:

Notes:

• tool_response for post_tool_use carries the tool’s result; tool_error is true when the tool failed (the failure detail is surfaced inside tool_response).
• prompt is only populated for user_prompt_submit. Sub-sessions (transferred tasks, background agents, skills) do not fire this event because their kick-off message is synthesised by the runtime, not authored by the user.
• stop_response carries the model’s final assistant text for stop, after_llm_call, and subagent_stop. last_user_message carries the latest user message at dispatch time.
• context_limit is 0 when the model definition is unavailable (treat 0 as “unknown”, not as a real limit).
• approval_decision is one of allow, deny, canceled. approval_source is a stable classifier of which step decided (e.g. yolo, session_permissions_allow, session_permissions_deny, team_permissions_allow, team_permissions_deny, pre_tool_use_hook_allow, pre_tool_use_hook_deny, readonly_hint, user_approved, user_approved_session, user_approved_tool, user_rejected, context_canceled).

Hook Output

Hooks communicate back via JSON output to stdout:

{
  "continue": true,
  "stop_reason": "Optional message when continue=false",
  "suppress_output": false,
  "system_message": "Warning message to show user",
  "decision": "block",
  "reason": "Explanation for the decision",
  "hook_specific_output": {
    "hook_event_name": "pre_tool_use",
    "permission_decision": "allow",
    "permission_decision_reason": "Command is safe",
    "updated_input": { "cmd": "modified command" }
  }
}

All fields are optional. Returning {} (or no output at all) means “do nothing, continue normally”.

Output Fields

Pre-Tool-Use / Permission-Request Specific Output

The hook_specific_output for pre_tool_use (and permission_request) supports:

Tool-Response-Transform Specific Output

The hook_specific_output for tool_response_transform supports:

This is the symmetric counterpart of pre_tool_use’s updated_input, applied to tool results instead of tool arguments. The rewrite reaches every downstream consumer — event subscribers, the persisted session file, the post_tool_use hook input, and the next LLM call. Use it to truncate excessive output, scrub PII, or normalise tool dialects. The built-in redact_secrets registers itself on this event as the third leg of the redact_secrets feature.

Context-Contributing Events

For session_start, user_prompt_submit, turn_start, post_tool_use, pre_compact, and stop, hooks may set hook_specific_output.additional_context to inject text into the conversation. turn_start context is transient (recomputed every turn, never persisted); session_start context persists for the life of the session.

Before-Compaction Specific Output

For before_compaction, the hook_specific_output.summary field, when non-empty, replaces the LLM-generated compaction summary. The runtime applies the string verbatim and skips the model call.

{
  "hook_specific_output": {
    "hook_event_name": "before_compaction",
    "summary": "User asked to refactor pkg/foo. Done in commit abc123."
  }
}

Returning decision: "block" (or exit code 2) instead vetoes the compaction entirely. Be cautious about denying when compaction_reason is overflow: the runtime is recovering from a context-overflow error and a denial there will leave the session unable to make progress.

Plain Text Output

For session_start, user_prompt_submit, turn_start, post_tool_use, pre_compact, and stop hooks, plain text written to stdout (i.e., output that is not valid JSON) is captured as additional context for the agent. For pre_compact it is appended to the compaction prompt; for the others it is spliced into the conversation as a (transient or persisted) system message depending on the event.

Exit Codes

Hook exit codes have special meaning:

Per-hook options

Hooks have a default timeout of 60 seconds. You can also give hooks a name, add environment variables, choose a working directory, and control how non-security hook failures behave:

hooks:
  post_tool_use:
    - matcher: "shell"
      hooks:
        - name: "summarize shell output"
          type: command
          command: "./summarize.sh"
          timeout: 120 # 2 minutes
          working_dir: ./hooks
          env:
            PROFILE: dev
          on_error: warn # warn | ignore | block

pre_tool_use is fail-closed for safety: a failed pre-tool hook blocks the tool call regardless of on_error.

Examples

Validation Script

A simple pre-tool-use hook that blocks dangerous shell commands:

#!/bin/bash
# scripts/validate-command.sh

# Read JSON input from stdin
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
CMD=$(echo "$INPUT" | jq -r '.tool_input.cmd // empty')

# Block dangerous commands
if [[ "$TOOL_NAME" == "shell" ]]; then
  if [[ "$CMD" =~ ^sudo ]] || [[ "$CMD" =~ rm.*-rf ]]; then
    echo '{"decision": "block", "reason": "Dangerous command blocked by policy"}'
    exit 2
  fi
fi

# Allow everything else (returning {} means "do nothing, continue normally")
echo '{}'
exit 0

Audit Logging

A post-tool-use hook that logs all tool calls:

#!/bin/bash
# scripts/log-tool-call.sh

INPUT=$(cat)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')

# Append to audit log
echo "$TIMESTAMP | $SESSION_ID | $TOOL_NAME" >> ./audit.log

# Don't block execution
echo '{"continue": true}'
exit 0

Session Lifecycle

Session start and end hooks for environment setup and cleanup:

hooks:
  session_start:
    - type: command
      timeout: 10
      command: |
        INPUT=$(cat)
        SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
        echo "Session $SESSION_ID started at $(date)" >> /tmp/agent-session.log
        echo '{"hook_specific_output":{"additional_context":"Session initialized."}}'

  session_end:
    - type: command
      timeout: 10
      command: |
        INPUT=$(cat)
        SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
        REASON=$(echo "$INPUT" | jq -r '.reason // "unknown"')
        echo "Session $SESSION_ID ended ($REASON) at $(date)" >> /tmp/agent-session.log

Response Logging with Stop Hook

Log every model response for analytics or compliance:

hooks:
  stop:
    - type: command
      timeout: 10
      command: |
        INPUT=$(cat)
        SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
        RESPONSE_LENGTH=$(echo "$INPUT" | jq -r '.stop_response // ""' | wc -c | tr -d ' ')
        echo "[$(date)] Session $SESSION_ID - Response: $RESPONSE_LENGTH chars" >> /tmp/agent-responses.log

The stop hook is useful for:

• Response quality checks — validate that responses meet criteria before returning
• Analytics — track response lengths, patterns, or content
• Compliance logging — record all agent outputs for audit

Error Notifications

Send alerts when the agent encounters errors:

hooks:
  notification:
    - type: command
      timeout: 10
      command: |
        INPUT=$(cat)
        LEVEL=$(echo "$INPUT" | jq -r '.notification_level // "unknown"')
        MESSAGE=$(echo "$INPUT" | jq -r '.notification_message // "no message"')
        echo "[$(date)] [$LEVEL] $MESSAGE" >> /tmp/agent-notifications.log

The notification hook fires when:

• The model returns an error (all models failed) — also fires on_error
• A degenerate tool call loop is detected — also fires on_error
• The maximum iteration limit is reached — also fires on_max_iterations

Use on_error and on_max_iterations instead of notification when you want a structured handler for one of these conditions without parsing notification_level.

Turn-Start: per-turn context

turn_start fires at the start of every agent turn (each model call). Anything you contribute via additional_context (or plain stdout) is appended as a transient system message for that turn only — it is not persisted to the session. Use it for fast-moving signals like the date, current git state, or per-turn prompt files. The built-in hooks add_date, add_prompt_files, add_git_status, and add_git_diff all target this event.

Turn-End: per-turn finalizer

turn_end is the symmetric counterpart of turn_start. It fires once per turn when the iteration finishes — no matter why. The runtime guarantees the dispatch on every exit path (a normal stop, an error, a hook-driven shutdown, the loop detector, even context cancellation), and it uses context.WithoutCancel internally so handlers run to completion on Ctrl+C.

The reason field classifies the exit:

turn_end is observational — the result is ignored. Use it to time turns, accumulate per-turn metrics (token usage, tool counts), or notify external observability pipelines symmetrically with turn_start.

Before/After-LLM-Call: budget guards and model auditing

before_llm_call fires immediately before every model call (after turn_start has assembled the messages). It cannot contribute context — use turn_start for that — but it can stop the run by returning decision: block (or exit code 2). The built-in max_iterations hook implements a hard cap on top of this event.

after_llm_call fires immediately after each successful model call, before the response is recorded into the session and tool calls are dispatched. The assistant text is in stop_response. Use it for response auditing, redaction logging, or quality metrics. Failed model calls fire on_error instead.

Before/After-Compaction: structured compaction control

before_compaction fires immediately before a compaction. Unlike pre_compact, it carries structured token-pressure data: input_tokens, output_tokens, context_limit, and a compaction_reason (threshold, overflow, or manual). Hooks can either:

• veto compaction by returning decision: block (the runtime skips compaction entirely), or
• replace the LLM-generated summary by returning hook_specific_output.summary (the runtime applies that summary verbatim and skips the model call).

after_compaction fires after a successful compaction. It carries the produced summary along with the pre-compaction input_tokens / output_tokens so observability handlers can naturally express “compacted from X to Y”. after_compaction is purely observational; output is ignored.

Agent-Switch and Session-Resume: observability for multi-agent and long runs

on_agent_switch fires whenever the runtime moves the active agent to a new one — transfer_task, handoff, or the return after a transferred task completes. The cause is in agent_switch_kind, the source and destination in from_agent and to_agent. Use it for audit, transcript, and metrics pipelines that track which agent ran which tools.

The built-in unload hooks into this event to release the resources held by the previous agent’s models. It’s the canonical way to run two heavy local models on a GPU that can only fit one at a time:

agents:
  coder:
    model: qwen3-large
    handoffs: [reviewer]
    hooks:
      on_agent_switch:
        - type: builtin
          command: unload
  reviewer:
    model: qwen3-coder
    handoffs: [coder]
    hooks:
      on_agent_switch:
        - type: builtin
          command: unload

models:
  qwen3-large:
    provider: dmr
    model: ai/qwen3-large
  qwen3-coder:
    provider: dmr
    model: ai/qwen3-coder

At every transfer the runtime calls Unload() on the previous agent’s model providers. For Docker Model Runner this hits the engine’s _unload endpoint; for cloud providers (OpenAI, Anthropic, …) it is a silent no-op. Cross-provider chains are safe — only the providers that actually implement provider.Unloader are touched. See examples/unload_on_switch.yaml for the full file.

on_session_resume fires when the user explicitly approves the runtime to continue past its configured max_iterations limit. previous_max_iterations carries the cap that was reached and new_max_iterations carries the new cap after approval. Useful for alerting on extended-runtime sessions or for billing / quota pipelines that meter resumes.

Tool-Approval-Decision: who-approved-what audit trail

on_tool_approval_decision fires after the runtime’s tool-approval chain (yolo / permissions / readonly / pre_tool_use hooks / interactive prompt) has resolved a verdict for a tool call. approval_decision is allow, deny, or canceled; approval_source is a stable classifier of which step produced the verdict. Observational only — it gives audit pipelines a single, structured “who approved what” record without re-implementing the chain.

Pre-Compact: steer the summary

pre_compact fires just before the runtime compacts the session transcript. Its source field tells you why compaction was triggered:

• manual — the user invoked /compact
• auto — proactive compaction at the configured threshold
• overflow — emergency compaction after a context-overflow error
• tool_overflow — proactive compaction triggered by tool results pushing the estimated context past the threshold

Return additional_context (or plain stdout) to append guidance to the compaction prompt without modifying the agent’s instruction. Block the event (decision: block / exit code 2) to cancel compaction — useful when you want to handle truncation yourself.

User-Prompt-Submit: gate or enrich every user message

user_prompt_submit fires once per user message, after the prompt is recorded in the session and before the first model call. The submitted text is in prompt. Use it to:

• block prompts that violate policy (decision: block / exit code 2),
• inject per-prompt context (additional_context is spliced as a transient system message for that turn),
• audit user prompts to a log.

It does not fire for sub-sessions (transferred tasks, background agents, skill sub-sessions) because their kick-off message is synthesised by the runtime.

Subagent-Stop: observe handoff completions

subagent_stop fires whenever a sub-agent finishes — transfer_task returns, a background agent completes, or a skill sub-session ends. It runs against the parent agent’s hooks executor, so handlers configured on the orchestrator see every child completion in one place. The sub-agent’s name is in agent_name, the parent’s session ID in parent_session_id, and the child’s final assistant message in stop_response.

Permission-Request: programmatic tool approval

permission_request fires just before the runtime would prompt the user to approve a tool call (i.e. when neither --yolo nor a permissions rule short-circuited the decision and the tool is not read-only). Use the same hook_specific_output.permission_decision shape as pre_tool_use to auto-approve or auto-deny the call:

hooks:
  permission_request:
    - matcher: "shell"
      hooks:
        - type: command
          command: |
            INPUT=$(cat)
            CMD=$(echo "$INPUT" | jq -r '.tool_input.cmd // ""')
            if echo "$CMD" | grep -qE '^(ls|pwd|cat) '; then
              echo '{"hook_specific_output":{"permission_decision":"allow","permission_decision_reason":"safe read-only command"}}'
            fi

Return nothing to fall through to the usual interactive confirmation.

LLM as a Judge (Auto-Approving Tool Calls)

The model hook type asks an LLM and translates its reply into the hook’s native output — no Go code, no shell glue, no JSON parsing on your side. Combined with the well-known pre_tool_use_decision schema it gives you a fully-configurable LLM judge that decides allow / ask / deny per tool call.

hooks:
  pre_tool_use:
    - matcher: "shell|edit_file|mcp:.*"
      hooks:
        - type: model
          model: openai/gpt-4o-mini
          timeout: 15
          schema: pre_tool_use_decision
          prompt: |
            You are a security judge for an autonomous agent.
            Decide whether this tool call is safe to auto-approve.

            Tool: 
            Args: 

            Project rules:
            - Reads under the working directory are safe.
            - Writes to ~/.ssh / ~/.aws / ~/.docker are deny.

The pre_tool_use_decision schema constrains the judge to reply with strict {decision, reason} JSON. Providers that honor structured output (OpenAI, …) are asked to emit that shape directly; on providers that ignore it the framework still parses tolerant JSON-in-text. Anything unparseable propagates as a hook error and the executor falls closed (deny) on pre_tool_use.

Pair it with deterministic permissions: rules so destructive calls (e.g. sudo, rm -rf) are blocked even if the judge is misled, and obvious read-only calls bypass the LLM entirely. See examples/llm_judge.yaml for a complete configuration.

Security considerations:

• Sensitive data: Tool arguments (including file paths, command arguments, and any other parameters) are sent to the judge LLM. Avoid using the judge on tools that handle secrets, or ensure your judge model is self-hosted.
• Defense in depth: The judge should not be your only security layer. Use deterministic permissions: rules to block obviously dangerous operations (e.g., sudo, rm -rf) before the judge sees them, as shown in the example configuration.

CLI Flags

You can add hooks from the command line without modifying the agent’s YAML file. This is useful for one-off debugging, audit logging, or layering hooks onto an existing agent.

All flags are repeatable — pass multiple to register multiple hooks.

# Add a session-start hook
$ docker agent run agent.yaml --hook-session-start "./scripts/setup-env.sh"

# Combine multiple hooks
$ docker agent run agent.yaml \
  --hook-pre-tool-use "./scripts/validate.sh" \
  --hook-post-tool-use "./scripts/log.sh"

# Add hooks to an agent from a registry
$ docker agent run agentcatalog/coder \
  --hook-pre-tool-use "./audit.sh"