Hooks

Hooks are guardrail code that runs at the runtime's lifecycle boundaries. Where a tool is a capability the model chooses to call, a hook sees (and may allow, block, modify, or gate) every input, tool call, and output, whoever produced it: chat, an intent, a skill, or a delegated agent. That makes hooks the right place for hard rules that must hold platform-wide: data-loss prevention, redaction, write policies, permission checks against your own stores.

Folder shape

Hooks live at the repo root under hooks/, one folder per hook:

hooks/
└── ready-to-quote-guard/
    ├── hook.json     ← declarative manifest (binding, capabilities, config)
    └── index.mjs     ← decision module (exports createHook)

The manifest is authoritative for what the hook binds to and what it may do; the module only supplies the decision function. The runtime discovers every subfolder of hooks/ automatically; there is no registration list.

Ship the handler as .mjs. Unlike intents and tools, the hook loader imports the module directly (no esbuild step), so plain ESM JavaScript is the reliable format. (index.js and index.ts are probed too, but a .ts handler only works where the host process can already import TypeScript.)

hook.json

{
  "name": "ready-to-quote-guard",
  "points": ["preToolUse"],
  "capabilities": ["store:read", "reads_tool_io", "gates_tools"],
  "failPolicy": "closed",
  "priority": 10,
  "config": {
    "guardedTools": ["store__submissions__set"],
    "blockedRecommendation": "ready-to-quote"
  }
}

The loader validates the manifest on startup. A malformed hook (bad JSON, unknown point or capability, missing handler) is skipped with a hook_skipped warning; it does not disable the other hooks. Two hooks with the same name keep the first one loaded (local hooks win over package hooks) and log hook_name_conflict.

Hook points

preToolUse runs before the connection ACL (access.json), so a hook can block or rewrite args first; the ACL then has the final, authoritative say (and re-evaluates rewritten args).

A few payload fields are ahead of the loop today: every live turn enters through the chat seam, so preInput currently always fires with source: 'chat' and preOutput with channels: ['chat']; preToolUse's isDelegated and planModeActive are declared in the contract but not yet populated. Branch on them only as forward-compatibility.

When any hook is loaded (whatever points it binds to), assistant text is buffered instead of streamed token by token: a preOutput hook cannot unsend text already on the wire, so the runtime holds each turn's text, runs the chain, and emits the result as one block.

postTurn is defined in the contract and accepted by the loader, but the live loop does not invoke it yet; today you can only exercise it through the test endpoint. Treat it as reserved for observability.

Handler contract

The module exports createHook(config) (or a default export) returning the decision function:

// hooks/ready-to-quote-guard/index.mjs
 
/** @param {Record<string, unknown>} config  merged hook.json config + amodal.json overrides */
export function createHook(config) {
  const guarded = new Set(config.guardedTools ?? []);
 
  return {
    /**
     * @param {string} point    the lifecycle point that fired
     * @param {object} payload  that point's payload (see table above)
     * @param {object} ctx      HookContext
     * @returns {Promise<{action: 'allow'} |
     *                   {action: 'block', reason: string} |
     *                   {action: 'modify', payload: object, note?: string} |
     *                   {action: 'ask', reason: string}>}
     */
    async run(point, payload, ctx) {
      if (point !== 'preToolUse' || !guarded.has(payload.toolName)) {
        return { action: 'allow' };
      }
      const row = payload.args?.value;
      if (row?.recommendation === config.blockedRecommendation) {
        ctx.log(`blocked ${payload.toolName}: docs incomplete`);
        return { action: 'block', reason: 'A submission with missing documents cannot be ready-to-quote.' };
      }
      return { action: 'allow' };
    },
  };
}

Accepted export shapes: a factory (config) => {run} or (config) => run, a plain {run} object, or a bare run function. run may be sync or async. A hook bound to several points receives each one through the same run and switches on point.

ctx (HookContext)

A common pattern is a permission hook that gates a tool on your own membership store: check ctx.caller.userId against a team_members row via ctx.store.get, allow on a matching role, block otherwise, with failPolicy: "closed" so a failed read never fails open.

Decisions

run returns one of four decisions:

When several hooks fire at one point, they run in ascending priority order and their decisions combine with precedence block > ask > modify > allow.

What block concretely does at each point:

modify details worth knowing: a preInput modify rewrites the text everything downstream sees (context, persistence, intent matching, the LLM), and the client is notified so the optimistic bubble can update; a preOutput modify is persisted to history, so the model's own next-turn view matches what the user saw; a preToolUse modify rewrites args before the ACL evaluates them.

Failure behavior

Each hook invocation is capped by a wall-clock timeout (default 1500 ms). A hook that throws, rejects, or times out is converted to a decision by its failure policy:

• failPolicy: "closed": the failure becomes a block (reason: Hook "<name>" failed (fail-closed)). This is the default at preInput, preToolUse, postToolUse, and preOutput.
• failPolicy: "open": the failure becomes an allow. Default at postTurn; opt into it elsewhere only for pure observability hooks.

Every non-allow decision and every failure is logged (guardrail_decision in runtime logs) with the hook name, point, action, and reason.

Capabilities

Declared in the manifest; must cover what run actually does.

Chain configuration (amodal.json)

The agent controls the composed chain through the optional hooks block:

{
  "hooks": {
    "order": ["pii-redactor", "ready-to-quote-guard"],
    "disabled": ["verbose-audit"],
    "config": {
      "ready-to-quote-guard": { "blockedRecommendation": "ready-to-quote" }
    }
  }
}

Hooks from packages

An installed package (declared in amodal.json packages) can contribute hooks: a hook package is simply a package with a hooks/ directory inside it, scanned by the same loader. Select a subset with the use selector:

{
  "packages": [
    { "package": "@acme/compliance-pack", "use": ["hooks.pii-redactor"] }
  ]
}

A bare string entry loads everything the package ships (hooks included). A use list that names no hooks.<name> entries opts the package out of contributing hooks. On a name conflict, the local hooks/ folder wins. A declared but uninstalled package logs a warning rather than failing the agent.

Testing a hook

The runtime exposes a deterministic test runner so you can exercise a hook against a fixture payload without driving a real turn:

# inventory the hook manifests discovered under hooks/ and installed packages
curl $RUNTIME/inspect/hooks
 
# run one hook (or the whole chain, omit hookName) at a point
curl -X POST $RUNTIME/inspect/hooks/test \
  -H 'content-type: application/json' \
  -d '{
    "point": "preToolUse",
    "hookName": "ready-to-quote-guard",
    "payload": {
      "toolName": "store__submissions__set",
      "args": { "value": { "recommendation": "ready-to-quote" } }
    }
  }'

The response reports the combined decision (action, reason), the input and output payloads, whether the payload was modified or blocked, which hooks ran, and any ctx.log lines.

Two cautions before you ship one:

• Fail-closed hooks are load-bearing. A preToolUse guard with failPolicy: "closed" that starts throwing will block every call it binds to. Keep handlers small, dependency-free, and fast (well under the 1500 ms cap).
• Hooks run in-process. The local hooks/ path is author-owned code, installed by consent; sandboxing and trust-tier gating apply to third-party packages as that ecosystem opens up.