@sema-agent/server 7.130.0 → 7.132.0

package/dist/hooks/hook-runner.js

@@ -1,10 +1,16 @@
 import { spawn } from "node:child_process";
+import { composeHostSubprocessEnv, hostSubprocessEnv } from "../server-secret-env.js";
 import vm from "node:vm";
 import { hostShell, resolveHostShell, adoptHostForegroundChild } from "../plugins/host-platform.js";
-import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, HOOK_EVENT_MATCHER_FIELD, hookMatcherForm, hookMatcherSelects, interpolateHookEnvVars, } from "@sema-agent/settings-schema/hooks";
-import { describeToolCatalog, isEngineRefusal, receiveHookResult } from "@sema-agent/core";
+import { classifyHooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_ENTRY_TYPES, HOOK_EVENTS, HOOK_EVENT_OWNER, HOOK_EVENT_MATCHER_FIELD, hookMatcherForm, hookMatcherSelects, interpolateHookEnvVars, } from "@sema-agent/settings-schema/hooks";
+import { formatConfigPath, outgoingPath } from "@sema-agent/settings-schema";
+import { ENGINE_OWNED_HOOK_EVENTS } from "@sema-agent/settings-schema/hooks";
+import { describeToolCatalog } from "@sema-agent/core";
+import { hangClassic } from "./classic-stations.js";
 import { boundedNoticeText } from "../fleet/fleet-bus.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { LIMIT_REASONS } from "../limit-refusal.js";
+import { echoCallerText } from "../caller-text-echo.js";
 import { redactSecrets, buildDisplaySafeUrl } from "../trace/redact.js";
 import { ccPromptSystemFor, wrapCondition, parseCcVerdict, CC_EVALUATOR_MAX_OUTPUT_TOKENS } from "./cc-stop-prompt.js";
 import { ccAgentHookSystemFor } from "./cc-agent-hook-prompt.js";
@@ -25,26 +31,35 @@ const HOOK_ENV_ALLOWLIST = [
     "PATH", "HOME", "SHELL", "USER", "LOGNAME", "TERM", "TZ",
     "LANG", "LC_ALL", "LC_CTYPE", "LC_MESSAGES", "TMPDIR",
 ];
