Hooks

# hooks/hooks.yaml
hooks:
  on_session_start:
    - script:check-auth.sh
      description: "Verify user authorization"

  pre_tool_use:
    - script:validate-command.sh
      description: "Block dangerous CLI commands"

  post_tool_failure:
    - script:notify-error.sh

  post_response:
    - script:log-response.sh

  pre_query:
    - script:rate-limit.sh

  file_changed:
    - script:track-changes.sh

  on_error:
    - script:incident-report.sh

{
  "event": "pre_tool_use",
  "session_id": "uuid",
  "tool": "cli",
  "args": {"command": "rm -rf /"}
}

{"action": "allow"}
{"action": "block", "reason": "Destructive command blocked"}
{"action": "modify", "args": {"command": "echo safe"}}

// sdk-hooks.ts
for await (const msg of query({
  prompt: "Deploy the service",
  hooks: {
    preToolUse: async (ctx) => {
      if (ctx.toolName === "cli" && ctx.args.command?.includes("rm -rf"))
        return { action: "block", reason: "Destructive command blocked" };
      if (ctx.toolName === "write" && !ctx.args.path.startsWith("/safe/"))
        return { action: "modify", args: { ...ctx.args, path: `/safe/${ctx.args.path}` } };
      return { action: "allow" };
    },
    onError: async (ctx) => {
      console.error(`Agent error: ${ctx.error}`);
    },
  },
})) { /* ... */ }