@sema-agent/core 7.40.1 → 7.41.0

package/dist/core/runner/call-hook-stations.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The per-call hook stations a tool call passes OUTSIDE the tool gate. ONE rule for every executed call, live or
+ * approved on a parked checkpoint: before it runs, the PreToolUse screening seat; after it runs, the `tool_result`
+ * station (the PostToolUse / PostToolUseFailure seats and the PreToolUse context drain).
+ *  · a LIVE call meets the screening inside the gate and the station through the loop's finalize (the gate-stations
+ *    phase registers the station on the harness);
+ *  · an APPROVED call meets {@link createApprovedCallScreen} — the SAME seat (`createPreToolUseScreening`), folded under
+ *    the decide that approved it — and the station through `AgentHarness.finalizeToolCall`, the loop's own finalize.
+ */
+import type { DocumentContent, ImageContent, TextContent } from "../../internal/llm.js";
+import { type HookEnvCapabilities, type HookInvocationIdentity, type Hooks } from "../hooks.js";
+import type { PermissionModeController } from "../mode-policy.js";
+import type { TaskSpec } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import { type ToolRosterDeltaSeat } from "../tool-roster.js";
+import { type FrameSettlement } from "../frame-settlement.js";
+import type { Prepared } from "./contracts.js";
+import type { Checkpoint } from "../checkpoint-store.js";
+/** One executed call's result as the station reads it (the harness `tool_result` event's members). */
+export interface ToolResultSeatEvent {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    content: Array<TextContent | ImageContent | DocumentContent>;
+    details: unknown;
+    isError: boolean;
+}
+/** The station: the patch the loop applies to the result (`undefined` = unchanged). */
+export type ToolResultStation = (e: ToolResultSeatEvent) => Promise<{
+    content: Array<TextContent | ImageContent | DocumentContent>;
+} | undefined>;
+export interface ToolResultStationInput {
+    /** borrowed-readonly — the resolved hook record: the two post seats and the failure seat, called through the record. */
+    hooks: Hooks | undefined;
+    /** borrowed-mutable — the blocked/suspended call ids. Writer here: the one-shot `delete`. */
+    blockedToolCalls: Set<string>;
+    /** borrowed-readonly — the leg's delta seat: the post seats receive the call's wire name off its current roster. */
+    toolRosterDeltas: ToolRosterDeltaSeat;
+    /** borrowed-mutable — PreToolUse `additionalContext` per call id. Writer here: the one-shot drain (`delete`). */
+    preToolContexts: Map<string, string[]>;
+    /** borrowed-readonly — the validated per-prepare hook seat bound. */
+    hookTimeoutMs: number;
+    /** borrowed-readonly — prepare's abort seat; `.signal` bounds the post seats and is the failure seat's interrupt fact. */
+    abortController: {
+        readonly signal: AbortSignal;
+    };
+    /** borrowed-readonly — the REBOUND spec's `signal` (the failure seat's interrupt fact). */
+    spec: Pick<TaskSpec, "signal">;
+    /** borrowed-readonly — the hand's live tracked cwd, or undefined; `current` is read per post seat. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the env face the post seats' contexts carry, or undefined. */
+    hookEnvFace: HookEnvCapabilities | undefined;
+    /** borrowed-readonly — the leg's identity envelope every HookToolContext carries. */
+    hookIdentity: HookInvocationIdentity;
+    /** borrowed-readonly — the leg's live permission-mode seat (each context reads `observed`). */
+    permissionMode: PermissionModeController;
+    /** borrowed-readonly — where an expired post seat is reported (the leg's own hook-crash lane). */
+    notifyOwnHookCrash: (err: unknown) => void;
+    /** borrowed-readonly — the leg's reminder provenance mark (every hook context line carries it). */
+    reminderMark: string;
+    /** borrowed-mutable — the leg's settlement seam. Writer here: a carrier whose output a host hook rewrote (`noteHostRewrite`). */
+    frameSettlement: FrameSettlement;
+}
+/** The `tool_result` station, or undefined when no post / screening hook is wired (nothing to register). */
+export declare function createToolResultStation(input: ToolResultStationInput): ToolResultStation | undefined;
+/** What the resumed leg does with the approved call: refuse it with a sentence (it is NOT executed), or run these bytes.
+ *  `admit` stashes the screen's context for the result's drain — called only once the call is past every belt and about
+ *  to run (a refused call stashes nothing, the live gate's rule). */
+export type ApprovedCallScreen = NonNullable<Prepared["approvedCallScreen"]>;
+export type ApprovedCallVerdict = Awaited<ReturnType<ApprovedCallScreen>>;
+export interface ApprovedCallScreenInput {
+    /** borrowed-readonly — the face the gate screens with (the observational wrapper when declared; the leg's mode on every context). */
+    preToolUse: Hooks["preToolUse"] | undefined;
+    /** borrowed-readonly — the validated per-prepare hook seat bound. */
+    hookTimeoutMs: number;
+    /** borrowed-readonly — prepare's abort seat (the screening seat is abort-ended on it). */
+    abortController: {
+        readonly signal: AbortSignal;
+    };
+    /** borrowed-readonly — the hand's live tracked cwd, or undefined. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the read-only env capability face, or undefined. */
+    hookEnvFace: HookEnvCapabilities | undefined;
+    /** borrowed-readonly — the leg's identity envelope. */
+    hookIdentity: HookInvocationIdentity;
+    /** borrowed-readonly — the own hook-crash reporter (a crashing or timed-out screening face is reported through it). */
+    notifyOwnHookCrash: (err: unknown) => void;
+    /** borrowed-mutable — PreToolUse `additionalContext` per call id. Writer here: `admit`'s stash (the station drains it). */
+    preToolContexts: Map<string, string[]>;
+}
+/**
+ * The approved call's PreToolUse screening — the gate's own seat, its answer FOLDED UNDER THE DECIDE that approved the
+ * call (the decide is the upper bound; the screen can only narrow): a deny, a crash, a silence or a refused answer
+ * refuses the call in the live gate's own sentences; an ask is the question the decide already answered — unless it
+ * demands a person and the decide was the deployment's policy (the one predicate every resume station holds a decide
+ * against); a rewrite is what executes when the decide carried none of its own (the person's bytes are the upper bound);
+ * context rides the result. Undefined when no face is wired.
+ */
+export declare function createApprovedCallScreen(input: ApprovedCallScreenInput): ApprovedCallScreen | undefined;
+/**
+ * Why the frozen inherited chain cannot judge bytes no gate judged (an approver's edit, the re-screen's rewrite): the
+ * row predates the chain, a layer is opaque, or a layer declares a live remainder — undefined when the frozen
+ * projections can judge them, or when no parent constraint binds. ONE rule for the pre-claim edit rung (which refuses
+ * the edit, the row pending) and the resumed leg's belt (which refuses a rewrite, the approval spent).
+ */
+export declare function chainCannotJudge(ig: Checkpoint["state"]["inheritedGate"]): string | undefined;

