Hooks

Hooks run reviewed behavior at Agent lifecycle boundaries. Kairo Code has two Hook surfaces:

• Host-owned Java Hooks and guards enforce product safety, evidence, and presentation policy.
• Activated Plugins can contribute session-scoped command, http, prompt, agent, and mcp_tool actions.

A Hook is not an Agent or Skill. It has no separate conversation and cannot widen the Task's workspace, permission profile, network policy, or administrator-owned security ceiling.

Author a Plugin Hook

Put Hook definitions in hooks/hooks.json inside a Plugin. For example:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${KAIRO_PLUGIN_ROOT}/scripts/check.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Matchers are case-sensitive and apply to the whole target. | separates alternatives, * matches any sequence, ? matches one Unicode code point, and a missing or blank matcher matches every target. Matchers are a bounded wildcard language, not arbitrary regular expressions.

The Plugin must be installed, reviewed, and activated before its Hooks can run. New Tasks receive an immutable capability snapshot; enabling, disabling, or rolling back a Plugin does not mutate an already running Task. See Plugins for the controlled installation flow.

Runtime and failure contract

Kairo Code installs exactly one session-scoped framework bridge for Plugin Hooks. It preserves Plugin, binding, and action declaration order and sends a bounded structured JSON payload to each action. command actions run through the Task execution sandbox; http actions use the reviewed network path; model-, Agent-, and MCP-backed actions use product-owned adapters.

Before a tool, prompt, compaction, permission, subagent, setup, worktree, or completion decision, an unavailable adapter, failed action, invalid decision, or truncated decision fails closed and stops later actions. Observational phases record the failure and leave the event unchanged. Plugin decisions currently support denial, modified tool input, and modified prompts; they do not map to the core SKIP, INJECT, or COMPLETE decisions.

Treat every Plugin Hook as executable code. Review its source, pinned revision, commands, URLs, model prompts, MCP targets, and requested data before activation. Hook logs do not include prompt, tool-input, command, or credential payloads.

Retired local shell format

Kairo Code does not read ~/.kairo-code/hooks.json or project .kairo-code/hooks.json. The former flat {matcher, command} shell format used an independent asynchronous executor and is not a supported compatibility path. Move reviewed behavior into a Plugin instead of copying placeholder commands into a local file.

Inspect Hooks and guards

Open Settings → Extensions → Hooks to inspect the Host-owned Hook and guard policy. Manage Plugin-contributed Hooks through Settings → Extensions → Plugins, where the complete Plugin snapshot can be reviewed and rolled back. There is no separate command surface for managing Hooks.