@sema-agent/core 7.4.0 → 7.5.1

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

@@ -0,0 +1,268 @@
+/**
+ * design/390 §1.2 M3b — prepareTask's INHERITED-GATE phase, verbatim from the driver: the live/seed fold of the
+ * chain this run inherits (ancestor rules rev-monotonic per (session, principal), shellGate by max rank, the
+ * re-supplied parent constraints with their rebuilt denial trackers, the auto-mode intent, the org-admission
+ * freeze with its tighten-only intersection and the monotonic governed bit), the effective shellGate against the
+ * spec, the three cells later phases fill for the children's chain (own session rules, own admitted org scopes,
+ * own org verdict), the checkpoint-section closures the suspend serializer reads (face / org / F-012 stamps), the
+ * FROZEN ask and question seats (spec over deps), the two delegation refs the memory phase binds late, the ONE
+ * child-chain assembly `inheritedGateForChildren`, the caller-tool ctx enrichment `enrichSpecToolCtx` shared by
+ * the roster wrap and the revival spawner, the denial-limit stop seat, and the full-shell reachability predicate.
+ * The interface is the dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await (the one `await` in it sits inside the
+ * `hostSessionFork` closure a tool calls later), so the phase adds no yield between the run-refs phase before it
+ * and the caps phase after it (design/390 §1.5: a stretch with no await is extracted as a sync function).
+ *
+ * LATE-BOUND SEATS. The closures minted here run long after this phase returns — at spawn time, at tool-call
+ * time, at suspend time — and several of the facts they read are resolved by LATER stations of the same prepare:
+ * the caps phase's `runtimeCaps` / fork verdict / observers grant / armed classifier trio, the hands mount's
+ * resolved face and deny additions, the policy-chain station's hook record and timeout, the wiring station's hook
+ * env face, the prompt-assembly station's center adoption, the memory phase's engine session. In the driver those
+ * were `let`s and later `const`s the closures captured by name; here each enters as a GETTER on the Input, and
+ * every closure reads it exactly where — and only when — the driver's closure read the variable (a head binding
+ * where the driver read a variable inside one synchronous evaluation; an in-place call where the driver's read
+ * sat behind a short-circuit). Read-stability of the host handles for the call: {@link RunInternals}
+ * (`@contract prepare.deps-read-stable`).
+ *
+ * Every cell that leaves here as `borrowed-mutable` carries its writer table on the Result member (design/238 R-3).
+ */
+import type { AgentHarness, ExecutionEnv } from "../../internal/harness.js";
+import type { SubagentWorktreeIsolation } from "../../agents/subagent.js";
+import { forkGovernanceDenial } from "../../agents/subagent.js";
+import type { SubagentRetainLedger } from "../../agents/retain-ledger.js";
+import type { PromptEpochArtifact } from "../../prompt-assembly/artifact.js";
+import type { ReadFace } from "../../tools/fs/index.js";
+import type { AutoModeArmingRecipe } from "../auto-mode-arming.js";
+import type { AutoModeDecider, AutoModeDenialTracker } from "../auto-mode.js";
+import { type OnQuestion } from "../ask-question.js";
+import { type HookEnvCapabilities, type Hooks } from "../hooks.js";
+import type { LockedPreflight } from "../locked-config.js";
+import type { OwnOrgAdmissionVerdict } from "../memory-admission.js";
+import type { DelegationContentSafety } from "../memory-engine/delegation-provenance.js";
+import type { SessionPermissionRules } from "../session-policy-store.js";
+import type { SessionStore } from "../session.js";
+import { type OnAsk } from "../tool-policy.js";
+import type { RunnerDeps, RuntimeCaps, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";
+import type { ActiveSkillScope } from "./active-skill-scope.js";
+import type { InheritedGate, Prepared, PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import { type StopForDenialLimit } from "./denial-limit-arms.js";
+export interface PrepareInheritedGateInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `shellGate` (the own doctrine the chain fold tightens), `durableApproval`
+     *  (the mandate tests + the children's copy), `onAsk`/`onQuestion` (the frozen seats), `handsReadOnly` / `interactiveTools`
+     *  / `oneShot` / `clientContext` / `principal` / `additionalDirectories` / `additionalReadDirectories` / `envFacts` /
+     *  `memoryPersistenceCapable` / `getApiKeyAndHeaders` / `checkpointStore` / `backgroundScope` / `enablePlanMode` (the ctx
+     *  enrichment's trusted seats). Never mutated. */
+    spec: Pick<TaskSpec, "shellGate" | "durableApproval" | "onAsk" | "onQuestion" | "handsReadOnly" | "interactiveTools" | "oneShot" | "clientContext" | "principal" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "getApiKeyAndHeaders" | "checkpointStore" | "backgroundScope" | "enablePlanMode">;
+    /** borrowed-readonly — the deployment seats: `autoMode.denialLimit` (the rebuilt trackers' bounds), `memoryScopeAdmission` /
+     *  `deploymentMemoryScopes` / `compliancePostureResolver` (the governed-provenance bit), `onError` (the screening-face crash
+     *  lane), `onNotice` (the stop seat's notice), `executionEnv` (the hook-env identity predicate), `delegationEntryCaps` (resolved
+     *  and validated once here), `rosterStore` / `onBackgroundChildEvent` (ctx seats), `onAsk` / `onQuestion` (the deps half of the
+     *  frozen seats). */
+    deps: Pick<RunnerDeps, "autoMode" | "memoryScopeAdmission" | "deploymentMemoryScopes" | "compliancePostureResolver" | "onError" | "onNotice" | "executionEnv" | "delegationEntryCaps" | "rosterStore" | "onBackgroundChildEvent" | "onAsk" | "onQuestion">;
+    /** borrowed-readonly — the trusted spawn-side channel: `inheritedGate` (the LIVE half of the chain fold), `ownOrgAdmissionRef`
+     *  (the same-session continuation's freeze), `delegationProvenance` (the F-012 stamp), and the identity / peer / notification
+     *  seats the ctx enrichment forwards. Never mutated. */
+    internals: Pick<RunInternals, "inheritedGate" | "ownOrgAdmissionRef" | "delegationProvenance" | "memoryCaptureAncestors" | "parentTaskId" | "parentSessionId" | "rootSessionId" | "placementRoot" | "explicitAgentName" | "peerSelfRef" | "peerInboundChainRef" | "onTaskNotification" | "onSubagentSpawn" | "insideFork"> | undefined;
+    /** borrowed-readonly — the resume leg, or undefined on a fresh one: `seed.inheritedGate` is the CHECKPOINT half of the chain
+     *  fold (the trust floor the live half may only tighten), `seed.readFace` the hands-less re-park's carried section. */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+    /** borrowed-readonly — the session store's fork face: `fork` / `release` are bound into the ctx's `hostSessionFork` (present
+     *  only when the store can fork). */
+    sessions: Pick<SessionStore, "fork" | "release">;
+    /** borrowed-readonly — the acquired session id (the crash lane's context, the ctx seat, the ancestor chain's own row). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (the stop seat's notice names it). */
+    runId: string;
+    /** borrowed-readonly — the per-task identity (`ctx.taskId`, the same fallback the runner uses). */
+    hostTaskId: string;
+    /** borrowed-readonly — the SETTLED task root (`ctx.parentCwd`). */
+    taskRootFinal: string;
+    /** borrowed-readonly — the run's resolved env: the full-shell predicate's kind test and the hook-env identity value. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the per-task owned env when a factory minted one (the hook-env identity predicate reads presence). */
+    ownedEnv: ExecutionEnv | undefined;
+    /** borrowed-readonly — the frozen preflight; only `toolPolicy` (the RESOLVED caller policy the children's chain carries). */
+    lockedPreflight: Pick<LockedPreflight, "toolPolicy">;
+    /** borrowed-readonly — the frozen tool-face snapshot (the ctx forwards exclude / defer / alwaysLoad / restoreGated; the
+     *  full-shell predicate reads the exclusion of Bash). */
+    toolFaceSnapshot: ToolFaceSnapshot;
+    /** borrowed-readonly — the resolved prompt profile (ctx seat). */
+    promptProfile: ToolExecuteContext["promptProfile"];
+    /** borrowed-readonly — the resolved interaction posture (ctx seat; absent ⇒ no key). */
+    resolvedInteractionPosture: ToolExecuteContext["interactionPosture"];
+    /** borrowed-readonly — the task's own auto-mode intent seat, screened and snapshotted before the first await. */
+    autoModeSeat: boolean;
+    /** borrowed-readonly — whether an execution env is wired at all (the full-shell predicate's first term). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the nested-usage sink the ctx forwards. */
+    reportUsage: ToolExecuteContext["reportUsage"];
+    /** borrowed-readonly — the harness seat (the ctx's model / thinking snapshots read it call-time). Not written here. */
+    harnessRef: {
+        current?: AgentHarness;
+    };
+    /** borrowed-readonly — the per-task skill scope (the ctx's `activeSkillScope` snapshot reads it call-time). Not written here. */
+    skillScope: ActiveSkillScope;
+    /** borrowed-readonly — the filtered display-forwarding wrapper (ctx seat; absent ⇒ no key). */
+    forwardEvent: ((e: TaskEvent) => void) | undefined;
+    /** borrowed-readonly — the retain ledger (ctx seat; absent ⇒ no key). */
+    subagentRetain: SubagentRetainLedger | undefined;
+    /** borrowed-readonly — the worktree-isolation helper (ctx seat; absent ⇒ no key). */
+    worktreeIsolation: SubagentWorktreeIsolation | undefined;
+    /** borrowed-readonly — the three run-ref primitives the ctx exposes (plan mode only under `enablePlanMode`). */
+    requestReview: (opts?: {
+        reason?: string;
+    }) => void;
+    /** borrowed-readonly — see `requestReview`. */
+    requestStopAfterTurn: () => void;
+    /** borrowed-readonly — see `requestReview`. */
+    enterPlanMode: () => void;
+    /** borrowed-readonly — the leg's reminder mark (ctx seat). */
+    reminderMark: string;
+    /** borrowed-readonly — the leg's disclosure counters (ctx seat; the outlets that bump them are not in this phase). */
+    reminderDisclosureCounts: Prepared["reminderDisclosureCounts"];
+    /** borrowed-readonly — the file-history fixed point the ctx threads to delegation tools (only when enabled). */
+    fileHistoryEnabled: boolean;
+    /** borrowed-readonly — see `fileHistoryEnabled`. */
+    historyScope: string;
+    /** borrowed-readonly — see `fileHistoryEnabled`. */
+    historyRoot: string;
+    /** borrowed-readonly — see `fileHistoryEnabled`. */
+    historyFs: string;
+    /** borrowed-readonly — the driver's composition of the run's abort (controller + harness), the stop seat's headless arm.
+     *  Composed by the driver because the harness is built after this phase; the seat only ever fires at run time. */
+    abortRun: () => void;
+    /** borrowed-readonly — LATE-BOUND: the per-principal entitlements the caps phase resolves after this one; read only inside
+     *  `inheritedGateForChildren` (the two mandate tests), at spawn time. */
+    runtimeCaps: () => RuntimeCaps | undefined;
+    /** borrowed-readonly — LATE-BOUND: the resolved hook record (`spec.hooks ?? deps.hooks`), read inside the chain assembly for
+     *  this task's own screening face. */
+    hooks: () => Hooks | undefined;
+    /** borrowed-readonly — LATE-BOUND: whether the deployment declared its screening face observational (then it rides no entry). */
+    preToolUseObservational: () => boolean;
+    /** borrowed-readonly — LATE-BOUND: the validated per-invocation hook bound the screening-face entry's policy runs under. */
+    hookTimeoutMs: () => number;
+    /** borrowed-readonly — LATE-BOUND: the hook-env capability face the screening-face entry's policy resolves paths in. */
+    hookEnvFace: () => HookEnvCapabilities | undefined;
+    /** borrowed-readonly — LATE-BOUND: the armed classifier (undefined = not armed), read where the chain freezes it onto both
+     *  entries and where the ctx exposes the spawn-review seat. */
+    autoModeDecider: () => AutoModeDecider | undefined;
+    /** borrowed-readonly — LATE-BOUND: the denial tracker built beside the decider; rides wherever the decider rides. */
+    autoModeDenialTracking: () => AutoModeDenialTracker | undefined;
+    /** borrowed-readonly — LATE-BOUND: the serializable arming recipe (persistArming opt-in only). */
+    autoModeArming: () => AutoModeArmingRecipe | undefined;
+    /** borrowed-readonly — LATE-BOUND: the fork-governance verdict (ctx `forkAccess`, present only when denied). */
+    agentForkDenial: () => ReturnType<typeof forkGovernanceDenial>;
+    /** borrowed-readonly — LATE-BOUND: the observers grant (ctx `observersAllowed`, present only when explicitly granted). */
+    observersActive: () => boolean;
+    /** borrowed-readonly — LATE-BOUND: the hands mount's resolved read face (undefined until/unless hands mount). */
+    resolvedReadFace: () => ReadFace | undefined;
+    /** borrowed-readonly — LATE-BOUND: the normalized deny additions in force (empty until the hands mount resolves them). */
+    readDenyAdditionsNormalized: () => ReadonlyArray<{
+        pattern: string;
+        caseSensitive: boolean;
+    }>;
+    /** borrowed-readonly — LATE-BOUND: the hands-less legs' resolved face (the carrier's second source). */
+    handsLessResolvedFace: () => ReadFace | undefined;
+    /** borrowed-readonly — LATE-BOUND: the adopted center artifact (ctx `centerArtifactDigest` / `centerSourceRevision`). */
+    centerAdoption: () => {
+        artifact: PromptEpochArtifact;
+        sourceRevision?: string;
+    } | undefined;
+    /** borrowed-readonly — LATE-BOUND: the memory-engine session (the ctx's capture-floor getters read it at THEIR call time). */
+    memoryEngineSession: () => Prepared["memoryEngineSession"];
+}
+export interface PrepareInheritedGateResult {
+    /** owned — the LIVE half of the inherited chain as supplied (`internals.inheritedGate`); the durable-gate notice reads it. */
+    liveInheritedGate: RunInternals["inheritedGate"];
+    /** owned — the CHECKPOINT half (`resume.seed.inheritedGate`); the suspend serializer re-reads its frozen chain. */
+    seedInheritedGate: PrepareResume["seed"]["inheritedGate"];
+    /** owned — the rev-monotonic fold of the two halves' ancestor rules (live replaces per (session, principal) only at ≥ rev). */
+    inheritedAncestorRules: InheritedGate["ancestorRules"];
+    /** owned — the max-rank fold of the two halves' shellGate doctrines (before the spec's own is applied). */
+    inheritedShellGate: InheritedGate["shellGate"];
+    /** owned — the live parent constraints with a fresh denial tracker attached per rebuilt decider. */
+    inheritedParentConstraints: NonNullable<InheritedGate["parentConstraints"]>[number][] | undefined;
+    /** owned — the auto-mode INTENT (own seat ∨ live chain ∨ checkpoint bit); the arming site judges the other two arms. */
+    autoModeIntent: boolean;
+    /** owned — the seed ∩ live admitted org scopes (one side absent ⇒ the other; both absent ⇒ undefined). */
+    inheritedAdmittedOrgScopes: readonly string[] | undefined;
+    /** owned — the prior own org verdict: checkpoint ∩ same-session ref (either alone stands; neither ⇒ undefined). */
+    priorOwnOrgVerdict: OwnOrgAdmissionVerdict | undefined;
+    /** owned — the monotonic governed-provenance bit for this leg. */
+    orgGovernedProvenance: boolean;
+    /** owned — the spec's own shellGate tightened by the inherited doctrine. */
+    effectiveShellGate: "off" | "classify" | "always";
+    /** borrowed-mutable — THIS task's own session-rule snapshot for its children's chain. Writers (R-3): the policy-chain
+     *  station's session-policy read, once per leg, when a store is wired and the task carries its own sessionId. Read by
+     *  `inheritedGateForChildren` at spawn time. */
+    ownSessionRulesRef: {
+        current?: {
+            sessionId: string;
+            principal?: string;
+            rev: number;
+            rules: SessionPermissionRules;
+        };
+    };
+    /** borrowed-mutable — THIS task's own frozen admitted org scopes for its children's chain. Writers: the memory phase's
+     *  admission door, once per leg. Read by the chain assembly (always emitted, empty = no org plane). */
+    memoryAdmittedOrgScopesRef: {
+        current: readonly string[];
+    };
+    /** borrowed-mutable — the SESSION-freeze record for the suspend writer (present iff this leg adjudicated an org plane).
+     *  Writers: the memory phase's admission door. Readers: the org stamp predicate here and the suspend serializer. */
+    ownOrgVerdictRef: {
+        current: OwnOrgAdmissionVerdict | undefined;
+    };
+    /** owned — the org-admission checkpoint stamp predicate (inherited set ∨ own verdict ∨ governed). */
+    orgAdmissionCheckpointState: () => boolean;
+    /** owned — the read-face checkpoint section builder (hands-less resume carries the seed; every other leg mints from the live
+     *  resolution; undefined for the default posture). */
+    faceCheckpointSection: () => {
+        face: "open" | "roots";
+        denyEntries?: Array<{
+            pattern: string;
+            caseSensitive: boolean;
+        }>;
+    } | undefined;
+    /** owned — the face stamp predicate (`faceCheckpointSection() !== undefined`). */
+    faceCheckpointState: () => boolean;
+    /** owned — the F-012 stamp predicate (opaque constraints present ∨ seed frozen chain ∨ provenance-armed). */
+    f012CheckpointState: () => boolean;
+    /** owned — the FROZEN approver seat (spec over deps) every station of this leg and its children's chain resolve at. */
+    frozenOnAsk: OnAsk | undefined;
+    /** owned — the env the screening face sees through `ctx.env` (identity half of a chain entry's `hookEnv`); the policy-chain
+     *  station's pass-through arm compares against it. */
+    hookEnvSource: unknown;
+    /** owned — the deployment lane for a screening face that crashes while screening a descendant's call (phase "hook"). */
+    notifyOwnHookCrash: (err: unknown) => void;
+    /** owned — the FROZEN question seat (spec over deps), the content-ask twin of `frozenOnAsk`. */
+    frozenOnQuestion: OnQuestion | undefined;
+    /** borrowed-mutable — the delegation runtime-provenance arming face. Writers: the memory phase's content-origin wrap section,
+     *  once per leg when armed. Read lazily by delegation tools through the ctx. */
+    provenanceForChildrenRef: {
+        current?: DelegationContentSafety;
+    };
+    /** borrowed-mutable — the delegation-settlement coordinates. Writers: the memory phase, once per leg when a session exists.
+     *  Read lazily by delegation tools through the ctx. */
+    delegationSettlementRef: {
+        current?: {
+            controlDir: string;
+            sessionId: string;
+        };
+    };
+    /** owned — chain assembly SINGLE SITE: upstream chain + this task's own contribution, called by delegation tools at spawn. */
+    inheritedGateForChildren: () => InheritedGate;
+    /** owned — the ONE carrier expression both delegation mounts consume (resolved face ?? hands-less face). */
+    carrierReadFace: () => ReadFace | undefined;
+    /** owned — the full shell's structural reachability from spec-time facts. */
+    fullShellReachable: boolean;
+    /** borrowed-mutable — the gate's typed stop seat (`Prepared.gateStopRef`). Writers: `stopForDenialLimit` only. */
+    gateStopRef: Prepared["gateStopRef"];
+    /** owned — the ONE closure that fills the stop seat (the denial-limit fallback's headless arm). */
+    stopForDenialLimit: StopForDenialLimit;
+    /** owned — the caller-tool ctx enrichment shared by the roster wrap and the revival spawner. */
+    enrichSpecToolCtx: (ctx: ToolExecuteContext) => ToolExecuteContext;
+}
+/** The M3b phase body — prepareTask's inherited-gate stretch, verbatim (see the module header). */
+export declare function prepareInheritedGate(input: PrepareInheritedGateInput): PrepareInheritedGateResult;

package/dist/core/runner/prepare-inherited-gate.js

@@ -0,0 +1,266 @@
+import { forkGovernanceDenial, resolveDelegationEntryCaps } from "../../agents/subagent.js";
+import { isLiveQuestionFace } from "../ask-question.js";
+import { createPreToolUseConstraintPolicy } from "../hooks.js";
+import { StubExecutionEnv } from "../stub-env.js";
+import { askApproverIdentity, isLiveApproverSeat } from "../tool-policy.js";
+import { attachRebuiltDenialTrackers, createDenialLimitStop } from "./denial-limit-arms.js";
+export function prepareInheritedGate(input) {
+    const { spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, autoModeSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun } = input;
+    const liveInheritedGate = internals?.inheritedGate;
+    const seedInheritedGate = resume?.seed.inheritedGate;
+    const inheritedAncestorRules = (() => {
+        const seedRules = seedInheritedGate?.ancestorRules;
+        const liveRules = liveInheritedGate?.ancestorRules;
+        if (seedRules === undefined || seedRules.length === 0)
+            return liveRules ?? seedRules;
+        if (liveRules === undefined || liveRules.length === 0)
+            return seedRules;
+        const merged = seedRules.map((s) => {
+            const live = liveRules.find((l) => l.sessionId === s.sessionId && l.principal === s.principal);
+            return live !== undefined && live.rev >= s.rev ? live : s;
+        });
+        const extras = liveRules.filter((l) => !seedRules.some((s) => s.sessionId === l.sessionId && s.principal === l.principal));
+        return [...merged, ...extras];
+    })();
+    const shellGateRank = { off: 0, classify: 1, always: 2 };
+    const liveShellGate = liveInheritedGate?.shellGate;
+    const seedShellGate = seedInheritedGate?.shellGate;
+    const inheritedShellGate = liveShellGate === undefined
+        ? seedShellGate
+        : seedShellGate === undefined
+            ? liveShellGate
+            : shellGateRank[liveShellGate] >= shellGateRank[seedShellGate]
+                ? liveShellGate
+                : seedShellGate;
+    const inheritedParentConstraints = attachRebuiltDenialTrackers(liveInheritedGate?.parentConstraints, deps.autoMode?.denialLimit);
+    const autoModeIntent = autoModeSeat || liveInheritedGate?.autoModeRequested === true || seedInheritedGate?.autoModeRequested === true;
+    const liveAdmittedOrg = liveInheritedGate?.admittedOrgScopes;
+    const seedAdmittedOrg = seedInheritedGate?.admittedOrgScopes;
+    const inheritedAdmittedOrgScopes = liveAdmittedOrg === undefined ? seedAdmittedOrg : seedAdmittedOrg === undefined ? liveAdmittedOrg : liveAdmittedOrg.filter((s) => seedAdmittedOrg.includes(s));
+    const inheritedOrgGoverned = liveInheritedGate?.orgAdmissionGoverned === true || seedInheritedGate?.orgAdmissionGoverned === true;
+    const checkpointOwnOrgVerdict = resume?.seed.inheritedGate?.ownAdmittedOrgScopes !== undefined
+        ? { scopes: resume.seed.inheritedGate.ownAdmittedOrgScopes, writeScope: resume.seed.inheritedGate.ownAdmittedOrgWriteScope ?? null }
+        : undefined;
+    const refOwnOrgVerdict = internals?.ownOrgAdmissionRef?.current;
+    const priorOwnOrgVerdict = checkpointOwnOrgVerdict === undefined
+        ? refOwnOrgVerdict
+        : refOwnOrgVerdict === undefined
+            ? checkpointOwnOrgVerdict
+            : {
+                scopes: checkpointOwnOrgVerdict.scopes.filter((sc) => refOwnOrgVerdict.scopes.includes(sc)),
+                writeScope: checkpointOwnOrgVerdict.writeScope !== null && checkpointOwnOrgVerdict.writeScope === refOwnOrgVerdict.writeScope
+                    ? checkpointOwnOrgVerdict.writeScope
+                    : null,
+            };
+    const orgGovernedProvenance = deps.memoryScopeAdmission !== undefined ||
+        (deps.deploymentMemoryScopes !== undefined && deps.deploymentMemoryScopes.length > 0) ||
+        deps.compliancePostureResolver !== undefined ||
+        inheritedOrgGoverned ||
+        priorOwnOrgVerdict !== undefined;
+    const specShellGate = spec.shellGate ?? "off";
+    const effectiveShellGate = inheritedShellGate !== undefined && shellGateRank[inheritedShellGate] > shellGateRank[specShellGate] ? inheritedShellGate : specShellGate;
+    const ownSessionRulesRef = {};
+    const memoryAdmittedOrgScopesRef = { current: [] };
+    const ownOrgVerdictRef = { current: undefined };
+    const orgAdmissionCheckpointState = () => inheritedAdmittedOrgScopes !== undefined || ownOrgVerdictRef.current !== undefined || orgGovernedProvenance;
+    const faceCheckpointSection = () => {
+        const resolvedReadFace = input.resolvedReadFace();
+        const handsLessResolvedFace = input.handsLessResolvedFace();
+        const readDenyAdditionsNormalized = input.readDenyAdditionsNormalized();
+        if (resolvedReadFace === undefined && resume !== undefined) {
+            const seed = resume.seed.readFace;
+            return seed !== undefined ? { face: seed.face, ...(seed.denyEntries !== undefined ? { denyEntries: seed.denyEntries.map((e) => ({ ...e })) } : {}) } : undefined;
+        }
+        const face = resolvedReadFace ?? handsLessResolvedFace;
+        if (face === undefined)
+            return undefined;
+        if (face === "open" || readDenyAdditionsNormalized.length > 0) {
+            return { face, ...(readDenyAdditionsNormalized.length > 0 ? { denyEntries: readDenyAdditionsNormalized.map((e) => ({ ...e })) } : {}) };
+        }
+        return undefined;
+    };
+    const faceCheckpointState = () => faceCheckpointSection() !== undefined;
+    const f012CheckpointState = () => (inheritedParentConstraints?.length ?? 0) > 0 ||
+        seedInheritedGate?.constraintChain !== undefined ||
+        internals?.delegationProvenance !== undefined;
+    const frozenOnAsk = spec.onAsk ?? deps.onAsk;
+    const hookEnvSource = (ownedEnv ?? deps.executionEnv) != null ? executionEnv : undefined;
+    const notifyOwnHookCrash = (err) => {
+        try {
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "hook", sessionId });
+        }
+        catch {
+        }
+    };
+    const frozenOnQuestion = spec.onQuestion ?? deps.onQuestion;
+    const provenanceForChildrenRef = {};
+    const delegationProvenanceForChildren = () => provenanceForChildrenRef.current;
+    const delegationSettlementRef = {};
+    const delegationSettlementForChildren = () => delegationSettlementRef.current;
+    const inheritedGateForChildren = () => {
+        const autoModeDecider = input.autoModeDecider();
+        const autoModeDenialTracking = input.autoModeDenialTracking();
+        const autoModeArming = input.autoModeArming();
+        const ancestorRules = [
+            ...(inheritedAncestorRules ?? []),
+            ...(ownSessionRulesRef.current !== undefined ? [ownSessionRulesRef.current] : []),
+        ];
+        const ownCallerPolicy = lockedPreflight.toolPolicy;
+        const durableMandate = input.runtimeCaps()?.forceDurableGate === true ||
+            (spec.durableApproval !== undefined && !isLiveApproverSeat(frozenOnAsk));
+        const contentMandate = input.runtimeCaps()?.forceDurableGate === true ||
+            (spec.durableApproval !== undefined && !isLiveQuestionFace(frozenOnQuestion));
+        const ownPreToolUse = input.preToolUseObservational() ? undefined : input.hooks()?.preToolUse;
+        const hookConstraint = ownPreToolUse !== undefined &&
+            !(inheritedParentConstraints ?? []).some((pc) => pc.preToolUse === ownPreToolUse &&
+                askApproverIdentity(pc.onAsk) === askApproverIdentity(frozenOnAsk) &&
+                (pc.durableMandate === true) === durableMandate &&
+                (pc.contentMandate === true) === contentMandate &&
+                pc.hookEnv === hookEnvSource &&
+                pc.autoMode?.decider === autoModeDecider)
+            ? [
+                {
+                    policy: createPreToolUseConstraintPolicy(ownPreToolUse, input.hookEnvFace(), notifyOwnHookCrash, input.hookTimeoutMs()),
+                    preToolUse: ownPreToolUse,
+                    ...(hookEnvSource !== undefined ? { hookEnv: hookEnvSource } : {}),
+                    ...(frozenOnAsk !== undefined ? { onAsk: frozenOnAsk } : {}),
+                    ...(durableMandate ? { durableMandate: true } : {}),
+                    ...(contentMandate ? { contentMandate: true } : {}),
+                    ...(autoModeDecider !== undefined
+                        ? { autoMode: { decider: autoModeDecider, ...(autoModeDenialTracking !== undefined ? { denialTracking: autoModeDenialTracking } : {}), ...(autoModeArming !== undefined ? { arming: autoModeArming } : {}) } }
+                        : {}),
+                },
+            ]
+            : [];
+        const parentConstraints = [
+            ...(inheritedParentConstraints ?? []),
+            ...hookConstraint,
+            ...(ownCallerPolicy !== undefined
+                ? [
+                    {
+                        policy: ownCallerPolicy,
+                        ...(frozenOnAsk !== undefined ? { onAsk: frozenOnAsk } : {}),
+                        ...(durableMandate ? { durableMandate: true } : {}),
+                        ...(contentMandate ? { contentMandate: true } : {}),
+                        ...(autoModeDecider !== undefined
+                            ? { autoMode: { decider: autoModeDecider, ...(autoModeDenialTracking !== undefined ? { denialTracking: autoModeDenialTracking } : {}), ...(autoModeArming !== undefined ? { arming: autoModeArming } : {}) } }
+                            : {}),
+                    },
+                ]
+                : []),
+        ];
+        return {
+            ...(ancestorRules.length > 0 ? { ancestorRules } : {}),
+            ...(effectiveShellGate !== "off" ? { shellGate: effectiveShellGate } : {}),
+            ...(autoModeIntent ? { autoModeRequested: true } : {}),
+            ...(parentConstraints.length > 0 ? { parentConstraints } : {}),
+            admittedOrgScopes: memoryAdmittedOrgScopesRef.current,
+            ...(orgGovernedProvenance ? { orgAdmissionGoverned: true } : {}),
+        };
+    };
+    const carrierReadFace = () => input.resolvedReadFace() ?? input.handsLessResolvedFace();
+    const fullShellReachable = handsEnabled &&
+        !(executionEnv instanceof StubExecutionEnv) &&
+        spec.handsReadOnly !== true &&
+        !(toolFaceSnapshot.exclude?.includes("Bash") ?? false);
+    const { gateStopRef, stopForDenialLimit } = createDenialLimitStop({ sessionId, runId, onNotice: deps.onNotice, abort: abortRun });
+    const delegationEntryCapsResolved = resolveDelegationEntryCaps(deps.delegationEntryCaps);
+    const enrichSpecToolCtx = (ctx) => {
+        const agentForkDenial = input.agentForkDenial();
+        const observersActive = input.observersActive();
+        const readDenyAdditionsNormalized = input.readDenyAdditionsNormalized();
+        const autoModeDecider = input.autoModeDecider();
+        const centerAdoption = input.centerAdoption();
+        return {
+            ...ctx,
+            delegationEntryCaps: delegationEntryCapsResolved,
+            reportUsage,
+            model: harnessRef.current?.getModel(),
+            thinkingLevel: harnessRef.current?.getThinkingLevel(),
+            principal: spec.principal,
+            ...(frozenOnAsk !== undefined ? { onAsk: frozenOnAsk } : {}),
+            ...(frozenOnQuestion !== undefined ? { onQuestion: frozenOnQuestion } : {}),
+            ...(spec.handsReadOnly === true ? { handsReadOnly: true } : {}),
+            ...(carrierReadFace() === "roots" ? { readFace: "roots" } : {}),
+            ...(readDenyAdditionsNormalized.length > 0 ? { readDenyPatterns: Object.freeze(readDenyAdditionsNormalized.map((e) => ({ ...e }))) } : {}),
+            ...(spec.interactiveTools === false ? { interactiveTools: false } : {}),
+            oneShot: spec.oneShot,
+            clientContext: spec.clientContext,
+            excludeTools: toolFaceSnapshot.exclude,
+            deferTools: toolFaceSnapshot.defer,
+            alwaysLoadTools: toolFaceSnapshot.alwaysLoad,
+            ...(toolFaceSnapshot.restoreGated !== undefined ? { restoreGatedTools: toolFaceSnapshot.restoreGated } : {}),
+            promptProfile,
+            ...(spec.additionalDirectories !== undefined ? { additionalDirectories: Object.freeze([...spec.additionalDirectories]) } : {}),
+            ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
+            ...(spec.envFacts !== undefined ? { envFacts: { ...spec.envFacts } } : {}),
+            ...(spec.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: spec.memoryPersistenceCapable } : {}),
+            get memoryCaptureOptedOut() {
+                return input.memoryEngineSession()?.captureOptOut?.optedOut() ?? false;
+            },
+            get memoryCaptureIndeterminate() {
+                return input.memoryEngineSession()?.captureOptOut?.indeterminate() ?? false;
+            },
+            get memoryCaptureControlDir() {
+                return input.memoryEngineSession()?.engine.controlPlaneDir;
+            },
+            get memoryCaptureAncestors() {
+                const ctl = input.memoryEngineSession()?.engine.controlPlaneDir;
+                return [...(internals?.memoryCaptureAncestors ?? []), { sessionId, ...(ctl !== undefined ? { controlDir: ctl } : {}) }];
+            },
+            getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
+            parentCwd: taskRootFinal,
+            ...(fileHistoryEnabled ? { fileHistoryLineage: { scope: historyScope, root: historyRoot, fs: historyFs } } : {}),
+            reminderMark,
+            reminderDisclosureCounts,
+            ...(centerAdoption !== undefined ? { centerArtifactDigest: centerAdoption.artifact.artifactDigest } : {}),
+            ...(centerAdoption?.sourceRevision !== undefined ? { centerSourceRevision: centerAdoption.sourceRevision } : {}),
+            activeSkillScope: () => skillScope.active(),
+            inheritedGateForChildren,
+            delegationProvenanceForChildren,
+            delegationSettlement: delegationSettlementForChildren,
+            ...(autoModeDecider ? { autoModeReview: { decider: autoModeDecider } } : {}),
+            ...(spec.durableApproval !== undefined ? { durableApprovalForChildren: { ...spec.durableApproval } } : {}),
+            ...(spec.checkpointStore === null ? { checkpointStoreDisabledForChildren: true } : {}),
+            taskId: hostTaskId,
+            ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
+            ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
+            ...(internals?.rootSessionId !== undefined ? { rootSessionId: internals.rootSessionId } : {}), ...(internals?.placementRoot !== undefined ? { placementRoot: internals.placementRoot } : {}),
+            ...(internals?.explicitAgentName !== undefined ? { spawnedAgentName: internals.explicitAgentName } : {}),
+            ...(internals?.peerSelfRef !== undefined ? { peerSelfRef: internals.peerSelfRef } : {}),
+            ...(internals?.peerInboundChainRef !== undefined ? { peerInboundChainRef: internals.peerInboundChainRef } : {}),
+            ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
+            ...(sessions.fork !== undefined
+                ? {
+                    hostSessionFork: async () => {
+                        const forked = (await sessions.fork(sessionId, spec.principal ?? null)) ?? null;
+                        if (forked === null)
+                            return null;
+                        return {
+                            sessionId: forked,
+                            release: async () => {
+                                await sessions.release?.(forked);
+                            },
+                        };
+                    },
+                }
+                : {}),
+            sessionId,
+            ...(spec.backgroundScope !== undefined ? { backgroundScope: spec.backgroundScope } : {}),
+            ...(resolvedInteractionPosture !== undefined ? { interactionPosture: resolvedInteractionPosture } : {}),
+            ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
+            ...(internals?.onTaskNotification ? { onTaskNotification: internals.onTaskNotification } : {}),
+            ...(forwardEvent ? { forwardEvent } : {}),
+            ...(internals?.onSubagentSpawn ? { onSubagentSpawn: internals.onSubagentSpawn } : {}),
+            ...(subagentRetain ? { subagentRetain } : {}),
+            ...(worktreeIsolation ? { worktreeIsolation } : {}),
+            ...(internals?.insideFork === true ? { insideFork: true } : {}),
+            ...(agentForkDenial !== undefined ? { forkAccess: { denied: agentForkDenial } } : {}),
+            ...(observersActive ? { observersAllowed: true } : {}),
+            requestReview,
+            requestStopAfterTurn,
+            ...(spec.enablePlanMode === true ? { enterPlanMode } : {}),
+        };
+    };
+    return { liveInheritedGate, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, inheritedParentConstraints, autoModeIntent, inheritedAdmittedOrgScopes, priorOwnOrgVerdict, orgGovernedProvenance, effectiveShellGate, ownSessionRulesRef, memoryAdmittedOrgScopesRef, ownOrgVerdictRef, orgAdmissionCheckpointState, faceCheckpointSection, faceCheckpointState, f012CheckpointState, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, frozenOnQuestion, provenanceForChildrenRef, delegationSettlementRef, inheritedGateForChildren, carrierReadFace, fullShellReachable, gateStopRef, stopForDenialLimit, enrichSpecToolCtx };
+}

