@sema-agent/core 7.5.1 → 7.6.0

package/dist/core/runner/park-commit.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The commit-side vocabulary of a durable park: which holder a COMMITTED checkpoint publishes to, the abort-classification
+ * marker the loop stamps on the contaminated siblings, and the deadline arithmetic every mint shares (the retention
+ * defaults and the one TTL sanitizer). Moved whole out of the orchestrator so the boundary-parks phase (resource /
+ * platform / review) and the park-ask phase (the approval park) reach DOWN for the same publication seam and the same
+ * numbers, and the driver keeps reaching down for the marker its harness stamps. Pure: no engine state; the only clock
+ * is the caller's.
+ */
+import type { CheckpointGate, CheckpointToken, PendingAction } from "../checkpoint-store.js";
+import type { WorkspaceHandle } from "../remote-env.js";
+import type { Prepared } from "./contracts.js";
+/** design/74 (HIGH-2): default resource-checkpoint retention (30 days, the spec's
+ *  `RESOURCE_SUSPEND_TTL_SEC`). Stamped onto the checkpoint `deadline` so the durable reaper can GC an
+ *  ORPHANED resource suspend; a legitimate auto-resume fires long before this. Override via
+ *  `TaskSpec.resourceSuspend.ttlMs`. */
+export declare const DEFAULT_RESOURCE_TTL_MS: number;
+/**
+ * design/164 件五 — how long AFTER a governance window frees a `usage_window` checkpoint stays reapable-free.
+ * The retention TTL answers "was this abandoned?"; a usage-window suspend is not abandoned while the window
+ * it waits on is still full, so its deadline is pushed to `retryAfterMs + this`. One hour gives a host's
+ * scheduler a realistic chance to pick the resume up (a cron tick, a queue drain) before the row is
+ * treated as garbage — small next to the 30-day retention it is compared against, and large next to any
+ * polling interval a driver would sanely use.
+ */
+export declare const USAGE_WINDOW_REAP_MARGIN_MS: number;
+/** design/80 D-2 (BLOCKER): abandonment TTL stamped on an UNATTENDED human/irreversible_ask suspend (no
+ *  `durableApproval` = no operator/resolver wired). Without it the checkpoint has `deadline=undefined` and the
+ *  reaper (which filters on a non-null deadline) can NEVER GC it → a pinned session + a stranded paused VM +
+ *  an orphan checkpoint leak forever. A `durableApproval` suspend keeps the operator's `ttlMs` (undefined =
+ *  unbounded by the operator's choice; D-D `terminalAt` is the eventual liveness backstop there). 30 days. */
+export declare const DEFAULT_UNATTENDED_APPROVAL_TTL_MS: number;
+/**
+ * RB-68 (2026-07-25, red probe): a caller-supplied TTL is only a TTL if it is a finite, positive number.
+ * `TaskSpec.durableApproval.ttlMs` / `resourceSuspend.ttlMs` are typed as a bare `number`, and the mint
+ * arithmetic was `Date.now() + ttlMs` with NO validation — so `Number(process.env.APPROVAL_TTL_MS)` on an
+ * unset/malformed env var (a config-center miss, an upstream arithmetic slip) silently produced
+ * `deadline = NaN`. Every reaper comparison is `deadline <= cutoff`, and `NaN <= anything` is FALSE, so a
+ * checkpoint that LOOKS bounded (it carries a ttlMs and a deadline) became permanently IMMORTAL: no reap
+ * cutoff, however far in the future, could ever expire it → a pinned session + a stranded paused VM, and
+ * a misconfigured deployment silently defeating its own abandoned-approval cleanup with no error anywhere.
+ *
+ * Handling follows the codebase's established treatment of malformed numeric config — sanitize to the
+ * documented default rather than throw — `task-registry-shared.ts`'s `TASK_OUTPUT_DEFAULT_CHARS` fallbacks
+ * (non-numeric / non-finite / non-positive all return the documented default) and `media-byte-cap.ts`'s
+ * `!Number.isFinite(limitBytes) || limitBytes <= 0` guard are the two live precedents: garbage in a bound
+ * field must never widen the bound, and
+ * killing an in-flight task over it would cost more than it saves. `undefined` (the deliberate
+ * "unbounded, D-D terminalAt is the backstop" choice) is preserved as-is and is NOT what this rejects.
+ */
+export declare function sanitizedTtlMs(ttlMs: number | undefined): number | undefined;
+/**
+ * WHICH tool call a committed durable park is holding this run — `undefined` when nothing parked, or
+ * when the park that did commit holds no call (a resource slice, a plan review).
+ *
+ * SINGLE derivation on purpose. Two consumers need this answer: the abort-classification seam, which
+ * stamps it into the `details` of the results the loop mints for the contaminated siblings, and the
+ * `tool_end` projection, which puts it on the wire. Reading it from one function keeps the two from
+ * disagreeing about what a pause with no call means. They are not otherwise
+ * interchangeable: the frame face applies strictly narrower conditions on top of this answer (see
+ * `tool_end.gatedCallId`), so a frame may omit an id this function returns — never the reverse.
+ * "Which holder wins" is no longer a question: there is one holder, and a pause that holds no call
+ * publishes absence.
+ *
+ * The frame side must not read the id back out of a tool RESULT even though the marker is there: a
+ * result's `details` is written by the tool (and replaceable by post-tool hooks), so lifting a
+ * cross-call attribution from it would let any failing tool name an arbitrary call and put a phantom
+ * approval wait on someone else's frame. Same rule, same reason, as `tool_end.gate`.
+ *
+ */
+export declare function gatedCallIdOf(p: Pick<Prepared, "pausedRef">): string | undefined;
+/**
+ * The abort-classification marker for the loop's short-circuit "Operation aborted" family: when a gate
+ * committed a durable park this run (`pausedRef.current`, whatever the pause's kind), the contaminated
+ * sibling frames carry something a consumer can key
+ * on instead of parsing the (contract-stable) result text (ruled 2026-08-04). The commit is published
+ * BEFORE the abort fires, so this read is race-free at mint time.
+ *
+ * `gatedCallId` NAMES the call the gate is holding, so a consumer can attribute a contaminated frame to
+ * its cause instead of inferring the pair from batch adjacency. Absent, never approximated: a park that
+ * holds no tool call (a resource slice, a plan review) publishes no id, and this marker does not invent
+ * one from whatever call happens to be in flight.
+ *
+ * Module-level rather than a closure in `prepareTask` (design/238 D-7: extract, don't accrete) — the
+ * marker's shape and its rules belong beside {@link gatedCallIdOf}, the derivation it reads.
+ */
+export declare function parkContaminationMarker(refs: Pick<Prepared, "pausedRef">): Record<string, unknown> | undefined;
+/**
+ * THE COMMIT-SIDE PUBLICATION. Called AFTER `commitSuspendSaga` returns true (the checkpoint is durably
+ * committed) to publish the run's one committed pause for the run loop's terminal assembly. There is no
+ * routing: the cause carries the committed gate whole, and WHICH terminal status it reads
+ * (`suspended` / `needs_review`) is the gate kind's registry row — the two holders the review family and
+ * the approval family used to be split across, and the branch that chose between them, are gone.
+ * (Review checkpoints themselves are minted by a PROFILE, out of core scope; core owns this seam and the
+ * gate/status/resume discriminants.)
+ *
+ * Module-level, taking the holder as a parameter (design/238 D-7: extract, don't accrete) — beside the
+ * two readers of what it publishes ({@link gatedCallIdOf}, {@link parkContaminationMarker}).
+ */
+export declare function publishCommittedSuspend(refs: Pick<Prepared, "pausedRef">, token: CheckpointToken, gate: CheckpointGate, scope: string, remoteHandle: WorkspaceHandle | undefined, checkpointId?: string, 
+/** The COMMITTED row's pendingAction — passed whole, not as a pre-extracted id, so no call site can
+ *  hand this seam an id the committed row does not actually park on. */
+pendingAction?: PendingAction): void;

