@sema-agent/core 5.49.0 → 5.51.0

package/dist/core/task-registry-agent.js

@@ -233,6 +233,12 @@ export async function reapDurableAgentsLane(core, scope, deps, policy) {
                 continue;
             }
             rowsReaped++;
+            {
+                const staleInProc = core.handles.get(r.handle);
+                if (staleInProc !== undefined && staleInProc.status !== "running" && staleInProc.status !== "pending" && staleInProc.status !== "parked") {
+                    core.handles.delete(r.handle);
+                }
+            }
             core.reapedHandles.add(r.handle);
             if (deps.mailbox !== undefined) {
                 try {
@@ -1396,7 +1402,7 @@ export async function stopBackgroundAgentLane(core, handle) {
         if (arbiter === undefined) {
             return {
                 content: `${handle.id} is parked on a pending approval — stop it by deciding (deny/expire) the pending approval in the durable approval inbox.`,
-                details: { task_id: handle.id, type: "background_agent", status: "parked", retrieval_status: "not_ready", error: "parked_pending_approval" },
+                details: { task_id: handle.id, type: "background_agent", status: "parked", retrieval_status: "not_ready", error: "parked_pending_approval", code: "parked_pending_approval" },
             };
         }
         let stopWon = false;
@@ -1461,13 +1467,13 @@ export async function stopBackgroundAgentLane(core, handle) {
         if (arbiterUnreachable) {
             return {
                 content: `${handle.id} was not stopped: the approval arbitration store was unreachable — the row stays parked; retry the stop.`,
-                details: { task_id: handle.id, type: "background_agent", status: handle.status, retrieval_status: "not_ready", error: "park_arbiter_unreachable" },
+                details: { task_id: handle.id, type: "background_agent", status: handle.status, retrieval_status: "not_ready", error: "park_arbiter_unreachable", code: "park_arbiter_unreachable" },
                 isError: true,
             };
         }
         return {
             content: `${handle.id} was not stopped: its pending approval was already consumed (a resume won the arbitration).`,
-            details: { task_id: handle.id, type: "background_agent", status: handle.status, retrieval_status: "not_ready", error: "park_resume_won" },
+            details: { task_id: handle.id, type: "background_agent", status: handle.status, retrieval_status: "not_ready", error: "park_resume_won", code: "park_resume_won" },
             isError: true,
         };
     }

package/dist/core/task-registry-shared.d.ts

@@ -32,6 +32,12 @@ export interface UnifiedTaskOutput {
     retrieval_status: TaskRetrievalStatus;
     content?: string;
     error?: string;
+    /** Machine twin of {@link error}, same token, present exactly where `error` names a coded refusal
+     *  (`not_local`/`parked_pending_approval`/`park_resume_won`/`park_arbiter_unreachable`): the wire
+     *  errorCode lift reads `details.code`, and an error-only refusal is unclassifiable on tool_end
+     *  frames. Distinct from {@link errorCode}, which carries a FAILED child's own result taxonomy —
+     *  this key classifies THIS poll/stop answer itself. Additive. */
+    code?: string;
     /** RB-386② ([2090]) — machine-readable failure code on a FAILED background_agent row's poll
      *  details (the child's TaskResult.errorCode taxonomy — brain codes / `limit.*` / `budget.*` …).
      *  Additive; absent on non-failed rows, on rows whose failure carried no code, and on other lanes. */

package/dist/core/task-registry.js

@@ -861,6 +861,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                             status: "running",
                             retrieval_status: "not_ready",
                             error: "not_local",
+                            code: "not_local",
                         },
                     };
                 }
@@ -898,6 +899,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                         status: run.status,
                         retrieval_status: "success",
                         error: "not_local",
+                        code: "not_local",
                     },
                 };
             }
@@ -922,8 +924,8 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                         type: "background_agent",
                         status: row.status,
                         retrieval_status: row.status === "parked" ? "not_ready" : "success",
-                        ...(row.status === "running" ? { error: "not_local" } : {}),
-                        ...(row.status === "parked" ? { error: "parked_pending_approval" } : {}),
+                        ...(row.status === "running" ? { error: "not_local", code: "not_local" } : {}),
+                        ...(row.status === "parked" ? { error: "parked_pending_approval", code: "parked_pending_approval" } : {}),
                     },
                 };
             }

