@sema-agent/core 7.51.1 → 7.52.0

package/dist/core/hooks.js

@@ -1,11 +1,9 @@
-import { decisionText, describeThrown, receiveHookResult, isEngineRefusal, unaskedSeatAnswer } from "./tool-policy.js";
-import { asThrownError } from "./thrown-value.js";
-import { createSettlementLedger, engineFailClosedExit, hookDenyExit } from "./runner/gate-exit.js";
-import { traceHookCrash } from "./gate-crash-trace.js";
+import { abortedSeatDeny, decisionText, describeThrown, isEngineRefusal, ownArgs, refuseOutOfContractDecision, unaskedSeatAnswer } from "./tool-policy.js";
+import { createSettlementLedger, engineFailClosedExit, hookDenyExit, unownedArgsExit } from "./runner/gate-exit.js";
+import { classicEventBase, dispatchClassic, ENGINE_CORE_ANSWER, engineCore, failedHandlerClause, judgedInputOf, observePermissionDenied, recordScreeningChain } from "./mods/stations.js";
 import { runGateFold } from "./gate-fold.js";
 import { runGateLanes } from "./gate-lanes.js";
 export { normalizeOrgGateVerdict, normalizePersistedRuleHit } from "./rule-lane-reads.js";
-export { cloneObserverInput } from "./runner/gate-exit.js";
 import { brandPolicyAskClass } from "./ask-class.js";
 import { isAskOrigin, screenAskClassMembers } from "./ask-origin.js";
 import { isAutoModeFallbackCause } from "./auto-mode.js";
@@ -13,92 +11,6 @@ import { inlineUntrusted } from "./untrusted-text.js";
 export { formatHookFeedback } from "./reminder-mint.js";
 import { createSafeNotifier } from "./safe-notify.js";
 import { wireOf } from "./tool-name-readings.js";
-export const DEFAULT_HOOK_TIMEOUT_MS = 600_000;
-export const MAX_HOOK_TIMEOUT_MS = 2_147_483_647;
-const POST_ABORT_GRACE_MS = 1_000;
-export function postAbortGraceMs(remainingMs) {
-    return Math.max(0, Math.min(POST_ABORT_GRACE_MS, remainingMs));
-}
-const badHookTimeoutReported = new WeakSet();
-export function resolveHookTimeoutMs(supplied, report, owner) {
-    if (supplied === undefined)
-        return DEFAULT_HOOK_TIMEOUT_MS;
-    if (Number.isFinite(supplied) && supplied >= 0 && supplied <= MAX_HOOK_TIMEOUT_MS)
-        return supplied;
-    if (report !== undefined && !(owner !== undefined && badHookTimeoutReported.has(owner))) {
-        if (owner !== undefined)
-            badHookTimeoutReported.add(owner);
-        try {
-            report(new Error(`Hooks.timeoutMs must be a non-negative finite number no greater than ${MAX_HOOK_TIMEOUT_MS} (got ${String(supplied)}) — ` +
-                `every hook seat falls back to the ${DEFAULT_HOOK_TIMEOUT_MS}ms default`));
-        }
-        catch {
-        }
-    }
-    return DEFAULT_HOOK_TIMEOUT_MS;
-}
-export async function runHookSeat(seat, bound, call) {
-    void seat;
-    const timeoutMs = resolveHookTimeoutMs(bound.timeoutMs, bound.onBadTimeout, bound.owner);
-    const taskSignal = bound.signal;
-    const controller = new AbortController();
-    const pending = Promise.resolve(call(controller.signal));
-    const startedAt = performance.now();
-    return await new Promise((resolve, reject) => {
-        let settled = false;
-        let listening = false;
-        let timer;
-        const clearTimer = () => {
-            if (timer !== undefined)
-                clearTimeout(timer);
-            timer = undefined;
-        };
-        const finish = (act) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimer();
-            if (listening)
-                taskSignal?.removeEventListener("abort", onAbort);
-            act();
-        };
-        const expire = (cause) => finish(() => {
-            void pending.then(undefined, () => {
-            });
-            resolve({ expired: true, cause });
-            queueMicrotask(() => {
-                try {
-                    controller.abort();
-                }
-                catch {
-                }
-            });
-        });
-        const collapseToGrace = () => {
-            if (settled)
-                return;
-            clearTimer();
-            timer = setTimeout(() => expire("aborted"), postAbortGraceMs(timeoutMs - (performance.now() - startedAt)));
-        };
-        const onAbort = () => (bound.abortEnds === true ? expire("aborted") : collapseToGrace());
-        timer = setTimeout(() => expire("timeout"), timeoutMs);
-        if (taskSignal !== undefined) {
-            if (taskSignal.aborted) {
-                onAbort();
-            }
-            else {
-                taskSignal.addEventListener("abort", onAbort, { once: true });
-                listening = true;
-            }
-        }
-        pending.then((value) => finish(() => resolve({ expired: false, value })), (err) => finish(() => reject(asThrownError(err))));
-    });
-}
-export function hookSeatExpiredError(seat, timeoutMs, cause, consequence) {
-    return new Error(cause === "timeout"
-        ? `the deployment's ${seat} hook did not answer within its ${timeoutMs}ms bound (Hooks.timeoutMs) — ${consequence}`
-        : `the deployment's ${seat} hook had not answered when the task was cancelled — ${consequence}`);
-}
 const reflectApply = Reflect.apply;
 const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
 const getPrototypeOf = Object.getPrototypeOf;
