Hooks are host lifecycle callbacks, not MCP tool calls. The hard part is that each CLI exposes hooks differently. agent-connector groups those differences into paradigms so a connector author can write one normalized handler and still get honest per-host behavior.

The hook mental model#

A hook runs because the host emitted an event: session started, a tool is about to run, a permission decision is needed, a tool failed, context was compacted, or a subagent changed state. The model does not choose a hook the way it chooses an MCP tool.

Connector declares a normalized hook handler
        |
        v
Target host adapter decides the hook paradigm
        |
        +-- json-stdio: host config calls the home-bin hook command
        |
        +-- ts-plugin: generated plugin module imports/dispatches handlers
        |
        +-- mcp-only: no host hook layer, so hooks skip with a warning
        |
        v
Handler returns context / allow / block / warn where supported

Official host surfaces to know first#

Start by separating three facts: MCP tools are model-selected, hooks are host lifecycle callbacks, and each host chooses its own hook transport. The links below are the current public references used by this guide.

Cross-validation before a hook claim#

The full host lists below are generated from adapter metadata, not typed by hand. A host is presented as hook-capable only when the registry reports a non-MCP-only paradigm and the docs drift tests keep the list in lock-step with loaded adapters. The examples table adds external evidence for representative host families.

CLI behavior by hook paradigm#

Write the connector hook once#

The connector author writes against agent-connector's normalized event type. This example blocks one dangerous shell pattern, injects context for this connector's MCP tools, and leaves unsupported host behavior to the adapter.

import {
  defineConnector,
  defineHook,
} from "@ken-jo/agent-connector/sdk";

const guardRiskyWrites = defineHook("PreToolUse", {
  matcher: "Bash|Write|Edit|apply_patch|mcp__acme_db__.*",
  handler(evt) {
    const input = JSON.stringify(evt.toolInput ?? {});

    if (evt.toolName === "Bash" && /\brm\s+-rf\b/.test(input)) {
      return {
        decision: "deny",
        reason: "rm -rf is blocked by acme-db policy.",
      };
    }

    if (evt.toolName.startsWith("mcp__acme_db__")) {
      return {
        decision: "context",
        additionalContext: "acme-db MCP tools are read-only in this connector.",
      };
    }
  },
});

export default defineConnector({
  server: { transport: "stdio", command: "node", args: ["./my-mcp-server.mjs"] },
  hooks: { PreToolUse: guardRiskyWrites },
});

What host config can look like#

These are representative rendered shapes, not extra files you maintain by hand. The stable part is the home-bin command: agent-connector hook <host> <event> --connector <id>.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "agent-connector hook claude-code PreToolUse --connector acme-db"
          }
        ]
      }
    ]
  }
}

What happens during dispatch#

• The host emits a native lifecycle payload in its own format.
• The adapter converts that payload into one normalized event shape where the host has a matching concept.
• The connector hook handler receives the event and returns context, allow/block, warning text, or another supported response.
• The adapter translates that response back to the native host contract.
• If the host cannot support that event or response, the installer and doctor surface the limitation as a warning or unavailable capability.

How to customize behavior safely#

• Use matcher to narrow the hook to specific tool names or MCP tool prefixes before adding logic.
• Use hosts overrides only when one host has different semantics; the top-level handler stays the mandatory fallback.
• Use platforms.<id>.nativeHooks for host-specific events that have no normalized event yet, then keep the payload parsing local to that host.
• Disable a surface per host with platforms.<id>.hooks = false when the host behavior is not mature enough for your package.

Beginner safety rules#

• Keep hook handlers fast. A hook sits on the host's interaction path.
• Return small context. Large hook output becomes model context or host UI noise.
• Treat hook payloads as host-specific observations, not guaranteed universal state.
• Test one host from each paradigm before claiming cross-host behavior.