package/dist/core/runner/park-commit.js

@@ -0,0 +1,31 @@
+export const DEFAULT_RESOURCE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const USAGE_WINDOW_REAP_MARGIN_MS = 60 * 60 * 1000;
+export const DEFAULT_UNATTENDED_APPROVAL_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export function sanitizedTtlMs(ttlMs) {
+    if (ttlMs === undefined)
+        return undefined;
+    return Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : DEFAULT_RESOURCE_TTL_MS;
+}
+export function gatedCallIdOf(p) {
+    return p.pausedRef.current?.gatedCallId;
+}
+export function parkContaminationMarker(refs) {
+    if (refs.pausedRef.current === undefined)
+        return undefined;
+    const gatedCallId = gatedCallIdOf(refs);
+    return { code: "gate.parked", ...(gatedCallId !== undefined ? { gatedCallId } : {}) };
+}
+export function publishCommittedSuspend(refs, token, gate, scope, remoteHandle, checkpointId, pendingAction) {
+    const pause = {
+        cause: {
+            kind: "paused",
+            gate,
+            token,
+            ...(checkpointId !== undefined ? { checkpointId } : {}),
+            ...(remoteHandle !== undefined ? { restoreMode: remoteHandle.restoreMode === "park_only" ? "park_only" : "snapshot" } : {}),
+        },
+        scope,
+        ...(pendingAction?.kind === "tool_approval" ? { gatedCallId: pendingAction.toolCallId } : {}),
+    };
+    refs.pausedRef.current = pause;
+}

