Hooks

The hooks block lets you run commands or inject prompts in response to events in the agent lifecycle. Hooks are useful for logging, notifications, guardrails, and dynamic prompt injection.

Basic Syntax

hooks {
  log-start {
    on: AgentStart
    run: "echo 'Agent started: $AGENT_NAME'"
    type: command
  }
}

Field Reference

Field	Type	Required	Description
`on`	identifier	Yes	The event that triggers this hook
`matcher`	string	No	Filter to specific agents or tools
`run`	string	Yes	Command to execute or prompt to inject
`type`	identifier	No	`command` (default) or `prompt`
`timeout`	number	No	Timeout in seconds for command execution

Events

Event	Fires When
`AgentStart`	An agent begins execution
`AgentStop`	An agent finishes execution
`ToolUse`	An agent invokes a tool
`Error`	An agent encounters an error
`SessionStart`	The topology session begins
`SessionEnd`	The topology session ends

Command Hooks

Command hooks run a shell command when the event fires:

hooks {
  notify-completion {
    on: AgentStop
    run: "curl -X POST https://slack.webhook/notify -d '{\"agent\": \"$AGENT_NAME\"}'"
    type: command
    timeout: 10
  }
}

Prompt Hooks

Prompt hooks inject additional instructions into the agent's context:

hooks {
  safety-reminder {
    on: AgentStart
    run: "Remember: never expose API keys or credentials in your output."
    type: prompt
  }
}

Matcher

Use matcher to scope a hook to specific agents or tools:

hooks {
  log-writes {
    on: ToolUse
    matcher: "Write"
    run: "echo 'Write tool used by $AGENT_NAME'"
    type: command
  }

  deployer-guardrail {
    on: AgentStart
    matcher: "deployer"
    run: "You must verify all tests pass before deploying."
    type: prompt
  }
}

Per-Agent Hooks

You can also define hooks inside an agent block to scope them to that agent only:

agent deployer {
  model: opus
  tools: [Bash]

  hooks {
    pre-deploy-check {
      on: AgentStart
      run: "Confirm the target environment before running any commands."
      type: prompt
    }
  }
}

Full Example

topology monitored-pipeline : [pipeline] {
  agent researcher { model: sonnet  tools: [WebSearch, Read] }
  agent writer     { model: sonnet  tools: [Write] }

  flow {
    researcher -> writer
  }

  hooks {
    session-log {
      on: SessionStart
      run: "echo 'Pipeline started at $(date)'"
      type: command
    }

    tool-audit {
      on: ToolUse
      run: "echo '$AGENT_NAME used $TOOL_NAME' >> audit.log"
      type: command
    }

    error-alert {
      on: Error
      run: "curl -X POST https://pagerduty.com/alert -d '{\"error\": \"$ERROR_MSG\"}'"
      type: command
      timeout: 5
    }
  }
}

Tips

Command hooks run in a shell environment with event-specific variables like $AGENT_NAME, $TOOL_NAME, and $ERROR_MSG.
Set timeout on command hooks to prevent slow external calls from blocking your topology.
Prompt hooks of type prompt are injected into the agent context — they do not run as shell commands.
Use matcher to avoid overly broad hooks that fire on every event.

Hooks

On this page