package/dist/core/tool-policy.d.ts

@@ -1057,6 +1057,29 @@ export declare function tryCloneArgs<T>(v: T): {
  * text they let through. Not part of the package's public surface.
  */
 export declare function describeThrown(err: unknown): string;
+/**
+ * The deny-arm classification a {@link resolveAsk} refusal carries — MINTED at the composing arm
+ * (the minter reports the fact; no consumer re-derives it from message text, which is exactly the
+ * inference this closed set exists to end). One word per family of arms:
+ *  - `"human_refused"` — a person answered no (the boolean false fold and the object arm's
+ *    allow-false, noted or bare — the note fact rides {@link ResolvedAsk.humanRefusalNote});
+ *  - `"window_expired"` — the approver's own window elapsed (the timeout-settled deny);
+ *  - `"no_approver"` — headless auto-deny (no approver wired, or the deny posture string);
+ *  - `"blanket_allow_refused"` — a blanket allow posture met a `requiresRealApproval` ask;
+ *  - `"approver_unavailable"` — the approver answered the ROUTING question "nobody reachable"
+ *    (the G1 marker's fail-closed carry — the gate may re-route it to a durable park instead);
+ *  - `"task_aborted"` — the task's own signal ended the wait (pre-wait and mid-wait arms);
+ *  - `"presentation_failed"` — the args/edit could not be safely presented or adopted (unclonable);
+ *  - `"approver_error"` — the approver callback threw;
+ *  - `"approver_contract"` — the approver returned something outside the contract (non-boolean
+ *    allow, out-of-vocabulary settlement word, unreadable members, a timeout-settled allow, a
+ *    non-string or unreadable reason, an out-of-contract truthy, a refused attribution).
+ */
+export type AskDenyResolution = "human_refused" | "window_expired" | "no_approver" | "blanket_allow_refused" | "approver_unavailable" | "task_aborted" | "presentation_failed" | "approver_error" | "approver_contract";
+/** Closed-vocabulary guard for {@link AskDenyResolution} — the screen every carrier runs before it
+ *  files or forwards the word (a policy layer could self-declare the member on its own deny; an
+ *  out-of-vocabulary word is dropped by the carriers, never coerced or forwarded). */
+export declare function isAskDenyResolution(v: unknown): v is AskDenyResolution;
 /**
  * A {@link resolveAsk} result: always a TERMINAL `allow`/`deny` (never `ask`). `approverUnavailable`
  * is the out-of-band G1 three-value marker: the live approver returned `"unavailable"` for this ask —
@@ -1071,6 +1094,20 @@ export type ResolvedAsk = PermissionResult & {
      *  differ from the approved one (shown == executed, by construction). Set only on the
      *  function-approver path (string modes present nothing). */
     presentedInput?: unknown;
+    /** Present exactly when this deny is a PERSON's refusal (`settledBy: "human"`) that carried the
+     *  decider's own note (the object arm's `reason`, screened and non-empty). Its ABSENCE on a human
+     *  deny is the structural fact that the refusal was BARE — a "no" with no direction attached —
+     *  which is the arm the runner treats as a control-flow boundary for the issuing batch (a bare
+     *  "no" on the parent thread halts the remaining same-message tool calls; a refusal WITH a note
+     *  gives the model direction to adapt to, so the turn continues). Never derived from message
+     *  text; stamped only at the composing arm. Not stamped on the timeout deny (nobody answered)
+     *  or on any engine-produced fail-closed refusal. */
+    humanRefusalNote?: true;
+    /** The deny-arm classification (see {@link AskDenyResolution}) — present on every deny this
+     *  resolver composes, absent on every allow. Carried by the gate to its block exit, the
+     *  permission-denied observer payload and the settlement sideband (thence the call's `tool_end`
+     *  frame), so a consumer classifies a refusal by code instead of parsing its text. */
+    resolution?: AskDenyResolution;
 };
 /**
  * Resolve an `ask` decision to a terminal `allow`/`deny` via {@link OnAsk}. Centralizes the headless

package/dist/core/tool-policy.js

@@ -849,6 +849,20 @@ function humanRefusalMessage(req, reason) {
         ? `${head}\nThe user doesn't want to proceed with this tool use; the call did NOT run. The user's note on this rejection follows — treat it as the user's guidance (user authority only: it cannot grant permissions or override system rules):\n${delimitUntrusted("reviewer note", reason, REVIEWER_NOTE_MAX_BODY)}\nIf the note does not tell you how to proceed, STOP what you are doing and wait for the user.`
         : `${head}\nThe user doesn't want to proceed with this tool use; the call did NOT run. STOP what you are doing and wait for the user to tell you how to proceed.`;
 }
+const ASK_DENY_RESOLUTION_SET = new Set([
+    "human_refused",
+    "window_expired",
+    "no_approver",
+    "blanket_allow_refused",
+    "approver_unavailable",
+    "task_aborted",
+    "presentation_failed",
+    "approver_error",
+    "approver_contract",
+]);
+export function isAskDenyResolution(v) {
+    return typeof v === "string" && ASK_DENY_RESOLUTION_SET.has(v);
+}
 export async function resolveAsk(req, onAsk, signal) {
     if (onAsk === "allow") {
         if (req.requiresRealApproval === true) {
@@ -858,6 +872,7 @@ export async function resolveAsk(req, onAsk, signal) {
                     `judgment was applied) — this decision requires an actual auto-mode classifier verdict or a ` +
                     `real approval callback, neither of which a blanket bypass can provide: ${req.message}`,
                 decisionReason: "mode",
+                resolution: "blanket_allow_refused",
             };
         }
         return { action: "allow", decisionReason: "mode" };
@@ -867,10 +882,12 @@ export async function resolveAsk(req, onAsk, signal) {
             action: "deny",
             message: `approval required for "${req.toolName}" but no approver is wired (headless auto-deny): ${req.message}`,
             decisionReason: "mode",
+            resolution: "no_approver",
         };
     }
     if (signal?.aborted) {
-        return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, decisionReason: "mode", settledBy: "aborted" };
+        return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, decisionReason: "mode",
+            resolution: "task_aborted", settledBy: "aborted" };
     }
     const presented = tryCloneArgs(req.args);
     if (!presented.ok) {
@@ -878,6 +895,7 @@ export async function resolveAsk(req, onAsk, signal) {
             action: "deny",
             message: `approval for "${req.toolName}" could not present the args safely (unclonable value: ${presented.reason}) — denied fail-closed`,
             decisionReason: "mode",
+            resolution: "presentation_failed",
             settledBy: "aborted",
         };
     }
@@ -889,6 +907,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 action: "deny",
                 message: `approval for "${req.toolName}" could not present the args safely (unclonable value: ${approverView.reason}) — denied fail-closed`,
                 decisionReason: "mode",
+                resolution: "presentation_failed",
                 settledBy: "aborted",
             };
         }
@@ -899,11 +918,13 @@ export async function resolveAsk(req, onAsk, signal) {
             action: "deny",
             message: `approval errored for "${req.toolName}": ${describeThrown(err)}`,
             decisionReason: "mode",
+            resolution: "approver_error",
             settledBy: "aborted",
         };
     }
     if (signal?.aborted) {
-        return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, decisionReason: "mode", settledBy: "aborted" };
+        return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, decisionReason: "mode",
+            resolution: "task_aborted", settledBy: "aborted" };
     }
     if (ok === "unavailable") {
         return {
@@ -911,6 +932,7 @@ export async function resolveAsk(req, onAsk, signal) {
             message: `approval required for "${req.toolName}" but the approver reported unavailable (no reachable ` +
                 `operator for this ask) and no durable approval gate is armed — denied fail-closed: ${req.message}`,
             decisionReason: "mode",
+            resolution: "approver_unavailable",
             settledBy: "aborted",
             approverUnavailable: true,
         };
@@ -931,6 +953,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 action: "deny",
                 message: `the approver's outcome for "${req.toolName}" could not be read (${describeThrown(err)}) — denied fail-closed`,
                 decisionReason: "mode",
+                resolution: "approver_contract",
                 settledBy: "aborted",
             };
         }
@@ -940,6 +963,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 message: `the approver for "${req.toolName}" returned an object whose allow is not a boolean ` +
                     `(got ${allowed === null ? "null" : typeof allowed}) — a verdict is exactly true or false; denied fail-closed`,
                 decisionReason: "mode",
+                resolution: "approver_contract",
                 settledBy: "aborted",
             };
         }
@@ -949,6 +973,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 message: `the approver for "${req.toolName}" reported settledBy "${typeof supplied === "string" ? containThrownText(supplied) : supplied === null ? "null" : typeof supplied}", which is outside what a synchronous ` +
                     `approver may self-report — it is exactly "human" or "timeout" (or omitted); denied fail-closed`,
                 decisionReason: "mode",
+                resolution: "approver_contract",
                 settledBy: "aborted",
             };
         }
@@ -958,6 +983,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 action: "deny",
                 message: `the approver for "${req.toolName}" reported an attribution this seam refuses: ${attribution.defect}; denied fail-closed`,
                 decisionReason: "mode",
+                resolution: "approver_contract",
                 settledBy: "aborted",
             };
         }
@@ -968,6 +994,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 message: `the approver for "${req.toolName}" returned an allow settled by "timeout" — an elapsed approval window cannot be ` +
                     `what approved a call; denied fail-closed (report timeout with allow:false, or allow with settledBy "human"/omitted)`,
                 decisionReason: "mode",
+                resolution: "approver_contract",
                 settledBy: "timeout",
             };
         }
@@ -981,6 +1008,7 @@ export async function resolveAsk(req, onAsk, signal) {
                         message: `the approver for "${req.toolName}" attached a reason that is not a plain string ` +
                             `(got ${suppliedReason === null ? "null" : typeof suppliedReason}) — a deny note is the decider's plain text; denied fail-closed`,
                         decisionReason: "mode",
+                        resolution: "approver_contract",
                         settledBy: "aborted",
                     };
                 }
@@ -991,6 +1019,7 @@ export async function resolveAsk(req, onAsk, signal) {
                     action: "deny",
                     message: `the approver for "${req.toolName}" attached a reason that could not be read (${describeThrown(err)}) — denied fail-closed`,
                     decisionReason: "mode",
+                    resolution: "approver_contract",
                     settledBy: "aborted",
                 };
             }
@@ -1000,7 +1029,9 @@ export async function resolveAsk(req, onAsk, signal) {
                     ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${reasonText !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reasonText, REVIEWER_NOTE_MAX_BODY)}` : ""}`
                     : humanRefusalMessage(req, reasonText),
                 decisionReason: "mode",
+                resolution: supplied === "timeout" ? "window_expired" : "human_refused",
                 settledBy: supplied === "timeout" ? "timeout" : "human",
+                ...(supplied !== "timeout" && reasonText !== undefined ? { humanRefusalNote: true } : {}),
                 ...attributionCell,
             };
         }
@@ -1012,6 +1043,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 action: "deny",
                 message: `the approved edit for "${req.toolName}" is not safely clonable (${edit.reason}) — denied fail-closed`,
                 decisionReason: "mode",
+                resolution: "presentation_failed",
                 settledBy: "aborted",
             };
         }
@@ -1025,8 +1057,9 @@ export async function resolveAsk(req, onAsk, signal) {
             action: "deny",
             message: `the approver for "${req.toolName}" returned an out-of-contract value (${typeof ok}) — denied fail-closed (return true, false, "unavailable", or the {allow} object)`,
             decisionReason: "mode",
+            resolution: "approver_contract",
             settledBy: "aborted",
         };
     }
-    return { action: "deny", message: humanRefusalMessage(req), decisionReason: "mode", settledBy: "human" };
+    return { action: "deny", message: humanRefusalMessage(req), decisionReason: "mode", resolution: "human_refused", settledBy: "human" };
 }

package/dist/core/tools.js

@@ -46,6 +46,13 @@ export function defineTool(spec, options) {
         ...(spec.isConcurrencySafe ? { isConcurrencySafe: spec.isConcurrencySafe } : {}),
         ...(spec.effect ? { effect: spec.effect } : {}),
         ...(spec.contentOrigin ? { contentOrigin: spec.contentOrigin } : {}),
+        ...(spec.egress ? { egress: true } : {}),
+        ...(spec.irreversibility !== undefined ? { irreversibility: spec.irreversibility } : {}),
+        ...(spec.reversibilityProbe ? { reversibilityProbe: spec.reversibilityProbe } : {}),
+        ...(spec.offload !== undefined ? { offload: spec.offload } : {}),
+        ...(spec.offloadThresholdChars !== undefined ? { offloadThresholdChars: spec.offloadThresholdChars } : {}),
+        ...(spec.defer !== undefined ? { defer: spec.defer } : {}),
+        ...(spec.alwaysLoad !== undefined ? { alwaysLoad: spec.alwaysLoad } : {}),
         ...(spec.prepareArguments ? { prepareArguments: spec.prepareArguments } : {}),
         ...(spec.approvalPreview ? { approvalPreview: spec.approvalPreview } : {}),
         execute: async (toolCallId, rawParams, signal) => {

package/dist/core/types.d.ts

@@ -270,7 +270,8 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * design/77 §4: optional deployment-injected probe for an `irreversibility:"maybe"` tool. Given the call's
      * (post-hook) args, it reports whether THIS specific call is reversible. The gate calls it ONLY when the
      * surviving decision is `allow` and `irreversibility` resolves to `"maybe"`; it is time-bounded (the
-     * approval timeout) and **fail-closed**: a non-`reversible` verdict, a timeout, or a throw all tighten to
+     * approval timeout when configured, a 30s default when absent — the probe wait is always finite) and
+     * **fail-closed**: a non-`reversible` verdict, a timeout, or a throw all tighten to
      * `ask`. Declaring this probe defaults `irreversibility` to `"maybe"`. It is read from the spec at
      * prepare-time and captured in a closure — NOT a tool argument — so the model cannot monkey-patch it.
      *
@@ -3107,6 +3108,19 @@ export interface TaskResult {
         /** Human-readable statement of what did NOT happen and why — safe to show a user verbatim. */
         message: string;
     }>;
