src/ops-hooks.ts

Functions

Imports

It imports src/env.ts, src/http.ts, src/ops-session-auth.ts, src/signed-requests.ts, src/time.ts. Imported by src/ops-feed.ts, src/routes.ts.

Source

1import type { Env } from "./env";
2import { readBoundedText } from "./signed-requests";
3import { resolveSessionCaller } from "./ops-session-auth";
4import { textResponse } from "./http";
5import { MINUTE_MS, DAY_MS } from "./time";
6
7// The hook receiver: POST /ops/hooks. Claude Code's HTTP hooks post each event's input
8// JSON here (docs/hooks.md), and this keeps a SUMMARY of each session in agent_sessions
9// and a trimmed row per event in session_events (migrations/0025).
10//
11// What is kept is an allowlist, never a denylist: every stored value is named below,
12// read off the body by key, checked against a pattern or capped in length. A hook body
13// also carries the prompt, the last assistant message, tool input and output, and the
14// transcript path; none of those is read, so none can reach D1. Two exceptions. One is
15// StopFailure's last_assistant_message, which on that event is the API error string,
16// kept capped at 300 characters. The other is the tool events (PostToolUse and
17// PostToolUseFailure, Dustin's D1 of 2026-10-03), which keep the tool's name; for Edit,
18// Write and MultiEdit the file path; for Bash the first word of the command, reduced to
19// its basename, and the exit code. Never the tool's input or output otherwise, its error
20// text, its id or its duration.
21//
22// The answer is 200 with an empty body, so Claude Code counts the hook a success and
23// never parses a decision out of it. Every refusal is non-2xx, which Claude Code shows
24// as a non-blocking error.
25//
26// Authorization: resolveSessionCaller (src/ops-session-auth.ts), the one caller check
27// this route shares with the OTLP receiver. The bearer resolves through resolveAgent,
28// and only two callers are admitted: a driver or the admin for testing. It is a route, not a tool, and src/scope.ts lists it among
29// the routes gated some other way.
30
31export const OPS_HOOKS_PATH = "/ops/hooks";
32// A hook body is a few hundred bytes of metadata plus whatever prompt or message the
33// event carries, which is read by nobody here. 64KB refuses a body that is trying to
34// be something else.
35export const HOOK_MAX_BYTES = 65_536;
36// session_events older than this are pruned, a bounded batch per call.
37const EVENT_RETENTION_DAYS = 30;
38const PRUNE_BATCH = 50;
39
40// The eight events docs/hooks.md configures. Any other event is refused with 400, so a
41// hook pointed here by mistake is visible instead of silently dropped.
42//
43// The tool events are the two that fire AFTER a tool ran: PostToolUse (it succeeded) and
44// PostToolUseFailure (it failed). PreToolUse is not taken: it would double the rows for
45// every call, and it fires before the exit code exists.
46export const HOOK_EVENTS = [
47  "SessionStart",
48  "Notification",
49  "StopFailure",
50  "ConfigChange",
51  "SessionEnd",
52  "Stop",
53  "PostToolUse",
54  "PostToolUseFailure",
55] as const;
56type HookEventName = (typeof HOOK_EVENTS)[number];
57const TOOL_EVENTS: ReadonlySet<HookEventName> = new Set(["PostToolUse", "PostToolUseFailure"]);
58
59// A Notification of one of these types means the session is waiting on a person.
60export const NEEDS_INPUT_TYPES: readonly string[] = [
61  "agent_needs_input",
62  "permission_prompt",
63  "idle_prompt",
64  "elicitation_dialog",
65  "elicitation_url_dialog",
66];
67
68// StopFailure errors a person has to act on. The feed shows a session stopped on one
69// as an incident, decided when the feed is read; no job is posted.
70export const INCIDENT_FAILURES: readonly string[] = [
71  "rate_limit",
72  "billing_error",
73  "authentication_failed",
74  "account_on_hold",
75  "oauth_org_not_allowed",
76];
77// A session waiting on a person for longer than this is an incident too.
78export const NEEDS_INPUT_INCIDENT_MS = 10 * MINUTE_MS;
79
80// A type word: notification_type, StopFailure's error, a source or a reason. Claude
81// Code's values are all lowercase snake case; one that is not is stored as null.
82const TOKEN = /^[a-z][a-z0-9_]{0,39}$/;
83const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
84const PERMISSION_MODE = /^[A-Za-z]{1,32}$/;
85// A tool name. MCP names fit, a hyphenated server's too (mcp__claude-in-chrome__navigate);
86// one that does not is stored as "unknown" so the call is still counted.
87const TOOL_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,127}$/;
88// The tools whose input carries the one path this receiver keeps.
89const FILE_TOOLS: readonly string[] = ["Edit", "Write", "MultiEdit"];
90// A Bash command's first word, kept only when it is a plain program name or path. An
91// env assignment (TOKEN=abc npm test) holds "=", so it fails and nothing is kept.
92const COMMAND_WORD = /^[A-Za-z0-9._+/-]{1,64}$/;
93// The first line of a failed Bash call's error when the command ran and exited.
94const EXIT_LINE = /^Exit code (-?\d{1,4})$/;
95const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/[\]-]{0,99}$/;
96
97export interface ParsedHook {
98  session_id: string;
99  event: HookEventName;
100  // The event's type word (see migrations/0025, session_events.subtype).
101  subtype: string | null;
102  // JSON of the allowlisted, capped fields, or null.
103  detail: string | null;
104  permission_mode: string | null;
105  source: string | null;
106  model: string | null;
107  notification_type: string | null;
108  // 1 sets needs_input, 0 clears it, null leaves it.
109  needs_input: 0 | 1 | null;
110  // StopFailure's error, which becomes last_failure.
111  failure: string | null;
112  // A Stop, which is a turn that ended normally, clears last_failure.
113  clears_failure: boolean;
114  // SessionEnd ends the session; a SessionStart (a resume) reopens it.
115  end_mode: "end" | "reopen" | "keep";
116  end_reason: string | null;
117}
118
119export type HookParse = { ok: true; hook: ParsedHook } | { ok: false; refusal: string };
120
121/** A string field, control characters folded to spaces and capped, or null. */
122function capped(value: unknown, max: number): string | null {
123  if (typeof value !== "string") return null;
124  // oxlint-disable-next-line no-control-regex -- folding control characters is the point
125  const clean = value.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
126  return clean.length === 0 ? null : clean.slice(0, max);
127}
128
129function matching(value: unknown, pattern: RegExp): string | null {
130  return typeof value === "string" && pattern.test(value) ? value : null;
131}
132
133function detailJson(fields: Record<string, string | null>): string | null {
134  const kept = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== null));
135  return Object.keys(kept).length === 0 ? null : JSON.stringify(kept);
136}
137
138/** A hook body to the summary this receiver stores. Reads named keys only. */
139export function parseHook(raw: string): HookParse {
140  let body: unknown;
141  try {
142    body = JSON.parse(raw);
143  } catch {
144    return { ok: false, refusal: "the body is not JSON: a Claude Code HTTP hook posts its input JSON" };
145  }
146  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, refusal: "the body is not a JSON object" };
147  const input = body as Record<string, unknown>;
148  const sessionId = matching(input.session_id, SESSION_ID);
149  if (!sessionId) return { ok: false, refusal: "the body carries no usable session_id" };
150  const name = input.hook_event_name;
151  if (typeof name !== "string" || !(HOOK_EVENTS as readonly string[]).includes(name)) {
152    return { ok: false, refusal: `hook_event_name must be one of ${HOOK_EVENTS.join(", ")}; this receiver records no other event` };
153  }
154  const event = name as HookEventName;
155  const hook: ParsedHook = {
156    session_id: sessionId,
157    event,
158    subtype: null,
159    detail: null,
160    permission_mode: matching(input.permission_mode, PERMISSION_MODE),
161    source: null,
162    model: null,
163    notification_type: null,
164    // Any event other than a Notification means the session moved on.
165    needs_input: 0,
166    failure: null,
167    clears_failure: false,
168    end_mode: "keep",
169    end_reason: null,
170  };
171  switch (event) {
172    case "SessionStart":
173      hook.source = matching(input.source, TOKEN);
174      hook.subtype = hook.source;
175      hook.model = matching(input.model, MODEL);
176      hook.end_mode = "reopen";
177      break;
178    case "Notification": {
179      const type = matching(input.notification_type, TOKEN);
180      hook.notification_type = type;
181      hook.subtype = type;
182      hook.needs_input = type !== null && NEEDS_INPUT_TYPES.includes(type) ? 1 : type === "agent_completed" ? 0 : null;
183      hook.detail = detailJson({ title: capped(input.title, 120), message: capped(input.message, 300) });
184      break;
185    }
186    case "StopFailure":
187      // An error word this receiver does not know is still a failure; it is kept as
188      // "unknown", Claude Code's own catch-all, rather than dropped.
189      hook.failure = matching(input.error, TOKEN) ?? "unknown";
190      hook.subtype = hook.failure;
191      // On this event last_assistant_message is the API error string, not model output.
192      hook.detail = detailJson({ error: capped(input.last_assistant_message, 300) });
193      break;
194    case "ConfigChange":
195      hook.subtype = matching(input.source, TOKEN);
196      hook.detail = detailJson({ file_path: capped(input.file_path, 300) });
197      break;
198    case "SessionEnd":
199      hook.end_reason = matching(input.reason, TOKEN) ?? "other";
200      hook.subtype = hook.end_reason;
201      hook.end_mode = "end";
202      break;
203    case "Stop":
204      hook.clears_failure = true;
205      break;
206    case "PostToolUse":
207    case "PostToolUseFailure": {
208      const tool = matching(input.tool_name, TOOL_NAME);
209      hook.subtype = tool ?? "unknown";
210      const toolInput = input.tool_input && typeof input.tool_input === "object" && !Array.isArray(input.tool_input) ? (input.tool_input as Record<string, unknown>) : {};
211      const failed = event === "PostToolUseFailure";
212      let exitCode: string | null = null;
213      if (tool === "Bash") {
214        const word = typeof toolInput.command === "string" ? toolInput.command.trim().split(/\s+/)[0] : null;
215        const program = matching(word, COMMAND_WORD)?.split("/").pop() || null;
216        // A call that failed without running (a denied or interrupted one) has no
217        // "Exit code N" line, and keeps no exit code.
218        if (failed) exitCode = typeof input.error === "string" ? (EXIT_LINE.exec(input.error.split("\n")[0].trim())?.[1] ?? null) : null;
219        else exitCode = "0";
220        hook.detail = detailJson({ command: program, exit_code: exitCode, interrupted: failed && input.is_interrupt === true ? "true" : null });
221      } else {
222        hook.detail = detailJson({
223          file_path: tool !== null && FILE_TOOLS.includes(tool) ? capped(toolInput.file_path, 300) : null,
224          interrupted: failed && input.is_interrupt === true ? "true" : null,
225        });
226      }
227      break;
228    }
229  }
230  return { ok: true, hook };
231}
232
233// The job an event belongs to, as resolveSessionCaller bound it.
234export interface HookBinding {
235  job_id: string;
236  namespace: string;
237}
238
239/** The three writes for one event, in one batch: the session upsert (RETURNING, so a
240 *  session another key reported first is seen as no row), the event row copied through
241 *  the session so it carries the session's bound job, and a bounded prune.
242 *
243 *  A session keeps the job it was first bound to (COALESCE on job_id). The upsert only
244 *  updates a row whose agent is this caller, so one key cannot mark another's session
245 *  waiting or ended. */
246export function hookStatements(db: D1Database, actor: string, binding: HookBinding | null, hook: ParsedHook, now: Date): D1PreparedStatement[] {
247  const at = now.toISOString();
248  const cutoff = new Date(now.getTime() - EVENT_RETENTION_DAYS * DAY_MS).toISOString();
249  return [
250    db
251      .prepare(
252        `INSERT INTO agent_sessions (session_id, agent, job_id, namespace, source, model, permission_mode, started_at,
253           last_event_at, last_event, last_notification_type, needs_input, last_failure, ended_at, end_reason, updated_at)
254         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?8, ?9, ?10, COALESCE(?11, 0), ?12,
255           CASE ?13 WHEN 'end' THEN ?8 ELSE NULL END, ?14, ?8)
256         ON CONFLICT(session_id) DO UPDATE SET
257           job_id = COALESCE(agent_sessions.job_id, excluded.job_id),
258           namespace = COALESCE(agent_sessions.namespace, excluded.namespace),
259           source = COALESCE(excluded.source, agent_sessions.source),
260           model = COALESCE(excluded.model, agent_sessions.model),
261           permission_mode = COALESCE(excluded.permission_mode, agent_sessions.permission_mode),
262           last_event_at = excluded.last_event_at,
263           last_event = excluded.last_event,
264           last_notification_type = COALESCE(excluded.last_notification_type, agent_sessions.last_notification_type),
265           needs_input = COALESCE(?11, agent_sessions.needs_input),
266           last_failure = CASE WHEN ?12 IS NOT NULL THEN ?12 WHEN ?15 = 1 THEN NULL ELSE agent_sessions.last_failure END,
267           ended_at = CASE ?13 WHEN 'end' THEN ?8 WHEN 'reopen' THEN NULL ELSE agent_sessions.ended_at END,
268           end_reason = CASE ?13 WHEN 'end' THEN ?14 WHEN 'reopen' THEN NULL ELSE agent_sessions.end_reason END,
269           updated_at = excluded.updated_at
270         WHERE agent_sessions.agent = excluded.agent
271         RETURNING session_id`
272      )
273      .bind(
274        hook.session_id,
275        actor,
276        binding?.job_id ?? null,
277        binding?.namespace ?? null,
278        hook.source,
279        hook.model,
280        hook.permission_mode,
281        at,
282        hook.event,
283        hook.notification_type,
284        hook.needs_input,
285        hook.failure,
286        hook.end_mode,
287        hook.end_reason,
288        hook.clears_failure ? 1 : 0
289      ),
290    db
291      .prepare(
292        `INSERT INTO session_events (session_id, job_id, agent, event, subtype, detail, at)
293         SELECT session_id, job_id, agent, ?3, ?4, ?5, ?6 FROM agent_sessions WHERE session_id = ?1 AND agent = ?2`
294      )
295      .bind(hook.session_id, actor, hook.event, hook.subtype, hook.detail, at),
296    // The oldest PRUNE_BATCH rows by id, of which those past retention go. Bounded
297    // whatever the table holds: rows are appended in time order, so the expired ones
298    // are the lowest ids, and a table with none expired costs one short index walk.
299    db
300      .prepare(
301        `DELETE FROM session_events WHERE id IN (SELECT id FROM session_events ORDER BY id LIMIT ?1) AND at < ?2`
302      )
303      .bind(PRUNE_BATCH, cutoff),
304  ];
305}
306
307export async function handleOpsHooks(request: Request, env: Env, ctx: ExecutionContext | null, now: Date = new Date()): Promise<Response> {
308  // 401 with realm capsid-hooks, or 403 for a caller that is not a driver, a runner or
309  // the admin, or that holds no write grant.
310  const caller = await resolveSessionCaller(request, env, now);
311  if (caller instanceof Response) return caller;
312  // Bounded at the stream, in bytes, before the parse (see handleCspReport in routes.ts).
313  const bounded = await readBoundedText(request, HOOK_MAX_BYTES);
314  if (!bounded.ok) return textResponse(`the hook body exceeds ${HOOK_MAX_BYTES} bytes`, 413);
315  const parsed = parseHook(bounded.text);
316  if (!parsed.ok) return textResponse(parsed.refusal, 400);
317
318  const binding: HookBinding | null = caller.job_id && caller.namespace ? { job_id: caller.job_id, namespace: caller.namespace } : null;
319  const [session] = await env.DB.batch(hookStatements(env.DB, caller.agent.actor, binding, parsed.hook, now));
320  if ((session.results ?? []).length === 0) {
321    return textResponse(`session ${parsed.hook.session_id} was first reported by another key, so this event was not recorded`, 409);
322  }
323  // last_seen is not part of authorizing; see handleOperatorMcp. A tool event skips it:
324  // tool calls come by the hundred an hour, and the Stop that ends every turn keeps
325  // last_seen current at a fraction of the writes.
326  if (!TOOL_EVENTS.has(parsed.hook.event)) {
327    if (ctx) ctx.waitUntil(caller.touch());
328    else await caller.touch();
329  }
330  return new Response(null, { status: 200 });
331}