package/dist/core/runner/call-hook-stations.js

@@ -0,0 +1,118 @@
+import { createPreToolUseScreening, formatHookFeedback, hookSeatExpiredError, runHookSeat } from "../hooks.js";
+import { isEngineRefusal } from "../tool-policy.js";
+import { policyCannotAnswer } from "../real-approval.js";
+import { traceHookCrash } from "../gate-crash-trace.js";
+import { createSafeNotifier } from "../safe-notify.js";
+import { rosterToolName } from "../tool-roster.js";
+import { wireOf } from "../tool-name-readings.js";
+import { noteHostRewrite } from "../frame-settlement.js";
+export function createToolResultStation(input) {
+    const { hooks, blockedToolCalls, toolRosterDeltas, preToolContexts, hookTimeoutMs, abortController, spec, handsCwdRef, hookEnvFace, hookIdentity, permissionMode, notifyOwnHookCrash, reminderMark, frameSettlement } = input;
+    const toolResultStationArmed = Boolean(hooks?.postToolUse || hooks?.preToolUse || hooks?.postToolUseFailure);
+    if (toolResultStationArmed) {
+        return async (e) => {
+            if (blockedToolCalls.delete(e.toolCallId)) {
+                return undefined;
+            }
+            let content = e.content;
+            let changed = false;
+            const post = { toolName: rosterToolName(toolRosterDeltas.current, e.toolName) };
+            if (e.isError) {
+                if (hooks?.postToolUseFailure) {
+                    let clonedDetails = e.details;
+                    try {
+                        clonedDetails = structuredClone(e.details);
+                    }
+                    catch {
+                    }
+                    const failedName = wireOf("hook.postToolUseFailure", post);
+                    const failureSeat = await runHookSeat("postToolUseFailure", { timeoutMs: hookTimeoutMs, signal: abortController.signal }, (sig) => hooks.postToolUseFailure(failedName, e.input, {
+                        error: e.content
+                            .filter((c) => c.type === "text")
+                            .map((c) => c.text)
+                            .join("\n"),
+                        isInterrupt: abortController.signal.aborted || spec.signal?.aborted === true,
+                        content: e.content.map((c) => ({ ...c })),
+                        details: clonedDetails,
+                    }, { toolCallId: e.toolCallId, toolName: failedName, signal: sig, ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}), ...(hookEnvFace !== undefined ? { env: hookEnvFace } : {}), identity: hookIdentity, permissionMode: permissionMode.observed }));
+                    if (failureSeat.expired) {
+                        notifyOwnHookCrash(hookSeatExpiredError("postToolUseFailure", hookTimeoutMs, failureSeat.cause, "the observation was abandoned and its additionalContext dropped; the failure result itself is unchanged"));
+                    }
+                    const patch = failureSeat.expired ? undefined : failureSeat.value;
+                    if (patch?.additionalContext) {
+                        content = [...content, { type: "text", text: formatHookFeedback(patch.additionalContext, reminderMark) }];
+                        changed = true;
+                    }
+                }
+            }
+            else if (hooks?.postToolUse) {
+                const ranName = wireOf("hook.postToolUse", post);
+                const successSeat = await runHookSeat("postToolUse", { timeoutMs: hookTimeoutMs, signal: abortController.signal }, (sig) => hooks.postToolUse(ranName, e.input, { content: e.content, details: e.details, isError: e.isError }, { toolCallId: e.toolCallId, toolName: ranName, signal: sig, ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}), ...(hookEnvFace !== undefined ? { env: hookEnvFace } : {}), identity: hookIdentity, permissionMode: permissionMode.observed }));
+                if (successSeat.expired) {
+                    notifyOwnHookCrash(hookSeatExpiredError("postToolUse", hookTimeoutMs, successSeat.cause, "the seat was abandoned; the tool result is delivered to the model UNMODIFIED (no updatedOutput, no additionalContext)"));
+                }
+                const patch = successSeat.expired ? undefined : successSeat.value;
+                if (patch?.updatedOutput) {
+                    content = patch.updatedOutput;
+                    changed = true;
+                    noteHostRewrite(frameSettlement, e.toolCallId);
+                }
+                if (patch?.additionalContext) {
+                    content = [...content, { type: "text", text: formatHookFeedback(patch.additionalContext, reminderMark) }];
+                    changed = true;
+                }
+            }
+            const pre = preToolContexts.get(e.toolCallId);
+            if (pre) {
+                preToolContexts.delete(e.toolCallId);
+                content = [...content, ...pre.map((t) => ({ type: "text", text: formatHookFeedback(t, reminderMark) }))];
+                changed = true;
+            }
+            return changed ? { content } : undefined;
+        };
+    }
+    return undefined;
+}
+export function createApprovedCallScreen(input) {
+    const { preToolUse, hookTimeoutMs, abortController, handsCwdRef, hookEnvFace, hookIdentity, notifyOwnHookCrash, preToolContexts } = input;
+    if (preToolUse === undefined)
+        return undefined;
+    return async ({ toolCallId, toolName, args, decidedBy }) => {
+        const notifier = createSafeNotifier();
+        const seatInput = { event: { toolCallId, toolName, input: args }, ...(handsCwdRef !== undefined ? { trackedCwd: () => handsCwdRef.current } : {}), ...(hookEnvFace !== undefined ? { hookEnv: hookEnvFace } : {}), identity: hookIdentity, onHookError: notifyOwnHookCrash, abortSignal: abortController.signal };
+        const screening = createPreToolUseScreening(preToolUse, seatInput, hookTimeoutMs, notifier);
+        const subject = `this call to "${toolName}"`;
+        let r;
+        try {
+            const seat = await screening.screen(args);
+            if (seat.expired)
+                return { refused: await screening.unansweredReason(subject, seat.cause) };
+            r = screening.screened(seat.value);
+        }
+        catch (err) {
+            traceHookCrash(seatInput, err, notifier);
+            return { refused: screening.crashReason(subject, err) };
+        }
+        if (r !== undefined && isEngineRefusal(r))
+            return { refused: screening.refusedReason(r) };
+        if (r?.action === "deny")
+            return { refused: screening.deniedReason(r) };
+        if (r !== undefined && policyCannotAnswer(r, decidedBy))
+            return { refused: `a PreToolUse hook requires a person's approval for ${subject}, and this approval was the deployment's policy — not executed` };
+        const context = r?.additionalContext;
+        return { args: r?.updatedInput !== undefined ? r.updatedInput : args, admit: () => {
+                if (context)
+                    preToolContexts.set(toolCallId, [context]);
+            } };
+    };
+}
+export function chainCannotJudge(ig) {
+    if (ig?.requiresParentConstraint !== true)
+        return undefined;
+    const chain = ig.constraintChain;
+    if (chain === undefined)
+        return "the checkpoint predates the frozen projection chain (no constraintChain recorded)";
+    if (chain.some((e) => "opaque" in e))
+        return "the inherited chain carries an OPAQUE layer (no projection exported)";
+    return chain.some((e) => !("opaque" in e) && e.requiresLiveRemainder) ? "an inherited chain layer declares a live remainder beyond its projection" : undefined;
+}