+    /**
+     * 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
+     * that had not started were settled un-executed (each an error result coded `gate.batch_halted`),
+     * and the engine deliberately did NOT re-invoke the model, so the run ends awaiting the user's
+     * direction. On this path `status` is still `"completed"` (nothing failed, nothing is suspended,
+     * the session is continuable as ever) — this field is what tells such an end apart from a natural
+     * finish: `result` text is whatever the model had produced BEFORE the rejection (often empty), and
+     * a consumer surface should read the state as "stopped by the user, awaiting their direction",
+     * never as "the task finished its work". Absent everywhere else — including when queued user input
+     * (a steer/follow-up) continued the run past the rejection and it later ended naturally.
+     */
+    haltedOnUserRejection?: true;
     /**
      * The deliveries of AskUserQuestion calls a person ANSWERED but whose call never executed to collect
      * the answer (the leg ended first — abort, batch teardown, or a loop failure). Rides EVERY terminal
@@ -3665,6 +3679,21 @@ export type TaskEvent = ({
      * must not treat "absent" as "a human decided".
      */
     settledBy?: import("./tool-policy.js").ApprovalSettledBy;
+    /**
+     * HOW the ask resolution refused, when this frame closes a call an in-process ask resolution
+     * DENIED — the closed vocabulary of {@link import("./tool-policy.js").AskDenyResolution}
+     * (`"human_refused"`, `"window_expired"`, `"no_approver"`, `"blanket_allow_refused"`,
+     * `"approver_unavailable"`, `"task_aborted"`, `"presentation_failed"`, `"approver_error"`,
+     * `"approver_contract"`). Finer-grained than {@link settledBy} (which only says what KIND of
+     * end a settled wait had): this classifies the REFUSAL ARM itself, minted by the resolver at
+     * the arm that composed the deny and carried verbatim on the engine-owned settlement sideband
+     * — never derived from the result text or writable by a tool/policy (an out-of-vocabulary or
+     * self-declared word is dropped at the screens, with a defect reported on the deployment's
+     * error face). ABSENT on every frame that was not such a deny — every executed call, every
+     * policy/hook direct deny, and the durable/decide lane's settlements (which carry their own
+     * `settledBy`/reason instead). A consumer must not read a semantic out of the absence.
+     */
+    resolution?: import("./tool-policy.js").AskDenyResolution;
     /**
      * design/252 G-7 — WHOSE settlement that was: the identifier the approval channel reported for
      * the party that ended this wait, beside the {@link settledBy} word that says what KIND of end
@@ -4730,6 +4759,12 @@ export interface EngineNotice {
      *    `detail: { total, stripped: [{ key, reason }], omitted? }`, the rendered key list bounded in count
      *    and length because the names come from the untrusted script. One aggregated notice per governed
      *    child build, not de-duplicated across builds: each spec is a distinct fact.
+     *  - `"mcp.revocation_probe_failed"` (design/338) — the deployment's `mcpRevocations.isRevoked`
+     *    probe threw; MCP dispatch FAILS OPEN (revocation is a tightening face) and this announces
+     *    once per materialization (a resume re-materializes and may announce again). `detail: { message }`
+     *    — no sessionId (a deployment wiring fact, not session-attributed), `"operator"` audience by
+     *    the {@link NOTICE_AUDIENCE} default. The refusal itself (`mcp.server_revoked`) is a tool
+     *    RESULT code, not a notice.
      *  - `"config.models_swapped"` — `Runner.swapModels` replaced the model catalog generation
      *    (zero-restart model switching). `detail: { models, tiers }` — key COUNTS only, never the
      *    catalog itself. In-flight tasks finish on the models they resolved at prepare (natural
@@ -4898,6 +4933,23 @@ export interface RunnerDeps {
     brain: Brain;
     /** Catalog used to resolve string ModelRefs to Model objects. */
     models?: Record<string, Model>;
