@sema-agent/settings-schema 12.2.1 → 13.0.0

package/dist/hooks.d.ts

@@ -13,7 +13,7 @@
  * discovering it the hard way (the 1.3.0 / 1.6.0 / 1.8.0 / 2.0.0 pattern).
  *
  * CONSUMERS
- * - service (the worker server): `TaskRequest.settings.hooks` wire face = `HooksConfig` below; the worker-side
+ * - service (the worker server): `TaskRequest.settings.hooks` wire face = `HooksConfig` (`./hooks-config`); the worker-side
  *   hook-runner translates matching entries into core `TaskSpec.hooks` in-process callbacks. Single-user
  *   gate first (requirePrincipal semantics, same as MCP injection ).
  * - core (engine): per-event input/output shapes for the engine-owned events; `stoppedBy` on settle.
@@ -26,11 +26,21 @@
  * only from their owner; the shell must NOT double-fire engine-owned events. Configuring an event whose
  * owner hasn't shipped its runner yet is LEGAL (no validation error) — it fires when that half ships.
  *
+ * CONFIG SURFACE: what a settings document's `hooks` key may carry — the event vocabulary {@link HOOK_EVENTS}, the entry types, the ONE
+ * classifier `classifyHooksConfig` and the zod faces that read it (`HooksConfig` / `HookMatcherEntry` / `HookEntry` …) — is defined in
+ * `./hooks-config` and re-exported here whole; import it from here (or the main barrel) as before.
+ *
+ * WORKSPACE TRUST AND THE HOOKS EXECUTION GATE (contract; the gate executes in the client core, in one place — not in this package):
+ * when the host reports the workspace `declined` (`WORKSPACE_TRUST_STATES`), NO hook runs from ANY settings layer — the user, managed
+ * and flag layers included (CC 2.1.296: an untrusted session runs no hooks at all, `cli296.js:249597`). `no_trust_step` (the host has no
+ * trust step) differs from `declined` at this gate only: the gate stays open, and what applies is layer admission alone
+ * (`layerAdmission`: a repository-controllable layer's hooks are `trust_withheld` until the workspace is `accepted`). The gate is not
+ * layer admission: it lives in neither `SAFETY_MERGE_SPEC` nor `SETTINGS_SOURCE_CONTRACT`.
+ *
  * Pure zod contract — zero runtime deps beyond zod, browser-safe, same as the rest of this package.
  */
 import { z } from "zod";
-/** The full 33-event contract set = CC 198's 27 + the 6 post-198 events — the one exported closed set of hook event names. */
-export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
+export * from "./hooks-config.js";
 export declare const HookEventName: z.ZodEnum<{
     PreToolUse: "PreToolUse";
     PostToolUse: "PostToolUse";
@@ -223,11 +233,11 @@ export type AssistantTurnError = z.infer<typeof AssistantTurnError>;
 /** SessionEnd `reason` values (CC EXIT_REASONS). */
 export declare const SESSION_EXIT_REASONS: readonly ["clear", "resume", "logout", "prompt_input_exit", "other", "bypass_permissions_disabled"];
 export declare const SessionExitReason: z.ZodEnum<{
+    other: "other";
     clear: "clear";
     resume: "resume";
     logout: "logout";
     prompt_input_exit: "prompt_input_exit";
-    other: "other";
     bypass_permissions_disabled: "bypass_permissions_disabled";
 }>;
 export type SessionExitReason = z.infer<typeof SessionExitReason>;
@@ -372,11 +382,11 @@ export declare const SessionEndHookInput: z.ZodObject<{
     agent_type: z.ZodOptional<z.ZodString>;
     hook_event_name: z.ZodLiteral<"SessionEnd">;
     reason: z.ZodEnum<{
+        other: "other";
         clear: "clear";
         resume: "resume";
         logout: "logout";
         prompt_input_exit: "prompt_input_exit";
-        other: "other";
         bypass_permissions_disabled: "bypass_permissions_disabled";
     }>;
 }, z.core.$strip>;
@@ -982,11 +992,11 @@ export declare const HookInput: z.ZodDiscriminatedUnion<[z.ZodObject<{
     agent_type: z.ZodOptional<z.ZodString>;
     hook_event_name: z.ZodLiteral<"SessionEnd">;
     reason: z.ZodEnum<{
+        other: "other";
         clear: "clear";
         resume: "resume";
         logout: "logout";
         prompt_input_exit: "prompt_input_exit";
-        other: "other";
         bypass_permissions_disabled: "bypass_permissions_disabled";
     }>;
 }, z.core.$strip>, z.ZodObject<{
@@ -2111,143 +2121,6 @@ export type HookOutput = z.infer<typeof HookOutput>;
 export declare const HOOK_INJECTED_ENV: readonly ["CLAUDE_PROJECT_DIR", "CLAUDE_ENV_FILE"];
 /** Default per-hook timeout when an entry does not set one (seconds; CC default). */
 export declare const DEFAULT_HOOK_TIMEOUT_SECONDS = 60;
-/** `command` — shell command on the worker host (DESIGN POINT ②). First runner phase. */
-export declare const CommandHookEntry: z.ZodObject<{
-    if: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    statusMessage: z.ZodOptional<z.ZodString>;
-    once: z.ZodOptional<z.ZodBoolean>;
-    type: z.ZodLiteral<"command">;
-    command: z.ZodString;
-    shell: z.ZodOptional<z.ZodEnum<{
-        bash: "bash";
-        powershell: "powershell";
-    }>>;
-    async: z.ZodOptional<z.ZodBoolean>;
-    asyncRewake: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
-/** `prompt` — one-shot LLM evaluation of the hook input ($ARGUMENTS = input JSON). */
-export declare const PromptHookEntry: z.ZodObject<{
-    if: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    statusMessage: z.ZodOptional<z.ZodString>;
-    once: z.ZodOptional<z.ZodBoolean>;
-    type: z.ZodLiteral<"prompt">;
-    prompt: z.ZodString;
-    model: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/** `agent` — agentic verifier loop over the hook input ($ARGUMENTS = input JSON). */
-export declare const AgentHookEntry: z.ZodObject<{
-    if: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    statusMessage: z.ZodOptional<z.ZodString>;
-    once: z.ZodOptional<z.ZodBoolean>;
-    type: z.ZodLiteral<"agent">;
-    prompt: z.ZodString;
-    model: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/** `http` — POST the hook input JSON to a URL. Headers may reference $NAMEs listed in allowedEnvVars
- *  (env-NAME interpolation only — the config NEVER carries a secret value; same boundary as the rest
- *  of this package). */
-export declare const HttpHookEntry: z.ZodObject<{
-    if: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    statusMessage: z.ZodOptional<z.ZodString>;
-    once: z.ZodOptional<z.ZodBoolean>;
-    type: z.ZodLiteral<"http">;
-    url: z.ZodString;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    allowedEnvVars: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-/** One configured hook (CC settings shape + shell superset fields; discriminated on `type`). */
-export declare const HookEntry: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    if: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    statusMessage: z.ZodOptional<z.ZodString>;
-    once: z.ZodOptional<z.ZodBoolean>;
-    type: z.ZodLiteral<"command">;
-    command: z.ZodString;
-    shell: z.ZodOptional<z.ZodEnum<{
-        bash: "bash";
-        powershell: "powershell";
-    }>>;
-    async: z.ZodOptional<z.ZodBoolean>;
-    asyncRewake: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>, z.ZodObject<{
-    if: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    statusMessage: z.ZodOptional<z.ZodString>;
-    once: z.ZodOptional<z.ZodBoolean>;
-    type: z.ZodLiteral<"prompt">;
-    prompt: z.ZodString;
-    model: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    if: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    statusMessage: z.ZodOptional<z.ZodString>;
-    once: z.ZodOptional<z.ZodBoolean>;
-    type: z.ZodLiteral<"agent">;
-    prompt: z.ZodString;
-    model: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    if: z.ZodOptional<z.ZodString>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    statusMessage: z.ZodOptional<z.ZodString>;
-    once: z.ZodOptional<z.ZodBoolean>;
-    type: z.ZodLiteral<"http">;
-    url: z.ZodString;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    allowedEnvVars: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>], "type">;
-export type HookEntry = z.infer<typeof HookEntry>;
-export type CommandHookEntry = z.infer<typeof CommandHookEntry>;
-export type PromptHookEntry = z.infer<typeof PromptHookEntry>;
-export type AgentHookEntry = z.infer<typeof AgentHookEntry>;
-export type HttpHookEntry = z.infer<typeof HttpHookEntry>;
-/** One matcher group: `matcher` (see HOOK_EVENT_MATCHER_FIELD) + the hooks it fires. */
-export declare const HookMatcherEntry: z.ZodObject<{
-    matcher: z.ZodOptional<z.ZodString>;
-    hooks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        if: z.ZodOptional<z.ZodString>;
-        timeout: z.ZodOptional<z.ZodNumber>;
-        statusMessage: z.ZodOptional<z.ZodString>;
-        once: z.ZodOptional<z.ZodBoolean>;
-        type: z.ZodLiteral<"command">;
-        command: z.ZodString;
-        shell: z.ZodOptional<z.ZodEnum<{
-            bash: "bash";
-            powershell: "powershell";
-        }>>;
-        async: z.ZodOptional<z.ZodBoolean>;
-        asyncRewake: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strip>, z.ZodObject<{
-        if: z.ZodOptional<z.ZodString>;
-        timeout: z.ZodOptional<z.ZodNumber>;
-        statusMessage: z.ZodOptional<z.ZodString>;
-        once: z.ZodOptional<z.ZodBoolean>;
-        type: z.ZodLiteral<"prompt">;
-        prompt: z.ZodString;
-        model: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        if: z.ZodOptional<z.ZodString>;
-        timeout: z.ZodOptional<z.ZodNumber>;
-        statusMessage: z.ZodOptional<z.ZodString>;
-        once: z.ZodOptional<z.ZodBoolean>;
-        type: z.ZodLiteral<"agent">;
-        prompt: z.ZodString;
-        model: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        if: z.ZodOptional<z.ZodString>;
-        timeout: z.ZodOptional<z.ZodNumber>;
-        statusMessage: z.ZodOptional<z.ZodString>;
-        once: z.ZodOptional<z.ZodBoolean>;
-        type: z.ZodLiteral<"http">;
-        url: z.ZodString;
-        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-        allowedEnvVars: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>], "type">>;
-}, z.core.$strip>;
-export type HookMatcherEntry = z.infer<typeof HookMatcherEntry>;
 /**
  * Does `matcher` select `name`? —— **the one reading** of a hooks matcher (11.0.0). The shell and the server both ask this
  * function; neither keeps a copy.
@@ -2313,17 +2186,6 @@ export interface HookEnvInterpolation {
  * Pure: no I/O, no logging, no global env —— `env` is the caller's view (`process.env` at the call site). Inputs are not modified.
  */
 export declare function interpolateHookEnvVars(headers: Readonly<Record<string, string>>, allowedEnvVars: readonly string[], env: Readonly<Record<string, string | undefined>>): HookEnvInterpolation;
-/**
- * The hooks config record — the shape `TaskRequest.settings.hooks` carries on the wire and the shell
- * reads from settings JSON: `{ [eventName]: [{ matcher?, hooks: [...] }] }`. Keys limited to the 33
- * contract events (an unknown event name fails parse — catch typos at the wire); all keys optional.
- *
- * 🔴 The closed set is what makes a typo loud, and it is ALSO what makes falling behind CC expensive: an
- * event this package has not adopted yet takes the WHOLE settings file down with it, not just its own key.
- * That blast radius is why {@link HOOK_EVENTS} now has an upstream drift gate rather than a human promise.
- */
-export type HooksConfig = Partial<Record<HookEventName, HookMatcherEntry[]>>;
-export declare const HooksConfig: z.ZodType<HooksConfig>;
 /**
  * DESIGN POINT ③ (slot semantics — RESERVED, core to finalize): how `spec.hooks` composes with the
  * engine's own `deps.hooks` (e.g. the service's process-level toolTracer). "override" = the spec slot

package/dist/hooks.js

@@ -13,7 +13,7 @@
  * discovering it the hard way (the 1.3.0 / 1.6.0 / 1.8.0 / 2.0.0 pattern).
  *
  * CONSUMERS
- * - service (the worker server): `TaskRequest.settings.hooks` wire face = `HooksConfig` below; the worker-side
+ * - service (the worker server): `TaskRequest.settings.hooks` wire face = `HooksConfig` (`./hooks-config`); the worker-side
  *   hook-runner translates matching entries into core `TaskSpec.hooks` in-process callbacks. Single-user
  *   gate first (requirePrincipal semantics, same as MCP injection ).
  * - core (engine): per-event input/output shapes for the engine-owned events; `stoppedBy` on settle.
@@ -26,58 +26,25 @@
  * only from their owner; the shell must NOT double-fire engine-owned events. Configuring an event whose
  * owner hasn't shipped its runner yet is LEGAL (no validation error) — it fires when that half ships.
  *
+ * CONFIG SURFACE: what a settings document's `hooks` key may carry — the event vocabulary {@link HOOK_EVENTS}, the entry types, the ONE
+ * classifier `classifyHooksConfig` and the zod faces that read it (`HooksConfig` / `HookMatcherEntry` / `HookEntry` …) — is defined in
+ * `./hooks-config` and re-exported here whole; import it from here (or the main barrel) as before.
+ *
+ * WORKSPACE TRUST AND THE HOOKS EXECUTION GATE (contract; the gate executes in the client core, in one place — not in this package):
+ * when the host reports the workspace `declined` (`WORKSPACE_TRUST_STATES`), NO hook runs from ANY settings layer — the user, managed
+ * and flag layers included (CC 2.1.296: an untrusted session runs no hooks at all, `cli296.js:249597`). `no_trust_step` (the host has no
+ * trust step) differs from `declined` at this gate only: the gate stays open, and what applies is layer admission alone
+ * (`layerAdmission`: a repository-controllable layer's hooks are `trust_withheld` until the workspace is `accepted`). The gate is not
+ * layer admission: it lives in neither `SAFETY_MERGE_SPEC` nor `SETTINGS_SOURCE_CONTRACT`.
+ *
  * Pure zod contract — zero runtime deps beyond zod, browser-safe, same as the rest of this package.
  */
 import { z } from "zod";
+import { HOOK_EVENTS } from "./hooks-config.js";
 import { INTEGER } from "./integer.js";
-import { buildQuotedIssue } from "./quoted-issue.js";
+export * from "./hooks-config.js";
 // ── event set ──────────────────────────────────────────────────────────────────────────────────────────
-// The two halves below are where each word came from (CC 2.1.198's own table, then the later additions) — provenance for the
-// reader of this file, not a contract: they are module-private, and the ONE exported closed set is {@link HOOK_EVENTS}.
-/** CC 2.1.198 full hook-event set (jP array) — 27 events. Order matches the shell's HOOK_EVENTS. */
-const CC_198_HOOK_EVENTS = [
-    "PreToolUse",
-    "PostToolUse",
-    "PostToolUseFailure",
-    "PostToolBatch",
-    "Notification",
-    "UserPromptSubmit",
-    "UserPromptExpansion",
-    "SessionStart",
-    "SessionEnd",
-    "Stop",
-    "StopFailure",
-    "SubagentStart",
-    "SubagentStop",
-    "PreCompact",
-    "PostCompact",
-    "PermissionRequest",
-    "PermissionDenied",
-    "Setup",
-    "TeammateIdle",
-    "TaskCreated",
-    "TaskCompleted",
-    "Elicitation",
-    "ElicitationResult",
-    "ConfigChange",
-    "WorktreeCreate",
-    "WorktreeRemove",
-    "InstructionsLoaded",
-];
-/**
- * Post-CC-2.1.198 additions (sema superset; CC added them after 198).
- * APPEND-ONLY: new members go at the tail (1.3.0 `DirectoryAdded`, CC 2.1.219 — CC's own tuple places it
- * between FileChanged and MessageDisplay; the declaration order here is not normative, the enum is a set).
- * 2.0.0 appends the model-switch pair (`PreModelSwitch` / `PostModelSwitch`, CC 2.1.259 — absent from the
- * 2.1.250 corpus, so 250→259 is when they landed upstream).
- *
- * 🔴 This list is no longer maintained by hand-reading a CLI bundle: `test/upstream-drift.test.ts` fails
- * (naming the missing words) whenever the CC anchor snapshot in `test/fixtures/cc-hook-events.json` holds an
- * event this set does not, and that snapshot is produced by `scripts/extract-cc-hook-events.mjs`, never typed.
- */
-const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
-/** The full 33-event contract set = CC 198's 27 + the 6 post-198 events — the one exported closed set of hook event names. */
-export const HOOK_EVENTS = [...CC_198_HOOK_EVENTS, ...POST_198_HOOK_EVENTS];
+// The ONE closed set of hook event names is {@link HOOK_EVENTS} (`./hooks-config`, re-exported above; drift-gated against CC).
 export const HookEventName = z.enum(HOOK_EVENTS);
 // ── ownership (owner-single) ─────────────────────────────────────────────────────────────────────
 export const HookOwner = z.enum(["engine", "shell"]);
@@ -612,8 +579,8 @@ export const HookOutput = z.union([AsyncHookOutput, SyncHookOutput]);
 //   - env  = the worker host process env, PLUS the injected names in HOOK_INJECTED_ENV below
 //   - timeout = per-entry `timeout` (seconds), else DEFAULT_HOOK_TIMEOUT_SECONDS
 //   - stdin = the HookInput JSON; stdout parsed as HookOutput (see exit-code semantics above)
-// `prompt` / `agent` / `http` hook types are part of the config contract (the shell already parses
-// them); the service runner may phase them in after `command` — config validity is not phased.
+// `prompt` / `agent` / `http` / `mcp_tool` hook types are part of the config contract (`HOOK_ENTRY_TYPES`); a runner
+// may phase them in after `command` — config validity is not phased (`classifyHooksConfig` is the one reading of it).
 /** Env names the hook runner injects into a command hook's environment (CC-parity). */
 export const HOOK_INJECTED_ENV = [
     /** Absolute path of the project/workspace root. */
@@ -623,66 +590,6 @@ export const HOOK_INJECTED_ENV = [
 ];
 /** Default per-hook timeout when an entry does not set one (seconds; CC default). */
 export const DEFAULT_HOOK_TIMEOUT_SECONDS = 60;
-/** A non-empty string with no NUL byte (spawn()/JSON-safe). */
-const hookStr = z.string().min(1).refine((s) => !s.includes("\0"), buildQuotedIssue `must not contain a NUL byte`);
-/**
- * `if` condition — permission-rule syntax (e.g. "Bash(git *)") evaluated against tool_name/tool_input
- * BEFORE spawning the hook (only meaningful on tool events). Shell superset field, CC-compatible.
- */
-const IfCondition = z.string().optional();
-const HookEntryCommon = {
-    if: IfCondition,
-    /** Timeout in seconds for this entry (default DEFAULT_HOOK_TIMEOUT_SECONDS). */
-    timeout: z.number().positive().optional(),
-    /** Spinner status message (shell superset). */
-    statusMessage: z.string().optional(),
-    /** Run once, then remove (shell superset). */
-    once: z.boolean().optional(),
-};
-/** `command` — shell command on the worker host (DESIGN POINT ②). First runner phase. */
-export const CommandHookEntry = z.object({
-    type: z.literal("command"),
-    command: hookStr,
-    /** 'bash' = the user's $SHELL family; 'powershell' = pwsh. Default bash. */
-    shell: z.enum(["bash", "powershell"]).optional(),
-    /** Run in background without blocking (shell superset). */
-    async: z.boolean().optional(),
-    /** Background + wake the model on exit 2 (implies async; shell superset). */
-    asyncRewake: z.boolean().optional(),
-    ...HookEntryCommon,
-});
-/** `prompt` — one-shot LLM evaluation of the hook input ($ARGUMENTS = input JSON). */
-export const PromptHookEntry = z.object({
-    type: z.literal("prompt"),
-    prompt: hookStr,
-    model: z.string().optional(),
-    ...HookEntryCommon,
-});
-/** `agent` — agentic verifier loop over the hook input ($ARGUMENTS = input JSON). */
-export const AgentHookEntry = z.object({
-    type: z.literal("agent"),
-    prompt: hookStr,
-    model: z.string().optional(),
-    ...HookEntryCommon,
-});
-/** `http` — POST the hook input JSON to a URL. Headers may reference $NAMEs listed in allowedEnvVars
- *  (env-NAME interpolation only — the config NEVER carries a secret value; same boundary as the rest
- *  of this package). */
-export const HttpHookEntry = z.object({
-    type: z.literal("http"),
-    url: hookStr,
-    headers: z.record(z.string(), z.string()).optional(),
-    allowedEnvVars: z.array(z.string()).optional(),
-    ...HookEntryCommon,
-});
-/** One configured hook (CC settings shape + shell superset fields; discriminated on `type`). */
-export const HookEntry = z.discriminatedUnion("type", [CommandHookEntry, PromptHookEntry, AgentHookEntry, HttpHookEntry]);
-/** One matcher group: `matcher` (see HOOK_EVENT_MATCHER_FIELD) + the hooks it fires. */
-export const HookMatcherEntry = z.object({
-    /** Read by {@link hookMatcherSelects} — the one reading (name list or unanchored JS regex; empty/`*`/absent matches everything). */
-    matcher: z.string().optional(),
-    hooks: z.array(HookEntry),
-});
 /** The characters a matcher may consist of to be read as a NAME LIST rather than a regex. */
 const HOOK_MATCHER_NAME_LIST = /^[a-zA-Z0-9_|, -]+$/;
 function readHookMatcher(matcher) {
@@ -849,7 +756,6 @@ export function interpolateHookEnvVars(headers, allowedEnvVars, env) {
     // fromEntries defines own properties: a header keyed `__proto__` stays a header instead of replacing the prototype.
     return { headers: Object.fromEntries(entries), blanked };
 }
-export const HooksConfig = z.partialRecord(HookEventName, z.array(HookMatcherEntry));
 /**
  * DESIGN POINT ③ (slot semantics — RESERVED, core to finalize): how `spec.hooks` composes with the
  * engine's own `deps.hooks` (e.g. the service's process-level toolTracer). "override" = the spec slot

package/dist/http-hook-allowlists.d.ts

@@ -0,0 +1,63 @@
+/**
+ * http hook 两张名单 `allowedHttpHookUrls` / `httpHookAllowedEnvVars`(13.0.0,U3 定稿 [10538] / S-1597)—— 类目 `httpHookAllowlists`
+ * (`SAFETY_MERGE_SPEC.httpHookAllowlists` 那一行是这两键的合并律与准入地板的唯一真源),本模块是它的读法与判决。纯函数,浏览器安全。
+ *
+ * CC 2.1.296 锚(cli296.js:237460 describe 原句):URL 名单「When set, HTTP hooks with non-matching URLs are blocked. If undefined, all URLs
+ * are allowed. If empty array, no HTTP hooks are allowed」;变量名单「each hook's effective allowedEnvVars is the intersection with this list.
+ * If undefined, no restriction」;坏形名单 ⇒「no HTTP hooks may run」/「no environment variables may be interpolated」(按空名单读)。
+ *
+ * 一条律:**每一张准入的名单都必须放行**(跨层取交)。准入只有一个读者:`layerAdmission(层的源, 工作区读数, "httpHookAllowlists") === "admitted"`
+ * (`./settings-sources`:层档取自源表 `SETTINGS_SOURCE_CONTRACT`,地板取自本类目行 `minTrust: "global"` ⇒ 用户 / flag / 托管层准入,项目 / 本地层
+ * 在地板之下)。本模块不推档,层对象只带源名 —— 调用方给不了档,也就抬不了档。两处与 CC 的差都在「下层不能放宽」方向(登 docs/CC-DIVERGENCE.md):
+ *  ① CC 各层**拼接**(「Arrays merge across settings sources」)⇒ 下层可往托管名单里加 URL = 绕过管理员 ⇒ 本包取交;
+ *  ② CC 任意层可设 ⇒ 本包只认准入层:项目 / 本地层(仓库可控)的一个 `[]` 会让用户自己的 http 守卫 hook 不发出 = 守卫失效(放行方向),
+ *     与 `sandboxNetwork.failIfUnavailable` 同一条边界;它们写的名单既不收窄也不放宽。
+ * 判官出结构不出句:放行 ⇒ `undefined`;拦下 ⇒ {@link HttpHookUrlBlock}(哪张名单 / 为什么 / 出自哪几层),用户面那一句由各宿主按它铸。
+ */
+import { z } from "zod";
+import { type SettingsSource, type WorkspaceTrustState } from "./settings-sources.js";
+/** 两键(闭集,声明序)。 */
+export declare const HTTP_HOOK_ALLOWLIST_KEYS: readonly ["allowedHttpHookUrls", "httpHookAllowedEnvVars"];
+export type HttpHookAllowlistKey = (typeof HTTP_HOOK_ALLOWLIST_KEYS)[number];
+/**
+ * 整份 `settings.json` 里本片段负责的两键:在场则必须是字符串数组。刻意 `passthrough`(与 `CrossSessionSettings` 同姿势):本片段不是整份
+ * 设置的闭集门。它是**写侧**的形门;读侧坏形不拒整份,按 {@link readHttpHookAllowlistLayer} 读成空名单(fail-closed)。
+ */
+export declare const HttpHookAllowlistSettings: z.ZodObject<{
+    allowedHttpHookUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    httpHookAllowedEnvVars: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type HttpHookAllowlistSettings = z.infer<typeof HttpHookAllowlistSettings>;
+/**
+ * 一个设置层对两键的读数。键缺席 = 这一层不设限;`[]` = 这一层一个都不许。`source` = 这一层是哪个设置源(闭集 `SETTINGS_SOURCES`,原样回显进
+ * `sources`);准入由判官按源经 `layerAdmission` 判,调用方不预先筛层、不给档。
+ */
+export interface HttpHookAllowlistLayer {
+    readonly source: SettingsSource;
+    readonly allowedHttpHookUrls?: readonly string[];
+    readonly httpHookAllowedEnvVars?: readonly string[];
+}
+/** 一层的读法结果:层读数 + 读成空名单的坏形键(调用方据此告警;读法本身不出句)。 */
+export interface HttpHookAllowlistLayerRead {
+    readonly layer: HttpHookAllowlistLayer;
+    readonly malformed: readonly HttpHookAllowlistKey[];
+}
+/**
+ * 从一层的原始设置对象读出两键(唯一读法)。键缺席(或值为 `undefined`)⇒ 不设;字符串数组 ⇒ 原样;其余一切(非数组、含非串条目、`null`)
+ * ⇒ **读成 `[]`**(CC 同向:坏形名单 = 一个都不许)并在 `malformed` 点名。整份设置不是对象 ⇒ 两键都缺。
+ */
+export declare function readHttpHookAllowlistLayer(source: SettingsSource, settings: unknown): HttpHookAllowlistLayerRead;
+/** 拦下一只 http hook 的原因。`rule`:`empty` = 有一张准入名单是空的(那一层改对之前一只都不许);`url` = 没命中那几张名单里的任何模式。
+ *  `sources` = 不放行它的那几张名单所在的层(入参序)。零 URL 回显 —— URL 调用方自己有,按受众给显示形。 */
+export interface HttpHookUrlBlock {
+    readonly list: "allowedHttpHookUrls";
+    readonly rule: "empty" | "url";
+    readonly sources: readonly SettingsSource[];
+}
+/**
+ * 一只 http hook 的 URL 过不过名单:每一张准入的 `allowedHttpHookUrls` 都要有一条模式按放行出口({@link urlAllowPatternMatches})命中它。
+ * 没有准入层写这张名单 ⇒ 不限(`undefined`)。`workspace` = 宿主对工作区信任的读数(读口抛或闭集外按 `declined` 交),与 `layerAdmission` 同一个入参。
+ */
+export declare function httpHookUrlVerdict(url: string, layers: readonly HttpHookAllowlistLayer[], workspace: WorkspaceTrustState): HttpHookUrlBlock | undefined;
+/** 一只 http hook 实际可插值进请求头的环境变量:它自己的 `allowedEnvVars` 与每一张准入的 `httpHookAllowedEnvVars` 取交(保持 hook 自己的序)。 */
+export declare function httpHookEnvVarsAllowed(hookVars: readonly string[], layers: readonly HttpHookAllowlistLayer[], workspace: WorkspaceTrustState): string[];

package/dist/http-hook-allowlists.js

@@ -0,0 +1,73 @@
+/**
+ * http hook 两张名单 `allowedHttpHookUrls` / `httpHookAllowedEnvVars`(13.0.0,U3 定稿 [10538] / S-1597)—— 类目 `httpHookAllowlists`
+ * (`SAFETY_MERGE_SPEC.httpHookAllowlists` 那一行是这两键的合并律与准入地板的唯一真源),本模块是它的读法与判决。纯函数,浏览器安全。
+ *
+ * CC 2.1.296 锚(cli296.js:237460 describe 原句):URL 名单「When set, HTTP hooks with non-matching URLs are blocked. If undefined, all URLs
+ * are allowed. If empty array, no HTTP hooks are allowed」;变量名单「each hook's effective allowedEnvVars is the intersection with this list.
+ * If undefined, no restriction」;坏形名单 ⇒「no HTTP hooks may run」/「no environment variables may be interpolated」(按空名单读)。
+ *
+ * 一条律:**每一张准入的名单都必须放行**(跨层取交)。准入只有一个读者:`layerAdmission(层的源, 工作区读数, "httpHookAllowlists") === "admitted"`
+ * (`./settings-sources`:层档取自源表 `SETTINGS_SOURCE_CONTRACT`,地板取自本类目行 `minTrust: "global"` ⇒ 用户 / flag / 托管层准入,项目 / 本地层
+ * 在地板之下)。本模块不推档,层对象只带源名 —— 调用方给不了档,也就抬不了档。两处与 CC 的差都在「下层不能放宽」方向(登 docs/CC-DIVERGENCE.md):
+ *  ① CC 各层**拼接**(「Arrays merge across settings sources」)⇒ 下层可往托管名单里加 URL = 绕过管理员 ⇒ 本包取交;
+ *  ② CC 任意层可设 ⇒ 本包只认准入层:项目 / 本地层(仓库可控)的一个 `[]` 会让用户自己的 http 守卫 hook 不发出 = 守卫失效(放行方向),
+ *     与 `sandboxNetwork.failIfUnavailable` 同一条边界;它们写的名单既不收窄也不放宽。
+ * 判官出结构不出句:放行 ⇒ `undefined`;拦下 ⇒ {@link HttpHookUrlBlock}(哪张名单 / 为什么 / 出自哪几层),用户面那一句由各宿主按它铸。
+ */
+import { z } from "zod";
+import { layerAdmission } from "./settings-sources.js";
+import { urlAllowPatternMatches } from "./url-pattern.js";
+/** 两键(闭集,声明序)。 */
+export const HTTP_HOOK_ALLOWLIST_KEYS = ["allowedHttpHookUrls", "httpHookAllowedEnvVars"];
+/**
+ * 整份 `settings.json` 里本片段负责的两键:在场则必须是字符串数组。刻意 `passthrough`(与 `CrossSessionSettings` 同姿势):本片段不是整份
+ * 设置的闭集门。它是**写侧**的形门;读侧坏形不拒整份,按 {@link readHttpHookAllowlistLayer} 读成空名单(fail-closed)。
+ */
+export const HttpHookAllowlistSettings = z
+    .object({
+    allowedHttpHookUrls: z.array(z.string()).optional(),
+    httpHookAllowedEnvVars: z.array(z.string()).optional(),
+})
+    .passthrough();
+/**
+ * 从一层的原始设置对象读出两键(唯一读法)。键缺席(或值为 `undefined`)⇒ 不设;字符串数组 ⇒ 原样;其余一切(非数组、含非串条目、`null`)
+ * ⇒ **读成 `[]`**(CC 同向:坏形名单 = 一个都不许)并在 `malformed` 点名。整份设置不是对象 ⇒ 两键都缺。
+ */
+export function readHttpHookAllowlistLayer(source, settings) {
+    const bag = typeof settings === "object" && settings !== null && !Array.isArray(settings) ? settings : {};
+    const malformed = [];
+    const lists = {};
+    for (const key of HTTP_HOOK_ALLOWLIST_KEYS) {
+        if (!Object.hasOwn(bag, key) || bag[key] === undefined)
+            continue;
+        const v = bag[key];
+        if (Array.isArray(v) && v.every((x) => typeof x === "string"))
+            lists[key] = [...v];
+        else {
+            lists[key] = [];
+            malformed.push(key);
+        }
+    }
+    return { layer: { source, ...lists }, malformed };
+}
+/** 进判决的那几层(入参序):`layerAdmission` 答 `admitted` 的层。每一层都问 —— 闭集外的源 / 工作区读数在这里响亮抛,哪怕那一层没写名单。 */
+function admittedLayers(layers, workspace) {
+    return layers.filter((l) => layerAdmission(l.source, workspace, "httpHookAllowlists") === "admitted");
+}
+/**
+ * 一只 http hook 的 URL 过不过名单:每一张准入的 `allowedHttpHookUrls` 都要有一条模式按放行出口({@link urlAllowPatternMatches})命中它。
+ * 没有准入层写这张名单 ⇒ 不限(`undefined`)。`workspace` = 宿主对工作区信任的读数(读口抛或闭集外按 `declined` 交),与 `layerAdmission` 同一个入参。
+ */
+export function httpHookUrlVerdict(url, layers, workspace) {
+    const refusing = admittedLayers(layers, workspace).filter((l) => l.allowedHttpHookUrls !== undefined && !l.allowedHttpHookUrls.some((p) => urlAllowPatternMatches(url, p)));
+    if (refusing.length === 0)
+        return undefined;
+    return { list: "allowedHttpHookUrls", rule: refusing.some((l) => l.allowedHttpHookUrls.length === 0) ? "empty" : "url", sources: refusing.map((l) => l.source) };
+}
+/** 一只 http hook 实际可插值进请求头的环境变量:它自己的 `allowedEnvVars` 与每一张准入的 `httpHookAllowedEnvVars` 取交(保持 hook 自己的序)。 */
+export function httpHookEnvVarsAllowed(hookVars, layers, workspace) {
+    const lists = admittedLayers(layers, workspace)
+        .filter((l) => l.httpHookAllowedEnvVars !== undefined)
+        .map((l) => l.httpHookAllowedEnvVars);
+    return hookVars.filter((v) => lists.every((list) => list.includes(v)));
+}

package/dist/index.d.ts

@@ -31,3 +31,8 @@ export * from "./web-admin-env.js";
 export * from "./web-admin-credential.js";
 export * from "./web-admin-session-url.js";
 export * from "./retired-envs.js";
+export * from "./settings-sources.js";
+export * from "./url-pattern.js";
+export * from "./http-hook-allowlists.js";
+export * from "./mcp-server-policy.js";
+export * from "./ui-language.js";

package/dist/index.js

@@ -19,7 +19,7 @@ export * from "./remote-exec.js";
 export * from "./safety-merge-spec.js"; // #14 per-category safety merge-spec (settings resolver authority)
 export * from "./scheduler-store.js"; // R7 self-wake scheduler store CONTRACT (pure: type + parse/serialize + SchedulerStore interface; fs binding in ./node)
 export * from "./cross-session.js"; // CC-parity `settings.json` cross-session keys (crossSessionInbound / dialogExpiry) — pure/browser-safe
-export * from "./hooks.js"; // CC-parity hooks contract (31-event set + owner map + per-event input/output shapes + HooksConfig) & stop attribution (stoppedBy) — pure/browser-safe
+export * from "./hooks.js"; // CC-parity hooks contract (33-event set + owner map + per-event input/output shapes + the config surface: classifyHooksConfig and its zod faces HooksConfig / HookEntry …) & stop attribution (stoppedBy) — pure/browser-safe
 export * from "./fleet.js"; // scheduling/fleet contract (drain protocol · instance discovery · dispatch policy · quota lease · usage report · quota reset event) — CONTROL-PLANE-SCHEDULING-DESIGN, pure/browser-safe
 export * from "./workers-rows.js"; // 11.0.0 the workers domain's per-row verdict (readWorkersRows: a row that does not read is held, the rest read on) — permanent read semantics, pure
 export * from "./api/auth.js"; // /api/v1/auth/* wire contract (RFC 8628 device flow + rotating refresh + logout + approve) — REGISTRY-REBUILD-DESIGN §2, M1 shipped shapes frozen, pure/browser-safe
@@ -31,6 +31,11 @@ export * from "./web-admin-env.js"; // WEB_ADMIN_ENV — every env name an engin
 export * from "./web-admin-credential.js"; // S-698 web-admin credential FILE contract: WebAdminCredentialEnvelope (user-session envelope, strict) + parseWebAdminCredentialFile (bare / envelope / unreadable — the one discrimination law) + judgeWebAdminCredentialDeclaration(env, credential) (pick-exactly-one over the credential's WEB_ADMIN_ENV pair; WEB_ADMIN_CREDENTIALS = access | assertion), pure/browser-safe
 export * from "./web-admin-session-url.js"; // webAdminSessionUrl(webBaseUrl, { worker, sessionId }) — THE web-admin session link template (<webBaseUrl>/chat?agent=<worker>&session=<sessionId>) + parseWebAdminSessionUrl(link) its paired reader, pure/browser-safe
 export * from "./retired-envs.js"; // the retired-env TOMBSTONE table (renamed / replaced / removed, closed set) + retiredEnvRefusal(env) (the one refusal sentence) + buildRetiredEnvWire() — engine boot, catalog wire, shell and web-admin read this one table, pure/browser-safe
+export * from "./settings-sources.js"; // settings SOURCES (merge order) + SETTINGS_SOURCE_CONTRACT (trust tier, repository-controllable) + WORKSPACE_TRUST_STATES + layerAdmission(source, workspace, category, member?, value?) — the one layer × key admission reading, pure/browser-safe
+export * from "./url-pattern.js"; // 13.0.0 (S-1597): THE URL-list pattern judge, two exits — urlAllowPatternMatches (⊆ upstream g9, four holes closed) / urlDenyPatternMatches (⊇ upstream ∪ whole-string glob), pure/browser-safe
+export * from "./http-hook-allowlists.js"; // 13.0.0 (U3): allowedHttpHookUrls / httpHookAllowedEnvVars — one layer reader + httpHookUrlVerdict / httpHookEnvVarsAllowed (admitted layers INTERSECT; SAFETY_MERGE_SPEC.httpHookAllowlists), pure/browser-safe
+export * from "./mcp-server-policy.js"; // 13.0.0 (U6): mcpServerPolicyVerdict → McpPolicyBlock{name, list, rule, target, written, sources} (structure, no sentence; target judged expanded, echoed only as written), pure/browser-safe
+export * from "./ui-language.js"; // 13.0.0 (S-1592): the UI-language settings fragment (semaUiLanguage, en | zh, category ui, user settings) + readUiLanguage, pure/browser-safe
 // NOTE: the Node-fs-backed helpers (FileConfigStore + the file editor) are NOT in this barrel — they pull
 // `node:fs`/`node:path` and would break a browser/client bundle that only wants the contract (e.g.
 // web-admin's client components import the zod types through here). Import them from the Node-only