package/dist/core/runner/{prepare-permission-rules.d.ts → permission-rule-lanes.d.ts}

@@ -1,5 +1,6 @@
 /**
- * design/389 — prepare's permission-rule phase: the TWO gate lanes the unified store feeds.
+ * design/389 — the permission-rule LANES the unified store feeds (prepare-path machinery, design/390 L1): the two gate
+ * lanes, and — since the policy-chain phase took the chain assembly — the rule-offer factory every ask-mint site calls.
  *
  * `prepareTask` used to assemble the personal lane inline (a store read + a hand-spliced session
  * overlay + two admission arms) and the org lane from a second seam. Both now read the ONE store query —
@@ -23,8 +24,8 @@
  * silence the ungated-write warning for deployments that wired no policy at all.
  */
 import type { AskRuleEvidence, ToolCallRequest } from "../tool-policy.js";
-import type { OrgGateVerdict, PersistedRuleAnswer, PersistedRuleHit } from "../hooks.js";
-import type { PersistedAllowRule } from "../permission-rule-model.js";
+import { persistedRuleMandateOf, type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit } from "../hooks.js";
+import type { PersistedAllowRule, RuleOffer, SegmentCoverage } from "../permission-rule-model.js";
 import { type OrgRuleResolution } from "../permission-rule-org.js";
 import type { PermissionRuleStoreProvider } from "../permission-rule-provider.js";
 /** The one SHELL tool the persisted-rule lane speaks for. */
@@ -130,3 +131,108 @@ export declare function createPermissionRuleLanes(cfg: {
      *  lane took the read. */
     onDisclosure: (message: string) => void;
 }): PermissionRuleLanes;