@@ -174,54 +86,92 @@ export function mintHookInvocationIdentity(facts) {
         ...(facts.parentToolCallId !== undefined ? { parentToolCallId: facts.parentToolCallId } : {}),
     }));
 }
-function preToolUseCrashReason(subject, err) {
-    const cause = inlineUntrusted(describeThrown(err), 200);
-    return (`a PreToolUse hook crashed while screening ${subject}; the call was NOT executed (fail-closed). ` +
-        `This is a failure of the deployment's hook, NOT of the tool itself — an identical retry reaches the ` +
-        `same hook and fails the same way. Hook error: ${cause || "(no message)"}`);
+function screenPreToolUseResult(r) {
+    if (r === undefined || r === null || r === false)
+        return r;
+    return refuseOutOfContractDecision(r, { reasonIsNonInput: true });
 }
-function preToolUseUnansweredReason(subject, timeoutMs, cause) {
-    return cause === "timeout"
-        ? `a PreToolUse hook did not answer within its ${timeoutMs}ms bound while screening ${subject}; the call was ` +
-            `NOT executed (fail-closed). This is a failure of the deployment's hook, NOT of the tool itself — the ` +
-            `screening face never returned a verdict, so nothing was decided about this call either way.`
-        : `the task was cancelled while a PreToolUse hook was still screening ${subject}; the call was NOT executed ` +
-            `(fail-closed). No verdict was reached — this is the run ending, not the tool failing.`;
+function preToolUseAnswerViolation(answer) {
+    const r = screenPreToolUseResult(answer);
+    if (r === undefined || r === null || r === false || !isEngineRefusal(r))
+        return undefined;
+    return typeof r.message === "string" ? r.message : "the PreToolUse answer was refused by the engine";
 }
-function screenPreToolUseResult(r) {
-    if (r === undefined)
+function preToolUseRefusedReason(subject, failed) {
+    if (failed === undefined) {
+        return `the task was cancelled while a PreToolUse hook was still screening ${subject}; the call was NOT executed ` + `(fail-closed). No verdict was reached — this is the run ending, not the tool failing.`;
+    }
+    const tail = failed.cause === "threw"
+        ? ` This is a failure of the deployment's hook, NOT of the tool itself — an identical retry reaches the same hook and fails the same way.`
+        : failed.cause === "timeout"
+            ? ` This is a failure of the deployment's hook, NOT of the tool itself — the screening face never returned a verdict, so nothing was decided about this call either way.`
+            : "";
+    return `a PreToolUse hook ${failedHandlerClause(failed)} while screening ${subject}; the call was NOT executed (fail-closed).${tail}`;
+}
+export function createPreToolUseScreening(input) {
+    const bus = input.modBus;
+    if (bus === undefined || !bus.hasHandlers("classic.PreToolUse"))
         return undefined;
-    return receiveHookResult(r);
+    const { toolCallId, toolName } = input.event;
+    const screenedName = wireOf("gate.preToolUse", input.event);
+    const eventOf = (args) => {
+        const cwd = input.trackedCwd?.();
+        return {
+            ...classicEventBase(input.identity, input.observedPermissionMode?.()),
+            tool: screenedName,
+            tool_use_id: toolCallId,
+            input: judgedInputOf(args),
+            ...(typeof cwd === "string" ? { cwd } : {}),
+            ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}),
+        };
+    };
+    return {
+        screen: async (args, subject) => {
+            let outcome;
+            try {
+                outcome = await dispatchClassic(bus, "classic.PreToolUse", eventOf(args), { ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), checkAnswer: preToolUseAnswerViolation });
+            }
+            catch (err) {
+                return { kind: "refused", reason: preToolUseRefusedReason(subject, { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the screening: ${describeThrown(err)}`, skipped: [] }) };
+            }
+            if (outcome === undefined || outcome.kind === "aborted")
+                return { kind: "refused", reason: preToolUseRefusedReason(subject, undefined) };
+            if (outcome.kind === "failed")
+                return { kind: "refused", reason: preToolUseRefusedReason(subject, outcome) };
+            const r = screenPreToolUseResult(outcome.answer);
+            return { kind: "answered", answer: r === null || r === false ? undefined : r, ...(outcome.answeredBy !== undefined ? { answeredBy: outcome.answeredBy } : {}) };
+        },
+        deniedReason: (answer) => decisionText(answer) ?? `tool "${toolName}" blocked by a PreToolUse hook`,
+    };
 }
-export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash, timeoutMs) {
-    return brandPolicyAskClass({
+export function createPreToolUseConstraintPolicy(chain, env) {
+    const judges = (p) => !p.observe;
+    const minted = brandPolicyAskClass({
         check: async (req, signal) => {
+            if (!chain.hasHandlers("classic.PreToolUse", judges))
+                return { action: "allow" };
             const unasked = unaskedSeatAnswer(req, signal, { aborted: `the inherited PreToolUse screening of "${req.toolName}" was not consulted: the run or turn was already interrupted`, unreachable: `the inherited PreToolUse screening of "${req.toolName}" was not consulted: nobody can be asked about this call` }, "hook");
             if (unasked !== undefined)
                 return unasked;
-            let r;
-            const boundMs = resolveHookTimeoutMs(timeoutMs, onCrash);
+            const subject = `this call to "${req.toolName}"`;
+            let outcome;
             try {
-                const seat = await runHookSeat("preToolUse", { timeoutMs: boundMs }, (sig) => preToolUse(req.toolName, req.args, { toolCallId: req.toolCallId, toolName: req.toolName, signal: sig, ...(env !== undefined ? { env } : {}) }));
-                if (seat.expired) {
-                    try {
-                        onCrash?.(hookSeatExpiredError("preToolUse", boundMs, seat.cause, `the inherited screening of "${req.toolName}" was refused fail-closed`));
-                    }
-                    catch {
-                    }
-                    return { action: "deny", message: preToolUseUnansweredReason(`this call to "${req.toolName}"`, boundMs, seat.cause), decisionReason: "hook" };
-                }
-                r = screenPreToolUseResult(seat.value);
+                outcome = await chain.dispatch("classic.PreToolUse", { tool: req.toolName, tool_use_id: req.toolCallId, input: judgedInputOf(req.args), ...(env !== undefined ? { env } : {}) }, {
+                    bottom: engineCore,
+                    participant: judges,
+                    ...(signal !== undefined ? { signal } : {}),
+                    checkAnswer: (a) => (a === ENGINE_CORE_ANSWER ? undefined : preToolUseAnswerViolation(a)),
+                });
             }
             catch (err) {
-                try {
-                    onCrash?.(err);
-                }
-                catch {
-                }
-                return { action: "deny", message: preToolUseCrashReason(`this call to "${req.toolName}"`, err), decisionReason: "hook" };
+                return { action: "deny", message: preToolUseRefusedReason(subject, { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the screening: ${describeThrown(err)}`, skipped: [] }), decisionReason: "hook" };
             }
-            if (r === undefined)
+            if (outcome.kind === "aborted")
+                return abortedSeatDeny(req, `the inherited PreToolUse screening of "${req.toolName}" ended when the run or turn was interrupted`, "hook");
+            if (outcome.kind === "failed")
+                return { action: "deny", message: preToolUseRefusedReason(subject, outcome), decisionReason: "hook" };
+            const r = screenPreToolUseResult(outcome.answer);
+            if (r === undefined || r === null || r === false)
                 return { action: "allow" };
             if (r.action === "deny") {
                 return { action: "deny", message: decisionText(r) ?? `tool "${req.toolName}" blocked by a PreToolUse hook`, decisionReason: "hook" };
@@ -239,6 +189,8 @@ export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash, timeo
             return r.updatedInput !== undefined ? { action: "allow", updatedInput: r.updatedInput, ...stated } : { action: "allow", ...stated };
         },
     }, "hook");
+    recordScreeningChain(minted, chain);
+    return minted;
 }
 export function askCarryRowMembers(carry) {
     if (carry === undefined)
@@ -253,54 +205,21 @@ export function askCarryRowMembers(carry) {
         ...(classed !== undefined ? classed : {}),
     };
 }
