Hooks Reference

Overview

Hooks are shell commands that Autohand runs at specific points in the agent lifecycle: before and after tool calls, when files change, when a turn or session ends, when permission is requested or refused, and across auto-mode, sub-agent, team, review, and context events. They let you automate around the agent without changing its behavior.

Common use cases:

• Run linters and formatters after file changes
• Execute related tests after code modifications
• Send notifications when a turn or session completes
• Block dangerous commands or auto-approve safe ones
• Log tool executions for audit trails and telemetry
• Trigger CI/CD pipelines and integrate with external services

Hooks can be defined in your config file, registered by enabled and trusted extensions through api.hooks.on(event, handler), and, when running in JSON-RPC mode for IDE integrations, emitted as JSON-RPC 2.0 notifications.

Configuration

Hooks live under the hooks key of your Autohand config file (~/.autohand/config.json by default, or the file passed with --config or AUTOHAND_CONFIG). The hooks object holds a global enabled switch and an array of hook definitions.

Basic structure

{
  "hooks": {
    "enabled": true,
    "hooks": [
      {
        "event": "pre-tool",
        "command": "echo \"Running tool: $HOOK_TOOL\" >> ~/.autohand/hooks.log",
        "description": "Log all tool executions",
        "enabled": true
      },
      {
        "event": "file-modified",
        "command": "./scripts/on-file-change.sh",
        "description": "Custom file change handler",
        "filter": { "path": ["src/**/*.ts"] }
      },
      {
        "event": "stop",
        "command": "printf '%s\\n' \"$HOOK_TOKENS\" >> token-usage.log",
        "description": "Track token usage",
        "async": true
      }
    ]
  }
}

Hook definition properties

Filter object

Limit when a hook fires with a filter object:

{
  "filter": {
    "tool": ["run_command", "write_file"],
    "path": ["src/**/*.ts", "lib/**/*.js"]
  }
}

• tool: array of tool names. The hook only fires for these tools.
• path: array of glob patterns. The hook only fires for matching file paths.

Matcher (regex filtering)

Use the matcher property to filter events with a regular expression:

{
  "event": "pre-tool",
  "command": "./log-dangerous.sh",
  "matcher": "^(run_command|delete_path)$",
  "description": "Log only dangerous tool calls"
}

What the matcher is tested against depends on the event:

Hook events

Every event below is available to config hooks, extension hooks, and the /hooks browser. post-response is a backward-compatible alias for stop and is listed under stop in /hooks.

Session

Prompt & turn

Tool

File

Subagent

Synchronous subagent-start and subagent-progress hooks can return additionalContext to queue context for that worker's next safe model step, or continue: false with a stopReason to stop only that worker. subagent-message, subagent-cancel-requested, and subagent-stop are observational, and any returned control fields are ignored.

Permission & notification

Rate limit & errors

Long-window quotas (5-hour, daily, weekly, or unscoped) are not retried within the turn. The turn ends immediately and both session-error and rate-limit fire once. HOOK_RETRY_AFTER_MS is set only when the provider advertised a Retry-After, so branch on its presence rather than assuming a value.

Auto-mode

Auto-research

Learn & goals

Teams

Review

Mode & context

Environment variables

When a hook command executes, these variables are set in its environment. Availability depends on the event.

JSON input and control-flow responses

JSON input (stdin)

In addition to environment variables, every hook receives its context as a JSON object on stdin. Read it once and parse the fields you need:

#!/bin/bash
# Hook script that reads JSON input
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
TOOL_ARGS=$(echo "$INPUT" | jq -r '.tool_input')

echo "Tool: $TOOL_NAME with args: $TOOL_ARGS"

Fields that do not apply to the current event are null. A pre-tool payload looks like this:

{
  "session_id": "abc123",
  "cwd": "/path/to/workspace",
  "hook_event_name": "pre-tool",
  "tool_name": "write_file",
  "tool_input": { "path": "src/index.ts", "content": "..." },
  "tool_use_id": "call_123",
  "tool_response": null,
  "tool_success": null,
  "file_path": null,
  "change_type": null,
  "instruction": null,
  "mentioned_files": null,
  "tokens_used": null,
  "tokens_usage_status": null,
  "tool_calls_count": null,
  "turn_tool_calls": null,
  "turn_duration": null,
  "duration": null,
  "error": null,
  "error_code": null,
  "session_type": null,
  "session_end_reason": null,
  "subagent_id": null,
  "subagent_name": null,
  "subagent_type": null,
  "subagent_success": null,
  "subagent_error": null,
  "subagent_duration": null,
  "permission_type": null,
  "notification_type": null,
  "notification_message": null,
  "automode_session_id": null,
  "automode_prompt": null,
  "automode_iteration": null,
  "automode_max_iterations": null,
  "automode_actions": null,
  "automode_files_created": null,
  "automode_files_modified": null,
  "automode_cancel_reason": null,
  "automode_checkpoint_commit": null,
  "automode_total_cost": null,
  "review_path": null,
  "review_scope": null,
  "review_instructions": null,
  "review_error": null,
  "team_name": null,
  "teammate_name": null,
  "teammate_agent_name": null,
  "teammate_pid": null,
  "team_task_id": null,
  "team_task_owner": null,
  "team_task_result": null,
  "team_member_count": null,
  "team_tasks_completed": null,
  "team_tasks_total": null,
  "additional_workspaces": null
}