-function hookEnv(ctx) {
-    const env = { CLAUDE_PROJECT_DIR: ctx.cwd };
-    for (const k of HOOK_ENV_ALLOWLIST) {
-        const v = process.env[k];
-        if (typeof v === "string")
-            env[k] = v;
-    }
-    return { ...env, ...ctx.shellEnv };
+function hookEnv(ctx, spawning) {
+    const base = spawning
+        ? hostSubprocessEnv({ site: "server.hooks.spawn-env", policy: [...HOOK_ENV_ALLOWLIST], allow: [] })
+        : composeHostSubprocessEnv({ policy: [...HOOK_ENV_ALLOWLIST], allow: [] });
+    return { ...base, CLAUDE_PROJECT_DIR: ctx.cwd, ...ctx.shellEnv };
+}
+export const SETTINGS_HOOK_STATIONS = {
+    PreToolUse: ["classic.PreToolUse"],
+    PostToolUse: ["classic.PostToolUse"],
+    PostToolUseFailure: ["classic.PostToolUseFailure"],
+    PostToolBatch: ["classic.PostToolBatch"],
+    UserPromptSubmit: ["classic.UserPromptSubmit"],
+    Stop: ["classic.Stop", "classic.SubagentStop"],
+    StopFailure: ["classic.StopFailure"],
+    PreCompact: ["classic.PreCompact"],
+    PostCompact: ["classic.PostCompact"],
+};
+function hangTranslator(on, event, translators) {
+    const translate = translators[event];
+    if (translate === undefined)
+        return;
+    for (const station of SETTINGS_HOOK_STATIONS[event])
+        hangClassic(on, station, translate);
+}
+export const SETTINGS_HOOKS_REGISTRATION = "settings.hooks";
+export const DEFAULT_SETTINGS_HOOKS_BUDGET_MS = MAX_HOOK_TIMEOUT_SECONDS * 1000;
+export function settingsHooksBudgetMs(config) {
+    return config.hooksTimeoutMs ?? DEFAULT_SETTINGS_HOOKS_BUDGET_MS;
 }
-const LIT_EVENTS = [
-    "PreToolUse",
-    "PostToolUse",
-    "PostToolUseFailure",
-    "PostToolBatch",
-    "UserPromptSubmit",
-    "Stop",
-    "StopFailure",
-    "PreCompact",
-    "PostCompact",
-];
 const BRAIN_TO_TURN_ERROR = {
     auth: "authentication_failed",
     rate_limit: "rate_limit",
@@ -57,8 +72,25 @@ function toAssistantTurnError(errorKind) {
         return "unknown";
     return Object.prototype.hasOwnProperty.call(BRAIN_TO_TURN_ERROR, errorKind) ? (BRAIN_TO_TURN_ERROR[errorKind] ?? "unknown") : "unknown";
 }
+const HOOK_ENTRY_TYPE_RUNS = {
+    command: true,
+    http: true,
+    prompt: true,
+    agent: true,
+    mcp_tool: false,
+};
+function isSupportedHookEntryType(t) {
+    return HOOK_ENTRY_TYPE_RUNS[t];
+}
+export const SUPPORTED_HOOK_ENTRY_TYPES = HOOK_ENTRY_TYPES.filter(isSupportedHookEntryType);
+function isHookEventName(key) {
+    return HOOK_EVENTS.includes(key);
+}
+function isRunnableHookEntry(entry) {
+    return isSupportedHookEntryType(entry.type);
+}
 export const MAX_MATCHER_EVAL_CHARS = MAX_HOOK_COMMAND_CHARS;
-export const ADMISSION_MATCHER_EVAL_BUDGET_MS = 1_000;
+export const ADMISSION_MATCHER_BUDGET = { budgetMs: 1_000, totalMs: 5_000 };
 export const MATCHER_ECHO_CHARS = 200;
 const MATCHER_UNJUDGED_TAG = "server.hooks.matcher-unjudged";
 function matcherReadsWireToolName(event) {
@@ -112,7 +144,7 @@ const MATCHER_EVALUATION = {
     regex: { regex: "budgeted", literal: "not_applicable" },
     invalid: { regex: "unreadable", literal: "not_applicable" },
 };
-function judgeMatcher(matcher, depth, budgetMs) {
+function judgeMatcher(matcher, depth, ledger, judgesAlias) {
     if (matcher.length > MAX_MATCHER_EVAL_CHARS)
         return { kind: "unjudged", reason: "oversize" };
     const evaluate = MATCHER_EVALUATION[hookMatcherForm(matcher)][depth];
@@ -123,14 +155,34 @@ function judgeMatcher(matcher, depth, budgetMs) {
             return { kind: "invalid_regex" };
         case "inline":
         case "budgeted":
+            if (!judgesAlias)
+                return undefined;
             break;
         default: {
             const unreachable = evaluate;
             return unreachable;
         }
     }
-    const selects = (name) => (evaluate === "inline" ? hookMatcherSelects(matcher, name) : matcherSelectsWithin(matcher, name, budgetMs));
-    const unanswered = (verdict) => (verdict === "over_budget" ? { kind: "over_budget" } : { kind: "invalid_regex" });
+    const selects = (name) => {
+        if (evaluate === "inline")
+            return hookMatcherSelects(matcher, name);
+        const startedAt = ledger.now();
+        const answer = matcherSelectsWithin(matcher, name, ledger.budgetMs);
+        ledger.spentMs += ledger.now() - startedAt;
+        if (answer === "over_budget" || answer === "invalid")
+            return answer;
+        return ledger.spentMs > ledger.totalMs ? "budget_exceeded" : answer;
+    };
+    const unanswered = (verdict) => {
+        switch (verdict) {
+            case "over_budget":
+                return { kind: "over_budget" };
+            case "budget_exceeded":
+                return { kind: "budget_exceeded" };
+            case "invalid":
+                return { kind: "invalid_regex" };
+        }
+    };
     for (const [alias, canonical] of engineToolAliases()) {
         const selectsAlias = selects(alias);
         if (typeof selectsAlias === "string")
@@ -145,50 +197,102 @@ function judgeMatcher(matcher, depth, budgetMs) {
     }
     return undefined;
 }
-export function buildToolMatcherRefusal(issue) {
+const HOOKS_CAPS = {
+    matcher_groups: { measure: "entries", cap: MAX_HOOK_MATCHER_GROUPS, sentence: (event, count) => `settings.hooks.${event}: ${count} matcher groups exceeds cap ${MAX_HOOK_MATCHER_GROUPS}` },
+    event_entries: { measure: "entries", cap: MAX_HOOK_ENTRIES_PER_EVENT, sentence: (event, count) => `settings.hooks.${event}: ${count} entries exceeds cap ${MAX_HOOK_ENTRIES_PER_EVENT}` },
+    command: { measure: "characters", cap: MAX_HOOK_COMMAND_CHARS, sentence: (event) => `settings.hooks.${event}: command exceeds ${MAX_HOOK_COMMAND_CHARS} chars` },
+    url: { measure: "characters", cap: MAX_HOOK_COMMAND_CHARS, sentence: (event) => `settings.hooks.${event}: url exceeds ${MAX_HOOK_COMMAND_CHARS} chars` },
+    headers: { measure: "entries", cap: MAX_HOOK_HTTP_HEADERS, sentence: (event, count) => `settings.hooks.${event}: ${count} headers exceeds cap ${MAX_HOOK_HTTP_HEADERS}` },
+    header_chars: { measure: "characters", cap: MAX_HOOK_COMMAND_CHARS, sentence: (event) => `settings.hooks.${event}: headers exceed ${MAX_HOOK_COMMAND_CHARS} chars total` },
+    allowed_env_vars: { measure: "entries", cap: MAX_HOOK_HTTP_HEADERS, sentence: (event) => `settings.hooks.${event}: allowedEnvVars exceeds cap ${MAX_HOOK_HTTP_HEADERS}` },
+};
+function hooksCapIssue(limit, event, path, count) {
+    const c = HOOKS_CAPS[limit];
+    return { reason: LIMIT_REASONS[c.measure], limit, event, path, count, cap: c.cap };
+}
+const matcherPath = (event, groupIndex) => ["hooks", event, groupIndex, "matcher"];
+export function buildHooksRefusal(issue) {
+    const field = "settings.hooks";
     switch (issue.reason) {
         case "dead_alias":
             return {
                 message: `settings.hooks.${issue.event}: matcher "${issue.alias}" is an alias; tool-event matchers match the tool's wire name (PostToolUse / PostToolUseFailure since 7.107.0) — use "${issue.canonical}"`,
-                field: "settings.hooks",
-                detail: { reason: issue.reason, event: issue.event, alias: issue.alias, canonical: issue.canonical },
+                field,
+                detail: { reason: issue.reason, event: issue.event, alias: issue.alias, canonical: issue.canonical, path: matcherPath(issue.event, issue.groupIndex) },
             };
         case "over_budget":
             return {
                 message: `settings.hooks.${issue.event}[${issue.groupIndex}].matcher: evaluating the pattern did not finish within ${issue.budgetMs} ms (catastrophic regex backtracking) — rewrite it as a tool-name list or a pattern without nested repetition`,
-                field: "settings.hooks",
-                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, budgetMs: issue.budgetMs },
+                field,
+                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, budgetMs: issue.budgetMs, path: matcherPath(issue.event, issue.groupIndex) },
+            };
+        case "budget_exceeded":
+            return {
+                message: `settings.hooks.${issue.event}[${issue.groupIndex}].matcher: evaluating this configuration's regular-expression matchers took longer than ${issue.totalMs} ms in total (very slow patterns) — write tool names as a list such as "Read|Edit", or simplify the patterns`,
+                field,
+                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, totalMs: issue.totalMs, path: matcherPath(issue.event, issue.groupIndex) },
             };
         case "invalid_regex":
             return {
                 message: `settings.hooks.${issue.event}[${issue.groupIndex}].matcher: ${JSON.stringify(issue.matcher)} is not a valid regular expression (${issue.compileError}) — fix the pattern, or write the tool names as a list such as "Read|Edit"`,
-                field: "settings.hooks",
-                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex },
+                field,
+                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, path: matcherPath(issue.event, issue.groupIndex) },
             };
+        case "unsupported_entry_type":
+            return {
+                message: `${hooksCoordinate(issue.path)}: this server does not run hook entries of type ${issue.type}; supported: ${SUPPORTED_HOOK_ENTRY_TYPES.join(" / ")}`,
+                field,
+                detail: { reason: issue.reason, path: hooksOutgoingPath(issue.path), type: issue.type },
+            };
+        case "over_cap":
+        case "too_long": {
+            const cap = issue;
+            return { message: HOOKS_CAPS[cap.limit].sentence(cap.event, cap.count), field, detail: { reason: cap.reason, path: hooksOutgoingPath(cap.path), count: cap.count, cap: cap.cap } };
+        }
+        case "unnamed_refusal":
+            return { message: `${hooksCoordinate(issue.path)}: the hooks reader refused this configuration without naming a piece`, field, detail: { reason: issue.reason, path: hooksOutgoingPath(issue.path) } };
         default: {
-            const unreachable = issue;
-            return unreachable;
+            const piece = issue;
+            const key = piece.key !== undefined ? hooksOutgoingKey(piece.key) : undefined;
+            return {
+                message: hooksPieceRefusal(piece),
+                field,
+                detail: { reason: piece.reason, path: hooksOutgoingPath(piece.path), ...(key !== undefined ? { key } : {}) },
+            };
         }
     }
 }
-export function toolMatcherIssue(config, depth, budget = {}) {
-    const budgetMs = budget.budgetMs ?? ADMISSION_MATCHER_EVAL_BUDGET_MS;
+export function hooksMatcherIssue(config, depth, budget = {}) {
+    const ledger = {
+        budgetMs: budget.budgetMs ?? ADMISSION_MATCHER_BUDGET.budgetMs,
+        totalMs: budget.totalMs ?? ADMISSION_MATCHER_BUDGET.totalMs,
+        now: budget.now ?? (() => performance.now()),
+        spentMs: 0,
+    };
+    const budgetMs = ledger.budgetMs;
     for (const [event, groups] of Object.entries(config)) {
-        if (!matcherReadsWireToolName(event))
-            continue;
+        const judgesAlias = matcherReadsWireToolName(event);
         for (const [groupIndex, group] of (groups ?? []).entries()) {
             if (group.matcher === undefined)
                 continue;
-            const verdict = judgeMatcher(group.matcher, depth, budgetMs);
+            const verdict = judgeMatcher(group.matcher, depth, ledger, judgesAlias);
             if (verdict === undefined)
                 continue;
             switch (verdict.kind) {
                 case "dead":
-                    return { reason: "dead_alias", event, alias: verdict.alias, canonical: verdict.canonical };
+                    return { reason: "dead_alias", event, groupIndex, alias: verdict.alias, canonical: verdict.canonical };
                 case "over_budget":
                     return { reason: "over_budget", event, groupIndex, budgetMs };
+                case "budget_exceeded":
+                    return { reason: "budget_exceeded", event, groupIndex, totalMs: ledger.totalMs };
                 case "invalid_regex":
-                    return { reason: "invalid_regex", event, groupIndex, matcher: clip(group.matcher, MATCHER_ECHO_CHARS), compileError: clip(matcherCompileSentence(group.matcher), MATCHER_ECHO_CHARS) };
+                    return {
+                        reason: "invalid_regex",
+                        event,
+                        groupIndex,
+                        matcher: echoCallerText(group.matcher, { maxChars: MATCHER_ECHO_CHARS }),
+                        compileError: echoCallerText(matcherCompileSentence(group.matcher), { maxChars: MATCHER_ECHO_CHARS }),
+                    };
                 case "unjudged":
                     recordFailOpen(MATCHER_UNJUDGED_TAG, `event=${event} reason=${verdict.reason} matcherChars=${group.matcher.length}`);
                     break;
@@ -201,47 +305,95 @@ export function toolMatcherIssue(config, depth, budget = {}) {
     }
     return undefined;
 }
+const HOOKS_PIECE_MEANING = {
+    "hooks-not-object": "`hooks` must be an object keyed by hook event name",
+    "unknown-event": "not a hook event name",
+    "event-not-array": "an event's value must be an array of matcher groups",
+    "matcher-invalid": "a matcher group must be an object with an optional string `matcher` and an array `hooks`",
+    "entry-invalid": "a hook entry must be an object whose `type` and fields are valid for that type",
+    "guard-outside-hooks": "a PreToolUse / PermissionRequest hook sits outside `hooks`",
+    "hooks-is-matcher": "`hooks` holds a matcher group or an entry directly; it must be an object keyed by hook event name",
+    "guard-under-unknown-event": "an unknown event name holds a PreToolUse / PermissionRequest hook",
+    "guard-event-not-array": "a PreToolUse / PermissionRequest event's value must be an array of matcher groups",
+    "guard-matcher-invalid": "a PreToolUse / PermissionRequest matcher group is not valid",
+    "guard-entry-invalid": "a PreToolUse / PermissionRequest hook entry is not valid",
+};
+export function hooksOutgoingPath(path) {
+    return outgoingPath(path).map((seg) => (typeof seg === "string" ? echoCallerText(seg) : seg));
+}
+export function hooksCoordinate(path) {
+    return `settings.${formatConfigPath(hooksOutgoingPath(path))}`;
+}
+function hooksOutgoingKey(key) {
+    return echoCallerText(String(outgoingPath([key])[0] ?? ""));
+}
+function hooksPieceIssue(piece) {
+    return piece.field !== undefined ? { reason: piece.code, path: piece.path, key: piece.field } : { reason: piece.code, path: piece.path };
+}
+function hooksPieceRefusal(piece) {
+    const field = piece.key !== undefined ? ` (field: ${hooksOutgoingKey(piece.key)})` : "";
+    return `${hooksCoordinate(piece.path)}: ${piece.reason} — ${HOOKS_PIECE_MEANING[piece.reason]}${field}`;
+}
+function hooksRefused(issue, pieces) {
+    const error = buildHooksRefusal(issue).message;
+    return pieces === undefined ? { issue, error } : { issue, error, pieces };
+}
 export function parseHooksConfig(raw) {
-    const parsed = HooksConfig.safeParse(raw);
-    if (!parsed.success) {
-        const first = parsed.error.issues[0];
-        return { error: `settings.hooks: ${first ? `${first.path.join(".")}: ${first.message}` : "invalid shape"}` };
+    const classified = classifyHooksConfig({ hooks: raw });
+    if (classified.outcome !== "loaded") {
+        const first = classified.outcome === "rejected" ? classified.rejections[0] : classified.dropped[0];
+        const pieces = classified.outcome === "rejected" ? classified.rejections : classified.dropped;
+        return hooksRefused(first !== undefined ? hooksPieceIssue(first) : { reason: "unnamed_refusal", path: ["hooks"] }, pieces);
     }
-    const config = parsed.data;
-    for (const [event, groups] of Object.entries(config)) {
+    const loaded = classified.hooks;
+    if (loaded === undefined) {
+        return hooksRefused({ reason: "hooks-not-object", path: ["hooks"] });
+    }
+    const config = {};
+    for (const key of Object.keys(loaded)) {
+        if (!isHookEventName(key)) {
+            return hooksRefused({ reason: "unknown-event", path: ["hooks", key] });
+        }
+        const event = key;
+        const groups = loaded[event];
         if (!groups)
             continue;
-        if (groups.length > MAX_HOOK_MATCHER_GROUPS) {
-            return { error: `settings.hooks.${event}: ${groups.length} matcher groups exceeds cap ${MAX_HOOK_MATCHER_GROUPS}` };
-        }
+        if (groups.length > MAX_HOOK_MATCHER_GROUPS)
+            return hooksRefused(hooksCapIssue("matcher_groups", event, ["hooks", event], groups.length));
         let entries = 0;
-        for (const group of groups) {
-            for (const entry of group.hooks) {
+        let firstPastCap;
+        const kept = [];
+        for (const [groupIndex, group] of groups.entries()) {
+            const hooks = [];
+            for (const [entryIndex, entry] of group.hooks.entries()) {
                 entries++;
-                if (entry.type === "command" && entry.command.length > MAX_HOOK_COMMAND_CHARS) {
-                    return { error: `settings.hooks.${event}: command exceeds ${MAX_HOOK_COMMAND_CHARS} chars` };
-                }
+                const at = ["hooks", event, groupIndex, "hooks", entryIndex];
+                if (entries === MAX_HOOK_ENTRIES_PER_EVENT + 1)
+                    firstPastCap = at;
+                if (!isRunnableHookEntry(entry))
+                    return hooksRefused({ reason: "unsupported_entry_type", path: [...at, "type"], type: entry.type });
+                if (entry.type === "command" && entry.command.length > MAX_HOOK_COMMAND_CHARS)
+                    return hooksRefused(hooksCapIssue("command", event, [...at, "command"], entry.command.length));
                 if (entry.type === "http") {
-                    if (entry.url.length > MAX_HOOK_COMMAND_CHARS) {
-                        return { error: `settings.hooks.${event}: url exceeds ${MAX_HOOK_COMMAND_CHARS} chars` };
-                    }
+                    if (entry.url.length > MAX_HOOK_COMMAND_CHARS)
+                        return hooksRefused(hooksCapIssue("url", event, [...at, "url"], entry.url.length));
                     const headerEntries = Object.entries(entry.headers ?? {});
-                    if (headerEntries.length > MAX_HOOK_HTTP_HEADERS) {
-                        return { error: `settings.hooks.${event}: ${headerEntries.length} headers exceeds cap ${MAX_HOOK_HTTP_HEADERS}` };
-                    }
+                    if (headerEntries.length > MAX_HOOK_HTTP_HEADERS)
+                        return hooksRefused(hooksCapIssue("headers", event, [...at, "headers"], headerEntries.length));
                     const headerChars = headerEntries.reduce((n, [k, v]) => n + k.length + v.length, 0);
-                    if (headerChars > MAX_HOOK_COMMAND_CHARS) {
-                        return { error: `settings.hooks.${event}: headers exceed ${MAX_HOOK_COMMAND_CHARS} chars total` };
-                    }
-                    if ((entry.allowedEnvVars?.length ?? 0) > MAX_HOOK_HTTP_HEADERS) {
-                        return { error: `settings.hooks.${event}: allowedEnvVars exceeds cap ${MAX_HOOK_HTTP_HEADERS}` };
-                    }
+                    if (headerChars > MAX_HOOK_COMMAND_CHARS)
+                        return hooksRefused(hooksCapIssue("header_chars", event, [...at, "headers"], headerChars));
+                    const envVars = entry.allowedEnvVars?.length ?? 0;
+                    if (envVars > MAX_HOOK_HTTP_HEADERS)
+                        return hooksRefused(hooksCapIssue("allowed_env_vars", event, [...at, "allowedEnvVars"], envVars));
                 }
+                hooks.push(entry);
             }
+            kept.push(group.matcher !== undefined ? { matcher: group.matcher, hooks } : { hooks });
         }
-        if (entries > MAX_HOOK_ENTRIES_PER_EVENT) {
-            return { error: `settings.hooks.${event}: ${entries} entries exceeds cap ${MAX_HOOK_ENTRIES_PER_EVENT}` };
-        }
+        if (firstPastCap !== undefined)
+            return hooksRefused(hooksCapIssue("event_entries", event, firstPastCap, entries));
+        config[event] = kept;
     }
     return { config };
 }
@@ -331,61 +483,40 @@ function noteHookFailure(ctx, args) {
     });
 }
 export function buildHookContext(parts) {
-    const present = parts.filter((p) => p.length > 0).map(readHookContextPart);
+    const present = parts.filter((p) => p.length > 0);
     if (present.length === 0)
         return undefined;
     const kept = [];
     let used = 0;
     let truncating = false;
-    let messages = 0;
     let omitted = 0;
     let droppedChars = 0;
     for (const part of present) {
-        messages += part.messages;
-        omitted += part.omitted;
-        droppedChars += part.dropped;
         if (!truncating) {
             const sep = kept.length > 0 ? 1 : 0;
             const room = MAX_HOOK_CONTEXT_TOTAL_CHARS - used - sep;
-            if (room >= part.body.length) {
-                if (part.body.length > 0) {
-                    kept.push(part.body);
-                    used += sep + part.body.length;
-                }
+            if (room >= part.length) {
+                kept.push(part);
+                used += sep + part.length;
                 continue;
             }
             truncating = true;
-            if (part.messages === 1 && room >= MIN_HOOK_CONTEXT_PARTIAL_CHARS) {
-                kept.push(part.body.slice(0, room));
+            if (room >= MIN_HOOK_CONTEXT_PARTIAL_CHARS) {
+                kept.push(part.slice(0, room));
                 used += sep + room;
-                droppedChars += part.body.length - room;
+                droppedChars += part.length - room;
                 continue;
             }
         }
-        omitted += part.messages - part.omitted;
-        droppedChars += part.body.length;
+        omitted += 1;
+        droppedChars += part.length;
     }
     const body = kept.join("\n");
     if (droppedChars === 0)
         return body;
-    const marker = `[hook context truncated at ${MAX_HOOK_CONTEXT_TOTAL_CHARS} chars: ${omitted} of ${messages} hook messages omitted, ${droppedChars} characters dropped]`;
+    const marker = `[hook context truncated at ${MAX_HOOK_CONTEXT_TOTAL_CHARS} chars: ${omitted} of ${present.length} hook messages omitted, ${droppedChars} characters dropped]`;
     return kept.length > 0 ? `${body}\n${marker}` : marker;
 }
-const HOOK_CONTEXT_MARKER_RE = new RegExp(`\\n\\[hook context truncated at ${MAX_HOOK_CONTEXT_TOTAL_CHARS} chars: (\\d+) of (\\d+) hook messages omitted, (\\d+) characters dropped\\]$`);
-const MAX_HOOK_CONTEXT_PARSED_COUNT = 2 ** 42;
-function readHookContextPart(part) {
-    const m = HOOK_CONTEXT_MARKER_RE.exec(part);
-    if (!m)
-        return { body: part, messages: 1, omitted: 0, dropped: 0 };
-    const omitted = Number(m[1]);
-    const messages = Number(m[2]);
-    const dropped = Number(m[3]);
-    const sane = (n) => Number.isSafeInteger(n) && n <= MAX_HOOK_CONTEXT_PARSED_COUNT;
-    if (!sane(omitted) || !sane(messages) || !sane(dropped) || messages < 1 || omitted > messages || dropped < 1) {
-        return { body: part, messages: 1, omitted: 0, dropped: 0 };
-    }
-    return { body: part.slice(0, part.length - m[0].length), messages, omitted, dropped };
-}
 function buildHookContextField(parts) {
     const text = buildHookContext(parts);
     return text === undefined ? {} : { additionalContext: text };
@@ -404,7 +535,7 @@ async function runCommandHook(entry, payload, ctx) {
             const sh = hostShell();
             child = spawn(sh.shell, [...sh.args, entry.command], {
                 cwd: ctx.cwd,
-                env: hookEnv(ctx),
+                env: hookEnv(ctx, true),
                 stdio: ["pipe", "pipe", "pipe"],
                 detached: true,
             });
@@ -467,7 +598,7 @@ async function fireAsyncCommandHook(entry, payload, ctx, event) {
         const sh = hostShell();
         const child = spawn(sh.shell, [...sh.args, entry.command], {
             cwd: ctx.cwd,
-            env: hookEnv(ctx),
+            env: hookEnv(ctx, true),
             stdio: ["pipe", "ignore", rewake ? "pipe" : "ignore"],
             detached: true,
         });
@@ -600,7 +731,7 @@ async function runLlmHook(entry, payload, ctx, extra) {
 const MAX_BLANKED_REFERENCES_LOGGED = 16;
 async function runHttpHook(entry, payload, ctx, event) {
     const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
-    const interpolated = interpolateHookEnvVars(entry.headers ?? {}, entry.allowedEnvVars ?? [], hookEnv(ctx));
+    const interpolated = interpolateHookEnvVars(entry.headers ?? {}, entry.allowedEnvVars ?? [], hookEnv(ctx, false));
     if (interpolated.blanked.length > 0) {
         ctx.logger.warn("hook_http_header_env_blanked", {
             event,
@@ -712,6 +843,23 @@ function parseHookStdout(stdout) {
         return undefined;
     }
 }
+function runRunnableEntry(entry, payload, ctx, event, llmExtra) {
+    switch (entry.type) {
+        case "http":
+            return runHttpHook(entry, payload, ctx, event);
+        case "prompt":
+            return runLlmHook(entry, payload, ctx, llmExtra);
+        case "agent":
+            return runLlmHook(entry, payload, ctx, { system: ccAgentHookSystemFor(event), event });
+        case "command":
+            return runCommandHook(entry, payload, ctx);
+        default: {
+            const unreachable = entry;
+            void unreachable;
+            throw new Error(`hook entry of an unsupported type reached the runner although parseHooksConfig admits only ${SUPPORTED_HOOK_ENTRY_TYPES.join(" / ")}`);
+        }
+    }
+}
 async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceFired, deadlineAt, keyBase, llmExtra) {
     const results = [];
     let llmEntries = 0;
@@ -720,7 +868,7 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
         gi++;
         const m = hookMatcherMatches(group.matcher, matchValue);
         if (m === "invalid") {
-            ctx.logger.warn("hook_matcher_invalid", { event, matcher: clip(group.matcher ?? "", 200) });
+            ctx.logger.warn("hook_matcher_invalid", { event, matcher: echoCallerText(group.matcher ?? "", { maxChars: MATCHER_ECHO_CHARS }) });
             continue;
         }
         if (!m)
@@ -731,10 +879,6 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
             const onceKey = `${keyBase ?? event}:${gi}:${ei}`;
             if (entry.once && onceFired.has(onceKey))
                 continue;
-            if (entry.type !== "command" && entry.type !== "http" && entry.type !== "prompt" && entry.type !== "agent") {
-                ctx.logger.warn("hook_entries_skipped", { event, type: entry.type, reason: "type_not_supported" });
-                continue;
-            }
             if (entry.type === "prompt" || entry.type === "agent") {
                 const carrier = entry.type === "prompt" ? ctx.hookLlm : ctx.hookAgent;
                 if (!carrier) {
@@ -771,9 +915,7 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
                 onceFired.add(onceKey);
             if (entry.type === "prompt" || entry.type === "agent")
                 llmEntries++;
-            const run = entry.type === "http" ? await runHttpHook(entry, payload, ctx, event)
-                : entry.type === "prompt" || entry.type === "agent" ? await runLlmHook(entry, payload, ctx, entry.type === "prompt" ? llmExtra : { system: ccAgentHookSystemFor(event), event })
-                    : await runCommandHook(entry, payload, ctx);
+            const run = await runRunnableEntry(entry, payload, ctx, event, llmExtra);
             if (run.spawnError) {
                 ctx.logger.warn(entry.type === "http" ? "hook_http_request_failed" : entry.type === "prompt" || entry.type === "agent" ? "hook_llm_failed" : "hook_command_spawn_failed", { event, type: entry.type, error: clip(run.spawnError, 300) });
                 if (!run.noticed)
@@ -828,12 +970,8 @@ async function runObserveOnlyEvent(event, groups, matchValue, payload, ctx, once
         }
     }
 }
-export function createTaskHooks(config, ctx) {
+export function createSettingsHooksRegistration(config, ctx, budgetMs) {
     const configured = Object.keys(config).filter((e) => (config[e]?.length ?? 0) > 0);
-    const dark = configured.filter((e) => HOOK_EVENT_OWNER[e] === "engine" && !LIT_EVENTS.includes(e));
-    if (dark.length > 0) {
-        ctx.logger.warn("hook_events_not_fired", { events: dark, phase: 2 });
-    }
     const shellOwned = configured.filter((e) => HOOK_EVENT_OWNER[e] === "shell");
     if (shellOwned.length > 0) {
         ctx.logger.debug("hook_events_shell_owned", { events: shellOwned });
@@ -855,9 +993,11 @@ export function createTaskHooks(config, ctx) {
         return undefined;
     }
     const onceFired = new Set();
-    const hooks = {};
+    const translators = {};
     if (pre) {
-        const preToolUseHook = async (toolName, input, tctx) => {
+        translators.PreToolUse = async (e) => {
+            const toolName = e.tool;
+            const input = e.input;
             let currentInput = input;
             let rewritten = false;
             let asked;
@@ -870,18 +1010,18 @@ export function createTaskHooks(config, ctx) {
                 gi++;
                 const m = hookMatcherMatches(group.matcher, toolName);
                 if (m === "invalid") {
-                    ctx.logger.warn("hook_matcher_invalid", { event: "PreToolUse", matcher: clip(group.matcher ?? "", 200) });
+                    ctx.logger.warn("hook_matcher_invalid", { event: "PreToolUse", matcher: echoCallerText(group.matcher ?? "", { maxChars: MATCHER_ECHO_CHARS }) });
                     continue;
                 }
                 if (!m)
                     continue;
                 const groupInput = currentInput;
                 const payload = {
-                    ...basePayload(ctx, tctx.permissionMode),
+                    ...basePayload(ctx, e.permissionMode),
                     hook_event_name: "PreToolUse",
                     tool_name: toolName,
                     tool_input: groupInput,
-                    tool_use_id: tctx.toolCallId,
+                    tool_use_id: e.tool_use_id,
                 };
                 const singles = await runMatchingEntries("PreToolUse", [{ ...group, matcher: undefined }], toolName, payload, ctx, onceFired, deadlineAt, `PreToolUse:${gi}`);
                 for (const { entry, run } of singles) {
@@ -964,21 +1104,23 @@ export function createTaskHooks(config, ctx) {
                 return carried;
             return undefined;
         };
-        hooks.preToolUse = preToolUseHook;
     }
     if (post) {
-        const postToolUseHook = async (toolName, input, output, tctx) => {
+        translators.PostToolUse = async (e) => {
+            const toolName = e.tool;
+            const input = e.input;
+            const output = e.output;
             const contexts = [];
             const responseText = output.content
                 .map((c) => (c && typeof c === "object" && typeof c.text === "string" ? c.text : ""))
                 .join("");
             const payload = {
-                ...basePayload(ctx, tctx.permissionMode),
+                ...basePayload(ctx, e.permissionMode),
                 hook_event_name: "PostToolUse",
                 tool_name: toolName,
                 tool_input: input,
                 tool_response: { isError: output.isError, text: clip(responseText, MAX_TOOL_RESPONSE_CHARS) },
-                tool_use_id: tctx.toolCallId,
+                tool_use_id: e.tool_use_id,
             };
             const singles = await runMatchingEntries("PostToolUse", post, toolName, payload, ctx, onceFired, Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
             for (const { entry, run } of singles) {
@@ -1016,17 +1158,18 @@ export function createTaskHooks(config, ctx) {
             const additionalContext = buildHookContext(contexts);
             return additionalContext === undefined ? undefined : { additionalContext };
         };
-        hooks.postToolUse = postToolUseHook;
     }
     if (postFailure) {
-        const postToolUseFailureHook = async (toolName, input, f, tctx) => {
+        translators.PostToolUseFailure = async (e) => {
+            const toolName = e.tool;
+            const f = e.failure;
             const contexts = [];
             const payload = {
-                ...basePayload(ctx, tctx.permissionMode),
+                ...basePayload(ctx, e.permissionMode),
                 hook_event_name: "PostToolUseFailure",
                 tool_name: toolName,
-                tool_input: input,
-                tool_use_id: tctx.toolCallId,
+                tool_input: e.input,
+                tool_use_id: e.tool_use_id,
                 error: clip(f.error, MAX_TOOL_RESPONSE_CHARS),
                 is_interrupt: f.isInterrupt,
             };
@@ -1062,15 +1205,14 @@ export function createTaskHooks(config, ctx) {
             const additionalContext = buildHookContext(contexts);
             return additionalContext === undefined ? undefined : { additionalContext };
         };
-        hooks.postToolUseFailure = postToolUseFailureHook;
     }
     if (postBatch) {
-        const postToolBatchHook = async (calls, _meta, bctx) => {
+        translators.PostToolBatch = async (e) => {
             const contexts = [];
             const payload = {
-                ...basePayload(ctx, bctx?.permissionMode),
+                ...basePayload(ctx, e.permissionMode),
                 hook_event_name: "PostToolBatch",
-                tool_calls: calls.map((c) => ({
+                tool_calls: e.batch.map((c) => ({
                     tool_name: c.toolName,
                     tool_input: boundedInputValue(c.input),
                     tool_use_id: c.toolCallId,
@@ -1105,12 +1247,11 @@ export function createTaskHooks(config, ctx) {
             const additionalContext = buildHookContext(contexts);
             return additionalContext === undefined ? undefined : { additionalContext };
         };
-        hooks.postToolBatch = postToolBatchHook;
     }
     if (promptSubmit) {
-        const userPromptSubmitHook = async (prompt, uctx) => {
+        translators.UserPromptSubmit = async (e) => {
             const contexts = [];
-            const payload = { ...basePayload(ctx, uctx?.permissionMode), hook_event_name: "UserPromptSubmit", prompt: clip(prompt, MAX_TOOL_INPUT_CHARS) };
+            const payload = { ...basePayload(ctx, e.permissionMode), hook_event_name: "UserPromptSubmit", prompt: clip(e.prompt, MAX_TOOL_INPUT_CHARS) };
             const singles = await runMatchingEntries("UserPromptSubmit", ignoreMatchers(promptSubmit), "", payload, ctx, onceFired, Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000);
             for (const { entry, run } of singles) {
                 if (run.code === 2) {
@@ -1145,10 +1286,9 @@ export function createTaskHooks(config, ctx) {
             const additionalContext = buildHookContext(contexts);
             return additionalContext === undefined ? undefined : { additionalContext };
         };
-        hooks.userPromptSubmit = userPromptSubmitHook;
     }
     if (stopEntries) {
-        const stopHook = async (sctx) => {
+        translators.Stop = async (sctx) => {
             const payload = { ...basePayload(ctx, sctx.permissionMode), hook_event_name: "Stop", stop_hook_active: sctx.stopHookActive };
             let llmExtra;
             const wantsPrompt = stopEntries.some((g) => g.hooks.some((h) => h.type === "prompt"));
@@ -1237,10 +1377,9 @@ export function createTaskHooks(config, ctx) {
                 ...buildHookContextField(contexts),
             };
         };
-        hooks.stop = stopHook;
     }
     if (stopFailureEntries) {
-        const stopFailureHook = async (fctx) => {
+        translators.StopFailure = async (fctx) => {
             const turnError = toAssistantTurnError(fctx.errorKind);
             const payload = {
                 ...basePayload(ctx, undefined),
@@ -1250,10 +1389,9 @@ export function createTaskHooks(config, ctx) {
             };
             await runObserveOnlyEvent("StopFailure", stopFailureEntries, turnError, payload, ctx, onceFired);
         };
-        hooks.stopFailure = stopFailureHook;
     }
     if (preCompactEntries) {
-        const preCompactHook = async (pctx) => {
+        translators.PreCompact = async (pctx) => {
             const payload = {
                 ...basePayload(ctx, undefined),
                 hook_event_name: "PreCompact",
@@ -1284,10 +1422,9 @@ export function createTaskHooks(config, ctx) {
             }
             return undefined;
         };
-        hooks.preCompact = preCompactHook;
     }
     if (postCompactEntries) {
-        const postCompactHook = async (cctx) => {
+        translators.PostCompact = async (cctx) => {
             const payload = {
                 ...basePayload(ctx, undefined),
                 hook_event_name: "PostCompact",
@@ -1296,177 +1433,16 @@ export function createTaskHooks(config, ctx) {
             };
             await runObserveOnlyEvent("PostCompact", postCompactEntries, cctx.trigger, payload, ctx, onceFired);
         };
-        hooks.postCompact = postCompactHook;
-    }
-    return hooks;
-}
-const HOOK_SLOT_FOLD = {
-    preToolUse: "custom",
-    preToolUseObservational: "custom",
-    postToolUse: "custom",
-    postToolUseFailure: "custom",
-    postToolBatch: "custom",
-    userPromptSubmit: "custom",
-    stop: "custom",
-    preCompact: "custom",
-    timeoutMs: "scalar",
-    postCompact: "observe-void",
-    stopFailure: "observe-void",
-    permissionDenied: "observe-void",
-};
-const OBSERVE_VOID_HOOK_SLOTS = Object.keys(HOOK_SLOT_FOLD).filter((k) => HOOK_SLOT_FOLD[k] === "observe-void");
-export function composeHooks(deployment, task) {
-    if (!deployment)
-        return task;
-    const d = deployment;
-    const t = task;
-    const out = {};
-    const timeoutMs = d.timeoutMs ?? t.timeoutMs;
-    if (timeoutMs !== undefined)
-        out.timeoutMs = timeoutMs;
-    if (d.preToolUse || t.preToolUse) {
-        const bothObservational = (d.preToolUse === undefined || d.preToolUseObservational === true) &&
-            (t.preToolUse === undefined || t.preToolUseObservational === true);
-        if (bothObservational)
-            out.preToolUseObservational = true;
-        out.preToolUse = async (toolName, input, ctx) => {
-            let current = input;
-            const contexts = [];
-            let asked;
-            let allowedFor;
-            for (const slot of [d.preToolUse?.bind(d), t.preToolUse?.bind(t)]) {
-                if (!slot)
-                    continue;
-                const r = receiveHookResult(await slot(toolName, current, ctx));
-                if (r === undefined || r === null || r === false)
-                    continue;
-                if (isEngineRefusal(r))
-                    return r;
-                if (r.additionalContext)
-                    contexts.push(r.additionalContext);
-                const action = r.action;
-                const updatedInput = r.updatedInput;
-                switch (action) {
-                    case "deny":
-                        return { ...r, ...buildHookContextField(contexts) };
-                    case "ask":
-                        asked = r;
-                        break;
-                    case "allow":
-                        if (updatedInput !== undefined)
-                            current = updatedInput;
-                        allowedFor = { input: current };
-                        break;
-                    case undefined:
-                        if (updatedInput !== undefined)
-                            current = updatedInput;
-                        break;
-                    default: {
-                        const unread = action;
-                        void unread;
-                        return r;
-                    }
-                }
-            }
-            if (asked) {
-                const askedUpdated = asked.updatedInput;
-                return {
-                    ...asked,
-                    ...(askedUpdated === undefined && current !== input ? { updatedInput: current } : {}),
-                    ...buildHookContextField(contexts),
-                };
-            }
-            const carried = { ...(current !== input ? { updatedInput: current } : {}), ...buildHookContextField(contexts) };
-            if (allowedFor !== undefined && allowedFor.input === current)
-                return { action: "allow", ...carried };
-            if (current !== input || contexts.length > 0)
-                return carried;
-            return undefined;
-        };
     }
-    if (d.postToolUse || t.postToolUse) {
-        out.postToolUse = async (toolName, input, output, ctx) => {
-            const rd = d.postToolUse ? await d.postToolUse(toolName, input, output, ctx) : undefined;
-            const rt = t.postToolUse ? await t.postToolUse(toolName, input, output, ctx) : undefined;
-            if (!rd && !rt)
-                return undefined;
-            const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            const updatedOutput = rt?.updatedOutput ?? rd?.updatedOutput;
-            return {
-                ...(updatedOutput ? { updatedOutput } : {}),
-                ...buildHookContextField(contexts),
-            };
-        };
-    }
-    if (d.postToolUseFailure || t.postToolUseFailure) {
-        out.postToolUseFailure = async (toolName, input, failure, ctx) => {
-            const rd = d.postToolUseFailure ? await d.postToolUseFailure(toolName, input, failure, ctx) : undefined;
-            const rt = t.postToolUseFailure ? await t.postToolUseFailure(toolName, input, failure, ctx) : undefined;
-            const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            const additionalContext = buildHookContext(contexts);
-            return additionalContext === undefined ? undefined : { additionalContext };
-        };
-    }
-    if (d.postToolBatch || t.postToolBatch) {
-        out.postToolBatch = async (calls, meta, bctx) => {
-            const rd = d.postToolBatch ? await d.postToolBatch(calls, meta, bctx) : undefined;
-            const rt = t.postToolBatch ? await t.postToolBatch(calls, meta, bctx) : undefined;
-            const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            const additionalContext = buildHookContext(contexts);
-            return additionalContext === undefined ? undefined : { additionalContext };
-        };
-    }
-    if (d.userPromptSubmit || t.userPromptSubmit) {
-        out.userPromptSubmit = async (prompt, uctx) => {
-            const rd = d.userPromptSubmit ? await d.userPromptSubmit(prompt, uctx) : undefined;
-            if (rd?.block)
-                return { ...rd, ...buildHookContextField(rd.additionalContext ? [rd.additionalContext] : []) };
-            const rt = t.userPromptSubmit ? await t.userPromptSubmit(prompt, uctx) : undefined;
-            if (!rd && !rt)
-                return undefined;
-            const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            return { ...(rt?.block ? { block: rt.block } : {}), ...buildHookContextField(contexts) };
-        };
-    }
-    if (d.stop || t.stop) {
-        out.stop = async (sctx) => {
-            const rd = d.stop ? await d.stop(sctx) : undefined;
-            if (rd?.block)
-                return { ...rd, ...buildHookContextField(rd.additionalContext ? [rd.additionalContext] : []) };
-            const rt = t.stop ? await t.stop(sctx) : undefined;
-            if (!rd && !rt)
-                return undefined;
-            const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            return { ...(rt?.block ? { block: rt.block } : {}), ...buildHookContextField(contexts) };
-        };
-    }
-    if (d.preCompact || t.preCompact) {
-        out.preCompact = async (pctx) => {
-            const rd = d.preCompact ? await d.preCompact(pctx) : undefined;
-            const rt = t.preCompact ? await t.preCompact(pctx) : undefined;
-            if (!rd && !rt)
-                return undefined;
-            const block = rd?.block ?? rt?.block;
-            const instructions = [rd?.additionalInstructions, rt?.additionalInstructions].filter((c) => typeof c === "string" && c.length > 0);
-            return {
-                ...(block !== undefined ? { block } : {}),
-                ...(instructions.length ? { additionalInstructions: instructions.join("\n") } : {}),
-            };
-        };
-    }
-    for (const slot of OBSERVE_VOID_HOOK_SLOTS) {
-        const ds = d[slot];
-        const ts = t[slot];
-        if (ds && ts) {
-            out[slot] = async (...args) => {
-                await ds(...args);
-                await ts(...args);
-            };
-        }
-        else if (ds || ts) {
-            out[slot] = (ds ?? ts);
-        }
-    }
-    return out;
+    const events = Object.keys(translators);
+    return {
+        name: SETTINGS_HOOKS_REGISTRATION,
+        uses: { events: events.flatMap((event) => SETTINGS_HOOK_STATIONS[event]), calls: [] },
+        budgetMs,
+        register(on) {
+            for (const event of events)
+                hangTranslator(on, event, translators);
+        },
+    };
 }
 //# sourceMappingURL=hook-runner.js.map