-export function createPreToolUseScreening(preToolUse, input, hookSeatMs, notifier) {
-    if (preToolUse === undefined)
-        return undefined;
-    const { toolCallId, toolName } = input.event;
-    const screenedName = wireOf("gate.preToolUse", input.event);
-    const hookCtx = (seatSignal) => ({
-        toolCallId,
-        toolName: screenedName,
-        ...(seatSignal !== undefined ? { signal: seatSignal } : {}),
-        ...(() => {
-            const c = input.trackedCwd?.();
-            return typeof c === "string" ? { cwd: c } : {};
-        })(),
-        ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}),
-        ...(input.identity !== undefined ? { identity: input.identity } : {}),
-    });
-    const bound = { timeoutMs: hookSeatMs, ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), abortEnds: true };
-    return {
-        screen: (args) => runHookSeat("preToolUse", bound, (sig) => preToolUse(screenedName, args, hookCtx(sig))),
-        screened: screenPreToolUseResult,
-        crashReason: preToolUseCrashReason,
-        unansweredReason: async (subject, cause) => {
-            if (cause === "timeout")
-                traceHookCrash(input, hookSeatExpiredError("preToolUse", hookSeatMs, cause, `${subject} was NOT executed (fail-closed) and the screening face was signalled to stop`), notifier);
-            return preToolUseUnansweredReason(subject, hookSeatMs, cause);
-        },
-        deniedReason: (answer) => decisionText(answer) ?? `tool "${toolName}" blocked by a PreToolUse hook`,
-        refusedReason: (answer) => String(answer.message ?? `the PreToolUse hook's result for "${toolName}" was refused by the engine`),
-    };
-}
 export async function runToolGate(input) {
-    const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
+    const { event, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
     const callSignal = input.callSignal;
     const modelInput = event.input;
+    const owned = ownArgs(modelInput);
+    const args = owned.ok ? owned.value : modelInput;
     const notifier = createSafeNotifier(input.onNotifyError !== undefined ? { onError: input.onNotifyError } : undefined);
-    const hookSeatMs = resolveHookTimeoutMs(input.hookTimeoutMs, (err) => traceHookCrash(input, err, notifier));
-    const observerBound = { timeoutMs: hookSeatMs, ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}) };
-    const notifyPermissionDeniedSeat = async (payload) => {
-        if (input.permissionDenied === undefined)
-            return;
-        await notifier.notifyAsync(async () => {
-            const seat = await runHookSeat("permissionDenied", observerBound, (sig) => input.permissionDenied?.({ ...payload, signal: sig }));
-            if (seat.expired)
-                throw hookSeatExpiredError("permissionDenied", hookSeatMs, seat.cause, "the deny observation was abandoned; the deny itself is unchanged");
-        }, "toolGate.permissionDenied");
+    const notifyPermissionDeniedSeat = (payload) => {
+        const mode = input.observedPermissionMode?.();
+        const seen = mode !== undefined ? { ...payload, permissionMode: mode } : payload;
+        const onHostObserverFailure = (err) => void notifier.notify(() => { throw err; }, "toolGate.permissionDenied");
+        return observePermissionDenied({ legBus: input.modBus, hostObserver: input.permissionDenied, payload: seen, signal: input.abortSignal, onHostObserverFailure });
     };
-    const screening = createPreToolUseScreening(preToolUse, input, hookSeatMs, notifier);
+    const screening = createPreToolUseScreening(input);
     const pass = {
         input,
         event,
@@ -315,8 +234,8 @@ export async function runToolGate(input) {
         notifyPermissionDenied: notifyPermissionDeniedSeat,
         screening,
         afterFold: runGateLanes,
-        currentInput: modelInput,
-        req: { toolName, args: modelInput, toolCallId, ...(() => { const f = input.toolFaceOf?.(toolName); return f !== undefined ? { face: f } : {}; })() },
+        currentInput: args,
+        req: Object.freeze({ toolName, args, toolCallId, ...(() => { const f = input.toolFaceOf?.(toolName); return f !== undefined ? { face: f } : {}; })() }),
         preToolContext: [],
         hookAsk: undefined,
         parkFailed: undefined,
@@ -326,29 +245,15 @@ export async function runToolGate(input) {
         tightenedBy: undefined,
         policyRewrite: undefined,
     };
+    if (!owned.ok)
+        return await unownedArgsExit(pass, owned.reason);
     if (screening !== undefined) {
-        let r;
-        let unanswered;
-        try {
-            const seat = await screening.screen(pass.currentInput);
-            if (seat.expired)
-                unanswered = seat.cause;
-            else
-                r = screening.screened(seat.value);
-        }
-        catch (err) {
-            const reason = screening.crashReason(`this call to "${toolName}"`, err);
-            traceHookCrash(input, err, notifier);
-            return await engineFailClosedExit(pass, reason);
-        }
-        if (unanswered !== undefined) {
-            const reason = await screening.unansweredReason(`this call to "${toolName}"`, unanswered);
-            return await engineFailClosedExit(pass, reason);
+        const screened = await screening.screen(pass.currentInput, `this call to "${toolName}"`);
+        if (screened.kind === "refused") {
+            return await engineFailClosedExit(pass, screened.reason);
         }
+        const r = screened.answer;
         if (r) {
-            if (isEngineRefusal(r)) {
-                return await engineFailClosedExit(pass, screening.refusedReason(r));
-            }
             if (r.additionalContext) {
                 pass.preToolContext.push(r.additionalContext);
             }
@@ -362,7 +267,7 @@ export async function runToolGate(input) {
                 pass.hookAsk = r;
             }
             if (r.action === "allow")
-                pass.hookAllowed = true;
+                pass.hookAllowedBy = screened.answeredBy !== undefined ? [screened.answeredBy] : [];
         }
     }
     return await runGateFold(pass);

package/dist/{tools/fs → core}/image-admission.d.ts

@@ -24,9 +24,27 @@
  * before the frame and the transcript read them. A block whose bytes the admission refuses becomes a text
  * block that names the tool, the refusal and the size — never the bytes, and never silently nothing.
  */
-import type { DocumentContent, ImageContent } from "../../internal/llm.js";
-import { type ImageDimensions, type ImageDownsampler } from "../../core/mcp.js";
-import { type MediaBlock } from "../../core/media-byte-cap.js";
+import type { DocumentContent, ImageContent } from "../internal/llm.js";
+import { type ImageDimensions, type ImageDownsampler } from "./image-downsample.js";
+import { type MediaBlock } from "./media-byte-cap.js";
+/** Byte cap on a Read-image WITHOUT a downsampler: an image file is returned AS a visual
+ *  `ImageContent` block (base64) rather than refused. Bounded so a huge image cannot blow the request.
+ *  This stat-time cap only bounds the READ; the accept/refuse decision is the base64 gate below (the
+ *  provider limit is on base64 LENGTH, so the effective no-sharp accept bound is raw ≤ 3.75MB). */
+export declare const MAX_IMAGE_READ_BYTES: number;
+/** Byte cap on a Read-image WITH a downsampler: sharp can shrink a big photo to CC's 2000×2000/3.75MB
+ *  target, so the smaller hard refusal does not apply (CC readImageWithTokenBudget reads the file
+ *  unbounded; we keep an OOM sanity bound — deliberate delta, camera photos fit comfortably). */
+export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
+/** Max raw size sent whole as a document block (CC `PDF_TARGET_RAW_SIZE`). */
+export declare const PDF_TARGET_RAW_SIZE: number;
+/** Verify the raw bytes actually ARE the image format the extension claims (magic-number sniff). Extension alone
+ *  is forgeable: a `.png` holding text / an empty file / a truncated blob would otherwise become a malformed
+ *  `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. */
+export declare function imageMagicMatches(bytes: Uint8Array, mimeType: string): boolean;
+/** True when the bytes start with the `%PDF-` magic. Magic outranks extension both ways: a mis-named
+ *  `.pdf` without it is refused, and a non-`.pdf` file carrying it is read AS a PDF. */
+export declare function pdfMagicMatches(bytes: Uint8Array): boolean;
 /** The image types the content API accepts — the only ones a signature check can verify. */
 export declare const ADMITTED_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
 /** The raw-byte read cap for an image, with or without a downsampler. */

package/dist/{tools/fs → core}/image-admission.js

@@ -1,9 +1,27 @@
-import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
-import { claimedMediaType } from "../../core/media-byte-cap.js";
-import { readMember } from "../../core/thrown-value.js";
-import { imageMagicMatches } from "./safety.js";
-import { MAX_IMAGE_READ_BYTES, MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES } from "./fs-shared.js";
-import { PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "./pdf.js";
+import { MCP_IMAGE_MAX_BASE64 } from "./image-downsample.js";
+import { claimedMediaType } from "./media-byte-cap.js";
+import { readMember } from "./thrown-value.js";
+export const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
+export const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;
+export const PDF_TARGET_RAW_SIZE = 20 * 1024 * 1024;
+export function imageMagicMatches(bytes, mimeType) {
+    const b = bytes;
+    switch (mimeType) {
+        case "image/png":
+            return b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 && b[4] === 0x0d && b[5] === 0x0a && b[6] === 0x1a && b[7] === 0x0a;
+        case "image/jpeg":
+            return b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff;
+        case "image/gif":
+            return b.length >= 6 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38 && (b[4] === 0x37 || b[4] === 0x39) && b[5] === 0x61;
+        case "image/webp":
+            return b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50;
+        default:
+            return false;
+    }
+}
+export function pdfMagicMatches(bytes) {
+    return bytes.length >= 5 && bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46 && bytes[4] === 0x2d;
+}
 export const ADMITTED_IMAGE_MIME_TYPES = Object.freeze(["image/png", "image/jpeg", "image/gif", "image/webp"]);
 export function imageReadCap(downsampler) {
     return downsampler ? MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES : MAX_IMAGE_READ_BYTES;

package/dist/core/locked-config.d.ts

@@ -39,8 +39,8 @@ export interface LockedPreflight {
     /** The validated lock set (empty when the deployment declares none). */
     lockedKeys: ReadonlySet<LockedKey>;
     /** Effective MCP server list for this task: a validated, frozen SNAPSHOT of `spec.mcp` when the
-     *  key is unlocked (see {@link snapshotAndValidateMcpEntries} — the content-class declaration is read once
-     *  and judged here, so no mint site downstream can be handed a different value than the door
+     *  key is unlocked (see {@link snapshotAndValidateMcpEntries} — the content-class and `toolAxes` declarations
+     *  are read once and judged here, so no mint site downstream can be handed a different value than the door
      *  approved); with `mcp` locked a spec-supplied value has already been refused, so this is always
      *  `undefined` (core has no deployment-level MCP seat — a locked deployment mounts no
      *  task-supplied servers). */
@@ -84,15 +84,36 @@ export declare function resolveLockedKeys(config: LockedConfig | undefined): Rea
  * Boundary, stated: the copy is one level deep — nested option objects (transport, headers, env,
  * toolAxes) stay shared with the caller's entry exactly as before, because the axis this owns is the
  * content class; readers of the nested shapes normalize their own values (the transport DISCRIMINATOR
- * is derived, never echoed raw). Own ENUMERABLE properties only: an entry whose fields live on a
- * prototype was never the plain configuration record this type describes, and its absent class reads
- * fail-closed like any other absence.
+ * is derived, never echoed raw). `toolAxes` is the one nested shape both entrances replace with its
+ * reader's plain copy ({@link judgeEntryToolAxes}), and the one member this snapshot reads BY NAME rather
+ * than by spread, once: a declaration an entry carries as a non-enumerable or inherited property would
+ * otherwise vanish before any reader sees it, and an absent caller axis is a tightening lost, not a
+ * fail-closed absence. Every other member is taken as own ENUMERABLE properties only: an entry whose
+ * fields live on a prototype was never the plain configuration record this type describes, and its
+ * absent class reads fail-closed like any other absence.
  *
  * Exported because the SECOND boundary needs the identical guarantee: `materializeMcpTools` is public
  * and a library caller reaches it without passing any door, so it snapshots its own input through
  * this same function (idempotent over an already-frozen entry). One spelling, both entrances.
  */
 export declare function snapshotMcpEntries(entries: readonly McpServerSpec[]): McpServerSpec[];
+/**
+ * The `toolAxes` question for ONE snapshot entry — asked by the preparation door (a refusal ends the prepare) and by the materialization
+ * entrance (a refusal fails that server's dial), so there is one reading, one copy and one sentence whichever time it is asked.
+ * `ok: true` carries the entry with the reader's PLAIN COPY of the axes in place of the caller's object: what was judged is the very value
+ * the connect and every refresh read, not a live object that could answer differently later. The copy is frozen with the entry — a tool
+ * that shallow-copies a server (`mountedMcp()`) to customise its axes must not rewrite what the parent reads. `ok: false` carries the
+ * coded refusal (`config.invalid_argument`) naming the server, the tool and the member, never a value.
+ */
+export declare function judgeEntryToolAxes(copy: McpServerSpec): {
+    ok: true;
+    entry: McpServerSpec;
+} | {
+    ok: false;
+    error: Error & {
+        code: string;
+    };
+};
 /**
  * The single preflight resolver: validate the lock declaration, refuse a spec that tries to occupy
  * a locked slot (`config.locked_key`, two-state — the whole prepare is rejected, nothing is

package/dist/core/locked-config.js

@@ -1,3 +1,4 @@
+import { readMcpToolAxes } from "./mcp-server-spec.js";
 import { isToolContentOrigin, TOOL_CONTENT_ORIGINS } from "./memory-engine/content-origin.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { assertNoRetiredToolPolicyKeys } from "./retired-keys.js";
@@ -27,7 +28,10 @@ export function resolveLockedKeys(config) {
     return keys;
 }
 export function snapshotMcpEntries(entries) {
-    return entries.map((entry) => Object.freeze({ ...entry }));
+    return entries.map((entry) => {
+        const { toolAxes, ...rest } = entry;
+        return Object.freeze((toolAxes === undefined ? rest : { ...rest, toolAxes }));
+    });
 }
 function describeDeclared(value) {
     try {
@@ -42,20 +46,41 @@ function describeDeclared(value) {
         }
     }
 }
+const serverNameOf = (copy) => inlineUntrusted(typeof copy.name === "string" ? JSON.stringify(copy.name) : describeDeclared(copy.name), 80);
+export function judgeEntryToolAxes(copy) {
+    const { toolAxes: declaredAxes, ...rest } = copy;
+    const axes = readMcpToolAxes(declaredAxes);
+    if (!axes.ok) {
+        return {
+            ok: false,
+            error: codedError("config.invalid_argument", `MCP server ${serverNameOf(copy)} declares toolAxes the engine cannot read: ${inlineUntrusted(axes.problem, 240)}. A per-tool safety-axis declaration is the ` +
+                `caller's trust root for the approval gate, so it is refused rather than partly applied — dropping one key or defaulting one word ` +
+                `would leave a declaration that reads as in force while it is not.`),
+        };
+    }
+    if (axes.toolAxes !== undefined) {
+        for (const perTool of Object.values(axes.toolAxes))
+            Object.freeze(perTool);
+        Object.freeze(axes.toolAxes);
+    }
+    return { ok: true, entry: Object.freeze(axes.toolAxes === undefined ? rest : { ...rest, toolAxes: axes.toolAxes }) };
+}
 function snapshotAndValidateMcpEntries(entries) {
-    const copies = snapshotMcpEntries(entries);
-    for (const copy of copies) {
+    return snapshotMcpEntries(entries).map((copy) => {
         const declared = copy.contentOrigin;
         if (declared !== undefined && !isToolContentOrigin(declared)) {
-            throw codedError("config.mcp_content_class", `MCP server ${inlineUntrusted(typeof copy.name === "string" ? JSON.stringify(copy.name) : describeDeclared(copy.name), 80)} declares contentOrigin ` +
+            throw codedError("config.mcp_content_class", `MCP server ${serverNameOf(copy)} declares contentOrigin ` +
                 `${inlineUntrusted(describeDeclared(declared), 80)}, which is not one of ` +
                 `${TOOL_CONTENT_ORIGINS.map((v) => `"${v}"`).join(" | ")}. The declaration decides whether this server's tools ` +
                 `mark the session's memory externally exposed — a value this engine cannot read is refused at the door rather ` +
                 `than folded to a class, because folding it would let a deployment believe a declaration is in force while every ` +
                 `call keeps writing a one-way durable mark.`);
         }
-    }
-    return copies;
+        const judged = judgeEntryToolAxes(copy);
+        if (!judged.ok)
+            throw judged.error;
+        return judged.entry;
+    });
 }
 export function preflightLockedConfig(spec, deps) {
     const lockedKeys = resolveLockedKeys(deps.lockedConfig);

package/dist/core/mcp-connection-pool.d.ts

@@ -56,8 +56,11 @@ export declare class McpConnectionPool {
      * transport object that answers differently to two readers cannot split the dial from its key); every other transport member is read here.
      * The declaration's mount identity (`fingerprint`) is part of the key when declared: the revocation probe is asked with it, so two mounts the
      * host tells apart never share one connection (an undeclared fingerprint leaves the key as it always was).
+     * So is the startup bound the dial runs under (`startupMs`, the dial's one reading of {@link mcpStartupTimeoutMs}, threaded like `kind`):
+     * a connection is dialled under the declaration of the mount that dials it, so a mount never waits on, or shares, a dial bounded by
+     * another mount's clock. No bound in force (none declared, no environment seat) leaves the key as it always was.
      */
-    static keyOf(spec: McpServerSpec, principal: string | undefined, kind: string | undefined): string;
+    static keyOf(spec: McpServerSpec, principal: string | undefined, kind: string | undefined, startupMs: number | undefined): string;
     /**
      * Lease the connection for `key`, dialling it with `dial` when none is live. `fresh` replaces the pool's current connection with a new
      * dial (a re-dial): the connection it replaces lives on until its other holders release it. Resolves `undefined` once the pool is

package/dist/core/mcp-connection-pool.js

@@ -4,10 +4,15 @@ export class McpConnectionPool {
     dialing = new Map();
     generation = new Map();
     shut = false;
-    static keyOf(spec, principal, kind) {
+    static keyOf(spec, principal, kind, startupMs) {
         const rest = Object.fromEntries(Object.keys(spec.transport).filter((k) => k !== "kind").map((k) => [k, Reflect.get(spec.transport, k)]));
         const fingerprint = spec.fingerprint;
-        return canonicalize(fingerprint === undefined ? [spec.name, kind ?? null, rest, principal ?? null] : [spec.name, kind ?? null, rest, principal ?? null, fingerprint]);
+        const identity = [spec.name, kind ?? null, rest, principal ?? null];
+        if (fingerprint !== undefined)
+            identity.push(fingerprint);
+        if (startupMs !== undefined)
+            identity.push({ startupTimeoutMs: startupMs });
+        return canonicalize(identity);
     }
     async acquire(key, dial, opts) {
         if (this.shut)

package/dist/core/mcp-probe.d.ts

@@ -38,15 +38,17 @@ export interface McpProbeOptions {
      *  on a real leg — so a server that applies per-user rules answers the probe as it would answer the
      *  task. */
     principal?: string;
-    /** Per-server ceiling on the VERDICT, in whole milliseconds within `[1, MCP_ENV_MS_MAX]` (the ceiling
-     *  every env-supplied MCP bound keeps, because a larger delay is silently rewritten to 1 ms). When it
-     *  elapses, THAT server's row reads `failed` with `errorCode: "timeout"` and the walk moves on; nothing
-     *  throws. It does NOT end the dial — nothing here can — so the transport stays open until the dial
-     *  lands on its own; see the residue note on {@link probeMcpServers}.
+    /** An OVERALL ceiling on the VERDICT for each server, in whole milliseconds within `[1, MCP_ENV_MS_MAX]` (the
+     *  ceiling every env-supplied MCP bound keeps, because a larger delay is silently rewritten to 1 ms). The
+     *  caller's own choice, and it lives BESIDE the per-phase startup bounds the dial runs under — whichever
+     *  arrives first decides. When it elapses, THAT server's row reads `failed` with `errorCode: "timeout"` and
+     *  the walk moves on; nothing throws. It does NOT end the dial — nothing here can — so the transport stays
+     *  open until the dial lands on its own; see the residue note on {@link probeMcpServers}.
      *
-     *  Default: the engine's own startup-phase bound ({@link mcpStartupTimeoutMs}, env `MCP_TIMEOUT`) when a
-     *  deployment set one; absent there, this module runs no clock and the answer for that server is
-     *  whatever the dial's own request budgets produce — which bound the REQUESTS, not the dial. */
+     *  Default: none. The probe has no clock of its own: it dials through the entrance a task does, so each
+     *  startup phase (the handshake, then the initial listing) carries that server's own bound from the one
+     *  reader ({@link import("./mcp.js").mcpStartupTimeoutMs}: its `startupTimeoutMs`, else env `MCP_TIMEOUT`, else
+     *  the SDK's 60 000 ms) — exactly what a task allows it. */
     timeoutMs?: number;
     /** Abort the whole probe. The call rejects with the signal's own reason (a bare `abort()` gives an
      *  `AbortError`) AFTER every server it had opened is closed — see the residue contract on
@@ -102,7 +104,8 @@ export interface McpProbeOptions {
  * return, and NOT that the call itself is bounded. What bounds it, stated part by part rather than
  * summarised into a number that would be wrong:
  *  · a dial has two REQUEST-BUDGET phases, each carrying the startup-phase bound ({@link
- *    mcpStartupTimeoutMs}, env `MCP_TIMEOUT`, else the SDK's 60 000 ms default): the handshake, one
+ *    import("./mcp.js").mcpStartupTimeoutMs}: the server's own `startupTimeoutMs`, else env `MCP_TIMEOUT`, else the SDK's
+ *    60 000 ms default): the handshake, one
  *    request; and the initial tool listing, a PAGINATED WALK whose whole budget is that same number
  *    (however many pages it takes — and no request at all when the peer advertises no tools). Two
  *    budgets, so twice that, not once;