Mode changes add previous_mode and mode. Subagent events add the task and queued message text as subagent_task and subagent_message.

Control-flow responses

A synchronous hook can print a JSON object on stdout to control what the agent does next. This is how you automate permission decisions, block dangerous operations, or modify tool inputs.

{
  "decision": "allow",
  "reason": "Approved by automation",
  "continue": true,
  "stopReason": null,
  "updatedInput": null,
  "additionalContext": null
}

A pre-prompt hook can prevent model work with a decision of deny or block, continue: false, or exit code 2.

Exit codes

Template variables

Any hook command may contain {{variable}} placeholders. They are replaced before the command runs, so they work alongside the $HOOK_* environment variables. Values that are not a single plain word are single-quoted for the shell, so eslint {{file}} is safe for paths with spaces. Unknown variables become empty strings.

{
  "event": "file-modified",
  "command": "eslint {{file}} --fix",
  "filter": { "path": ["**/*.ts"] }
}

Legacy event names

The first hooks documentation described an event-keyed config shape, on_* / before_* / after_* event names, and {{variable}} placeholders. All three still work and are rewritten onto the lifecycle events above, so an older configuration keeps firing without changes. Legacy hooks receive the same environment variables and JSON input as the event they map to, their results are reported under that event, and /hooks lists them under the mapped event.

Legacy config shape

Commands may be listed directly under an event name. Each string (or object with a command) becomes a hook definition for that event, and the array form and the event-keyed form can be mixed. The next time hooks are saved from /hooks, the file is written in the array form.

{
  "hooks": {
    "on_file_change": [
      "eslint {{file}} --fix",
      { "command": "prettier --write {{file}}", "async": true }
    ],
    "on_session_end": ["notify-send \"Autohand session finished\""]
  }
}

Legacy name mapping

Examples

Each example is one entry for the hooks.hooks array. Scripts under ~/.autohand/hooks/ must be executable.

Auto-lint on file changes

Run ESLint and Prettier whenever the agent creates or modifies a TypeScript file:

{
  "event": "file-modified",
  "command": "eslint \"$HOOK_PATH\" --fix && prettier --write \"$HOOK_PATH\"",
  "description": "Auto-lint TypeScript",
  "filter": { "path": ["**/*.ts", "**/*.tsx"] }
}

Run tests after changes

Execute the tests related to the changed file. Test runs take longer than the 5-second default, so raise the timeout:

{
  "event": "file-modified",
  "command": "npm test -- --findRelatedTests {{file}}",
  "description": "Run related tests",
  "filter": { "path": ["src/**/*"] },
  "timeout": 30000
}

Slack notifications

Post a message when a session ends. Keep the webhook URL in an environment variable, and run the hook asynchronously so it never blocks shutdown:

{
  "event": "session-end",
  "command": "curl -X POST \"$SLACK_WEBHOOK\" -H 'Content-type: application/json' -d \"{\\\"text\\\": \\\"Autohand session ended ($HOOK_SESSION_END_REASON) after ${HOOK_DURATION}ms\\\"}\"",
  "description": "Slack notification on session end",
  "async": true
}

Audit logging

Record every tool call with its outcome and duration for compliance:

{
  "event": "post-tool",
  "command": "echo \"$(date -u +%FT%TZ) | $HOOK_TOOL | success=$HOOK_SUCCESS | ${HOOK_DURATION}ms\" >> ~/.autohand/audit.log",
  "description": "Audit tool calls"
}

Block dangerous commands

Use a synchronous pre-tool hook to inspect shell commands before they run. Return {"decision": "deny"} to reject the call without prompting, or exit with code 2 to stop execution with the stderr message:

{
  "event": "pre-tool",
  "command": "~/.autohand/hooks/block-dangerous.sh",
  "description": "Block destructive shell commands",
  "matcher": "^run_command$"
}

With ~/.autohand/hooks/block-dangerous.sh:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if [[ "$COMMAND" =~ rm.*-rf.*/ ]]; then
  echo '{"decision": "deny", "reason": "Recursive delete of a root path is not allowed"}'
  exit 0
fi

# Equivalent hard stop: report on stderr and exit 2
# echo "Blocked dangerous rm command: $COMMAND" >&2
# exit 2

exit 0

Type checking on TypeScript files

Run the type checker whenever a TypeScript file changes:

{
  "event": "file-modified",
  "command": "npx tsc --noEmit",
  "description": "Type-check after TypeScript edits",
  "filter": { "path": ["**/*.ts", "**/*.tsx"] },
  "timeout": 60000
}

