Hooks

Hooks let you attach external logic to caliban's event stream — shell scripts, HTTP callbacks, or MCP tools — without modifying the agent or recompiling. Hooks run in-process (for the built-in PermissionsHook and audit hooks) or via an external HookRouter (for operator-configured handlers).

Event taxonomy

Caliban fires events at the following lifecycle points (ADR 0024):

Additional events (Setup, UserPromptExpansion, PostToolBatch, InstructionsLoaded, WorktreeCreate, WorktreeRemove, Elicitation, ElicitationResult, TeammateIdle) are reserved but not yet fired.

Handler types

Each hook entry declares one or more handlers. Two handler types are fully wired; three are stubs (see below).

Decision protocol

For PreToolUse and UserPromptSubmit, command and http handlers report their decision as:

Stdout JSON (preferred):

{
  "hookSpecificOutput": {
    "permissionDecision": "allow",
    "permissionDecisionReason": "matched allowlist",
    "updatedInput": {}
  }
}

permissionDecision values: allow, deny, ask. updatedInput lets the hook rewrite the tool input before dispatch (the rewritten input is validated against the tool's schema; validation failure is a hard deny).

Exit codes (shell-script shorthand):

• 0 — Allow
• 2 — Deny (stderr becomes the reason)
• anything else — Allow with a logged warning

PostToolUse and observer-only hooks ignore the decision even when a handler provides one. Handlers marked async = true are fire-and-forget; their decisions are always ignored.

Config: settings hooks table (preferred)

Hooks live in the unified settings file under the hooks key. The table maps event names to arrays of handler groups. See Settings Layering for how scopes merge — hook arrays concatenate across scopes (project entries append to user entries).

# .caliban/settings.toml  — project scope

disable_all_hooks = false
allow_managed_hooks_only = false

allowed_http_hook_urls = [
  "https://hooks.example.com/*",
]
http_hook_allowed_env_vars = ["AUDIT_TOKEN"]

[[hooks.SessionStart]]
matcher = "*"
[[hooks.SessionStart.handlers]]
type    = "command"
command = "/usr/local/bin/caliban-audit"
args    = ["session-start"]
timeout = "5s"

[[hooks.PreToolUse]]
matcher = "Bash"
if      = "Bash:rm *"
[[hooks.PreToolUse.handlers]]
type    = "command"
command = "${CALIBAN_PROJECT_DIR}/.caliban/hooks/guard-rm.sh"
async   = false

[[hooks.PreToolUse]]
matcher = "WebFetch"
[[hooks.PreToolUse.handlers]]
type    = "http"
url     = "https://hooks.example.com/preflight"
headers = { Authorization = "Bearer ${AUDIT_TOKEN}" }
timeout = "3s"

[[hooks.PostToolUse]]
matcher = "*"
[[hooks.PostToolUse.handlers]]
type  = "mcp"
mcp   = "audit-server"
tool  = "log_tool_call"
async = true

Config: legacy hooks.toml (compat)

If no hooks key appears in any settings file, caliban falls back to loading:

• <workspace>/.caliban/hooks.toml (project scope)
• ~/.config/caliban/hooks.toml (user scope)

The legacy file uses the same TOML shape shown above (top-level keys plus [[hooks.<Event>]] arrays). The two scopes merge with project entries taking priority. This path is deprecated — prefer the unified settings file for new configurations.

Safety controls

Related pages

• Permissions concepts
• Plugins — plugins can bundle hook configurations
• Slash Command Index — /hooks shows the active handler set