Agent hooks in Azure SRE Agent

Hooks are custom checkpoints that intercept and control agent behavior at key moments. Use hooks to enforce quality gates on agent responses, audit and control tool usage, block dangerous operations by enforcing policies, and prevent early task completion by validating agent output.

The problem agent hooks solve

Your agent runs tasks autonomously by investigating incidents, running tools, and generating responses. But autonomy without oversight creates risk:

• Incomplete responses: The agent says "done" before addressing everything you asked for.
• Unaudited tool usage: You have no visibility into which tools the agent calls or what results it gets.
• No policy enforcement: Dangerous operations (destructive commands, unauthorized changes) proceed unchecked.
• Quality gaps: Responses miss critical information because there's no validation step.

You need a way to intercept agent behavior at key moments without slowing it down or removing its autonomy entirely.

How agent hooks work

Hooks are custom checkpoints you attach to specific agent events. When an event fires, your hook evaluates the situation and decides whether to allow or block the action.

Agent about to stop → Stop hook evaluates response → Allow or reject
Agent uses a tool   → PostToolUse hook checks result → Allow, block, or inject context

Two hook events are currently supported:

Two levels of hooks

Hooks operate at two levels:

Both levels can coexist. If an agent-level hook and a custom-agent-level hook both match the same event, both run. The agent-level hooks fire first.

Execution types

You can implement hooks by using either an LLM or a shell script:

Prompt hooks are powerful for subjective evaluation, such as checking if a response addresses all user concerns or verifying that an investigation was thorough enough. They use the $ARGUMENTS placeholder to receive the full hook context. If $ARGUMENTS isn't present in the prompt, the context is appended automatically. When a conversation transcript is available, prompt hooks also receive ReadFile and GrepSearch tools, which let the LLM reason about the full conversation history.

Command hooks are better for deterministic checks, such as validating that a response contains required markers, blocking dangerous commands, or logging tool usage to an external system.

Agent behavior with and without hooks

The following table compares agent behavior with and without hooks.

Hooks don't replace run mode safety controls. Instead, they complement them. Run modes control what the agent can do. Hooks control how well it does and what happens with the results.

Before and after adding agent hooks

Configure agent hooks

Create hooks through the portal UI:

1. Agent-level hooks: Go to Builder → Hooks → select Create hook.
2. Custom-agent-level hooks: Go to Agent Canvas → select a custom agent → Manage Hooks.

For step-by-step instructions, see Create and manage hooks in the portal.

The following example shows a complete hook configuration:

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check if the response ends with "Task complete."
          $ARGUMENTS
          Respond with:
          - {"ok": true} if it does
          - {"ok": false, "reason": "End your response with 'Task complete.'"} if not
        timeout: 30

    PostToolUse:
      - type: command
        matcher: "Bash|ExecuteShellCommand"
        timeout: 30
        failMode: block
        script: |
          #!/usr/bin/env python3
          import sys, json, re

          context = json.load(sys.stdin)
          command = context.get('tool_input', {}).get('command', '')

          dangerous = [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']
          for pattern in dangerous:
              if re.search(pattern, command):
                  print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
                  sys.exit(0)

          print(json.dumps({"decision": "allow"}))

Hook response format

Hooks must output JSON. Two formats are supported:

Simple format (recommended for prompt hooks):

{"ok": true}
{"ok": false, "reason": "Please include more details."}

Expanded format (recommended for command hooks):

{"decision": "allow"}
{"decision": "block", "reason": "Dangerous command detected."}
{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Tool audit logged."}}

Command hooks can also use exit codes instead of JSON output:

Configuration reference

The following table describes all available hook configuration options.

Hook context schema

Hooks receive structured JSON context about the current event. Prompt hooks receive context via the $ARGUMENTS placeholder in the prompt text. Command hooks receive context as JSON on stdin.

For both hook types, the execution_summary field contains a file path to the conversation transcript (not inline content). For prompt hooks, the LLM receives ReadFile and GrepSearch tools to access this file. For command hooks, the file is available at the specified path in the sandbox.

Common fields

All hooks receive the following fields:

{
  "hook_event_name": "Stop",
  "agent_name": "my_agent",
  "current_turn": 5,
  "max_turns": 50,
  "execution_summary": "/path/to/transcript.txt"
}

Stop hook fields

Stop hooks receive extra fields about the agent's final output.

{
  "final_output": "Here is my response...",
  "stop_hook_active": false,
  "stop_rejection_count": 0
}

PostToolUse hook fields

PostToolUse hooks receive extra fields about the tool execution.

{
  "tool_name": "ExecutePythonCode",
  "tool_input": { "code": "print(2+2)" },
  "tool_result": "4",
  "tool_succeeded": true
}

Model tiers

Prompt hooks use an AI model to evaluate agent behavior. You can select which model tier the hook uses, balancing evaluation quality against cost and latency.

Limits

The following limits apply to agent hooks.

Example: Audit all tool usage

The following PostToolUse hook logs every tool call and adds an audit context message:

hooks:
  PostToolUse:
    - type: command
      matcher: "*"
      timeout: 30
      failMode: allow
      script: |
        #!/usr/bin/env python3
        import sys, json

        context = json.load(sys.stdin)
        tool_name = context.get('tool_name', 'unknown')

        print(f"Tool used: {tool_name}", file=sys.stderr)

        output = {
            "decision": "allow",
            "hookSpecificOutput": {
                "additionalContext": f"[AUDIT] Tool '{tool_name}' was executed."
            }
        }
        print(json.dumps(output))

The additionalContext field is added as a user message into the conversation, giving the agent visibility into the audit trail.

Example: Require a completion marker

The following Stop hook rejects responses that don't end with "Task complete.":

hooks:
  Stop:
    - type: command
      timeout: 30
      failMode: allow
      script: |
        #!/bin/bash
        CONTEXT=$(cat)
        FINAL_OUTPUT=$(echo "$CONTEXT" | jq -r '.final_output // empty')

        if [[ "$FINAL_OUTPUT" == *"Task complete."* ]]; then
          exit 0
        else
          echo "Please end your response with 'Task complete.'" >&2
          exit 2
        fi

Best practices

When you configure agent hooks:

1. Always provide a reason when rejecting. Treat rejections without reasons as approvals.
2. Use appropriate timeouts: Long-running hooks slow down agent execution.
3. Handle errors gracefully: Use failMode: allow unless strict enforcement is required.
4. Be specific with matchers: Overly broad PostToolUse matchers can cause performance problems.
5. Test hooks thoroughly: Hooks that always reject can cause loops (mitigated by maxRejections).
6. Log to stderr: Use stderr for debugging output. The system parses stdout as the hook result.

Try agent hooks yourself

The following screenshot shows a Stop hook in action. The agent initially responds with just "4", but the hook rejects the response because the completion marker is missing. The agent then continues and adds the marker.

Get started

Related content