@sema-agent/core 7.3.0 → 7.4.0

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
@@ -715,6 +733,32 @@ export interface ToolExecuteContext {
      * the tool runs outside a Runner task.
      */
     parentCwd?: string;
+    /**
+     * The RUNNING task's file-history LINEAGE (Runner-filled, read-only, never a model/tool argument;
+     * present iff a `RunnerDeps.fileHistoryStore` is live for the run): the history scope this run
+     * records its first-touch edits into and the TREE those records' keys are minted against — the
+     * canonical root spelling plus the env's filesystem identity (`fs`: a remote workspace's handle,
+     * `"host"` for the control-plane host's filesystem, else a per-env-instance token).
+     *
+     * WHICH children are threaded it, exactly: the Agent tool's FRESH spawn legs (sync / steer /
+     * background / fork) pass it VERBATIM into the child's trusted internals
+     * (`RunInternals.fileHistoryLineage`), which is how a same-process delegation tree keeps ONE
+     * history: a child on the SAME tree (both coordinates equal) records into the lineage's scope (the
+     * root session's), so the root session's `rewindFilesTo` reaches the child's edits; a child on a
+     * different tree (worktree isolation, an explicit `cwd`, a fresh per-task sandbox) starts its own
+     * lineage, because root-relative keys re-joined against a different tree would name files that run
+     * never edited. Three delegated legs deliberately carry NO lineage and keep their own scope: the
+     * Agent tool's REVIVE arm (a revival's lineage would be the REVIVER's tree, which says nothing
+     * about the revived row's), and the workflow / team orchestration spawn legs (`run_workflow`,
+     * `runTeamDiscussion` — they build their children's internals without this seat). Edits made by
+     * those children are therefore NOT reachable from the root session's rewind, and a restore request
+     * on one of them is not refused either — it converges that child's own scope.
+     */
+    fileHistoryLineage?: {
+        scope: string;
+        root: string;
+        fs: string;
+    };
     /**
      * design/319 (A ticket) — the RUNNING task's reminder provenance mark, Runner-filled, read-only,
      * NEVER a model/tool argument. The Agent tool's FORK route threads it into the forked child's
@@ -1281,6 +1325,35 @@ export type TrackEditResult = {
     refusal: string;
 };
 export type TrackFileEditHook = (req: TrackEditRequest) => Promise<TrackEditResult>;
+/**
+ * The hands band's MUTATION-EDITED observation seat — the counterpart of {@link TrackEditRequest},
+ * fired at the other end of the same lane. Called once per Write/Edit/NotebookEdit call whose FINAL
+ * env write did not PROVABLY write nothing, at the single point every mutation lane funnels through,
+ * under the same three-valued law as the first-touch record's own retraction:
+ *  - a call the argument checks, the read-before-edit gate, the write gate or the first-touch
+ *    history seat refused never fires it (nothing was written);
+ *  - a call whose write FAILED with a code whose contract says nothing was written never fires it;
+ *  - a call whose write failed AMBIGUOUSLY (a non-atomic env that truncated and then errored) or
+ *    THREW fires it — exactly the arm where the retraction KEEPS the first-touch record because the
+ *    file may really have changed. The two seats agree on purpose: a file whose baseline was kept
+ *    for a possible modification must also be listed as possibly modified;
+ *  - a `Bash` command that changed a file never fires it: bash does not run through this band's
+ *    write lanes at all, which is the whole reason this seat is not a tool-name table.
+ * PURE OBSERVATION: it returns nothing and it cannot refuse. A FAULT in it is contained in both
+ * shapes an observer can fail in — a synchronous throw, and (the return type is `void`, but an
+ * `async` function still type-checks there) a rejected promise, which is sunk rather than left
+ * unhandled. Neither is awaited: an observer must never turn a landed write into a failed tool
+ * answer, nor delay one.
+ */
+export interface FileEditedNotice {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument — the SAME coordinate the delegated-child projection's
+     *  `SubagentEditedFile.path` carries, so the two seats can be read side by side. */
+    path: string;
+    /** The resolved canonical containment key the bytes actually landed on. */
+    key: string;
+}
+export type FileEditedHook = (notice: FileEditedNotice) => void;
 /**
  * design/141 件2 — the SAFE deployment-configurable subset of the hands toolkit ({@link RunnerDeps.hands}).
  * Only fields whose injection is purely additive for a deployment are here; Runner-internal orchestration
@@ -2112,6 +2185,15 @@ export interface TaskSpec {
      * target with no history boundary fails loud (`rewind_snapshot.unresolvable`). Requires
      * `RunnerDeps.fileHistoryStore`. The session leaf is untouched — the next turn continues the
      * CURRENT conversation, only the files moved.
+     *
+     * A same-process child THE AGENT TOOL SPAWNED FRESH (the legs that are handed a lineage — see
+     * `ToolExecuteContext.fileHistoryLineage` for the exact set, and for the legs that are not) which
+     * shares its root session's tree records its edits into the ROOT session's history, so a rewind
+     * that should cover those edits is the root session's action; a restore request on such a child run
+     * is refused loud (`rewind.child_scope_unsupported`) rather than converging a scope that holds none
+     * of its edits. A delegated child that was handed NO lineage — a revival, a workflow/team member —
+     * keeps its own scope: its edits are outside this target's reach, and its own restore request is an
+     * ordinary one.
      */
     rewindFilesTo?: string;
     /**
@@ -3514,7 +3596,7 @@ export interface TaskResult {
      * ignores the field is unchanged. A rewind that could NOT be delivered as asked is NOT a note — it is a
      * terminal failure (`rewind_snapshot.unresolvable` / `rewind.store_unconfigured` /
      * `rewind.restore_failed` / `rewind.invalid_spec` / `rewind.rewind_files_retired` /
-     * `rewind.conflicting_targets`).
+     * `rewind.conflicting_targets` / `rewind.child_scope_unsupported`).
      *
      * - `conversation_only` — {@link TaskSpec.resumeAt} branched the transcript WITHOUT
      *   {@link TaskSpec.restoreFiles}, so the working tree was deliberately left where it was (CC's
@@ -3537,6 +3619,56 @@ export interface TaskResult {
         /** Human-readable statement of what did NOT happen and why — safe to show a user verbatim. */
         message: string;
     }>;
