@sema-agent/core 7.3.0 → 7.3.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 7.3.1 — 2026-09-03
+
+### Changed (narrowing, named) — #531 Edit validates BEFORE it asks
+- **`ToolSpec.validateInput?(args, ctx)`** — a pure input pre-validation hook the loop runs BEFORE the permission gate (CC parity: `validateInput` precedes the permission prompt; a refusal is a typed tool result, not a card). Edit / Write-on-existing / NotebookEdit implement it with the same `requireRead` + path checks the execute path keeps (double-checked; TOCTOU-safe). **Narrowing**: an Edit of a file the model never Read no longer raises an approval card — the model receives the read-first refusal directly (the auto classifier is not consulted); a Read-then-Edit still asks exactly as before. A throwing validator reads as "no verdict" (the call proceeds to the gate; one `onError` hook-phase disclosure).
+
+### Added — #530 `waiting_first_token` status phase (closed set 6 → 7)
+- `BrainStatusPhase` +`"waiting_first_token"`: with an armed first-token watchdog (`firstTokenTimeoutMs` > 30s), a `status` frame is emitted once the first token has been awaited 30s and every 30s after (`elapsedMs`, `timeoutMs`; no `retryAtMs`); cleared by the token, the watchdog or the call's end. An announced wait closes with the terminal frame (`recovered`, detail `first token arrived`) — never a retry's wording. Constants `WAITING_FIRST_TOKEN_AFTER_MS` / `WAITING_FIRST_TOKEN_EVERY_MS` exported. **Consumers pinning the six-member phase set must widen** (cli client-core retry-status closed set; server status projection is a pass-through).
+
+### Added — #529 `WiringManifest.autoMode { armed, reason }`
+- Minted on every leg (effective half; fingerprinted like `modelGate`): `reason ∈ armed | no_intent | no_face | denied | resolver_fault | latch_open` (`AUTO_MODE_ARM_REASONS`), `armed ⇔ reason === "armed"`. The per-leg READ face of the #521 arming decision.
+
+### Fixed — #532 format characters inside / around a secret (family fix of A-087 root C)
+- The format-free scanning view sinks into `runRedactionPasses`, so BOTH entries (`scrubSecrets`, `redactSecrets`) and every consumer (`primaryActivityArg` → `TaskResult.stats.humanReview.gates[].toolArg`, previews, error text) redact a key split by U+200B / U+00AD / U+FEFF as one marker; the raw scan and one suffix scan per format slot are unioned in so a format character used as the BOUNDARY before a key (`x<ZWSP>sk-…`) is still found; past 64 format slots the input is replaced whole (over-strip, never a leak). Format characters outside a secret are preserved; format-free input is byte-identical.
+
 ## 7.3.0 — 2026-09-03
 
 ### Added — design/385 slice 2a + 2b (cross-session peer messaging: mailbox contract, file backend, agents domain; +40 exports, 0 removed)

package/dist/brain/status-sink.d.ts