+/** The closed reason set for the rule-offer factory's empty answer (#490 修②) — the same three
+ *  spellings the `AskRequest` and durable-row seats declare, kept at the one factory that fills both.
+ *  Deliberately not exported: this is a wire vocabulary, and its two faces declare it literally (the
+ *  `previewWithheld` precedent) so a consumer reads the closed set on the type it is holding rather
+ *  than through an import. */
+type RuleOffersAbsence = "mandated" | "lane_cannot_speak" | "shadowed";
+/** The surviving-ask facts the rule-offer factory reads (see {@link createRuleOffersOf}): the
+ *  synchronous mint sites spread the surviving decision, which carries them; the park leg threads
+ *  each as its own parameter. */
+interface RuleOffersAskFacts {
+    requiresRealApproval?: boolean;
+    persistedRuleShadowed?: string;
+    decisionReason?: import("../tool-policy.js").DecisionReason;
+    /** #457 ④: an EXPLICIT `ask` permission rule matched this call (design/127 DSL, stamped at
+     *  the rule policy's three matched-ask exits — bare, covering and param). */
+    matchedAskRule?: string;
+    /** #502: the engine-stamped probe mandate (the reversibility probe declared this call's
+     *  demotion structural — for the built-in shell probe, a read outside the session's
+     *  allowed directories). */
+    probeMandated?: boolean;
+    inheritedUnresolved?: boolean;
+    /** The ask is being resolved at an ANCESTOR's frozen approver (the three inherited-lane
+     *  mint sites pass it literally) — this task's rule lane never adjudicates it. */
+    ancestorResolved?: boolean;
+    /** design/375 §5.2②: the surviving ask's engine-stamped per-segment coverage table — the
+     *  batch offer carries exactly the segments this table calls uncovered. Absent ⇒ all
+     *  segments read as uncovered (over-offer, the safe direction). */
+    segmentCoverage?: readonly SegmentCoverage[];
+}
+/**
+ * design/179 §4 — the rule forms that could cover this exact call, for a surface's "stop asking me
+ * this" option (extracted from the prepare body, the spliceSessionOverlayRows precedent; the maker
+ * captures the per-task wiring once and the returned factory serves all five ask-mint sites — the
+ * approval-preview field is a standing example of what happens otherwise: it reached two of the
+ * five, so a delegated child's card was silently poorer than the top-level one).
+ *
+ * Empty unless a rule lane is armed — offering an option that redemption would refuse is worse than
+ * offering none — and empty for any call the lane cannot speak for (a compound, a redirection, a
+ * substitution, or a tool that is not the shell tool).
+ *
+ * Empty, too, on any ask a persisted rule could never CLEAR — "allow rules silence the classifier's
+ * questions, never a mandated one". Two doors, matching the two halves of that boundary:
+ *  · the marks half, judged from the SAME resolved sources the gate input is built from, through the
+ *    gate's own single-source predicate (an operator's shellGate:"always", the tool's own
+ *    egress/irreversibility marks, and — #502 — the PER-CALL member that predicate also takes: a
+ *    demotion this call's reversibility probe declared structural, read off the ask the gate
+ *    stamped rather than off the tool seat, because it is true of one call and not of the seat) —
+ *    a drift here would offer a rule the lane then refuses to honor;
+ *  · the decision half (`ask`, REQUIRED at every mint site so a site added later cannot skip it):
+ *    `requiresRealApproval` (org/governance — only judgment clears it), the shadowed-rule
+ *    disclosure (the standing proof that a matching rule does not clear THIS ask), a hook-raised
+ *    ask (`decisionReason === "hook"` — the lane's own clearing conjuncts refuse hook asks, so a
+ *    rule minted from one would never silence it), an EXPLICIT `ask` rule match (`matchedAskRule`
+ *    — see below), and an inherited-unresolved marked call (the
+ *    ask is an ANCESTOR's authority, which this task's rule lane never adjudicates). Offering
+ *    "stop asking me this" on a card that will keep asking lets a person mint a rule that never
+ *    takes effect where they minted it.
+ *
+ * #457 ④ (CC 2.1.245 toolPolicy 对表, F11: "wildcard `ask` … keeps every matching tool behind a
+ * per-call prompt (no persistent always-allow)") — `matchedAskRule` was the one conjunct of the
+ * lane's own clearing predicate this door did not mirror, and the asymmetry was live: the
+ * persisted-rule lane refuses to clear ANY ask carrying it (`hooks.ts`, the
+ * `decision.matchedAskRule === undefined` conjunct on its allow arm), so a person who wrote a
+ * standing `Bash` `ask` rule and had no allow rule yet was still offered "allow, and stop asking
+ * me this" — and the rule they minted came back on the very next call as a SHADOWED match
+ * (`persistedRuleShadowed`, which this door was already refusing). The offer was only ever
+ * suppressed one call too late, after the useless rule existed. The shadowed conjunct stays: it
+ * covers the person who ALREADY has the allow rule; this one covers the person about to mint it.
+ *
+ * #490 修② — every door above that answers "no offers" now also names WHICH door, on the
+ * `ruleOffersAbsence` seat (`AskRequest`'s and the durable row's, ONE factory so the two faces
+ * cannot disagree). The doctrine it serves is the loud-bad-value one, applied to an absence: a
+ * surface reading an empty card could not tell "there is nothing this lane could offer" from
+ * "offers were deliberately suppressed", and a person reading it could not tell "write the rule
+ * yourself" from "no rule can excuse this approval". The seat is CLOSED
+ * (`mandated | lane_cannot_speak | shadowed`), mutually exclusive with `ruleOffers` by
+ * construction, and structural-door silent (see the first two guards).
+ */
+export declare function createRuleOffersOf(cfg: {
+    /** `permissionRuleLane !== undefined` at wiring time — the armed-lane structural door. */
+    laneArmed: boolean;
+    principal: string | undefined;
+    /** `deps.localOwnerRules === true` — the declared local-owner exception to the anonymous floor. */
+    localOwnerDeclared: boolean;
+    /** The live mark sources the gate input is built from — passed as REFERENCES (read per call, so a
+     *  late-registered tool seat is seen exactly as the gate sees it). */
+    egressTools: {
+        has(name: string): boolean;
+    };
+    irreversibilityTier: {
+        get(name: string): Parameters<typeof persistedRuleMandateOf>[0]["irreversibility"];
+    };
+    shellGatedBash: boolean;
+    taskRoot: string | undefined;
+    /** The live tracked-cwd ref (read per call — the relative-cd resolution base, adversarial-review P1/r3). */
+    cwdRef: {
+        current: string;
+    } | undefined;
+    deniesDirectoryRead: ((directory: string) => boolean) | undefined;
+}): (toolName: string, args: unknown, ask: RuleOffersAskFacts | undefined) => {
+    ruleOffers?: readonly RuleOffer[];
+    ruleOffersAbsence?: RuleOffersAbsence;
+    execCwd?: string;
+};
+export {};