+    /**
+     * The files THIS RUN's hands actually mutated, with how many times each — the same
+     * `{path, edits}` shape the delegated-child projection publishes as
+     * {@link import("../agents/subagent-steps.js").SubagentEditedFile}, so a host can read the two
+     * seats side by side. A run is one host-side user message, which is the granularity a
+     * "restore the code this message changed" affordance needs; the per-model-turn beat
+     * (`turn_end`) deliberately has no such seat.
+     *
+     * **Source**: the hands band's own mutation lane. One entry is bumped when a `Write`/`Edit`/
+     * `NotebookEdit` call's FINAL env write returns success — not when a tool call starts, not from a
+     * tool-name table over the event stream. The consequences are the contract:
+     *  - a refused, gated or FAILED write is not counted (a write whose bytes never landed is not an
+     *    edit — the same lane point that retracts its first-touch history record);
+     *  - a `Bash` command that changed a file is not counted: it does not go through those lanes.
+     *    This matches the reference implementation's own trigger set;
+     *  - one tool CALL counts once, so a batch `Edit` (multiple `edits[]` against one file in one
+     *    call) is one edit here, exactly as the child projection counts it.
+     *
+     * **`path` form**: the model-supplied path argument, verbatim — the same coordinate
+     * `SubagentEditedFile.path` uses, deliberately not the canonical containment key, so both seats
+     * spell a file the way the transcript does. IDENTITY, however, is the canonical FILE, not the
+     * spelling: a relative argument resolves against the run's LIVE cwd, so one spelling can name two
+     * different files across a `cd` (two entries, each showing that spelling) and two spellings can
+     * name one file (ONE entry, showing the first spelling that reached it). Insertion order = order
+     * of first edit.
+     *
+     * **Three-valued on the failure edge, upper bound never lower**: a write failure is three-valued.
+     * A failure whose error code's contract states nothing was written is a proven no-op and is NOT
+     * counted. An AMBIGUOUS failure or a thrown write IS counted: an `ExecutionEnv` whose write is not
+     * atomic can truncate a file and then report an error, that file may really have changed, and the
+     * first-touch history record for it is kept for exactly that reason — so this list names it too,
+     * and a `rewindFilesTo` will restore it. (The reference env replaces whole files by stage+rename —
+     * fully old or fully new — so this edge belongs to its in-place fallback arms and to third-party
+     * envs.) A host therefore reads this list as "files that may differ from before this run", never
+     * as "writes the model saw succeed"; the tool answers carry that.
+     *
+     * **In-presence condition**: present iff this run's hands landed ≥1 such write — zero edits means
+     * the key is ABSENT, never an empty array. It does NOT depend on whether a
+     * `RunnerDeps.fileHistoryStore` is wired: this is an observation of what this run did, not a
+     * durable history, and a deployment with no history store still gets it (what a store adds is the
+     * ability to REWIND, not the ability to say what changed). It covers this run's OWN band only — a
+     * delegated child's writes ride the child's own result and the delegation projection, not this
+     * key.
+     *
+     * **Bound**: at most 1000 distinct files. Past that, already-listed files keep counting and new
+     * ones are not added — a result seat cannot be unbounded, and a single user message reaching a
+     * thousand distinct files is already outside what this observation is for. A consumer that must
+     * know whether it is reading a saturated list can compare the length against that ceiling.
+     */
+    editedFiles?: import("../agents/subagent-steps.js").SubagentEditedFile[];
     /**
      * Present (`true`) exactly when the run's FINAL turn was halted by a person's BARE rejection of a
      * tool call — the parent-thread control-flow boundary: the rejected call's same-message siblings
@@ -3994,11 +4126,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 +4199,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;
@@ -5915,6 +6068,20 @@ export interface EngineNotice {
      *    (whoever answered the card is the one entitled to hear the answer ran nothing); a host may
      *    forward it on its own wire.
      *
+     *  - `"classifier.denial_limit"` (#548, CC 2.1.250 `FO`/"too many classifier denials in headless
+     *    mode") — the auto-mode classifier's DENIAL LIMIT was reached (3 consecutive blocks, or 20 in the
+     *    run; `RunnerDeps.autoMode.denialLimit`) and the fallback ask it turns into had NO approver to go
+     *    to: none wired, a blanket `onAsk:"allow"` (refused for a real-approval ask), or an approver that
+     *    reported unavailable with no durable park to take it. The run was STOPPED — `TaskResult.status`
+     *    `"failed"`, `errorCode` the same code, `errorMessage` the limit sentence — rather than kept
+     *    spending on a model the classifier denies without end; the triggering call's own result is the
+     *    deny that stood. Once per run (the first headless fallback owns the terminal);
+     *    `detail: { sessionId, runId, toolName, toolCallId, consecutive, total, limit }` — `limit` is
+     *    `"consecutive"` | `"total"`, the bound that tripped. Audience `"user"` (the person whose run
+     *    ended is the one entitled to hear why, and to review the transcript the sentence points at).
+     *    With an approver wired the same bound mints NO notice — the fallback ask reaches the person
+     *    instead (`AskRequest.denialLimitFallback`).
+     *
      *  - `"steering.parked_input_blocked"` (design/373 §4.3) — a PARKED steer entry was withheld when
      *    a resume redelivered it (any resume kind that drains parked steers — wake included) by the
      *    deployment's `userPromptSubmit` screen (block verdict, or a fail-closed non-answer/crash):
@@ -6086,23 +6253,61 @@ export interface EngineNotice {
      *    disposition table with the error dispositions. The loser MUST NOT retry into the winner's
      *    account. A consumer diffing its own table against the catalog must not add a row for it.
      *
+     *  - `"config.peer_admission_out_of_range"` (#551) — a `RunnerDeps.peerAdmission` field the
+     *    resolver could not use: outside its legal range, or not a finite number at all (a string off
+     *    an untyped host's wiring, `NaN`, `Infinity`). THAT FIELD falls back to its own default (never
+     *    a clamp to the nearest edge, never a whole-config reject) and every other field is unaffected.
+     *    One notice PER FIELD — two bad fields in one config are two notices — deduped per SINK on
+     *    `(field, given)` rather than per call (the resolver runs on every SendMessage and every drain
+     *    round; the fact is about the wiring, not about the call). Per SINK, not per process: two
+     *    Runners in one process each own an `onNotice`, and a process-global ledger would deliver the
+     *    fact to whichever resolved first and leave the other silently without its own disclosure. The
+     *    unwired arm (no `onNotice`: the shared `console.warn` throat) latches per process instead —
+     *    the console IS one process-wide channel. `detail: { field, given, default,
+     *    range: [lo, hi], reason }`, where `reason` is `"out_of_range" | "not_a_finite_number"`.
+     *    Audience `"operator"` (a configuration fact; the fix is the deployment's).
      *  - `"config.peer_lane_unmounted"` (design/385 §1.2⑥) — `RunnerDeps.peerDirectory` is wired but
      *    the cross-session lane could not mount on this leg: no `mailboxStore`, or one that does not
      *    declare `crossProcessSafe: true` (several terminals would share one session box on luck). The
      *    seat is inert for the run (no ListAgents, peer addresses refuse with the same reason). Once per
      *    prepared leg; `detail: { reason, code, mailboxWired, sessionId, runId }`. Audience `"operator"`
      *    (a wiring fact; the fix is the deployment's).
-     *  - `"peer.inbound_disposition"` (design/385 §1.2④ / §4.6) — a message parked in THIS session's
-     *    own box was settled at the drain WITHOUT reaching the model. `detail.disposition` is the arm:
-     *    `"refused"` (this session's `crossSessionInbound` setting, or a record whose typed fields
-     *    cannot be rendered canonically), `"admission_refused"` (the drain-stage admission re-check:
-     *    duplicate / hop loop / runaway — `cause` names it), `"notice_unrouted"` (a notice-kind record
-     *    — idle/delivery notice — met a build with no notice face: settled without delivery, never
-     *    ridden through the peer-message envelope), or `"held"` (mode parity held it; the
-     *    held-message review face is not mounted in this build, so the message STAYS PARKED and the
-     *    drain stops at it — disclosed once per seq per leg). `detail: { disposition, cause, seq, box,
+     *  - `"peer.inbound_disposition"` (design/385 §1.2④ / §4.6 / §4.4) — a message parked in THIS
+     *    session's own box was settled at the drain WITHOUT reaching the model. `detail.disposition` is
+     *    the arm (closed set `PeerInboundDisposition`): `"refused"` (this session's `crossSessionInbound`
+     *    setting, or a record whose typed fields cannot be rendered canonically), `"admission_refused"`
+     *    (the drain-stage admission re-check: duplicate / hop loop / runaway — `cause` names it),
+     *    `"notice_unrouted"` (a notice-kind record the notice face cannot render — no typed `notice`, or
+     *    a state that does not fit its kind — settled without delivery, never ridden through the
+     *    peer-message envelope), `"notice_user_only"` (a delivery receipt / idle notice whose sender this
+     *    session's parity would HOLD: surfaced here for the user, not read by the model — CC's
+     *    `modelVisible:false` arm; `cause` carries the rendered notice text), or `"held"` — the parity
+     *    judgment held it: the message ENTERED this session's process-level held queue and was acked
+     *    from the box (later messages are not blocked behind it), where it is re-judged at every
+     *    boundary, released or refused with a receipt, and expires WITH a receipt under `dialogExpiry`
+     *    (see `peer.held_settled`); `cause` is a `PeerInboundHoldCause` — the parity causes, or the
+     *    drain gate's TRANSIENT `rate_limited` (that one does NOT enter the queue: the message stays in
+     *    the box and the drain stops at its seq until the bucket refills). Disclosed once per seq per leg,
+     *    and again when a re-judgment moves a held entry's cause. `detail: { disposition, cause, seq, box,
      *    fromSession?, sessionId, runId }`. Audience `"user"`: the session's user is the one who did
      *    not receive it.
+     *  - `"peer.held_settled"` (design/385 §4.4, slice 4) — a message left THIS session's held queue.
+     *    `detail.settlement` names how: `"delivered"` (a re-judgment or an approval released it into
+     *    this session's model context), `"refused"` (the setting moved to refuse, or an approval met a
+     *    refusing policy), `"expired"` (the `dialogExpiry` deadline, an eviction when the 100-entry queue
+     *    was full, a cancelled review, or a graceful shutdown), `"denied"` (the review face), `"dropped"`
+     *    (the injection lane refused the released frame). `detail.reason` is the trigger
+     *    (`deadline | evicted | shutdown | rejudge | approved | denied | cancelled | inject_failed`); the
+     *    sender was sent the matching receipt whenever the record carried a reply address.
+     *    `detail: { settlement, reason, seq, box, fromSession?, heldCount, sessionId, runId }`. Audience
+     *    `"user"`: it is this session's user who held (or was holding) the message.
+     *  - `"peer.idle_subscription"` (design/385 §5.2, slice 4) — a peer session asked to be told when
+     *    THIS session next goes idle (`SendMessage … notify_when_idle`). `detail.outcome`: `"recorded"`
+     *    / `"refreshed"` (a same-requester re-ask; the subscription is one-shot and expires unfired after
+     *    12 h), `"full"` (the 32-entry table is full) or `"refused"` (this session's `crossSessionInbound`
+     *    is `refuse`) — the last two answered the requester with an `unavailable` notice. `detail:
+     *    { outcome, fromSession, live, seq, box, sessionId, runId }`. Audience `"user"`: the person whose
+     *    session is being watched is the one entitled to know (CC announces it in the session UI).
      *
      *  - `"delegation.transcript_integrity"` (subagent transcript persistence) — a durable agent row
      *    with a BOUND transcript sessionId met a session store that attests `not_found` for it: the
@@ -6852,6 +7057,25 @@ export interface RunnerDeps {
             consecutiveFailures: number;
             lastCause: string;
         }) => void;
+        /**
+         * The classifier DENIAL LIMIT (CC 2.1.250 `FO`/`AKe`): a run whose classifier keeps blocking falls
+         * back to a PERSON instead of being denied without end. Per run: a `block` first increments the
+         * consecutive and total counts and then judges `consecutive >= maxConsecutive || total >= maxTotal`
+         * — the block that reaches a bound is itself the one that becomes an `ask` (the 3rd consecutive
+         * block asks). That ask carries `requiresRealApproval: true` (no automatic lane may clear it — not
+         * a sandbox admission, not an inherited resolver, not a blanket `onAsk:"allow"`) plus the additive
+         * `denialLimitFallback` member with the counts and its own auto-deny window; an unanswered ask
+         * auto-denies after `autoDenyAfterMs` (default 120s; `0` = no window). A classifier allow, or a
+         * person's allow of the fallback ask, zeroes the consecutive count; reaching the total bound
+         * zeroes everything. With no approver wired at all (headless), the fallback has nowhere to go and
+         * the run STOPS with `TaskResult.errorCode = "classifier.denial_limit"` (a notice of the same
+         * code is minted).
+         *
+         * Every member optional (defaults 3 / 20 / 120_000). A present member with a bad value is refused
+         * loudly at prepare — never clamped, never silently read as the default.
+         * See {@link import("./auto-mode.js").AutoModeDenialLimitOptions}.
+         */
+        denialLimit?: import("./auto-mode.js").AutoModeDenialLimitOptions;
         /**
          * #503 — OPT IN to recording this arming's serializable criteria (an
          * {@link import("./auto-mode-arming.js").AutoModeArmingRecipe}) on the constraint-chain entries a
@@ -7012,6 +7236,18 @@ export interface RunnerDeps {
      * everywhere (mode parity, the CC default). Inert without {@link peerDirectory}.
      */
     crossSessionInbound?: import("../agents/cross-session-judge.js").CrossSessionInboundSettingLayers | (() => import("../agents/cross-session-judge.js").CrossSessionInboundSettingLayers);
+    /**
+     * design/385 §4.4 (slice 4) — this deployment's `dialogExpiry` (CC settings key, verbatim vocabulary
+     * `"60s" | "5m" | "10m" | "never"`, default `"5m"`): how long a HELD cross-session message whose cause
+     * a human review could resolve (mode-mismatch / no-mode-asserted / invalid attestation) waits in this
+     * session's held queue before it resolves to its safe no-action default — EXPIRED, dropped WITH a
+     * receipt to the sender, never silently. `"never"` disables the deadline. Read at every drain round
+     * (getter form for a host that re-reads its settings). A value outside the vocabulary is announced
+     * ONCE per leg through `onError` (`classification: "peer-dialog-expiry"`) and the default applies —
+     * a garbage setting never silently reads as a policy. Absent = the default. Inert without
+     * {@link peerDirectory}.
+     */
+    crossSessionDialogExpiry?: import("../agents/peer-notices.js").CrossSessionDialogExpiry | (() => import("../agents/peer-notices.js").CrossSessionDialogExpiry | undefined);
     /**
      * design/164 件五 — DEPLOYMENT-level usage governance: allowances that span TASKS, evaluated per
      * principal (or once for the whole deployment when a task declares none). A different axis from
@@ -7542,4 +7778,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) {