Hooks

Hooks are shell scripts that run automatically at moments you choose — before the agent edits a file, after it runs a command, when a session starts.

A quick example

Inject today's date into every prompt automatically, without adding it to every message yourself:

# ~/.agents/hooks/inject-date.sh
echo '{"context": "Today is '$(date +%Y-%m-%d)'"}'

# ~/.agents/agents.yaml
hooks:
  inject-date:
    script: inject-date.sh
    events:
      - UserPromptSubmit

You type a prompt
free-form input
UserPromptSubmit hook fires
injects “today is 2026-06-07” into context
Model picks a tool
e.g. Edit a file
PreToolUse hook gates the call
approve · block · log
Result returns to you

Events you can hook into

SessionStart — fires when the agent session begins. Perfect for injecting today's date or a reminder of project rules.
SessionEnd — fires when the session ends (Claude, Grok). Good for writing a summary or sending a notification.
UserPromptSubmit — fires before the model sees your message. Use it to append context automatically.
PreToolUse — fires before any tool call executes. Use it to log, approve, or block actions.
PostToolUse — fires after a tool call completes. Good for audit trails or follow-up actions.
PreCompact — fires before context compaction (Claude, Grok). Use it to preserve important context.
Stop — fires when the agent finishes its final turn. Use it to run tests or send a notification.
Notification — fires when the agent sends a notification. Use it to route alerts to Slack or a log file.

The manifest

Declare hooks in ~/.agents/agents.yaml. The user layer wins over the system layer on key collision.

# ~/.agents/agents.yaml
hooks:
  post-edit:
    script: post-edit.sh           # filename in ~/.agents/hooks/
    events:
      - PostToolUse
    timeout: 30                    # seconds; default 600
    matches:
      tool_name: "Edit"            # only fire on Edit tool calls
      cwd_includes: /projects/myapp

  session-start:
    script: session-start.sh
    events:
      - SessionStart
    timeout: 10

  prompt-guard:
    script: prompt-guard.sh
    events:
      - UserPromptSubmit
    matches:
      prompt_contains: "deploy"

The script field is a filename resolved from ~/.agents/hooks/ then ~/.agents-system/hooks/. The agent passes event context as JSON on stdin when the script fires.

Predicate matchers

All predicates in a matches: block AND together — every declared predicate must pass, or the script is skipped. An empty matches: block always passes.

prompt_contains: "text" — user prompt contains this substring (exact match)
prompt_matches: "^(deploy|release)" — user prompt matches this regex; capped at 200 chars, max group depth 3
tool_name: ["Edit", "Write"] — tool name equals one of these values (string or array)
tool_args_match: "production" — serialized tool arguments match this regex
cwd_includes: "/projects/myapp" — working directory contains any of these substrings (string or array)
project_has: "Cargo.toml" — nearest .git ancestor directory contains this file or directory
git_dirty: true — working tree dirty state matches this boolean

# Fire only on Edit or Write, in a specific repo, when git is dirty
matches:
  tool_name: ["Edit", "Write"]
  project_has: "go.mod"
  git_dirty: true

Disable a system hook

To turn off a hook shipped by the system without deleting or forking it, add an entry with enabled: false in your user layer:

# ~/.agents/agents.yaml
hooks:
  03-linear-inject-tasks-context:
    script: 03-linear-inject-tasks-context.sh
    events:
      - UserPromptSubmit
    enabled: false

An enabled: false entry is stripped before it reaches the agent — the hook will not fire for any agent.

Managing hooks

agents hooks list                    # show all registered hooks
agents hooks list claude             # filter to claude
agents hooks list --scope user       # only user-layer hooks
agents hooks add gh:team/hooks --agents claude,codex
agents hooks add --names post-edit --agents claude
agents hooks view post-edit          # print the script source
agents hooks remove post-edit        # remove from agent version homes

Config layers — hooks participate in the same layered resolution as commands, skills, and rules.
Permissions — allow/deny lists that gate tool calls at the harness level.
Secrets — credential bundles hooks can consume via agents secrets exec.