package/dist/core/runner/{prepare-permission-rules.js → permission-rule-lanes.js}

@@ -1,4 +1,5 @@
-import { directoryRuleAdmits, eligiblePersisted, findAdmittingRule, lexicalNormalAbsolutePathOf, segmentCoverageOf } from "../permission-rule-model.js";
+import { persistedRuleMandateOf } from "../hooks.js";
+import { directoryRuleAdmits, eligiblePersisted, findAdmittingRule, lexicalNormalAbsolutePathOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 export const PERSISTED_RULE_TOOL = "Bash";
 export const DIRECTORY_RULE_TOOL = "Read";
@@ -138,3 +139,48 @@ export function createPermissionRuleLanes(cfg) {
         : undefined;
     return { personal, org };
 }
+export function createRuleOffersOf(cfg) {
+    return (toolName, args, ask) => {
+        if (!cfg.laneArmed || toolName !== PERSISTED_RULE_TOOL)
+            return {};
+        if ((cfg.principal === undefined || cfg.principal === "") && !cfg.localOwnerDeclared)
+            return {};
+        const closedDoor = (() => {
+            if (ask?.requiresRealApproval === true)
+                return "mandated";
+            if (ask?.persistedRuleShadowed !== undefined)
+                return "shadowed";
+            if (ask?.decisionReason === "hook")
+                return "mandated";
+            if (ask?.matchedAskRule !== undefined)
+                return "shadowed";
+            if (ask?.inheritedUnresolved === true)
+                return "mandated";
+            if (ask?.ancestorResolved === true)
+                return "mandated";
+            return undefined;
+        })();
+        if (closedDoor !== undefined)
+            return { ruleOffersAbsence: closedDoor };
+        if (persistedRuleMandateOf({
+            egress: cfg.egressTools.has(toolName),
+            irreversibility: cfg.irreversibilityTier.get(toolName),
+            shellGated: cfg.shellGatedBash,
+            probeMandated: ask?.probeMandated === true,
+        }) !== undefined) {
+            return { ruleOffersAbsence: "mandated" };
+        }
+        const command = args?.command;
+        if (typeof command !== "string")
+            return { ruleOffersAbsence: "lane_cannot_speak" };
+        const offers = suggestRulesForCommand(command, {
+            ...(ask?.segmentCoverage !== undefined ? { coverage: ask.segmentCoverage } : {}),
+            ...(cfg.taskRoot !== undefined ? { scope: { kind: "project", root: cfg.taskRoot }, cwd: cfg.taskRoot } : {}),
+            ...(cfg.cwdRef?.current !== undefined ? { execCwd: cfg.cwdRef.current } : {}),
+            ...(cfg.deniesDirectoryRead !== undefined ? { deniesDirectoryRead: cfg.deniesDirectoryRead } : {}),
+        });
+        return offers.length > 0
+            ? { ruleOffers: offers, ...(cfg.cwdRef?.current !== undefined ? { execCwd: cfg.cwdRef.current } : {}) }
+            : { ruleOffersAbsence: "lane_cannot_speak" };
+    };
+}

package/dist/core/runner/prepare-ask-lane.d.ts

@@ -0,0 +1,107 @@
+/**
+ * design/390 §1.2 M19 (ask lane) — prepareTask's IN-STREAM ASK LANE, verbatim from the driver's gate-machinery block:
+ * the per-call signal composition bound to this task's run signal, the abort-bound `adjudicate` wrapper (the budget
+ * snapshot and the live tracked cwd stamped onto every request), the approval-preview projection over the live roster,
+ * the `resolveAskBound` mint (the inherited-unavailable intercept, the duplicate-frame grant reuse, the human-review
+ * ledger, the bare-human-rejection record), the pre-wrapped deny observer and the hook-crash notifier. The three
+ * module-scope helpers only this segment called moved with it (the deny-observer factory, the preview sanitizer and
+ * resolver). The interface is the dependency list the segment had implicitly (design/238 R-1) — the closures below
+ * used to capture every seat here off the driver's scope.
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (every await lives inside the closures
+ * it builds, which run per tool call), so the phase adds no yield between the wiring-manifest station before it and
+ * the suspend saga after it (design/390 §1.5: a stretch with no await is extracted as a sync function). Read-stability
+ * of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * The lane exists exactly when the wiring-manifest phase's `gateMachineryActive` holds — the driver's `if` around the
+ * whole block became this phase's one early return (the block's other four phases key off the lane's presence), so
+ * the orchestrator grows no branch.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { AutoModeDenialTracker } from "../auto-mode.js";
+import { type Hooks } from "../hooks.js";
+import { type OnAsk, type ToolCallRequest, type ToolPolicy } from "../tool-policy.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import type { AskLane, Prepared } from "./contracts.js";
+import { consumeInheritedAskGrant } from "./inherited-ask-grants.js";
+import type { createRuleOffersOf } from "./permission-rule-lanes.js";
+export interface PrepareAskLaneInput {
+    /** borrowed-readonly — the wiring-manifest phase's ONE activation predicate; false ⇒ this phase builds nothing and
+     *  returns an absent lane. */
+    gateMachineryActive: boolean;
+    /** borrowed-readonly — prepare's abort seat; only `.signal` is read (composed into every per-call signal and bound
+     *  onto the deny observer). Never aborted here. */
+    abortController: {
+        readonly signal: AbortSignal;
+    };
+    /** borrowed-readonly — the policy chain's effective policy, or undefined (then no `adjudicate` wrapper is built and
+     *  the gate reads a missing policy as allow). Called at RUN time, per tool call, through the abort-bound wrapper. */
+    effectivePolicy: ToolPolicy | undefined;
+    /** borrowed-readonly — the per-leg-immutable durable budget snapshot stamped onto EVERY adjudicated request. Same
+     *  object every call; the policy cannot write it back. */
+    budgetSnapshot: NonNullable<ToolCallRequest["budget"]>;
+    /** borrowed-readonly — the hand's live tracked cwd, or undefined (hands-less). Read per call at RUN time (`current`),
+     *  never captured: the fs hand tools resolve their relative paths against this very ref. Not written here. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the shared mount roster; read at RUN time by the approval-preview projection (alias-aware
+     *  lookup over whatever the roster holds when the ask is minted). Never mutated here. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the inherited-unavailable marker set. Writer here: `resolveAskBound` consumes (`delete`) a
+     *  marked call at its fail-closed intercept; the policy-chain phase records, the gate station sweeps. */
+    inheritedUnavailableAsks: Set<string>;
+    /** borrowed-mutable — the duplicate-frame ask-grant record. Writer here: the grant-reuse consume half
+     *  (`consumeInheritedAskGrant`); the policy-chain phase records, the gate station sweeps. */
+    inheritedAskGrants: Parameters<typeof consumeInheritedAskGrant>[0];
+    /** borrowed-readonly — the run's own approver seat (spec over deps), or undefined: the resolve target, the
+     *  live-approver test the carry mint reads, and the grant-reuse identity law's approver. */
+    onAsk: OnAsk | undefined;
+    /** borrowed-mutable — the per-task human-review accumulator (`Prepared.humanReviewRef`). Writers here: every
+     *  synchronous resolve that a person actually judged (count / totalWaitMs / gates push); runtask adds the durable
+     *  resume latency. */
+    humanReviewRef: Prepared["humanReviewRef"];
+    /** borrowed-readonly — the injectable wall clock every human-time observable reads (`Prepared.now`). */
+    now: () => number;
+    /** borrowed-readonly — the policy-chain phase's rule-offer factory (the suggestion members the ask mint threads). */
+    ruleOffersOf: ReturnType<typeof createRuleOffersOf>;
+    /** borrowed-readonly — the policy-chain phase's Runner-filled source identity (one factory, every ask mint site). */
+    askSourceIdentity: () => {
+        principal?: string;
+        sourceTaskId?: string;
+        fromSubagent?: true;
+        sourceAgentName?: string;
+        isDelegatedChild?: true;
+    };
+    /** borrowed-readonly — the policy-chain phase's per-tool risk-axes projection (`riskAxes` on the ask). */
+    riskAxesOf: (toolName: string) => {
+        riskAxes?: {
+            irreversible?: boolean;
+            egress?: boolean;
+        };
+    };
+    /** borrowed-mutable — the auto-mode denial tracker, or undefined. Writer here: the carry mint arms the auto-deny
+     *  window on it iff the seat about to be called is live (the tracker's one writer). */
+    autoModeDenialTracking: AutoModeDenialTracker | undefined;
+    /** borrowed-readonly — the REBOUND spec; only `taskId` is read (the late-settlement observer's tag). */
+    spec: Pick<TaskSpec, "taskId">;
+    /** borrowed-readonly — the deployment seats this lane reports on, as a Pick over the SAME `deps` object (receiver
+     *  preserved for `deps.onError?.()`): the late-settlement observer's notice/error sinks and the hook-crash notifier. */
+    deps: Pick<RunnerDeps, "onNotice" | "onError">;
+    /** borrowed-readonly — the acquired session id (the observer's tag, the hook-phase error tag). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (the observer's tag). */
+    runId: string;
+    /** borrowed-readonly — the resolved hook record; only `permissionDenied` is read (the deny observer's seat). */
+    hooks: Hooks | undefined;
+    /** borrowed-readonly — the validated per-prepare hook seat bound (the deny observer's timeout). */
+    hookTimeoutMs: number;
+    /** borrowed-readonly — the own hook-crash reporter (the deny observer's swallow-guarded report sink). */
+    notifyOwnHookCrash: (err: unknown) => void;
+}
+export interface PrepareAskLaneResult {
+    /** owned — the lane, or undefined exactly when `gateMachineryActive` is false (then the suspend saga, the boundary
+     *  parks, the park closure and the gate station are not built either — they key off this seat). */
+    askLane: AskLane | undefined;
+}
+/** The M19 ask-lane phase body — prepareTask's in-stream ask stretch, verbatim (see the module header). */
+export declare function prepareAskLane(input: PrepareAskLaneInput): PrepareAskLaneResult;