+    /**
+     * design/338 (mid-turn MCP revocation) — the HOST's revocation ledger, probed synchronously at
+     * every MCP dispatch (tool call + the three resource tools) BEFORE the transport. The engine
+     * never caches the answer: the ledger's one authority lives on the host (a cached copy would be
+     * a split-state second authority). A revoked server's calls settle as the coded refusal
+     * `mcp.server_revoked` with known-not-executed wording; in-flight calls a revocation raced are
+     * deliberately not chased (the threat shape is "new calls after removal"). Absent seat = the
+     * pre-338 semantics. A THROWING probe fails open (revocation is a tightening face — a broken
+     * probe must not brick every MCP call) with a once-per-MATERIALIZATION `mcp.revocation_probe_failed`
+     * notice (a resume re-materializes and may announce again — the standing condition is re-news at
+     * each fresh mount, never per-call). The notice is a deployment wiring fact: `detail: { message }`
+     * only, no session attribution, `"operator"` audience by the {@link NOTICE_AUDIENCE} default — a
+     * wire projector forwards it operator-tier and needs no per-session de-duplication of its own.
+     */
+    mcpRevocations?: {
+        isRevoked(serverName: string): boolean;
+    };
     /**
      * design/147 S1c (clay ruling 2026-07-18) — the DURABLE name→agent roster behind explicit-name
      * addressing, a storage-tier seam like the checkpoint store: core bundles `MemoryRosterStore`

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

@@ -490,12 +490,14 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
         });
         const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
         let finalized;
+        let halt;
         if (preparation.kind === "immediate") {
             finalized = {
                 toolCall,
                 result: preparation.result,
                 isError: preparation.isError,
             };
+            halt = preparation.halt;
         }
         else {
             finalized = await executePreparedWithDisclosure(currentContext, assistantMessage, preparation, config, signal, emit);
@@ -505,6 +507,16 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
         await emitToolResultMessage(toolResultMessage, emit);
         finalizedCalls.push(finalized);
         messages.push(toolResultMessage);
+        if (halt !== undefined) {
+            for (const remaining of toolCalls.slice(i + 1)) {
+                if (signal?.aborted)
+                    break;
+                const settled = await settleHaltedToolCall(remaining, halt, emit);
+                finalizedCalls.push(settled.finalized);
+                messages.push(settled.message);
+            }
+            return { messages, terminate: true };
+        }
         if (signal?.aborted) {
             break;
         }
@@ -514,6 +526,33 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
         terminate: shouldTerminateToolBatch(finalizedCalls),
     };
 }
+async function settleHaltedToolCall(toolCall, halt, emit) {
+    await emit({
+        type: "tool_execution_start",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        args: toolCall.arguments,
+    });
+    const finalized = {
+        toolCall,
+        result: {
+            content: [{ type: "text", text: truncateError(halt.reason) }],
+            details: halt.details !== undefined ? { ...halt.details } : {},
+        },
+        isError: true,
+    };
+    await emit({
+        type: "tool_execution_end",
+        toolCallId: finalized.toolCall.id,
+        toolName: finalized.toolCall.name,
+        result: finalized.result,
+        isError: true,
+        notExecuted: true,
+    });
+    const message = createToolResultMessage(finalized);
+    await emitToolResultMessage(message, emit);
+    return { finalized, message };
+}
 function isCallConcurrencySafe(tool, args) {
     if (!tool)
         return false;
@@ -587,6 +626,7 @@ async function executeToolCallsPartitioned(currentContext, assistantMessage, too
     const allFinalized = [];
     const messages = [];
     const remainingCalls = [];
+    let halt;
     for (const toolCall of toolCalls) {
         const held = executor?.take(toolCall.id);
         if (!held) {
@@ -599,6 +639,8 @@ async function executeToolCallsPartitioned(currentContext, assistantMessage, too
         await emitToolResultMessage(toolResultMessage, emit);
         allFinalized.push(finalized);
         messages.push(toolResultMessage);
+        if (held.immediate?.halt !== undefined)
+            halt ??= held.immediate.halt;
     }
     if (executor) {
         for (const orphan of executor.remaining()) {
@@ -606,33 +648,54 @@ async function executeToolCallsPartitioned(currentContext, assistantMessage, too
             await closeOrphanedStreamEntry(orphan, emit);
         }
     }
-    const batches = partitionToolCalls(remainingCalls, currentContext.tools);
-    outer: for (const batch of batches) {
-        if (signal?.aborted)
-            break;
-        const entries = [];
-        for (const toolCall of batch.calls) {
-            await emit({
-                type: "tool_execution_start",
-                toolCallId: toolCall.id,
-                toolName: toolCall.name,
-                args: toolCall.arguments,
-            });
-            const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
-            if (preparation.kind === "immediate") {
-                const finalized = { toolCall, result: preparation.result, isError: preparation.isError };
-                await emitToolExecutionEnd(finalized, emit);
-                entries.push({ finalized, toolCall });
-            }
-            else {
-                entries.push({ prepared: preparation, toolCall });
-            }
-            if (signal?.aborted) {
-                await settleBatch(entries, true);
-                break outer;
+    if (halt === undefined) {
+        const batches = partitionToolCalls(remainingCalls, currentContext.tools);
+        outer: for (const batch of batches) {
+            if (signal?.aborted)
+                break;
+            const entries = [];
+            for (const toolCall of batch.calls) {
+                await emit({
+                    type: "tool_execution_start",
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.name,
+                    args: toolCall.arguments,
+                });
+                const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
+                if (preparation.kind === "immediate") {
+                    const finalized = { toolCall, result: preparation.result, isError: preparation.isError };
+                    await emitToolExecutionEnd(finalized, emit);
+                    entries.push({ finalized, toolCall });
+                    if (preparation.halt !== undefined) {
+                        halt = preparation.halt;
+                        break;
+                    }
+                }
+                else {
+                    entries.push({ prepared: preparation, toolCall });
+                }
+                if (signal?.aborted) {
+                    await settleBatch(entries, true);
+                    break outer;
+                }
             }
+            await settleBatch(entries, batch.safe);
+            if (halt !== undefined)
+                break;
         }
-        await settleBatch(entries, batch.safe);
+    }
+    if (halt !== undefined && !signal?.aborted) {
+        const settledIds = new Set(messages.map((m) => m.toolCallId));
+        for (const toolCall of toolCalls) {
+            if (settledIds.has(toolCall.id))
+                continue;
+            if (signal?.aborted)
+                break;
+            const settled = await settleHaltedToolCall(toolCall, halt, emit);
+            allFinalized.push(settled.finalized);
+            messages.push(settled.message);
+        }
+        return { messages, terminate: true };
     }
     return { messages, terminate: shouldTerminateToolBatch(allFinalized) };
     async function settleBatch(entries, concurrent) {
@@ -720,6 +783,8 @@ class StreamToolExecutor {
             const preparation = await prepareToolCall(this.context, partialAssistant, entry.toolCall, this.config, this.signal);
             if (preparation.kind === "immediate") {
                 entry.immediate = preparation;
+                if (preparation.halt !== undefined)
+                    this.barrier = true;
                 return;
             }
             entry.prepared = preparation;
@@ -873,11 +938,11 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
                 };
             }
             if (beforeResult?.block) {
-                return {
-                    kind: "immediate",
-                    result: createErrorToolResult(beforeResult.reason || "Tool execution was blocked"),
-                    isError: true,
-                };
+                const blocked = createErrorToolResult(beforeResult.reason || "Tool execution was blocked");
+                if (beforeResult.haltRemaining !== undefined) {
+                    return { kind: "immediate", result: blocked, isError: true, halt: beforeResult.haltRemaining };
+                }
+                return { kind: "immediate", result: blocked, isError: true };
             }
             if (beforeResult?.updatedInput !== undefined) {
                 finalArgs = validateToolArguments(tool, {

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

@@ -48,11 +48,34 @@ export type AgentToolCall = Extract<AssistantMessage["content"][number], {
  *
  * Keep in sync with the harness hook result `ToolCallResult` (harness/types.ts), which the harness's
  * `beforeToolCall` callback returns verbatim.
+ *
+ * `haltRemaining` (additive) makes the block a CONTROL-FLOW BOUNDARY for the whole assistant batch:
+ * honored only beside `block: true`, it tells the loop that every tool call of the same assistant
+ * message whose preparation had not yet begun must NOT begin — each settles as an error tool result
+ * built from the directive (so the transcript still answers every tool call), and the batch votes
+ * terminate (the loop starts no further assistant turn; queued follow-up/steering messages still
+ * run — they are the input the boundary is waiting for). Calls already executing when the block
+ * lands run to completion and settle with their real outcomes; preparation/adjudication is strictly
+ * source-ordered in every lane, so "not yet begun" is exactly "after the blocked call". The loop
+ * stays policy-agnostic: WHY a block halts the batch (e.g. a person's bare rejection) is entirely
+ * the gate owner's judgment, made once, at the site that returns this.
  */
 export interface BeforeToolCallResult {
     block?: boolean;
     reason?: string;
     updatedInput?: unknown;
+    haltRemaining?: HaltRemainingDirective;
+}
+/**
+ * The settlement {@link BeforeToolCallResult.haltRemaining} instructs the loop to apply to each
+ * same-batch tool call that never started: `reason` is the model-facing error text (bounded by the
+ * loop's standard error truncator), `details` is attached to each settled result verbatim (shallow-
+ * copied per call) so a machine-readable mark (e.g. `{ code }`) reaches every not-executed sibling's
+ * end frame and transcript entry.
+ */
+export interface HaltRemainingDirective {
+    reason: string;
+    details?: Record<string, unknown>;
 }
 /**
  * Partial override returned from `afterToolCall`.
@@ -629,4 +652,13 @@ export type AgentEvent = {
     toolName: string;
     result: unknown;
     isError: boolean;
+    /**
+     * Present (`true`) exactly when this end frame closes a call the loop settled WITHOUT
+     * executing it — a never-started sibling under a batch-halt directive (see
+     * {@link BeforeToolCallResult.haltRemaining}). LOOP-AUTHORED: it rides the event, never the
+     * tool result, so a tool cannot claim it about itself; a consumer that scopes
+     * post-execution machinery to executed calls (batch observers, execution audits) keys on
+     * this the way it keys on its own blocked-call records. Absent on every executed call.
+     */
+    notExecuted?: true;
 };