Git pre-commit style check

Gate git commit behind lint and type checks. A non-zero exit from the checks becomes exit code 2, which blocks the command:

{
  "event": "pre-tool",
  "command": "~/.autohand/hooks/commit-gate.sh",
  "description": "Lint and type-check before git commit",
  "matcher": "^run_command$",
  "timeout": 120000
}

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if [[ "$COMMAND" == git\ commit* ]]; then
  if ! npm run lint && npm run typecheck; then
    echo "Commit blocked: lint or typecheck failed" >&2
    exit 2
  fi
fi

exit 0

Advanced configuration

Timeouts

Each hook has a timeout in milliseconds (default 5000). Quick logging needs 1000-2000ms, network calls usually need 10000-30000ms, and anything longer should run asynchronously.

{
  "event": "file-modified",
  "command": "npm test -- --findRelatedTests \"$HOOK_PATH\"",
  "timeout": 30000
}

Async hooks

Set async: true to run a hook in the background without blocking the agent. Use it for logging, metrics, and notifications, not for hooks that return control-flow decisions, since their output is not waited for:

{
  "event": "file-modified",
  "command": "npm run build",
  "async": true
}

External scripts

For anything beyond a one-liner, point command at a script. Scripts created from /hooks are saved under ~/.autohand/hooks/generated/, and the bundled examples live in ~/.autohand/hooks/. Scripts read the JSON payload from stdin and the $HOOK_* variables from the environment:

{
  "hooks": {
    "hooks": [
      { "event": "file-modified", "command": "~/.autohand/hooks/on-change.sh" },
      { "event": "session-end", "command": "~/.autohand/hooks/session-complete.sh" }
    ]
  }
}

Conditional hooks

Prefer filter and matcher over shell conditionals so hooks that do not apply never spawn a process:

{
  "hooks": {
    "hooks": [
      {
        "event": "file-modified",
        "command": "npm test -- \"$HOOK_PATH\"",
        "filter": { "path": ["**/*.test.ts"] }
      },
      {
        "event": "file-modified",
        "command": "eslint \"$HOOK_PATH\"",
        "filter": { "path": ["**/*.ts"] }
      },
      {
        "event": "post-tool",
        "command": "~/.autohand/hooks/shell-audit.sh",
        "matcher": "^(run_command|custom_command)$"
      }
    ]
  }
}

Debugging hooks

View configured hooks

Open /hooks for the interactive event browser, which shows installed and active counts per event and lists each hook with its source. /hooks list prints the same table and also works without a TTY:

/hooks list

# Hooks — Lifecycle hooks from config and enabled plugins.
# Event                     Installed  Active   Description
# session-start             1          1        When a session begins
# pre-tool                  2          2        Before a tool executes
# file-modified             1          0        When files are changed
# ...

An installed hook with an active count of zero is disabled, either individually or by the global switch. /hooks manage toggles hooks on and off, removes them, adds them manually, and can run a hook with sample context (only do this when you intend its side effects to occur).

Test hooks manually

Run the script outside Autohand with the same inputs the agent provides: the $HOOK_* variables in the environment and the JSON payload on stdin. Then check its exit code and stdout:

# Environment-variable style
HOOK_EVENT=file-modified HOOK_PATH=src/auth.ts HOOK_CHANGE_TYPE=modify \
HOOK_WORKSPACE="$PWD" HOOK_SESSION_ID=test \
  ~/.autohand/hooks/on-change.sh

# JSON-stdin style, checking a control-flow decision
echo '{"hook_event_name":"pre-tool","tool_name":"run_command","tool_input":{"command":"rm -rf /"}}' \
  | ~/.autohand/hooks/block-dangerous.sh; echo "exit=$?"

Common issues

Best practices

Keep hooks fast

Synchronous hooks block the agent until they finish. Keep them short, and move long-running or non-critical work behind async: true.

Handle failures deliberately

Hook failures never crash the agent. A non-zero exit other than 2 is logged and execution continues, while exit code 2 blocks the current action with the stderr message. Exit 2 only when you mean to stop the agent.

Use control flow sparingly

Reserve decision: "allow" for operations you are certain are safe, fall back to decision: "ask", use decision: "block" or exit code 2 for truly dangerous operations, and always include a reason so allow and deny decisions are auditable.

Treat hook input as untrusted

Hooks run in your shell with your permissions and receive model-generated arguments. Quote $HOOK_* values, pass values as arguments rather than interpolating them into shell strings, keep secrets in environment variables, and avoid loading hooks from config files you do not trust.

Document your hooks

Give each hook a description so it is recognizable in /hooks, and explain team hooks in your AGENTS.md:

# AGENTS.md

## Hooks
The following hooks are configured:
- **file-modified**: Auto-formats code with Prettier and ESLint
- **session-end**: Posts a summary to the #dev-updates Slack channel

Frequently asked questions