package/dist/core/runner/prepare-ask-lane.js

@@ -0,0 +1,131 @@
+import { primaryActivityArg } from "../arg-summary.js";
+import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
+import { isLiveApproverSeat, resolveAsk } from "../tool-policy.js";
+import { composeCallSignal, raceAbort } from "./abort-race.js";
+import { gateAskCarry, lateAskSettlementObserver } from "./denial-limit-arms.js";
+import { consumeInheritedAskGrant } from "./inherited-ask-grants.js";
+function createDenyObserverNotifier(hooks, hookTimeoutMs, signal, report) {
+    if (hooks?.permissionDenied === undefined)
+        return undefined;
+    return async (payload) => {
+        try {
+            const seat = await runHookSeat("permissionDenied", { timeoutMs: hookTimeoutMs, signal }, (sig) => hooks.permissionDenied({ ...payload, signal: sig }));
+            if (seat.expired)
+                report(hookSeatExpiredError("permissionDenied", hookTimeoutMs, seat.cause, "the deny observation was abandoned; the deny itself is unchanged"));
+        }
+        catch (err) {
+            report(err);
+        }
+    };
+}
+const sanitizePreview = (node, depth = 0) => {
+    if (depth > 6)
+        return undefined;
+    if (typeof node === "string") {
+        return node.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "\u2400");
+    }
+    if (node === null || typeof node !== "object")
+        return node;
+    if (Array.isArray(node))
+        return node.map((v) => sanitizePreview(v, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        out[sanitizePreview(k, depth + 1)] = sanitizePreview(v, depth + 1);
+    }
+    return out;
+};
+function resolveApprovalPreview(tools, toolName, args) {
+    const t = tools.find((x) => x.name === toolName || (x.aliases?.includes(toolName) ?? false));
+    if (t?.approvalPreview === undefined)
+        return {};
+    try {
+        const raw = t.approvalPreview(args);
+        if (raw === undefined)
+            return {};
+        const bytes = JSON.stringify(raw);
+        if (bytes === undefined)
+            return { withheld: "unavailable" };
+        if (bytes.length > 16_384) {
+            return { preview: { truncated: true, note: `approval preview exceeded 16KiB (${bytes.length} chars serialized)` }, withheld: "oversize" };
+        }
+        return { preview: sanitizePreview(raw) };
+    }
+    catch {
+        return { withheld: "unavailable" };
+    }
+}
+export function prepareAskLane(input) {
+    const { gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash } = input;
+    if (!gateMachineryActive)
+        return { askLane: undefined };
+    const composedCallSignal = (callSignal) => composeCallSignal(abortController.signal, callSignal);
+    const adjudicate = effectivePolicy
+        ? (req, callSignal) => {
+            const signal = composedCallSignal(callSignal);
+            return raceAbort(Promise.resolve(effectivePolicy.check({ ...req, budget: budgetSnapshot, ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}) }, signal)), signal, () => ({
+                action: "deny",
+                message: "policy check aborted (task timed out or cancelled)",
+            }));
+        }
+        : undefined;
+    const approvalPreviewOf = (toolName, args) => resolveApprovalPreview(tools, toolName, args);
+    const resolveAskBound = async (decision, req, callSignal) => {
+        if (inheritedUnavailableAsks.delete(req.toolCallId)) {
+            return {
+                action: "deny",
+                message: `approval for "${req.toolName}" requires an ancestor task's approval that cannot be resolved here ` +
+                    `(no live approver reachable, or a durable-park mandate applies), and no durable approval park is ` +
+                    `available — denied fail-closed (the inherited constraint stands).`,
+                decisionReason: "mode",
+                settlement: { kind: "approver_unavailable", who: { party: "none" }, when: now() },
+                approverUnavailable: true,
+            };
+        }
+        const grantReuse = consumeInheritedAskGrant(inheritedAskGrants, onAsk, humanReviewRef, decision, req);
+        if (grantReuse !== undefined)
+            return grantReuse;
+        const t0 = now();
+        const resolved = await resolveAsk({
+            toolName: req.toolName,
+            toolCallId: req.toolCallId,
+            args: req.args,
+            ...(() => {
+                const p = approvalPreviewOf(req.toolName, req.args);
+                return { ...(p.preview !== undefined ? { preview: p.preview } : {}), ...(p.withheld !== undefined ? { previewWithheld: p.withheld } : {}) };
+            })(),
+            ...ruleOffersOf(req.toolName, req.args, decision.action === "ask" ? decision : undefined),
+            message: decision.message ?? `approval required for "${req.toolName}"`,
+            ...askSourceIdentity(),
+            ...riskAxesOf(req.toolName),
+            ...(decision.action === "ask" && decision.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+            ...(decision.action === "ask" && decision.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: decision.persistedRuleShadowed } : {}),
+            ...(decision.action === "ask" ? gateAskCarry(decision, isLiveApproverSeat(onAsk), autoModeDenialTracking) : {}),
+            ...(decision.action === "ask" && decision.probeReason !== undefined ? { probeReason: decision.probeReason } : {}),
+            ...(decision.action === "ask" && decision.probeCause !== undefined ? { probeCause: decision.probeCause } : {}),
+            ...(decision.action === "ask" && decision.ruleEvidence !== undefined ? { ruleEvidence: decision.ruleEvidence } : {}),
+        }, onAsk, composedCallSignal(callSignal), lateAskSettlementObserver({ toolName: req.toolName, toolCallId: req.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
+        const waitMs = Math.max(0, now() - t0);
+        if (resolved.approverUnavailable !== true && resolved.settlement?.kind !== "task_aborted") {
+            humanReviewRef.count += 1;
+            humanReviewRef.totalWaitMs += waitMs;
+            const toolArg = primaryActivityArg(req.args);
+            humanReviewRef.gates.push({
+                kind: "human",
+                waitMs,
+                decision: resolved.action === "allow" ? "allow" : "deny",
+                toolName: req.toolName,
+                ...(toolArg !== undefined ? { toolArg } : {}),
+            });
+        }
+        return resolved;
+    };
+    const notifyPermissionDenied = createDenyObserverNotifier(hooks, hookTimeoutMs, abortController.signal, notifyOwnHookCrash);
+    const notifyHookError = (err) => {
+        try {
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "hook", sessionId });
+        }
+        catch {
+        }
+    };
+    return { askLane: { composedCallSignal, adjudicate, approvalPreviewOf, resolveAskBound, notifyPermissionDenied, notifyHookError } };
+}