@@ -16,6 +16,16 @@ export declare function runWithStatusSink<T>(emit: (s: BrainStatus) => void, fn:
  * call site for this exact reason and states the contract ("an advisory frame must never break a settled
  * call"); the guard belongs HERE so every call site inherits it rather than each remembering.
  */
+/**
+ * #530 — bind the ACTIVE sink now, for an emit that will happen from a timer callback later. The
+ * async-local store propagates through Node's timers, but not through every timer implementation a
+ * process may run under (fake clocks in tests replace `setTimeout` outright and run callbacks from
+ * their own stack, where `getStore()` is empty). A frame scheduled inside the sink's scope must reach
+ * that sink whichever clock fires it, so the scheduler captures the store here and the callback emits
+ * through the bound function. Same swallow guard and the same retryAtMs stamp as {@link emitBrainStatus};
+ * a no-op function when no sink is active.
+ */
+export declare function bindBrainStatusEmitter(): (status: BrainStatus) => void;
 export declare function emitBrainStatus(status: BrainStatus): void;
 /**
  * Silent-fallback telemetry (C1/C4/C5/C6) — the brain→runner TELEMETRY channel, a

package/dist/brain/status-sink.js

@@ -3,16 +3,25 @@ const statusSinkStore = new AsyncLocalStorage();
 export function runWithStatusSink(emit, fn) {
     return statusSinkStore.run({ emit }, fn);
 }
-export function emitBrainStatus(status) {
+export function bindBrainStatusEmitter() {
+    const sink = statusSinkStore.getStore();
+    if (sink === undefined)
+        return () => undefined;
+    return (status) => deliverBrainStatus(sink, status);
+}
+function deliverBrainStatus(sink, status) {
     try {
-        const sink = statusSinkStore.getStore();
-        if (sink === undefined)
-            return;
         sink.emit(withRetryDeadline(status));
     }
     catch {
     }
 }
+export function emitBrainStatus(status) {
+    const sink = statusSinkStore.getStore();
+    if (sink === undefined)
+        return;
+    deliverBrainStatus(sink, status);
+}
 function withRetryDeadline(status) {
     if (status.retryAtMs !== undefined)
         return status;

package/dist/brain/stream-engine.d.ts

@@ -89,6 +89,17 @@ export declare function sameRequestModuloCap(original: SSERequest, rebuilt: SSER
  * Tolerates a `doFetch` (BYOM injection point) whose Response-shaped return has no usable `headers`.
  */
 export declare function shouldRetryHeaderVerdict(res: Response | undefined): boolean | undefined;
+/**
+ * #530 — the first-token WAIT disclosure. While a first-token watchdog is armed
+ * (`firstTokenTimeoutMs > 0`) and no content token has arrived, the engine says so on the status
+ * channel: the FIRST `waiting_first_token` frame goes out once the wait has lasted
+ * {@link WAITING_FIRST_TOKEN_AFTER_MS}, and one more every {@link WAITING_FIRST_TOKEN_EVERY_MS} after
+ * that, until the first token lands, the watchdog fires, or the attempt ends. A short wait (under the
+ * threshold) announces nothing — the frame exists for the unattended "no answer for a minute" case,
+ * not for every request. The same 30s slice the retry countdown re-announces on.
+ */
+export declare const WAITING_FIRST_TOKEN_AFTER_MS = 30000;
+export declare const WAITING_FIRST_TOKEN_EVERY_MS = 30000;
 export interface SSERequest {
     url: string;
     headers: Record<string, string>;

package/dist/brain/stream-engine.js

@@ -3,7 +3,7 @@ import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } fr
 import { BrainError, classifyConnectFailure, classifyHttp, describeNetworkError, namesTheFailure, readProviderRequestId } from "./errors.js";
 import { classifyInputTooLong } from "./input-too-long.js";
 import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.js";
-import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
+import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { createConnectController, resolveStallTimeoutMs } from "./timeout.js";
 const DEFAULT_MAX_RETRIES = 10;
 const MAX_RETRIES_ENV_CEILING = 15;
@@ -189,6 +189,8 @@ export function shouldRetryHeaderVerdict(res) {
     return undefined;
 }
 const RETRY_STATUS_SLICE_MS = 30_000;
+export const WAITING_FIRST_TOKEN_AFTER_MS = 30_000;
+export const WAITING_FIRST_TOKEN_EVERY_MS = 30_000;
 const THINKING_RETRY_BUDGET = 2;
 const EMPTY_USAGE = {
     input: 0,
@@ -249,6 +251,8 @@ export function runStreamingBrain(args) {
     const out = createAssistantMessageEventStream();
     let cleanup;
     let announcedRetry = false;
+    let announcedWait = false;
+    let terminalWaitDetail = "first token arrived";
     let terminalRetryPhase = "recovered";
     let terminalRetryDetail = "recovered after retrying";
     let requestIdSeen;
@@ -257,6 +261,7 @@ export function runStreamingBrain(args) {
         const aborted = signal?.aborted === true || isAbortError(err);
         terminalRetryPhase = "gave_up";
         terminalRetryDetail = aborted ? "cancelled while retrying" : "retries exhausted";
+        terminalWaitDetail = aborted ? "cancelled while waiting for the first token" : "the first-token wait ended in failure";
         const errorMsg = emptyAssistant(model);
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = err instanceof Error ? err.message : String(err);
@@ -278,10 +283,10 @@ export function runStreamingBrain(args) {
     })
         .finally(() => {
         cleanup?.();
-        if (!announcedRetry)
+        if (!announcedRetry && !announcedWait)
             return;
         try {
-            emitBrainStatus({ phase: terminalRetryPhase, detail: terminalRetryDetail });
+            emitBrainStatus({ phase: terminalRetryPhase, detail: announcedRetry ? terminalRetryDetail : terminalWaitDetail });
         }
         catch {
         }
@@ -468,11 +473,39 @@ export function runStreamingBrain(args) {
             let firstTokenSeen = false;
             let firstTokenTimedOut = false;
             let ftTimer;
+            let waitTimer;
+            const clearWaitTimer = () => {
+                if (waitTimer) {
+                    clearTimeout(waitTimer);
+                    waitTimer = undefined;
+                }
+            };
             if (firstTokenTimeoutMs && firstTokenTimeoutMs > 0) {
                 ftTimer = setTimeout(() => {
                     firstTokenTimedOut = true;
+                    clearWaitTimer();
                     void reader.cancel().catch(() => undefined);
                 }, firstTokenTimeoutMs);
+                if (firstTokenTimeoutMs > WAITING_FIRST_TOKEN_AFTER_MS) {
+                    const waitStartedAt = Date.now();
+                    const emitWaitFrame = bindBrainStatusEmitter();
+                    const scheduleWaitFrame = (delayMs) => {
+                        waitTimer = setTimeout(() => {
+                            waitTimer = undefined;
+                            if (firstTokenSeen || firstTokenTimedOut || Date.now() - waitStartedAt >= firstTokenTimeoutMs)
+                                return;
+                            announcedWait = true;
+                            emitWaitFrame({
+                                phase: "waiting_first_token",
+                                detail: "waiting for the first token",
+                                elapsedMs: Date.now() - waitStartedAt,
+                                timeoutMs: firstTokenTimeoutMs,
+                            });
+                            scheduleWaitFrame(WAITING_FIRST_TOKEN_EVERY_MS);
+                        }, delayMs);
+                    };
+                    scheduleWaitFrame(WAITING_FIRST_TOKEN_AFTER_MS);
+                }
             }
             let idleTimedOut = false;
             let idleTimer;
@@ -497,12 +530,14 @@ export function runStreamingBrain(args) {
                     clearTimeout(ftTimer);
                     ftTimer = undefined;
                 }
+                clearWaitTimer();
             };
             cleanup = () => {
                 if (ftTimer) {
                     clearTimeout(ftTimer);
                     ftTimer = undefined;
                 }
+                clearWaitTimer();
                 if (idleTimer) {
                     clearTimeout(idleTimer);
                     idleTimer = undefined;
@@ -575,6 +610,7 @@ export function runStreamingBrain(args) {
                 clearTimeout(ftTimer);
                 ftTimer = undefined;
             }
+            clearWaitTimer();
             if (idleTimer) {
                 clearTimeout(idleTimer);
                 idleTimer = undefined;

package/dist/core/arg-summary.d.ts

@@ -71,9 +71,19 @@ export interface RedactionPass {
     /** A literal replacement (only `$1` substitution is used by these passes) or a replacer fn. */
     replace: string | ((match: string, ...groups: string[]) => string);
 }
-/** Run the declared passes in order, collecting findings (original-input spans) when a report is given.
- *  An idempotent no-op replacement (inserted === matched, e.g. re-scrubbing already-redacted text) is
- *  NOT a finding — nothing was removed. */
+/**
+ * Run the declared passes in order, collecting findings (original-input spans) when a report is given.
+ *
+ * FORMAT CHARACTERS (#532): the passes scan a VIEW of the input with every `\p{Cf}` removed, so a
+ * credential split by a zero-width character is one token to the scanner, not two fragments of which
+ * only the first (or neither) matches. The OUTPUT keeps every format character that sits OUTSIDE a
+ * replaced span — a joiner in an emoji sequence, a non-joiner in Persian text, a soft hyphen in a word
+ * — and drops only those INSIDE the span the marker replaces (they were part of the secret). A
+ * format-free input takes the exact historical path (byte-identical output). When the replacements
+ * cannot be mapped back exactly (a later pass matched across an earlier pass's inserted text), the
+ * output is the redacted view itself — every format character dropped: the failure direction is
+ * over-stripping, never a leak.
+ */
 export declare function runRedactionPasses(input: string, passes: readonly RedactionPass[], report?: RedactionReport): string;
 /** The credential-shape passes (the pre-channel SECRET_PATTERNS, now with declared kinds/confidence).
  *  Exported for {@link runRedactionPasses} composition (untrusted-egress chains its URL passes after

package/dist/core/arg-summary.js

@@ -25,10 +25,10 @@ function mapBackOnePass(edits, pos) {
     return pos - delta;
 }
 const PREEXISTING_MARKER_RE = /\[redacted(?:-[a-z]+)?\]/g;
-export function runRedactionPasses(input, passes, report) {
-    if (report !== undefined && report.preexistingMarkers === undefined) {
-        report.preexistingMarkers = input.match(PREEXISTING_MARKER_RE)?.length ?? 0;
-    }
+const FORMAT_CHAR_RE = /\p{Cf}/u;
+const MAX_FORMAT_SLOT_SCANS = 64;
+const REDACTED_WHOLE = "[redacted]";
+function applyPasses(input, passes, report, toOriginal) {
     const batches = [];
     let cur = input;
     for (const pass of passes) {
@@ -51,18 +51,149 @@ export function runRedactionPasses(input, passes, report) {
                     report.findings.push({
                         kind: pass.kind,
                         confidence: pass.confidence,
-                        span: [s0, e0],
+                        span: [toOriginal(s0), toOriginal(e0)],
                         marker: pass.marker,
                         source: pass.source,
                     });
                 }
-                edits.push({ at: offset, removedLen: match.length, insertedLen: inserted.length });
+                edits.push({ at: offset, removedLen: match.length, insertedLen: inserted.length, inserted });
             }
             return inserted;
         });
         batches.push(edits);
     }
-    return cur;
+    return { out: cur, batches };
+}
+function replacedSpans(batches) {
+    const spans = [];
+    for (let j = 0; j < batches.length; j++) {
+        for (const e of batches[j]) {
+            let s0 = e.at;
+            let e0 = e.at + e.removedLen;
+            for (let i = j - 1; i >= 0; i--) {
+                s0 = mapBackOnePass(batches[i], s0);
+                e0 = mapBackOnePass(batches[i], e0);
+            }
+            if (e0 - s0 !== e.removedLen)
+                return undefined;
+            spans.push({ start: s0, end: e0, inserted: e.inserted, pass: j });
+        }
+    }
+    spans.sort((a, b) => a.start - b.start);
+    for (let i = 1; i < spans.length; i++)
+        if (spans[i].start < spans[i - 1].end)
+            return undefined;
+    return spans;
+}
+export function runRedactionPasses(input, passes, report) {
+    if (report !== undefined && report.preexistingMarkers === undefined) {
+        report.preexistingMarkers = input.match(PREEXISTING_MARKER_RE)?.length ?? 0;
+    }
+    if (!FORMAT_CHAR_RE.test(input))
+        return applyPasses(input, passes, report, (pos) => pos).out;
+    const viewChars = [];
+    const viewToOriginal = [];
+    const formatAtSlot = [];
+    const charStartOffsets = [];
+    {
+        let orig = 0;
+        let viewOff = 0;
+        let slotBuf = "";
+        for (const ch of input) {
+            if (FORMAT_CHAR_RE.test(ch)) {
+                slotBuf += ch;
+            }
+            else {
+                formatAtSlot.push(slotBuf);
+                slotBuf = "";
+                viewToOriginal.push(orig);
+                charStartOffsets.push(viewOff);
+                viewChars.push(ch);
+                viewOff += ch.length;
+            }
+            orig += ch.length;
+        }
+        formatAtSlot.push(slotBuf);
+        viewToOriginal.push(input.length);
+        charStartOffsets.push(viewOff);
+    }
+    const view = viewChars.join("");
+    const offsetToCharIndex = new Map();
+    charStartOffsets.forEach((off, idx) => offsetToCharIndex.set(off, idx));
+    const toOriginal = (pos) => {
+        const idx = offsetToCharIndex.get(pos);
+        return idx === undefined ? input.length : viewToOriginal[idx];
+    };
+    const { out, batches } = applyPasses(view, passes, report, toOriginal);
+    const viewSpans = replacedSpans(batches);
+    if (viewSpans === undefined)
+        return out;
+    const spans = viewSpans.map((sp) => {
+        const startIdx = offsetToCharIndex.get(sp.start) ?? viewChars.length;
+        const endIdx = offsetToCharIndex.get(sp.end) ?? viewChars.length;
+        const lastIdx = endIdx - 1;
+        const endOrig = lastIdx >= startIdx && lastIdx < viewChars.length ? viewToOriginal[lastIdx] + viewChars[lastIdx].length : viewToOriginal[startIdx];
+        return { start: viewToOriginal[startIdx], end: endOrig, inserted: sp.inserted };
+    });
+    const viewOffsetToOriginal = (viewStart, viewEnd) => {
+        const startIdx = offsetToCharIndex.get(viewStart) ?? viewChars.length;
+        const endIdx = offsetToCharIndex.get(viewEnd) ?? viewChars.length;
+        const lastIdx = endIdx - 1;
+        const endOrig = lastIdx >= startIdx && lastIdx < viewChars.length ? viewToOriginal[lastIdx] + viewChars[lastIdx].length : viewToOriginal[startIdx];
+        return { start: viewToOriginal[startIdx], end: endOrig };
+    };
+    const cutOffsets = [];
+    for (let k = 1; k < viewChars.length; k++)
+        if (formatAtSlot[k] !== "")
+            cutOffsets.push(charStartOffsets[k]);
+    if (cutOffsets.length > MAX_FORMAT_SLOT_SCANS)
+        return REDACTED_WHOLE;
+    const extra = [];
+    const rawSpans = replacedSpans(applyPasses(input, passes, undefined, (pos) => pos).batches);
+    if (rawSpans !== undefined)
+        extra.push(...rawSpans);
+    for (const cut of cutOffsets) {
+        const cutSpans = replacedSpans(applyPasses(view.slice(cut), passes, undefined, (pos) => pos).batches);
+        if (cutSpans === undefined)
+            continue;
+        for (const c of cutSpans) {
+            const o = viewOffsetToOriginal(c.start + cut, c.end + cut);
+            extra.push({ start: o.start, end: o.end, inserted: c.inserted, pass: c.pass });
+        }
+    }
+    extra.sort((a, b) => a.start - b.start);
+    for (const r of extra) {
+        const overlapping = spans.find((v) => r.start < v.end && v.start < r.end);
+        if (overlapping !== undefined) {
+            if (r.start < overlapping.start)
+                overlapping.start = r.start;
+            if (r.end > overlapping.end)
+                overlapping.end = r.end;
+            continue;
+        }
+        spans.push({ start: r.start, end: r.end, inserted: r.inserted });
+        if (report !== undefined) {
+            const pass = passes[r.pass];
+            report.findings.push({ kind: pass.kind, confidence: pass.confidence, span: [r.start, r.end], marker: pass.marker, source: pass.source });
+        }
+        spans.sort((a, b) => a.start - b.start);
+    }
+    for (let i = 1; i < spans.length;) {
+        if (spans[i].start < spans[i - 1].end) {
+            spans[i - 1].end = Math.max(spans[i - 1].end, spans[i].end);
+            spans.splice(i, 1);
+        }
+        else
+            i++;
+    }
+    let result = "";
+    let cursor = 0;
+    for (const sp of spans) {
+        result += input.slice(cursor, sp.start) + sp.inserted;
+        cursor = sp.end;
+    }
+    result += input.slice(cursor);
+    return result;
 }
 export const SECRET_PASSES = [
     { kind: "prefixed-token", confidence: "high", marker: "[redacted]", source: "arg-summary", re: /(?<![A-Za-z0-9])(?:sk|pk|rk|gh[opsur])[-_][A-Za-z0-9_-]{8,}/g, replace: "[redacted]" },

package/dist/core/runner/prepare-task.js

@@ -1210,6 +1210,18 @@ function autoModeLatchHealthy(d) {
         return false;
     }
 }
+function autoModeArmReasonOf(intent, facePresent, capsAutoMode, capsFaulted) {
+    if (!intent)
+        return "no_intent";
+    if (!facePresent)
+        return "no_face";
+    if (capsAutoMode === false)
+        return capsFaulted ? "resolver_fault" : "denied";
+    return "armed";
+}
+function validateInputFaultNotice(onError, sessionId) {
+    return ({ toolName, toolCallId, error }) => onError?.(new Error(`tool input pre-validation (validateInput) threw for ${toolName} (call ${toolCallId}) — read as no verdict; the call proceeded to the gate: ${error instanceof Error ? error.message : String(error)}`), { phase: "hook", sessionId });
+}
 function refuseInvalidAutoModeSeat(spec) {
     if (spec.autoModeRequested !== undefined && spec.autoModeRequested !== true) {
         const e = new Error(`autoModeRequested must be the literal true when present (got ${JSON.stringify(spec.autoModeRequested)}) — omit it for a non-auto task; a non-boolean or false value is refused rather than read as either polarity.`);
@@ -1977,6 +1989,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         }
         agentForkDenial = forkGovernanceDenial(spec.enableFork, runtimeCaps?.allowFork);
         observersActive = runtimeCaps?.allowObservers === true;
+        const autoModeArmReason = autoModeArmReasonOf(autoModeIntent, deps.autoMode !== undefined, runtimeCaps?.autoMode, runtimeCapsFaulted);
         if (autoModeIntent && deps.autoMode !== undefined && runtimeCaps?.autoMode !== false) {
             const am = deps.autoMode;
             let classifierModel;
@@ -3614,6 +3627,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             };
         const harness = new AgentHarness({
             abortResultDetails: () => parkContaminationMarker({ suspendRef, reviewRef }),
+            onToolInputValidationFault: validateInputFaultNotice(deps.onError, sessionId),
             ...(spec.limits?.maxOutputTokens !== undefined && spec.limits.maxOutputTokens > 0
                 ? { maxOutputTokens: spec.limits.maxOutputTokens }
                 : {}),
@@ -4400,6 +4414,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             memoryAdmissionWired: deps.memoryScopeAdmission !== undefined,
             retentionPolicyWired: deps.retentionPolicy !== undefined,
             ...(modelGateManifest !== undefined ? { modelGate: modelGateManifest } : {}),
+            autoMode: { armed: autoModeArmReason === "armed", reason: autoModeArmReason },
         });
         peerLaneRefs.askEffective = wiringManifest.ask.effective;
         if (peerLaneActive && internals?.onTaskNotification !== undefined) {

package/dist/core/runner/runtask.js

@@ -2872,6 +2872,8 @@ export class Runner {
                 ...(s.retryInSec !== undefined ? { retryInSec: s.retryInSec } : {}),
                 ...(s.retryInMs !== undefined ? { retryInMs: s.retryInMs } : {}),
                 ...(s.retryAtMs !== undefined ? { retryAtMs: s.retryAtMs } : {}),
+                ...(s.elapsedMs !== undefined ? { elapsedMs: s.elapsedMs } : {}),
+                ...(s.timeoutMs !== undefined ? { timeoutMs: s.timeoutMs } : {}),
                 ...(s.attempt !== undefined ? { attempt: s.attempt } : {}),
                 ...(s.maxRetries !== undefined ? { maxRetries: s.maxRetries } : {}),
                 ...(s.errClass !== undefined ? { errClass: s.errClass } : {}),

package/dist/core/tools.js

@@ -55,6 +55,7 @@ export function defineTool(spec, options) {
         ...(spec.alwaysLoad !== undefined ? { alwaysLoad: spec.alwaysLoad } : {}),
         ...(spec.prepareArguments ? { prepareArguments: spec.prepareArguments } : {}),
         ...(spec.approvalPreview ? { approvalPreview: spec.approvalPreview } : {}),
+        ...(spec.validateInput ? { validateInput: spec.validateInput } : {}),
         execute: async (toolCallId, rawParams, signal) => {
             const params = spec.prepareArguments ? spec.prepareArguments(rawParams) : rawParams;
             if (!Value.Check(spec.parameters, params)) {

package/dist/core/types.d.ts

@@ -1,5 +1,5 @@
 import type { TSchema } from "typebox";
-import type { AgentTool, ThinkingLevel } from "../internal/harness.js";
+import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict } from "../internal/harness.js";
 import type { ActorAssertion, CompleteSimpleFn, DocumentContent, ImageContent, Model, ResilienceOptions, StreamFn, TextContent } from "../internal/llm.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
 /** A model reference: either a fully-formed Model, or a `"provider/id"` ref resolved via a catalog. */
@@ -241,6 +241,24 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     /** approval display projection (see AgentTool.approvalPreview): pure args→display value
      *  for human approval surfaces; clamped + throw-swallowed by the gate; never adjudication input. */
     approvalPreview?: (args: unknown) => unknown;
+    /**
+     * OPTIONAL input pre-validation — runs BEFORE the permission ask (and before every other tool-call
+     * gate station: PreToolUse hooks, policy, the auto-mode classifier), AFTER schema validation. A
+     * refusal (`{ ok: false, message }`) is returned to the model as a typed error result and NO
+     * approval card is shown for the call; `{ ok: true }` / `undefined` lets the call proceed to the
+     * gate unchanged. Upstream form (CC 2.1.250 `validateInput` → `{result:false, message, errorCode}`,
+     * consulted ahead of the permission prompt): a call the tool would refuse on its own precondition —
+     * an Edit/Write/NotebookEdit whose target file was never Read this session — used to reach the
+     * operator as a card that could only ever fail; the model then retried the same failing call under
+     * auto mode until the turn cap. A validator MUST be pure (read tracking state, path grammar; no
+     * side effects, no writes, nothing the run observes) and MUST refuse with the SAME text its
+     * execution would have produced for that input, so the model sees one refusal either way. A
+     * validator that THROWS is read as "no verdict": the call proceeds to the gate and the fault is
+     * disclosed via `RunnerDeps.onError` (phase `"hook"`) — a broken validator must not refuse tools.
+     * The execution-time check stays in place (validate and execute are two reads; a direct
+     * `AgentTool.execute` caller — durable replay — never passes this seat).
+     */
+    validateInput?: (args: unknown, ctx: ToolInputValidationContext) => Promise<ToolInputVerdict | undefined> | ToolInputVerdict | undefined;
     /**
      * [c209-C] Q4 — the model catalog names (`SubagentToolOptions.models` keys), filled by
      * `createSubagentTool` alongside {@link agentListing}. Rendered as the agent_listing INITIAL frame's
@@ -3994,11 +4012,25 @@ export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "c
  * RB-420-c — TERMINAL frames closing a retry sequence. Without them a consumer that rendered a
  * `rate_limited`/`retrying`/`reconnecting` frame has nothing telling it the wait is over, so the
  * warning row stays pinned until the next unrelated event. Exactly one terminal frame is emitted,
- * and only for a call that actually waited: `recovered` = a later attempt served the call,
- * `gave_up` = the retry budget ran out (or the call was cancelled) and a terminal error follows.
+ * and only for a call that actually waited (a retry wait, or a `waiting_first_token` trail —
+ * #530): `recovered` = the call was served after the wait (a later attempt, or the first token
+ * finally arriving), `gave_up` = the retry budget ran out (or the call was cancelled) and a
+ * terminal error follows.
  * Both mean the same thing to a renderer — stop showing the retry state.
  */
- | "recovered" | "gave_up";
+ | "recovered" | "gave_up"
+/**
+ * #530 — the first-token WAIT, before any failure: a first-token watchdog is armed
+ * (`firstTokenTimeoutMs > 0`) and nothing has arrived yet. Emitted once the wait has lasted
+ * `WAITING_FIRST_TOKEN_AFTER_MS` and re-emitted every `WAITING_FIRST_TOKEN_EVERY_MS` while it goes
+ * on, carrying {@link BrainStatus.elapsedMs} and {@link BrainStatus.timeoutMs}; never carries a
+ * retry countdown (`retryInMs`/`retryAtMs` — no wait is being announced, a wait is being
+ * OBSERVED). CLOSED like a retry trail: once a wait frame went out, the call's terminal frame
+ * follows — `recovered` when the call went on to be served (the first token arrived, on this
+ * attempt or a later one), `gave_up` when it failed for good — so a renderer that pinned the row
+ * has its "stop" signal. No frame at all when no watchdog is armed.
+ */
+ | "waiting_first_token";
 /**
  * WHY a retry wait is happening, as a closed, provider-NEUTRAL bucket — the companion to
  * {@link BrainStatusPhase}, which says what the brain is doing about it. A consumer rendering an
@@ -4053,6 +4085,13 @@ export interface BrainStatus {
      * the authoritative RELATIVE quantity, and this seat is the absolute convenience derived from it.
      */
     retryAtMs?: number;
+    /** #530 — on a `waiting_first_token` frame: how long the first token has been awaited, ms, at the
+     *  moment the frame is emitted (the emitting process's clock; approximate across a hop). Absent on
+     *  every other phase. */
+    elapsedMs?: number;
+    /** #530 — on a `waiting_first_token` frame: the armed first-token watchdog, ms — the wait's ceiling,
+     *  so a consumer can render "45s of 120s". Absent on every other phase. */
+    timeoutMs?: number;
     /** RB-420-c — 1-based index of the attempt that just failed (the wait precedes attempt `attempt + 1`);
      *  same numbering as the `brain.retry` telemetry frame. Absent on frames that are not a retry wait. */
     attempt?: number;
@@ -7542,4 +7581,4 @@ export interface RunnerDeps {
      *  3, CC parity). The Runner tracks the consecutive-reuse counter per task across both compaction sites. */
     maxConsecutiveProviderReuse?: number;
 }
-export type { AgentTool, Model, StreamFn, ThinkingLevel };
+export type { AgentTool, Model, StreamFn, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict };

package/dist/core/wiring-manifest.d.ts

@@ -56,6 +56,28 @@ export type QuestionChannelState = "wired" | "absent" | "stripped_bg_lane";
 export type SeamProvenance = "spec" | "deps";
 /** Machine-readable reason codes for a park lane that is not (or not provably) effective. */
 export type ParkLaneReason = "no_checkpoint_store" | "no_durable_approval_opt_in" | "no_force_durable_gate" | "no_armed_safety_vocabulary" | "await_runtime_caps" | "await_tool_vocabulary";
+/**
+ * #529 — the closed set of auto-mode ARMING outcomes a leg's manifest reports
+ * ({@link WiringManifest.autoMode}). Minted from the arming predicate's own three-arm read, as the
+ * FIRST failing arm in predicate order:
+ *  - `no_intent`      — no `TaskSpec.autoModeRequested` seat and no intent inherited on the chain /
+ *                       recorded on the resumed checkpoint (a non-auto run; byte-identical arming).
+ *  - `no_face`        — intent, but no `RunnerDeps.autoMode` deployment face (the trust gate).
+ *  - `denied`         — intent + face, but the organization's deny bit (`RuntimeCaps.autoMode:false`)
+ *                       as the resolver STATED it.
+ *  - `resolver_fault` — intent + face, and the deny bit was COINED by a resolver fault (a throw, or a
+ *                       marshalled/non-record result the value screen refused) — an outage, not a
+ *                       verdict; the same fail-closed outcome as `denied`, named apart so a consumer
+ *                       can tell "policy said no" from "the entitlement source was unreachable".
+ *  - `armed`          — all three arms held; the classifier decider was minted for this leg.
+ *  - `latch_open`     — the session's one-way "back to non-auto" breaker has tripped. A leg-START
+ *                       manifest never carries it (a decider is minted fresh at prepare and its latch
+ *                       is closed by construction; a tripped ancestor hands no intent forward, which
+ *                       reads as `no_intent`); it is in the vocabulary so a consumer switching on the
+ *                       closed set is complete for a mid-leg re-read face, which nothing mints today.
+ */
+export declare const AUTO_MODE_ARM_REASONS: readonly ["armed", "no_intent", "no_face", "denied", "resolver_fault", "latch_open"];
+export type AutoModeArmReason = (typeof AUTO_MODE_ARM_REASONS)[number];
 /**
  * design/173 §2.2/§8.4 — the wiring manifest. Consumers MUST ignore unknown fields
  * (`schemaVersion` bumps only on a semantic break of an EXISTING field). The TaskEvent face is the
@@ -190,6 +212,19 @@ export interface WiringManifest {
         removed: readonly string[];
         restore: string;
     };
+    /**
+     * #529 — EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest (unlike
+     * `modelGate`, which is present only when a trim happened: auto mode has an answer on every leg,
+     * so absence here means an older mint or an external derivation, never "not applicable"). The
+     * per-leg READ face of the auto-mode arming decision: `armed` ⇔ `reason === "armed"` (the
+     * classifier decider was minted for this leg), and `reason` names the first arm that failed
+     * otherwise — see {@link AUTO_MODE_ARM_REASONS}. A serving layer that used to infer the mode from
+     * spec shape reads it here instead.
+     */
+    autoMode?: {
+        armed: boolean;
+        reason: AutoModeArmReason;
+    };
     /** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
      *  JSON of this manifest's own resolved facts; every field here is an enum/boolean/count, no
      *  secrets) so an operator can correlate legs that ran under the same resolved assembly. */
@@ -252,6 +287,12 @@ export interface WiringFacts {
         removed: readonly string[];
         restore: string;
     };
+    /** Effective half only — see {@link WiringManifest.autoMode}; the static half has no leg to arm.
+     *  `armed` must agree with `reason` (`armed ⇔ reason === "armed"`); a contradicting pair is refused. */
+    autoMode?: {
+        armed: boolean;
+        reason: AutoModeArmReason;
+    };
 }
 /** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
  *  single-source shapes, no parallel hand-copied interface). */
@@ -313,11 +354,6 @@ export declare function resolveSubagentTranscriptTier(agentStoreWired: boolean,
  *    else the headless degrade `auto_deny`.
  */
 export declare function deriveAskEffective(form: AskSeamForm, parkEffective: boolean | "unresolved"): AskEffective;
-/**
- * design/173 §2.1 — the SINGLE derivation from facts to manifest, shared by both halves. The static
- * half omits `ask.effective`, `leg` and the fingerprint; the effective half carries all three. Any
- * second construction point for {@link WiringManifest} is a defect (single-mint rule).
- */
 export declare function deriveWiringManifest(facts: WiringFacts): WiringManifest;
 /** The one ask-seat resolution (`spec` wins over `deps`), shared with the effective half so the
  *  form/provenance read cannot fork. Junk values (a JS caller passing something outside the OnAsk

package/dist/core/wiring-manifest.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { canonicalize } from "./canonical-json.js";
 import { resolveCheckpointStore } from "./checkpoint-store.js";
 import { isLiveQuestionFace } from "./ask-question.js";
+export const AUTO_MODE_ARM_REASONS = ["armed", "no_intent", "no_face", "denied", "resolver_fault", "latch_open"];
 export function resolveDeclaredDurability(store, storeName) {
     const declared = store?.durability;
     if (declared === undefined)
@@ -66,6 +67,12 @@ function deriveParkLane(facts) {
         reasons.push("no_armed_safety_vocabulary");
     return { capable: true, effective: unresolved ? "unresolved" : false, reasons, ...durability };
 }
+function readAutoModeFact(fact) {
+    if (!AUTO_MODE_ARM_REASONS.includes(fact.reason) || fact.armed !== (fact.reason === "armed")) {
+        throw new Error(`the auto-mode wiring fact is inconsistent (armed=${String(fact.armed)}, reason=${JSON.stringify(fact.reason)}) — armed must hold exactly when reason is "armed", and reason must be one of ${AUTO_MODE_ARM_REASONS.join("|")}`);
+    }
+    return { armed: fact.armed, reason: fact.reason };
+}
 export function deriveWiringManifest(facts) {
     if (facts.half === "static" && facts.leg !== undefined) {
         throw new Error("a static wiring manifest has no leg — leg identity is an effective-half fact");
@@ -118,6 +125,7 @@ export function deriveWiringManifest(facts) {
             retention: facts.retentionPolicyWired,
         },
         ...(facts.half === "effective" && facts.modelGate !== undefined ? { modelGate: { class: facts.modelGate.class, removed: [...facts.modelGate.removed], restore: facts.modelGate.restore } } : {}),
+        ...(facts.half === "effective" && facts.autoMode !== undefined ? { autoMode: readAutoModeFact(facts.autoMode) } : {}),
     };
     if (facts.half === "effective") {
         const { leg: _leg, ...assembly } = manifest;

package/dist/engine/harness/agent-harness.d.ts

@@ -203,6 +203,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private stallTimeoutsPerCall?;
     private abortResultDetails?;
     private loopTrace?;
+    private onToolInputValidationFault?;
     private resilience?;
     private maxToolConcurrency?;
     private streamingToolExecution?;

package/dist/engine/harness/agent-harness.js

@@ -252,6 +252,7 @@ export class AgentHarness {
     stallTimeoutsPerCall;
     abortResultDetails;
     loopTrace;
+    onToolInputValidationFault;
     resilience;
     maxToolConcurrency;
     streamingToolExecution;
@@ -285,6 +286,7 @@ export class AgentHarness {
         this.stallTimeoutsPerCall = options.stallTimeoutsPerCall;
         this.abortResultDetails = options.abortResultDetails;
         this.loopTrace = options.loopTrace;
+        this.onToolInputValidationFault = options.onToolInputValidationFault;
         this.resilience = options.resilience;
         this.maxToolConcurrency = options.maxToolConcurrency;
         this.streamingToolExecution = options.streamingToolExecution;
@@ -577,6 +579,7 @@ export class AgentHarness {
             ...(this.maxOutputTokensPerCall !== undefined ? { maxTokensPerCall: this.maxOutputTokensPerCall } : {}),
             ...(this.stallTimeoutsPerCall !== undefined ? { stallTimeoutsPerCall: this.stallTimeoutsPerCall } : {}),
             ...(this.abortResultDetails !== undefined ? { abortResultDetails: this.abortResultDetails } : {}),
+            ...(this.onToolInputValidationFault !== undefined ? { onToolInputValidationFault: this.onToolInputValidationFault } : {}),
             ...(this.resilience !== undefined ? { resilience: this.resilience } : {}),
             ...(this.maxToolConcurrency !== undefined ? { maxToolConcurrency: this.maxToolConcurrency } : {}),
             ...(this.streamingToolExecution === true && (this.getHandlers("tool_call")?.size ?? 0) === 0

package/dist/engine/harness/types.d.ts

@@ -1367,6 +1367,9 @@ export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTempla
      * recoveries were invisible outside display:false nudge messages). Must not throw; hot path.
      */
     loopTrace?: (step: import("../loop/agent-loop.js").LoopStep) => void;
+    /** Loop-config pass-through — see `AgentLoopConfig.onToolInputValidationFault` (a throwing
+     *  `AgentTool.validateInput` is read as no verdict and disclosed here). */
+    onToolInputValidationFault?: import("../loop/types.js").AgentLoopConfig["onToolInputValidationFault"];
     /**
      * design/131 (拍): per-task resilience intent flags, forwarded to every provider
      * call (`StreamOptions.resilience`) so the deployment's decorator stack (degrading / failover /

package/dist/engine/loop/agent-loop.d.ts

@@ -103,3 +103,10 @@ export declare const ROSTER_LISTING_MAX = 25;
  * core/tool-errors.ts, same reason).
  */
 export declare const ROSTER_SEARCH_HINT_NAME = "ToolSearch";
+/** The structured `details.code` of a tool result minted by an input pre-validation refusal (lifted onto
+ *  the wire frame's `errorCode` like every other loop-minted code, e.g. `tool.not_found`). */
+export declare const TOOL_VALIDATION_REFUSED_CODE = "tool.validation_refused";
+/** How long an asynchronous `validateInput` may take to answer before it is read as "no verdict" (and
+ *  reported on the fault seat): a validator is a precondition read, not a network call, so a single
+ *  bound serves every tool; a deployment validator that needs longer is a validator doing too much. */
+export declare const TOOL_INPUT_VALIDATION_TIMEOUT_MS = 10000;

package/dist/engine/loop/agent-loop.js

@@ -1122,6 +1122,76 @@ function formatRosterRecovery(availableTools) {
         : "";
     return ` Available tools: ${listing}${hint}`;
 }
+export const TOOL_VALIDATION_REFUSED_CODE = "tool.validation_refused";
+export const TOOL_INPUT_VALIDATION_TIMEOUT_MS = 10_000;
+async function runInputValidation(tool, args, toolCallId, signal, onFault) {
+    if (tool.validateInput === undefined)
+        return undefined;
+    try {
+        const verdict = await boundedValidatorCall(() => tool.validateInput(args, signal !== undefined ? { toolCallId, signal } : { toolCallId }), signal);
+        if (verdict !== null && typeof verdict === "object" && verdict.ok === false && typeof verdict.message === "string") {
+            return typeof verdict.code === "string" ? { message: verdict.message, code: verdict.code } : { message: verdict.message };
+        }
+        return undefined;
+    }
+    catch (error) {
+        if (signal?.aborted === true)
+            return undefined;
+        try {
+            const ret = onFault?.({ toolName: tool.name, toolCallId, error });
+            if (ret !== null && typeof ret === "object" && typeof ret.then === "function") {
+                ret.then(undefined, () => undefined);
+            }
+        }
+        catch {
+        }
+        return undefined;
+    }
+}
+function boundedValidatorCall(call, signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            fn();
+        };
+        const onAbort = () => finish(() => reject(Object.assign(new Error("tool input pre-validation aborted"), { name: "AbortError" })));
+        const timer = setTimeout(() => finish(() => reject(new Error(`tool input pre-validation did not answer within ${TOOL_INPUT_VALIDATION_TIMEOUT_MS}ms`))), TOOL_INPUT_VALIDATION_TIMEOUT_MS);
+        if (signal?.aborted === true) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+        let out;
+        try {
+            out = call();
+        }
+        catch (err) {
+            finish(() => reject(err));
+            return;
+        }
+        Promise.resolve(out).then((v) => finish(() => resolve(v)), (err) => finish(() => reject(err)));
+    });
+}
+function sameToolArgs(a, b) {
+    if (a === b)
+        return true;
+    const canon = (v) => JSON.stringify(v, (_k, x) => (x !== null && typeof x === "object" && !Array.isArray(x) ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, x[k]])) : x));
+    return canon(a) === canon(b);
+}
+function validationRefusedOutcome(tool, refusal) {
+    return {
+        kind: "immediate",
+        result: createErrorToolResult(refusal.message, {
+            details: { code: TOOL_VALIDATION_REFUSED_CODE, toolName: tool.name, ...(refusal.code !== undefined ? { reason: refusal.code } : {}) },
+        }),
+        isError: true,
+    };
+}
 async function prepareToolCall(currentContext, assistantMessage, toolCall, config, signal) {
     const tool = findToolByName(currentContext.tools, toolCall.name);
     if (!tool) {
@@ -1135,6 +1205,10 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
     try {
         const preparedToolCall = prepareToolCallArguments(tool, toolCall);
         let finalArgs = validateToolArguments(tool, preparedToolCall);
+        const refusal = await runInputValidation(tool, finalArgs, toolCall.id, signal, config.onToolInputValidationFault);
+        if (refusal !== undefined)
+            return validationRefusedOutcome(tool, refusal);
+        const validatedArgs = finalArgs;
         if (config.beforeToolCall) {
             const beforeResult = await config.beforeToolCall({
                 assistantMessage,
@@ -1161,6 +1235,11 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
                     ...preparedToolCall,
                     arguments: beforeResult.updatedInput,
                 });
+                if (!sameToolArgs(validatedArgs, finalArgs)) {
+                    const rewrittenRefusal = await runInputValidation(tool, finalArgs, toolCall.id, signal, config.onToolInputValidationFault);
+                    if (rewrittenRefusal !== undefined)
+                        return validationRefusedOutcome(tool, rewrittenRefusal);
+                }
             }
         }
         if (signal?.aborted) {

package/dist/engine/loop/types.d.ts

@@ -19,6 +19,26 @@ export type StreamFn = LlmStreamFn;
  *   while tool-result message artifacts are emitted later in assistant source order.
  */
 export type ToolExecutionMode = "sequential" | "parallel";
+/**
+ * The verdict a tool's INPUT PRE-VALIDATION returns (see {@link AgentTool.validateInput}). `ok: true`
+ * (or an `undefined` return) lets the call proceed to the gate; `ok: false` refuses it BEFORE any
+ * permission question is asked — `message` is the model-facing text (the same text the tool's own
+ * execution would have produced for the same input, so the refusal reads identically either way) and
+ * `code` an optional machine-readable reason that rides the error result's structured details.
+ */
+export type ToolInputVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    code?: string;
+};
+/** The context an input pre-validation hook receives: the call's identity and its abort signal, and
+ *  nothing else — a validator reads state, it does not act on the run. */
+export interface ToolInputValidationContext {
+    toolCallId: string;
+    signal?: AbortSignal;
+}
 /**
  * Controls how many queued user messages are injected when the agent loop reaches a queue drain point.
  *
@@ -527,6 +547,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * signal re-check, which has always minted its abort result with no details.
      */
     abortResultDetails?: () => Record<string, unknown> | undefined;
+    /**
+     * Fault seat for a THROWING {@link AgentTool.validateInput}: the loop reads the throw as "no
+     * verdict" (the call proceeds to the gate as if the tool had no validator) and reports the fault
+     * here so a host can disclose it. Must not throw; a throwing sink is swallowed.
+     */
+    onToolInputValidationFault?: (info: {
+        toolName: string;
+        toolCallId: string;
+        error: unknown;
+    }) => void;
     /**
      * Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.
      *
@@ -684,6 +714,18 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      *  (boundInputHash binds args, never the preview). NEVER adjudication input. Mechanism-neutral:
      *  any tool may declare one (run_workflow projects its script meta). */
     approvalPreview?: (args: unknown) => unknown;
+    /**
+     * OPTIONAL input pre-validation, run by the loop AFTER schema validation and BEFORE the tool-call
+     * gate (permission hooks, policy, the human/classifier ask). A refusal is returned to the model as a
+     * typed error result and no question is ever asked for the call — the point of the seat: a call the
+     * tool would refuse on its own precondition (a file edit whose target was never read this session)
+     * must not cost the operator an approval card it can only ever fail on. Pure by contract: reads
+     * state (read-tracking, path grammar), never acts. A THROWING validator is read as "no verdict"
+     * (the call proceeds to the gate; the fault is disclosed through the loop's fault seat) — a broken
+     * validator must not refuse tools. The tool's own execution keeps validating the same precondition
+     * (the two reads are not one atomic step, and direct `execute` callers skip this seat).
+     */
+    validateInput?: (args: Static<TParameters>, ctx: ToolInputValidationContext) => Promise<ToolInputVerdict | undefined> | ToolInputVerdict | undefined;
     /** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
     execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
     /**

package/dist/index.d.ts

@@ -119,7 +119,7 @@ export { createFsWriteGatePolicy, type FsWriteGatePolicyOptions } from "./core/f
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, type TaskNotificationPayload, type TaskNotificationStatus, type ExternalNotificationInput, type SystemInjection, type SystemInjectionPriority, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, type SemaProvenance, } from "./core/task-notification.js";
-export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, type SubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, type WiringManifest, type WiringFacts, type WiringLegKind, type AskSeamForm, type AskEffective, type QuestionChannelState, type SeamProvenance, type ParkLaneReason, type ManifestDurability, type StaticWiringDeps, type StaticWiringSpec, } from "./core/wiring-manifest.js";
+export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, type SubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, AUTO_MODE_ARM_REASONS, type AutoModeArmReason, type WiringManifest, type WiringFacts, type WiringLegKind, type AskSeamForm, type AskEffective, type QuestionChannelState, type SeamProvenance, type ParkLaneReason, type ManifestDurability, type StaticWiringDeps, type StaticWiringSpec, } from "./core/wiring-manifest.js";
 export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK_SCOPE_PREFIX, type ParkSelfCheckResult, type ParkProbeFinding, type ParkProbeFindingCode, } from "./core/park-selfcheck.js";
 export { type StoreDurability } from "./core/checkpoint-store.js";
 export { type StoreFidelity } from "./core/checkpoint-store.js";
@@ -277,13 +277,14 @@ export { repairTextToolCalls } from "./brain/tool-call-repair.js";
 export { createCircuitBreakerBrain, type CircuitBreakerOptions, type BreakerState, type BreakerSnapshot, type BreakerPhase, CIRCUIT_OPEN_MARKER, } from "./brain/circuit-breaker.js";
 export { createDegradingBrain, readDegradation, DEGRADED_DIAGNOSTIC_TYPE, type DegradingBrainOptions, type DegradeReason, type DegradationInfo, } from "./brain/degrading.js";
 export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
+export { WAITING_FIRST_TOKEN_AFTER_MS, WAITING_FIRST_TOKEN_EVERY_MS } from "./brain/stream-engine.js";
 export { adjudicateModelRoute, resolveRouteCredential, routeRefusalText, routePairingStatus, normalizeBaseUrl, hasAuthCarrier, type RoutePairingStatus, } from "./brain/route-adjudicator.js";
 export type { RouteAdjudication, RouteCredential, RouteCredentialSource, RoutePairingConfig, RoutePairingPosture, RouteRefusalCode, RouteRefusalDetail, } from "./internal/llm.js";
 export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } from "./brain/route-conformance.js";
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";

package/dist/index.js

@@ -96,7 +96,7 @@ export { createFsWriteGatePolicy } from "./core/fs-write-gate-policy.js";
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, } from "./core/task-notification.js";
-export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, } from "./core/wiring-manifest.js";
+export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, AUTO_MODE_ARM_REASONS, } from "./core/wiring-manifest.js";
 export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK_SCOPE_PREFIX, } from "./core/park-selfcheck.js";
 export {} from "./core/checkpoint-store.js";
 export {} from "./core/checkpoint-store.js";
@@ -234,6 +234,7 @@ export { repairTextToolCalls } from "./brain/tool-call-repair.js";
 export { createCircuitBreakerBrain, CIRCUIT_OPEN_MARKER, } from "./brain/circuit-breaker.js";
 export { createDegradingBrain, readDegradation, DEGRADED_DIAGNOSTIC_TYPE, } from "./brain/degrading.js";
 export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
+export { WAITING_FIRST_TOKEN_AFTER_MS, WAITING_FIRST_TOKEN_EVERY_MS } from "./brain/stream-engine.js";
 export { adjudicateModelRoute, resolveRouteCredential, routeRefusalText, routePairingStatus, normalizeBaseUrl, hasAuthCarrier, } from "./brain/route-adjudicator.js";
 export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS } from "./brain/route-conformance.js";
 export {} from "./brain/timeout.js";

package/dist/internal/harness-types.d.ts

@@ -7,7 +7,7 @@
 export type { CompactionPreparation, SummarizationClampDryRun } from "../engine/compaction/compaction.js";
 export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
 export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";
-export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, } from "../engine/loop/types.js";
+export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, ToolInputValidationContext, ToolInputVerdict, } from "../engine/loop/types.js";
 export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
 export type { ExecutionEnvExecOptions, ExecResult } from "../engine/harness/types.js";
 export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/types.js";

package/dist/tools/fs/fs-write.js

@@ -83,6 +83,35 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             replace_all: Type.Optional(Type.Boolean({ description: "Replace all occurrences of old_string (default false)" })),
         }),
         effect: "write",
+        validateInput: async (args, ctx) => {
+            const a = args;
+            if (Array.isArray(a.edits) && a.edits.length > 0)
+                return { ok: true };
+            if (typeof a.old_string !== "string" || typeof a.new_string !== "string")
+                return { ok: true };
+            const path = fileArgPath(args);
+            if (path === undefined)
+                return { ok: true };
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            if (!r.ok)
+                return { ok: true };
+            if (a.old_string === a.new_string)
+                return { ok: true };
+            const exists = await env.exists(r.key, ctx.signal);
+            if (!exists.ok || !exists.value)
+                return { ok: true };
+            const editInfo = await env.fileInfo(r.key, ctx.signal);
+            if (editInfo.ok && editInfo.value.size > MAX_EDIT_BYTES)
+                return { ok: true };
+            if (a.old_string === "")
+                return { ok: true };
+            if (ipynbRedirect("Edit", path))
+                return { ok: true };
+            const notRead = requireRead(state, r.key);
+            if (notRead === undefined)
+                return { ok: true };
+            return { ok: false, code: notRead.code, message: await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT) };
+        },
         execute: async (args, ctx) => {
             const a = args;
             const batch = Array.isArray(a.edits) && a.edits.length > 0;
@@ -290,6 +319,23 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             content: Type.String({ description: "The content to write to the file" }),
         }),
         effect: "write",
+        validateInput: async (args, ctx) => {
+            const path = fileArgPath(args);
+            if (path === undefined)
+                return { ok: true };
+            if (ipynbRedirect("Write", path))
+                return { ok: true };
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            if (!r.ok)
+                return { ok: true };
+            const exists = await env.exists(r.key, ctx.signal);
+            if (!exists.ok || !exists.value)
+                return { ok: true };
+            const notRead = requireRead(state, r.key);
+            if (notRead === undefined)
+                return { ok: true };
+            return { ok: false, code: notRead.code, message: await notReadRefusalText(env, "Write", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT) };
+        },
         execute: async (args, ctx) => {
             const { content } = args;
             const path = fileArgPath(args);
@@ -356,6 +402,9 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
         },
     });
 }
+const notebookNotIpynbMessage = (notebookPath) => `Error (NotebookEdit): "${notebookPath}" is not a .ipynb file; use Edit for other file types.`;
+const NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE = `Error (NotebookEdit): Cell type is required when using edit_mode=insert.`;
+const NOTEBOOK_CELL_ID_REQUIRED_MESSAGE = `Error (NotebookEdit): cell_id is required for replace/delete.`;
 export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit) {
     return defineTool({
         name: "NotebookEdit",
@@ -382,18 +431,35 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
             })),
         }),
         effect: "write",
+        validateInput: async (args, ctx) => {
+            const a = args;
+            const mode = a.edit_mode ?? "replace";
+            if (!a.notebook_path.toLowerCase().endsWith(".ipynb"))
+                return { ok: false, code: "invalid", message: notebookNotIpynbMessage(a.notebook_path) };
+            if (mode === "insert" && !a.cell_type)
+                return { ok: false, code: "invalid", message: NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE };
+            if (mode !== "insert" && !a.cell_id)
+                return { ok: false, code: "invalid", message: NOTEBOOK_CELL_ID_REQUIRED_MESSAGE };
+            const r = await resolveKey(env, rootCanonical, a.notebook_path, ctx.signal, cwdRef?.current, additionalRoots);
+            if (!r.ok)
+                return { ok: true };
+            const notRead = requireRead(state, r.key);
+            if (notRead === undefined)
+                return { ok: true };
+            return { ok: false, code: notRead.code, message: await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT) };
+        },
         execute: async (args, ctx) => {
             const a = args;
             const { notebook_path, cell_id, new_source } = a;
             let cellType = a.cell_type;
             const mode = a.edit_mode ?? "replace";
             if (!notebook_path.toLowerCase().endsWith(".ipynb")) {
-                return errorResult(`Error (NotebookEdit): "${notebook_path}" is not a .ipynb file; use Edit for other file types.`);
+                return errorResult(notebookNotIpynbMessage(notebook_path));
             }
             if (mode === "insert" && !cellType)
-                return errorResult(`Error (NotebookEdit): Cell type is required when using edit_mode=insert.`);
+                return errorResult(NOTEBOOK_CELL_TYPE_REQUIRED_MESSAGE);
             if (mode !== "insert" && !cell_id)
-                return errorResult(`Error (NotebookEdit): cell_id is required for replace/delete.`);
+                return errorResult(NOTEBOOK_CELL_ID_REQUIRED_MESSAGE);
             const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
                 return errorResult(violationText("NotebookEdit", r.violation), violationDetails(r.violation));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.3.0",
+  "version": "7.3.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 1958,
+  "count": 1964,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -30,6 +30,7 @@
     "AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT": "variable",
     "AUTONOMOUS_LOOP_SENTINEL": "variable",
     "AUTO_MODE_ARMING_RECIPE_VERSION": "variable",
+    "AUTO_MODE_ARM_REASONS": "variable",
     "AUTO_MODE_BASE_PROMPT": "variable",
     "AUTO_MODE_DEFAULTS_SENTINEL": "variable",
     "AUTO_MODE_PERMISSIONS_EXTERNAL": "variable",
@@ -78,6 +79,7 @@
     "AssertOracleIsolationOptions": "interface",
     "AssistantMessage": "interface",
     "AssistantMessageEvent": "type",
+    "AutoModeArmReason": "type",
     "AutoModeArmingFace": "interface",
     "AutoModeArmingFold": "type",
     "AutoModeArmingRecipe": "interface",
@@ -1199,6 +1201,8 @@
     "ToolEffect": "type",
     "ToolExecuteContext": "interface",
     "ToolFingerprintInput": "interface",
+    "ToolInputValidationContext": "interface",
+    "ToolInputVerdict": "type",
     "ToolModelGateRule": "interface",
     "ToolOrigin": "type",
     "ToolPolicy": "interface",
@@ -1251,6 +1255,8 @@
     "VerificationResult": "interface",
     "VerifyConfig": "interface",
     "VmLifecycleOptions": "interface",
+    "WAITING_FIRST_TOKEN_AFTER_MS": "variable",
+    "WAITING_FIRST_TOKEN_EVERY_MS": "variable",
     "WEBFETCH_SUMMARY_GUIDELINES": "variable",
     "WEBFETCH_SUMMARY_MAX_CONTENT": "variable",
     "WEB_FETCH_TOOL_NAME": "variable",
@@ -1990,6 +1996,7 @@
     "AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT": "advanced",
     "AUTONOMOUS_LOOP_SENTINEL": "advanced",
     "AUTO_MODE_ARMING_RECIPE_VERSION": "advanced",
+    "AUTO_MODE_ARM_REASONS": "advanced",
     "AUTO_MODE_BASE_PROMPT": "advanced",
     "AUTO_MODE_DEFAULTS_SENTINEL": "advanced",
     "AUTO_MODE_PERMISSIONS_EXTERNAL": "advanced",
@@ -2038,6 +2045,7 @@
     "AssertOracleIsolationOptions": "advanced",
     "AssistantMessage": "stable",
     "AssistantMessageEvent": "stable",
+    "AutoModeArmReason": "advanced",
     "AutoModeArmingFace": "advanced",
     "AutoModeArmingFold": "advanced",
     "AutoModeArmingRecipe": "advanced",
@@ -3159,6 +3167,8 @@
     "ToolEffect": "advanced",
     "ToolExecuteContext": "advanced",
     "ToolFingerprintInput": "advanced",
+    "ToolInputValidationContext": "internal",
+    "ToolInputVerdict": "internal",
     "ToolModelGateRule": "advanced",
     "ToolOrigin": "advanced",
     "ToolPolicy": "stable",
@@ -3211,6 +3221,8 @@
     "VerificationResult": "advanced",
     "VerifyConfig": "advanced",
     "VmLifecycleOptions": "advanced",
+    "WAITING_FIRST_TOKEN_AFTER_MS": "advanced",
+    "WAITING_FIRST_TOKEN_EVERY_MS": "advanced",
     "WEBFETCH_SUMMARY_GUIDELINES": "advanced",
     "WEBFETCH_SUMMARY_MAX_CONTENT": "advanced",
     "WEB_FETCH_TOOL_NAME": "advanced",