package/dist/core/runner/contracts.d.ts

@@ -55,7 +55,7 @@ import type { ToolDisclosureManifest } from "../trace.js";
 import type { AgentDefinition, Brain, CompactOutcome, ModelRef, ModelRoles, NestedUsageAccum, PermissionMode, RunnerDeps, ShellGateDoctrine, TaskEvent, TaskEventIdentity, TaskResult, TaskSpec, TaskStream, ToolActivity, ToolEffect } from "../types.js";
 import type { PermissionModeController } from "../mode-policy.js";
 import type { WiringManifest } from "../wiring-manifest.js";
-import type { ActiveSkillFrame } from "./active-skill-scope.js";
+import type { SkillGateSeats, SkillGrantLane, SkillGrantRecord, SkillGrantSource } from "../skill-grant.js";
 import type { BudgetAxis } from "./assemble-result.js";
 import type { GitStatusLaneRef } from "./git-status-frame.js";
 import type { SessionReadFileStates } from "./session-read-file-states.js";
@@ -239,6 +239,8 @@ export type StopForDenialLimit = (info: {
     fallback: DenialLimitFallbackFace;
     settlement?: SettlementKind;
 }) => void;
+/** The gate's seat inputs for one call (the static seat or the `Skill` tool's per-call reader, and the run's skill rows). */
+export type GateSeatInputsFor = (calledName: string, wireName: string) => import("../mode-policy.js").PermissionSeatInputs & SkillGateSeats;
 export interface Prepared {
     harness: AgentHarness;
     /** The CONCRETE built-in session (engine-internal: prepare constructs/acquires `StoredSession` itself,
@@ -418,9 +420,14 @@ export interface Prepared {
      *  the run's settle, every terminal (suspend included), under the session lock; undefined argument
      *  (no commits) is a no-op. Synchronous, never throws. Absent ⇔ hands-less / no seat channel. */
     sealReadStateSeat?: (ownCommittedTailEntryId: string | undefined) => void;
-    /** The DENY-NARROWING layers (session rules + skill scope, deny-only). Re-checked on RESUME
-     *  before an approved pending tool executes, so a rule tightened during the suspend still applies. */
+    /** The DENY-NARROWING layers (session rules, inherited ancestor rules, the frozen constraint projections; deny-only).
+     *  Re-checked on RESUME before an approved pending tool executes, so a rule tightened during the suspend still applies. */
     denyNarrowingPolicy?: ToolPolicy;
+    /** The run's skill grant lane: its deny rows (a skill's `disallowed-tools`) are re-read on RESUME at the same station as the
+     *  person's deny rows, on the bytes that will run. */
+    skillGrants: SkillGrantLane;
+    /** The skills this leg loads (normalized, past the load gate; empty when none) — the one list its `Skill` tool activates from, its park binds and the resumed execution boundary judges a parked Skill approval against. */
+    skillSpecs: readonly SkillGrantSource[];
     /** The person's own persisted-rule lane (deny/ask rows), re-adjudicated on RESUME at the same
      *  station as the deny-narrowing layers: a deny row added while the call was parked vetoes the execution
      *  (`deniedBy: "persisted_rule"`), and so does a call the lane could not read against the rows (re-issue and
@@ -429,9 +436,19 @@ export interface Prepared {
     persistedRuleLane?: {
         adjudicate: (req: ToolCallRequest) => Promise<import("../hooks.js").PersistedRuleAnswer>;
     };
-    /** The deployment's own caller policy, re-checked on a durable resume ONLY when the approver
-     *  rewrote the pending call's args (see the composition site for why the edit case is special). */
+    /** The deployment's caller policy, re-checked on a durable resume when the bytes to execute are not the bytes the gate saw. */
     basePolicyForResumeEdit?: ToolPolicy;
+    approvedCallScreen?: (call: {
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+        decidedBy: "person" | "sla_timeout" | "policy";
+    }) => Promise<{
+        readonly refused: string;
+    } | {
+        readonly args: unknown;
+        readonly admit: () => void;
+    }>;
     /** The leg's shell READ STATION, re-run on a durable RESUME before an approved shell call executes: the parked leg's
      *  admission died with that leg, so the resumed bytes are judged (and admitted for their pre-spawn re-establishment)
      *  on THIS leg — a deny row found now vetoes, an operator's edit is judged on the `rejudge` seat. */
@@ -1608,10 +1625,10 @@ export interface RunInternals {
     /**
      * Parent effective-policy inheritance (tighten-only): the spawning parent's already-evaluated FINAL
      * gate, threaded into a child task so the child inherits it as ADDITIONAL constraint layers — a child
-     * can only ever be narrowed by this, never widened (its own session rules / skill scope / caller policy
+     * can only ever be narrowed by this, never widened (its own session rules / skill rows / caller policy
      * still apply in full). Filled ONLY by core delegation callers (`createSubagentTool`'s execute via
      * `ToolExecuteContext.inheritedGateForChildren`, the workflow spawn legs) — NEVER a {@link TaskSpec}
-     * field (the untrusted-caller surface), mirroring `inheritedManifestScope`'s ctx-injection posture.
+     * field (the untrusted-caller surface), mirroring `inheritedSkillGrants`'s ctx-injection posture.
      * Absent ⇒ no inheritance (a top-level task; fully backward-compatible).
      */
     inheritedGate?: InheritedGate;
@@ -1686,7 +1703,7 @@ export interface RunInternals {
      * itself inside a workflow (e.g. service's `/v1/workflows`), it threads `workflowDepth = parentDepth + 1`
      * into `startWorkflow`/`runWorkflow` so the one-level nesting guard fires across the process boundary.
      * In-process nesting needs nothing here — the engine's `AsyncLocalStorage` propagates depth automatically.
-     * Mirrors how `repairBundle`/`inheritedManifestScope` thread trusted run-scoped internals the Runner cannot
+     * Mirrors how `repairBundle`/`inheritedSkillGrants` thread trusted run-scoped internals the Runner cannot
      * see from `spec`. Consumed by the `run_workflow` tool wiring (S8c), not by `prepareTask` itself.
      */
     workflowDepth?: number;
@@ -1711,7 +1728,7 @@ export interface RunInternals {
      * child it spawns: this run IS a forked child. `prepareTask` threads it to tool ctx as `insideFork` so the
      * child's own Agent tool refuses a nested fork (nesting guard — mirrors CC's "fork is not available inside a
      * forked worker"; a fork can still delegate via `Agent`, just not fork again). TRUSTED internal (NOT a
-     * `TaskSpec` field — the untrusted-caller surface), mirrors `inheritedManifestScope`.
+     * `TaskSpec` field — the untrusted-caller surface), mirrors `inheritedSkillGrants`.
      */
     insideFork?: boolean;
     /**
@@ -1783,23 +1800,16 @@ export interface RunInternals {
      */
     goalMode?: boolean;
     /**
-     * 🔴 Skill→subagent manifest-scope PROPAGATION (must close before ON). The parent task's
-     * ACTIVE skill-manifest frames, snapshotted at the moment a subagent was spawned WHILE a manifest scope
-     * was live on the parent. The child's {@link prepareTask} seeds its own {@link ActiveSkillScope} from
-     * these so the child inherits the parent skill's deny-narrowing — fail-closed and MONOTONIC: a child of
-     * a manifested skill is AT MOST as capable as the manifest (its own manifests can only narrow further,
-     * never re-grant a tool/path the parent removed).
-     *
-     * This is a TRUSTED, run-scoped channel filled ONLY by `createSubagentTool`'s `execute` (a core caller),
-     * NEVER a {@link TaskSpec} field (TaskSpec is the untrusted-caller surface). It mirrors
-     * how `repairBundle`/`resume.seed` thread live per-task state the Runner cannot see from `spec`.
+     * The skill grant rows the PARENT task held at the moment it spawned this child (its `allowed-tools` / `disallowed-tools`
+     * rows of the run, whatever wrote them), captured by `createSubagentTool`'s `execute` from the parent's
+     * `ctx.activeSkillGrants()` and seeded into this child's table as `inherited` rows: they hold until THIS child ends
+     * (the parent's run ending ends the parent's rows, not this copy), beside the child's own activations.
      *
-     * Fail-closed: when the parent HAD an active manifest at spawn but the precise frames cannot be
-     * snapshotted, the subagent tool threads a single DENY-ALL `unresolved` frame here rather than letting the
-     * child run unmanifested — the safe path is the default. An empty/absent value = no inheritance (a
-     * subagent spawned with no active parent manifest behaves exactly as before, backward-compatible).
+     * A TRUSTED, run-scoped channel (never a {@link TaskSpec} field — TaskSpec is the untrusted-caller surface), in the
+     * posture `repairBundle` / `resume.seed` keep. A capture the delegation could not read refuses the spawn rather than
+     * seeding nothing (it carries refusals too). Absent or empty ⇒ nothing inherited.
      */
-    inheritedManifestScope?: readonly ActiveSkillFrame[];
+    inheritedSkillGrants?: readonly SkillGrantRecord[];
     /**
      * When this task runs as a SUB-AGENT spawned under a parent task's
      * tool call, the spawning tool's `ToolExecuteContext.toolCallId`. The Runner stamps it onto this task's
@@ -1807,7 +1817,7 @@ export interface RunInternals {
      * content to the delegation subtree WITHOUT core merging the child stream into the parent (lightweight
      * message-identity, not stream-merge). A TRUSTED, run-scoped channel filled by a core caller
      * (`createSubagentTool`'s `execute`) — NEVER a {@link TaskSpec} field (the untrusted-caller surface),
-     * mirroring `inheritedManifestScope`/`workflowDepth`. Absent for a top-level (non-delegated) task.
+     * mirroring `inheritedSkillGrants`/`workflowDepth`. Absent for a top-level (non-delegated) task.
      */
     parentToolCallId?: string;
     /**

package/dist/core/runner/gate-exit.d.ts

@@ -138,6 +138,10 @@ export interface PreToolUseScreening {
     /** The model-facing text for a face that never ANSWERED while screening `subject` (the timeout arm also
      *  reports on the deployment lane; a task-abort expiry does not). */
     unansweredReason(subject: string, cause: "timeout" | "aborted"): Promise<string>;
+    /** The model-facing text for the face's OWN deny of this call (unwrapped; every exit wraps it with the leg's mark). */
+    deniedReason(answer: PreToolUseResult): string;
+    /** The model-facing text for an answer the decision receipt refused (an ENGINE fail-closed, not the face's deny). */
+    refusedReason(answer: PreToolUseResult): string;
 }
 /**
  * ONE gate pass — the record the station groups (`runGateFold`, `runGateLanes`) and the exits read and write,
@@ -318,7 +322,7 @@ export interface GatePass {
 export declare function engineFailClosedExit(pass: GatePass, reason: string): Promise<ToolGateResult>;
 /** The hook's OWN deny in phase 1. A PreToolUse hook deny does NOT fire `permissionDenied`
  *  (the exclusion recorded on `Hooks.permissionDenied`) — this return stays observer-free. */
-export declare function hookDenyExit(pass: GatePass, r: PreToolUseResult): ToolGateResult;
+export declare function hookDenyExit(pass: GatePass, deniedReason: string): ToolGateResult;
 /**
  * The exit of the adjudicate chain — the pass has a standing `deny` or `allow` (every ask was resolved or
  * parked before this), and this is where it becomes the gate result and the ONE record of the pass.

package/dist/core/runner/gate-exit.js

@@ -1,7 +1,8 @@
 import { screenGateOutcome, SETTLEMENT_IS_REFUSAL } from "../gate-outcome.js";
-import { headlessApprovalRemedy } from "../ask-origin.js";
+import { classifyAsk, headlessApprovalRemedy } from "../ask-origin.js";
 import { isProtectedWrite } from "../tool-registry.js";
 import { askUnresolvableCauseOf, classifierDenyCauseOf, classifierRoundOf, decisionText, engineSettlementOf } from "../tool-policy.js";
+import { askUnresolvableRemedySeat } from "../ask-unresolvable-notice.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { formatHookFeedback } from "../reminder-mint.js";
 export function mintGateOutcome(facts) {
@@ -102,15 +103,16 @@ export async function engineFailClosedExit(pass, reason) {
     await notifyPermissionDenied({ toolName, input: cloneObserverInput(pass.currentInput), toolCallId, reason, gate, ...(input.identity !== undefined ? { identity: input.identity } : {}) });
     return { block: true, reason: formatHookFeedback(reason, input.reminderMark), gate, preToolContext: pass.preToolContext };
 }
-export function hookDenyExit(pass, r) {
-    const { input, toolName } = pass;
+export function hookDenyExit(pass, deniedReason) {
+    const { input } = pass;
     return {
         block: true,
-        reason: formatHookFeedback(decisionText(r) ?? `tool "${toolName}" blocked by a PreToolUse hook`, input.reminderMark),
+        reason: formatHookFeedback(deniedReason, input.reminderMark),
         gate: directDeny("hook"),
         preToolContext: pass.preToolContext,
     };
 }
+const ANCESTOR_UNRESOLVED_CLASSIFICATION = classifyAsk({ action: "ask", message: "" }, { contentQuestion: false, markedUnresolvable: true, org: undefined, tightened: undefined, mandateMarks: {} });
 function unresolvableCauseOfSettlement(gate) {
     if (gate.disposition.kind !== "denied" || gate.disposition.deniedBy !== "ask_resolution" || gate.settlement === undefined)
         return undefined;
@@ -135,8 +137,10 @@ export async function exitGate(pass) {
             ledger.supersede();
         }
         const gate = mintGateOutcome({ deniedBy: pass.deniedBy, ...(pass.denyCause !== undefined ? { cause: pass.denyCause } : {}), ...(ledger.settled !== undefined ? { settled: ledger.settled } : {}), ...(pass.classifierRound !== undefined ? { classifier: pass.classifierRound } : {}), ...(modeRefusal !== undefined ? { modeRefusal: { mode: modeRefusal.mode, askClass: modeRefusal.askClass, classes: modeRefusal.classes } } : {}) });
-        const unresolvable = askUnresolvableCauseOf(pass.decision, { toolCallId, toolName }) ?? unresolvableCauseOfSettlement(gate);
-        const remedy = unresolvable === "no_approver_wired" ? headlessApprovalRemedy({ mode: input.permissionMode?.(), classification: pass.askClassification, coveredWrite: isProtectedWrite(pass.req), ...(pass.shellUnplacedOptions !== undefined ? { unplacedOptions: pass.shellUnplacedOptions } : {}) }) : undefined;
+        const foldCause = askUnresolvableCauseOf(pass.decision, { toolCallId, toolName });
+        const unresolvable = foldCause ?? unresolvableCauseOfSettlement(gate);
+        const remedySeat = unresolvable !== undefined ? askUnresolvableRemedySeat(unresolvable) : undefined;
+        const remedy = remedySeat !== undefined ? headlessApprovalRemedy({ mode: input.permissionMode?.(), classification: foldCause !== undefined ? ANCESTOR_UNRESOLVED_CLASSIFICATION : pass.askClassification, approverSeat: remedySeat, coveredWrite: isProtectedWrite(pass.req), ...(pass.shellUnplacedOptions !== undefined ? { unplacedOptions: pass.shellUnplacedOptions } : {}) }) : undefined;
         const denyReason = withParkFailureCause(`${decisionText(pass.decision) ?? `tool "${toolName}" denied by policy`}${remedy !== undefined ? ` — ${remedy}` : ""}`, pass.parkFailed);
         if (unresolvable !== undefined) {
             const cause = unresolvable;

package/dist/core/runner/prepare-delegation-surface.d.ts

@@ -99,6 +99,7 @@ export interface PrepareDelegationSurfaceInput {
     /** borrowed-readonly — the caller-tool ctx enrichment: the revival spawner re-enters the delegation tool through it, and
      *  the SendMessage / AgentTranscript mounts activate their ctx-first arms with it. */
     enrichSpecToolCtx: (ctx: ToolExecuteContext) => ToolExecuteContext;
+    /** borrowed-readonly — the seat this run hands its children (`checkpointSeatOf`); the background-agent read faces read a parked agent's approval card through it. */ checkpointSeat: import("../checkpoint-seat.js").CheckpointSeat | undefined;
     /** borrowed-mutable — the hands mount's tracked-cwd seat: present ⇔ real shell + write hands; the worktree pair's mount
      *  predicate. Not written by this phase, but the tools it mounts over it ARE its writers: EnterWorktree and
      *  ExitWorktree assign `current` at run time (the hands band's shared cwd then points at the worktree, and back); the

package/dist/core/runner/prepare-delegation-surface.js

@@ -12,14 +12,14 @@ import { deliverEngineNotice } from "../types.js";
 import { RosterBuilder } from "../tool-roster.js";
 import { sendMessageContinuationSeats } from "./send-message-continuation.js";
 export function prepareDelegationSurface(input) {
-    const { spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, taskRootCanonical, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, sessionBox, roster, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle } = input;
+    const { spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, taskRootCanonical, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, sessionBox, roster, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, checkpointSeat, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle } = input;
     let worktreeSessionRef;
     const delegationSurfaceActive = backgroundTaskToolsActive || workflowToolsActive;
     let sendMessageTier;
     if (delegationSurfaceActive || internals?.parentNotify !== undefined || peerLaneActive) {
         if (delegationSurfaceActive) {
             roster.mountAll([
-                firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore })),
+                firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore, ...(checkpointSeat !== undefined ? { checkpointSeat } : {}) })),
                 firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })),
             ], { source: "builtin", mountedBy: "delegation" });
         }
@@ -66,7 +66,7 @@ export function prepareDelegationSurface(input) {
                 roster.mount(firstPartyOffload(createAgentTranscriptTool({
                     runner: runnerSelf,
                     registry: defaultTaskRegistry,
-                    agentStore: deps.backgroundAgentStore,
+                    agentStore: deps.backgroundAgentStore, ...(checkpointSeat !== undefined ? { checkpointSeat } : {}),
                     owner: hostTaskId,
                     scope: taskScope,
                     ...(sessionId !== undefined ? { sessionId } : {}),
@@ -84,7 +84,7 @@ export function prepareDelegationSurface(input) {
         toolEffects.set(READ_INBOX_TOOL_NAME, "read");
         roster.mount(firstPartyOffload(createReadInboxTool({ pull: () => peerLaneRefs.pull })), { source: "builtin", mountedBy: "peerLane" });
     }
-    const listAgents = (peerLaneActive || delegationSurfaceActive) && peerSendMessageBuiltIn && listAgentsMountable({ exclude: toolFaceSnapshot.exclude, specTools: spec.tools ?? [] }) ? mountListAgents({ ...(peerLaneActive ? { peerDirectory: deps.peerDirectory } : {}), freshWindowMs: resolvePeerLaneConfig(deps.peerLane, deps.onNotice).listingFreshWindowMs, sessionId, scope: taskScope, hostTaskId, ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}), ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}), registry: defaultTaskRegistry, ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}), ...(sendMessageTier !== undefined ? { continuationTier: sendMessageTier } : {}), specTools: spec.tools ?? [], toolEffects }) : undefined;
+    const listAgents = (peerLaneActive || delegationSurfaceActive) && peerSendMessageBuiltIn && listAgentsMountable({ exclude: toolFaceSnapshot.exclude, specTools: spec.tools ?? [] }) ? mountListAgents({ ...(peerLaneActive ? { peerDirectory: deps.peerDirectory } : {}), freshWindowMs: resolvePeerLaneConfig(deps.peerLane, deps.onNotice).listingFreshWindowMs, sessionId, scope: taskScope, hostTaskId, ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}), ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}), registry: defaultTaskRegistry, ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}), ...(sendMessageTier !== undefined ? { continuationTier: sendMessageTier } : {}), ...(checkpointSeat !== undefined ? { readSeats: { checkpointSeat } } : {}), specTools: spec.tools ?? [], toolEffects }) : undefined;
     if (listAgents !== undefined)
         roster.mount(firstPartyOffload(listAgents), { source: "builtin", mountedBy: "peerLane" });
     if (backgroundTaskToolsActive) {

package/dist/core/runner/prepare-gate-stations.d.ts

@@ -3,7 +3,8 @@
  * effect sync, the write-protection judge compiled once per task, the arming predicate, the compliance and plan-mode
  * short-circuits, the `runToolGate` call with every seat it is handed, the lifecycle sweep, the deferred sandbox-admission
  * disclosure, the PreToolUse context stash, the settlement sideband write and the bare-human-rejection boundary) and the
- * `tool_result` station (the PostToolUse / PostToolUseFailure seats and the PreToolUse context drain). The two module-scope
+ * `tool_result` station's registration (its body, the PostToolUse / PostToolUseFailure seats and the PreToolUse context
+ * drain, lives in call-hook-stations.ts). The two module-scope
  * helpers only these stations called moved with them (the settlement screen, the rejection-boundary judgment). The
  * interface is the dependency list the stations had implicitly.
  *
@@ -36,11 +37,12 @@ import { type WiringManifest } from "../wiring-manifest.js";
 import type { WriteProtectionCheck } from "../write-protect.js";
 import type { ShellReadCheck } from "../../tools/fs/shell-read-check.js";
 import type { CwdRef } from "../../tools/fs/fs-shared.js";
-import type { AskLane, IrreversibilityTier, ParkAsk, Prepared, ReversibilityProbes, StopForDenialLimit } from "./contracts.js";
+import type { AskLane, GateSeatInputsFor, IrreversibilityTier, ParkAsk, Prepared, ReversibilityProbes, StopForDenialLimit } from "./contracts.js";
 import type { PermissionRuleLanes } from "./permission-rule-lanes.js";
 import { type ToolRosterDeltaSeat } from "../tool-roster.js";
 import type { ToolCallLike } from "../tool-registry.js";
-import { type FrameSettlement } from "../frame-settlement.js";
+import type { FrameSettlement } from "../frame-settlement.js";
+import { type ApprovedCallScreen } from "./call-hook-stations.js";
 /**
  * The parent-thread human-rejection boundary — judged ONCE here, from the pass's own record (CC parity:
  * the reference CLI's reject path aborts exactly when there is no feedback and the run is not a
@@ -205,6 +207,7 @@ export interface PrepareGateStationsInput {
     stopForDenialLimit: StopForDenialLimit;
     /** borrowed-readonly — the persisted allow-rule lane, or undefined (absent entirely with no store). */
     permissionRuleLane: PermissionRuleLanes["personal"];
+    /** borrowed-readonly — the call's seat inputs: the permission seat (static, or the `Skill` tool's per-call reader) and the run's skill rows. */ seatInputsFor: GateSeatInputsFor;
     /** borrowed-readonly — the org rule lane, or undefined (absent on an ungoverned deployment). */
     permissionRuleOrgLane: PermissionRuleLanes["org"];
     /** borrowed-readonly — whether the ENGINE's question tool is what is mounted under the reserved name (the org lane's
@@ -239,6 +242,8 @@ export interface PrepareGateStationsResult {
     toolCallStationArmed: boolean;
     /** owned — whether the `tool_result` station registered (a post or screening hook is wired; observation seat only). */
     toolResultStationArmed: boolean;
+    /** owned — the approved call's PreToolUse re-screen (the gate's face and seat), present exactly when a face is wired. */
+    approvedCallScreen?: ApprovedCallScreen;
 }
 /** The M20 phase body — prepareTask's two gate stations, verbatim (see the module header). */
 export declare function prepareGateStations(input: PrepareGateStationsInput): PrepareGateStationsResult;