Hooks

​

Setup

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.deepagents/hooks/block-rm.sh",
            "timeout": 600
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "~/.deepagents/hooks/load-context.sh"
          }
        ]
      }
    ]
  }
}

1. Project hooks from {project_root}/.deepagents/hooks.json, after workspace trust is granted.
2. User hooks from ~/.deepagents/hooks.json.
3. Hooks contributed by enabled plugins.

​

Trust project hooks

• Interactive sessions prompt when an untrusted workspace contains .deepagents/hooks.json. Trusting the workspace persists the decision for that project root under ~/.deepagents/.state/hooks_trust.json.
• Denying the prompt skips project hooks for that session and continues with user and plugin hooks.
• Canceling the prompt with Esc or Ctrl+D aborts startup.
• Headless and CI runs never prompt. Pass --trust-project-hooks to opt in for that run.

​

Plugin hooks

​

Handler fields

​

Handler environment

​

Matchers

• Omitted, empty, or * matches all values for that event.
• A simple name matches exactly (Bash).
• | or , separates exact alternatives (Edit|Write).
• Any other value is treated as an unanchored regular expression (mcp__.*).

​

Events

​

Input payload

​

Common fields

​

Event-specific fields

{
  "session_id": "abc123",
  "transcript_path": "/Users/you/.deepagents/.../transcript.jsonl",
  "cwd": "/Users/you/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build"
  },
  "tool_use_id": "toolu_01ABC"
}

​

Tool names

​

Handler output

​

Universal output fields

{
  "continue": true,
  "stopReason": "optional user-facing reason when continue is false",
  "suppressOutput": false,
  "systemMessage": "optional message shown to the user",
  "terminalSequence": "optional restricted terminal control sequence",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse"
  }
}

​

Control tool execution with PreToolUse

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

​

Allow or deny with PermissionRequest

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Not allowed in this environment"
    }
  }
}

​

Continue a turn with Stop

{
  "decision": "block",
  "reason": "Tests are still failing; keep working"
}

​

Inject context

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current sprint: ENG-1421. Prefer the staging database."
  }
}

​

Unsupported output fields

​

Examples

#!/usr/bin/env bash
command=$(jq -r '.tool_input.command // ""')

if printf '%s' "$command" | grep -Eq 'rm[[:space:]]+.*-[a-zA-Z]*[rf]'; then
  cat <<'JSON'
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Recursive or forced rm is blocked by policy"
  }
}
JSON
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.deepagents/hooks/block-rm.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
context=$(git -C "$(jq -r '.cwd')" log --oneline -5 2>/dev/null)

jq -n --arg ctx "$context" '{
  hookSpecificOutput: {
    hookEventName: "SessionStart",
    additionalContext: ("Recent commits:\n" + $ctx)
  }
}'

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          { "type": "command", "command": "~/.deepagents/hooks/load-context.sh" }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Agent finished\" with title \"Deep Agents Code\"'"
          }
        ]
      }
    ]
  }
}

import json
import sys


def handle(payload: dict[str, object]) -> None:
    event = payload["hook_event_name"]
    if event == "PreToolUse":
        tool_name = payload["tool_name"]
        print(f"About to run {tool_name}", file=sys.stderr)


if __name__ == "__main__":
    handle(json.load(sys.stdin))

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.deepagents/hooks/handler.py"
          }
        ]
      }
    ]
  }
}

​

Troubleshoot hooks

• A running handler shows its statusMessage, or Running <event> hook when it sets none. Concurrent handlers share one status slot, so the most recent one is displayed until it finishes.
• A handler’s systemMessage appears as an informational notice.
• Configuration errors, nonzero exits, timeouts, and unsupported output fields appear as Hook warning or Hook error notices, once per invocation.
• A permission answer from a hook is attributed to the hook, for example PermissionRequest hook denied Bash.
• Set DEEPAGENTS_CODE_DEBUG=1 to capture every diagnostic, including debug-level entries that are never shown as notices.

​

Legacy configuration

​

Security

• Payload data flows to stdin as JSON, never interpolated into command arguments.
• Credential-looking environment variables are stripped from handler environments.
• Hook configuration remains fixed until /reload or a new session.
• Prefer explicit shell executables you control over shell wrappers.
• Only install hooks from sources you trust.

​

See also

• Configuration
• Plugins and marketplaces
• Data locations
• CLI reference