package/dist/core/runner/prepare-listings.d.ts

@@ -0,0 +1,77 @@
+/**
+ * design/390 M15 — prepareTask's LISTINGS phase: the per-task agent definitions' tool-name audit
+ * (deny entries fail loud, allow entries advise), the agent-listing announce face read off the
+ * delegation tool's roster (with its deferred / excluded / removal-to-zero arms), the two listing
+ * opt-out advisories, the announced-listings mirror seeded from the once-per-session ledger, the
+ * deferred roster's ToolSearch ride, and the date_change seam. The body is the driver's stretch moved
+ * verbatim; the interface is the dependency list it had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between
+ * the disclosure mount before it and the context-lane seats after it (design/390 §1.5 S1: a stretch
+ * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
+ *
+ * Throws pass through unchanged: `config.agent.unknown_tool` (a deny entry naming a tool this
+ * deployment does not mount — a typo there would silently guard nothing).
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { TaskSpec } from "../types.js";
+import type { AnnounceOnceSink, Prepared, PrepareResume, ToolFaceSnapshot } from "./contracts.js";
+import type { AnnouncedListingSnapshot } from "../../internal/harness.js";
+export interface PrepareListingsInput {
+    /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `agents` (the audit's subject), `tools`
+     *  (the roster-bearing delegation tool, by its `agentListing` marker), `sessionId` (continuation
+     *  ⇒ seeded/removal projections), `attachments` (the two opt-outs). Never mutated. */
+    spec: Pick<TaskSpec, "agents" | "tools" | "sessionId" | "attachments">;
+    /** borrowed-readonly — the FULLY ASSEMBLED mount array (names + aliases = the audit's universe).
+     *  Read only; this phase never mutates the roster. */
+    tools: ReadonlyArray<AgentTool>;
+    /** borrowed-readonly — the once-per-session ledger: its deduplicated operator sink (`onError`) and
+     *  the whole announced snapshot (`arms()`) the mirror is seeded from. */
+    onceLedger: AnnounceOnceSink & {
+        arms(): AnnouncedListingSnapshot;
+    };
+    /** borrowed-readonly — the acquired session's id (operator-line context). */
+    sessionId: string;
+    /** borrowed-readonly — the frozen tool face: `exclude` / `defer` decide the roster face's arm. */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude" | "defer">;
+    /** borrowed-readonly — the activated deferred names as of prepare (transcript replay / checkpoint
+     *  seed); only `has()` is read: an already-ACTIVE roster tool un-defers its listing face. The set
+     *  keeps mutating mid-run (ToolSearch activations) — this phase reads it once, here. */
+    activeTools: ReadonlySet<string>;
+    /** borrowed-readonly — the durable-resume carrier: presence (seedAnnounced) and
+     *  `seed.announcedListings.agents` (the removal-to-zero projection's gate). */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+    /** borrowed-readonly — the project-context phase's skills-listing projection; read only for the
+     *  skills opt-out advisory (entries.length). */
+    skillsListing: Prepared["skillsListing"];
+    /** borrowed-mutable — the deferred roster's ToolSearch RIDE seat (declared by the disclosure
+     *  mount, read at activation time through `listingRideRef.current?.(newly)`). Written here, once,
+     *  on a deferred roster face; no later writer. Identity is the contract (the mount's closures read
+     *  this exact cell). */
+    listingRideRef: {
+        current?: (newly: readonly string[]) => string | undefined;
+    };
+    /** borrowed-readonly — the prompt assembly's date re-renderer; presence alone decides whether the
+     *  date_change seam exists (a provider that owns the whole prompt has none). */
+    renderWithDate: ((date: string) => string) | undefined;
+    /** borrowed-readonly — the environment facts; only `date` is read (the leg's frozen date). */
+    envFacts: {
+        readonly date?: string;
+    };
+    /** borrowed-readonly — whether the client zone validated (the seam re-judges "today" in it). */
+    tzValid: boolean;
+    /** borrowed-readonly — the client's declared zone (used only when `tzValid`). */
+    userTz: string | undefined;
+}
+export interface PrepareListingsResult {
+    /** owned — the agent-listing announce projection (`Prepared.agentListing`): the roster off the
+     *  delegation tool's effective face, the removal-to-zero projection, or undefined (silent). */
+    agentListing: Prepared["agentListing"];
+    /** owned — the announced-listings mirror seeded from the ledger's whole snapshot
+     *  (`Prepared.announcedListingsRef`); the run loop and the checkpoint serializer write it from here on. */
+    announcedListingsRef: Prepared["announcedListingsRef"];
+    /** owned — the date_change seam (`Prepared.dateChange`), or undefined when the prompt has no date re-renderer. */
+    dateChange: Prepared["dateChange"];
+}
+/** The M15 phase body — prepareTask's listings stretch, verbatim (see the module header). */
+export declare function prepareListings(input: PrepareListingsInput): PrepareListingsResult;