@sema-agent/core 7.5.1 → 7.6.0

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

@@ -0,0 +1,377 @@
+import { uuidv7 } from "../../engine/session/uuid.js";
+import { Value } from "typebox/value";
+import { ASK_USER_QUESTION_TOOL_NAME, classifyQuestionOutcome, validateAskQuestions } from "../ask-question.js";
+import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
+import { boundInputHashOf } from "../canonical-json.js";
+import { BINDING_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, mintCheckpointId, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, resolveDeclaredFidelity, samePlainValue, TOKEN_CHECKPOINT_VERSION, } from "../checkpoint-store.js";
+import { pauseOf } from "../pause-registry.js";
+import { askCarryRowMembers } from "../hooks.js";
+import { defaultTaskRegistry } from "../task-registry.js";
+import { isLiveApproverSeat, carriesBidiControls, describeThrown, refuseOutOfContractDecision, tryCloneArgs } from "../tool-policy.js";
+import { InMemoryToolResultStore, ScopedToolResultStore, isVolatileOffloadStore } from "../tool-result-store.js";
+import { raceAbort, raceSettlementAgainstSignal } from "./abort-race.js";
+import { checkpointScopeOf } from "./checkpoint-scope.js";
+import { CONTENT_ASK_BINDING_CAP } from "./content-ask-bindings.js";
+import { DEFAULT_UNATTENDED_APPROVAL_TTL_MS, publishCommittedSuspend, sanitizedTtlMs } from "./park-commit.js";
+import { remoteEnvFailureNote } from "./remote-env-retry.js";
+class ParkRefusal extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ParkRefusal";
+    }
+}
+export function prepareParkAsk(input) {
+    const { askLane, saga, spec, deps, sessionId, checkpointStore, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedBash, shellGatedMonitor, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef } = input;
+    if (askLane === undefined || saga === undefined)
+        return { parkAsk: undefined };
+    const { composedCallSignal, approvalPreviewOf } = askLane;
+    const { inFlightSpendMicroUsd, serializeCheckpointState, compensatePausedVM, commitSuspendSaga, suspendLoopCapHit, suspendableEnv, parkOnlyRemoteEnv, parkOnlyHandle } = saga;
+    const resolveContentAsk = async (req, callSignal) => {
+        const contentAskSignal = composedCallSignal(callSignal);
+        if (!contentAskRoutable(req.toolCallId) || liveQuestionFace === undefined || mountedQuestionTool === undefined) {
+            return { kind: "unavailable", parkDeclined: false };
+        }
+        const deliveryId = uuidv7();
+        const bindOutcome = (entry, questionsHash) => {
+            if (contentAskBindings.size >= CONTENT_ASK_BINDING_CAP && !contentAskBindings.has(req.toolCallId))
+                return;
+            contentAskBindings.set(req.toolCallId, { ...entry, questionsHash, deliveryId });
+        };
+        const refuseBeforeDelivery = (code, presentedInput) => ({
+            kind: "delivery_failure",
+            code,
+            ...(presentedInput !== undefined ? { presentedInput } : {}),
+        });
+        let retained;
+        let presented;
+        try {
+            retained = structuredClone(req.args);
+            presented = structuredClone(retained.questions);
+        }
+        catch {
+            return refuseBeforeDelivery("question.malformed_request");
+        }
+        const retainedQuestionsHash = boundInputHashOf(retained.questions);
+        if (!Value.Check(mountedQuestionTool.parameters, retained) || validateAskQuestions(presented) !== undefined) {
+            return refuseBeforeDelivery("question.malformed_request", retained);
+        }
+        if (contentAskBindings.size >= CONTENT_ASK_BINDING_CAP && !contentAskBindings.has(req.toolCallId)) {
+            return { kind: "unavailable", parkDeclined: true };
+        }
+        if (contentAskSignal.aborted) {
+            return { kind: "delivery_failure", code: "question.aborted", presentedInput: retained };
+        }
+        try {
+            const facePromise = (async () => liveQuestionFace({
+                toolCallId: req.toolCallId,
+                questions: presented,
+                ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
+                sourceTaskId: sessionId,
+                boundInputHash: boundInputHashOf(retained),
+                deliveryId,
+            }, contentAskSignal))();
+            const settlement = await raceAbort(facePromise.then((outcome) => ({ tag: "outcome", outcome }), (error) => ({ tag: "threw", error })), contentAskSignal, () => ({ tag: "aborted" }));
+            if (settlement.tag === "aborted") {
+                void facePromise.then((late) => {
+                    if (classifyQuestionOutcome(late).shape !== "answered")
+                        return;
+                    lateStrandedAnswers.push({ deliveryId, toolCallId: req.toolCallId });
+                    discloseStrandedAnswers([{ deliveryId, toolCallId: req.toolCallId }], "the task had already ended when the answer arrived");
+                }, () => undefined).catch(() => undefined);
+            }
+            if (settlement.tag === "outcome") {
+                const outcome = settlement.outcome;
+                const reading = classifyQuestionOutcome(outcome);
+                if (reading.shape === "contradictory") {
+                    bindOutcome({ kind: "failed", error: new Error("the question channel returned a contradictory outcome (an unavailable answer)") }, retainedQuestionsHash);
+                    return { kind: "delivery_failure", code: "question.human_channel_failed", presentedInput: retained };
+                }
+                if (reading.shape === "unavailable")
+                    return { kind: "unavailable", parkDeclined: true, presentedInput: retained };
+                const answerSnapshot = reading.answer;
+                bindOutcome({ kind: "answered", answer: answerSnapshot }, retainedQuestionsHash);
+                return { kind: "answered", presentedInput: retained };
+            }
+            const error = settlement.tag === "threw"
+                ? settlement.error
+                : Object.assign(new Error("the task ended while this question was still out"), { name: "AbortError" });
+            bindOutcome({ kind: "failed", error }, retainedQuestionsHash);
+            return {
+                kind: "delivery_failure",
+                code: settlement.tag === "aborted" || contentAskSignal.aborted ? "question.aborted" : "question.human_channel_failed",
+                presentedInput: retained,
+            };
+        }
+        catch (err) {
+            bindOutcome({ kind: "failed", error: err }, retainedQuestionsHash);
+            return { kind: "delivery_failure", code: "question.human_channel_failed", presentedInput: retained };
+        }
+    };
+    const suspendAsk = parkLaneArmed && checkpointStore !== undefined
+        ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule, askDecisionReason, probeReason, probeCause, segmentCoverage, matchedAskRule, probeMandated, carry) => {
+            const syncFirstEligible = req.toolName === ASK_USER_QUESTION_TOOL_NAME ? contentAskRoutable(req.toolCallId) : isLiveApproverSeat(onAsk);
+            if (syncFirstEligible &&
+                runtimeCaps?.forceDurableGate !== true &&
+                liveFaceUnavailable !== true &&
+                !inheritedUnavailableAsks.has(req.toolCallId)) {
+                return undefined;
+            }
+            const cutSignal = composedCallSignal(carry?.signal);
+            let token;
+            let gate;
+            let cp;
+            let remoteHandle;
+            const remoteEnv = suspendableEnv;
+            try {
+                const parked = tryCloneArgs(postHookArgs);
+                if (!parked.ok) {
+                    throw new ParkRefusal(`the arguments of "${req.toolName}" cannot be captured onto an approval checkpoint (unclonable value: ${parked.reason}) — ` +
+                        `a durable approval row must hold an inert snapshot of exactly what a human approves and a resume executes`, { cause: parked.cause });
+                }
+                let backendFidelity;
+                try {
+                    backendFidelity = resolveDeclaredFidelity(checkpointStore, "checkpointStore");
+                }
+                catch (err) {
+                    throw new ParkRefusal(`the checkpoint backend declares an unrecognized encoding fidelity, so the width of the snapshot this row may hold is unknown (${describeThrown(err)}) — ` +
+                        `refusing to park rather than guess which values would survive it`, { cause: err });
+                }
+                const captured = encodeAtFidelity(backendFidelity, parked.value);
+                if (!captured.ok) {
+                    throw new ParkRefusal(`the arguments of "${req.toolName}" cannot be encoded by this checkpoint backend (${describeThrown(captured.cause)}) — ` +
+                        `a durable approval row must hold an inert snapshot of exactly what a human approves and a resume executes`, { cause: captured.cause });
+                }
+                const parkedArgs = captured.value;
+                const projectionMovedArgs = backendFidelity !== "structured-clone" && !samePlainValue(parked.value, parkedArgs);
+                if (projectionMovedArgs && basePolicyForResumeEdit === undefined) {
+                    throw new ParkRefusal(`the arguments of "${req.toolName}" change shape when stored by this checkpoint backend, and no policy is wired to re-adjudicate the stored shape ` +
+                        `(no basePolicyForResumeEdit override and no caller toolPolicy) — refusing to file a row whose executable form nothing adjudicated`);
+                }
+                if (projectionMovedArgs && basePolicyForResumeEdit !== undefined) {
+                    const presented = encodeAtFidelity(backendFidelity, parkedArgs);
+                    if (!presented.ok) {
+                        throw new ParkRefusal(`the stored form of "${req.toolName}"'s arguments could not be presented for re-adjudication (${describeThrown(presented.cause)})`, { cause: presented.cause });
+                    }
+                    const reprojectedRaced = await raceSettlementAgainstSignal(Promise.resolve(basePolicyForResumeEdit.check({
+                        toolName: req.toolName,
+                        args: presented.value,
+                        toolCallId: req.toolCallId,
+                        budget: budgetSnapshot,
+                        ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}),
+                    }, cutSignal)), cutSignal);
+                    if (reprojectedRaced.tag === "aborted")
+                        return undefined;
+                    if (reprojectedRaced.tag === "threw")
+                        throw reprojectedRaced.error;
+                    const reprojected = refuseOutOfContractDecision(reprojectedRaced.value);
+                    const demanded = reprojected.updatedInput !== undefined ? tryCloneArgs(reprojected.updatedInput) : undefined;
+                    const rewroteTheFiledValue = reprojected.updatedInput !== undefined &&
+                        !(demanded?.ok === true &&
+                            samePlainValue(demanded.value, parkedArgs) &&
+                            samePlainValue(reprojected.updatedInput, parkedArgs));
+                    if (reprojected.action === "deny" || rewroteTheFiledValue) {
+                        throw new ParkRefusal(`the arguments of "${req.toolName}" change shape when stored by this checkpoint backend, and the deployment's tool policy does not accept the stored shape` +
+                            `${reprojected.action === "deny" && reprojected.message ? `: ${reprojected.message}` : ""} — ` +
+                            `refusing to file a row whose executable form nothing adjudicated`);
+                    }
+                }
+                if (offloadStore && isVolatileOffloadStore(offloadStore) && !offloadStore.isEmpty()) {
+                    throw new ParkRefusal("durable suspend requires a durable toolResultStore (the default InMemoryToolResultStore " +
+                        "holds offloaded results that are lost across a cross-replica resume); inject " +
+                        "RunnerDeps.toolResultStore or disable offload.");
+                }
+                if (ownedEnv !== undefined && remoteEnv === undefined && parkOnlyRemoteEnv === undefined) {
+                    throw new ParkRefusal(incompleteSuspendAdapter !== undefined
+                        ? `durable suspend is not supported with this per-task executionEnvFactory env: it declares capabilities.suspendable but its adapter does not implement ${incompleteSuspendAdapter.join(" or ")}, so a snapshot taken now could never be restored. Implement the full RemoteExecutionEnv restore surface, or declare capabilities.suspendable:false if the workspace is externally durable (the park-only lane).`
+                        : "durable suspend is not supported with a non-remote per-task executionEnvFactory env: the " +
+                            "minted env is destroyed on suspend, so a resumed file/shell tool would act on a fresh " +
+                            "(empty) env. Use a RemoteExecutionEnv factory (it is paused, not destroyed) or a static, " +
+                            "caller-owned RunnerDeps.executionEnv.");
+                }
+                const leafId = await session.getLeafId();
+                if (!leafId) {
+                    throw new ParkRefusal("cannot suspend: session has no committed leaf to resume from");
+                }
+                const { messages } = await session.buildContext();
+                const { batchToolCallIds, completedCallIds } = batchContextAt(messages, req.toolCallId);
+                if (cutSignal.aborted) {
+                    return undefined;
+                }
+                if (suspendLoopCapHit(suspendChainBase(), maxSuspends, ` for tool "${req.toolName}" — likely a resume/restart loop.`))
+                    return undefined;
+                if (remoteEnv !== undefined) {
+                    if (hasBackgroundShell(remoteEnv))
+                        await sweepBackgroundShells(remoteEnv, defaultTaskRegistry);
+                    const snap = await remoteEnv.suspendVM({ abortSignal: cutSignal });
+                    if (!snap.ok) {
+                        remoteEnvFailures.push(remoteEnvFailureNote("suspendVM", snap.error, 1));
+                        throw new Error(`suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error });
+                    }
+                    remoteHandle = { ...remoteEnv.workspaceHandle(), snapshotId: snap.value };
+                    if (cutSignal.aborted) {
+                        const back = await compensatePausedVM(remoteEnv, snap.value);
+                        if (!back.ok) {
+                            abortController.abort();
+                            void harness.abort();
+                        }
+                        return undefined;
+                    }
+                }
+                else if (parkOnlyRemoteEnv !== undefined) {
+                    if (hasBackgroundShell(parkOnlyRemoteEnv) && spec.retainBackgroundProcesses !== true)
+                        await sweepBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry);
+                    remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+                }
+                token = mintCheckpointToken();
+                const riskDescriptor = buildRiskDescriptor({
+                    toolName: req.toolName,
+                    args: parkedArgs,
+                    safety,
+                    ...(shadowedRule !== undefined ? { shadowedRule } : {}),
+                    ...(probeReason !== undefined ? { probeReason } : {}),
+                    ...(probeCause !== undefined ? { probeCause } : {}),
+                    shellGated: (req.toolName === "Bash" && shellGatedBash) || (req.toolName === "Monitor" && shellGatedMonitor),
+                    ...(effectiveShellGate !== "off" ? { shellGateDoctrine: effectiveShellGate } : {}),
+                });
+                gate =
+                    safety !== undefined || realApproval !== undefined
+                        ? {
+                            kind: "irreversible_ask",
+                            reason: safety !== undefined
+                                ? `human approval required before safety-tightened tool "${req.toolName}"`
+                                : `real human approval required for tool "${req.toolName}" (non-budgetable: ${realApproval.origin})`,
+                            toolName: req.toolName,
+                            ...(safety !== undefined ? { safetyAxis: safety } : {}),
+                            ...(realApproval !== undefined ? { realApproval } : {}),
+                            riskDescriptor,
+                        }
+                        : durableApproval
+                            ? {
+                                kind: "human",
+                                reason: `human approval required for tool "${req.toolName}"`,
+                                toolName: req.toolName,
+                                riskDescriptor,
+                            }
+                            : {
+                                kind: "irreversible_ask",
+                                reason: `human approval required before irreversible tool "${req.toolName}"`,
+                                toolName: req.toolName,
+                                riskDescriptor,
+                            };
+                const scope = durableApproval?.scope || checkpointScopeOf({ principal: spec.principal });
+                const ttlMs = sanitizedTtlMs(durableApproval?.ttlMs);
+                const checkpointState = serializeCheckpointState(remoteHandle, inFlightSpendMicroUsd());
+                if (realApproval !== undefined && checkpointState.readFace !== undefined) {
+                    checkpointState.readFace = { ...checkpointState.readFace, realApproval: true };
+                }
+                const approvalLedger = debitLedger(priorLedger, liveSpendRef.get?.() ?? { costMicroUsd: 0, tokens: 0, turns: 0, walltimeMs: 0 }, resourceTotal, { countSlice: false });
+                const mintedAt = Date.now();
+                cp = {
+                    token,
+                    checkpointId: mintCheckpointId(),
+                    version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : realApproval !== undefined ? REAL_APPROVAL_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : approvalLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
+                    scope,
+                    sessionId,
+                    leafId,
+                    ...pauseOf(gate, {
+                        kind: "tool_approval",
+                        toolCallId: req.toolCallId,
+                        toolName: req.toolName,
+                        args: parkedArgs,
+                        ...(() => {
+                            const p = approvalPreviewOf(req.toolName, parkedArgs);
+                            const bidi = carriesBidiControls(parkedArgs) || carriesBidiControls(p.preview);
+                            return {
+                                ...(p.preview !== undefined ? { preview: p.preview } : {}),
+                                ...(p.withheld !== undefined ? { previewWithheld: p.withheld } : {}),
+                                ...(bidi ? { hasBidiControls: true } : {}),
+                            };
+                        })(),
+                        ...(realApproval !== undefined ? { requiresRealApproval: true } : {}),
+                        ...askCarryRowMembers(carry),
+                        ...ruleOffersOf(req.toolName, parkedArgs, {
+                            ...(realApproval !== undefined ? { requiresRealApproval: true } : {}),
+                            ...(shadowedRule !== undefined ? { persistedRuleShadowed: shadowedRule } : {}),
+                            ...(askDecisionReason !== undefined ? { decisionReason: askDecisionReason } : {}),
+                            ...(matchedAskRule !== undefined ? { matchedAskRule } : {}),
+                            ...(probeMandated === true ? { probeMandated: true } : {}),
+                            ...(inheritedUnavailableAsks.has(req.toolCallId) ? { inheritedUnresolved: true } : {}),
+                            ...(segmentCoverage !== undefined ? { segmentCoverage } : {}),
+                        }),
+                        boundInputHash: boundInputHashOf(parkedArgs),
+                        batchToolCallIds,
+                        completedCallIds,
+                    }),
+                    state: checkpointState,
+                    deadline: ttlMs !== undefined
+                        ? mintedAt + ttlMs
+                        : durableApproval !== undefined
+                            ? undefined
+                            : mintedAt + DEFAULT_UNATTENDED_APPROVAL_TTL_MS,
+                    status: "pending",
+                    createdAt: mintedAt,
+                    suspendedAt: now(),
+                    humanReview: humanReviewRef.count > 0
+                        ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                        : undefined,
+                    suspendCount: suspendChainBase() + 1,
+                    resourceLedger: approvalLedger,
+                    sourceTaskId: sessionId,
+                    ...(spec.principal ? { principal: spec.principal } : {}),
+                    ...(durableApproval !== undefined ? { durableApproval: { ...durableApproval } } : {}),
+                };
+            }
+            catch (err) {
+                const cutWon = cutSignal.aborted;
+                const preselected = cutWon
+                    ? undefined
+                    : {
+                        parkFailed: err instanceof ParkRefusal
+                            ? err.message
+                            : "the durable approval park could not be prepared (the deployment's error face carries the exception)",
+                    };
+                try {
+                    deps.onError?.(err, { phase: "config", sessionId });
+                }
+                catch {
+                }
+                return preselected;
+            }
+            const committed = await commitSuspendSaga(token, cp, remoteEnv, remoteHandle, cutSignal);
+            if (committed.tag !== "committed") {
+                if (committed.tag === "cut")
+                    return undefined;
+                if (committed.tag === "absent") {
+                    if (cutSignal.aborted)
+                        return undefined;
+                    return committed.reason !== undefined ? { parkFailed: committed.reason } : undefined;
+                }
+                return { parkFailed: committed.reason };
+            }
+            publishCommittedSuspend({ pausedRef }, token, gate, cp.scope, remoteHandle, cp.checkpointId, cp.pendingAction);
+            try {
+                await sessions.pin?.(sessionId);
+            }
+            catch (pinErr) {
+                deps.onError?.(pinErr, { phase: "config", sessionId });
+            }
+            abortController.abort();
+            void harness.abort();
+            return { token, gate };
+        }
+        : undefined;
+    return { parkAsk: { resolveContentAsk, suspendAsk } };
+}
+export function batchContextAt(messages, currentId) {
+    let batch = [];
+    for (const m of messages) {
+        if (m.role === "assistant") {
+            const ids = [...new Set(m.content.filter((c) => c.type === "toolCall").map((c) => c.id))];
+            if (ids.includes(currentId))
+                batch = ids;
+        }
+    }
+    const resolved = new Set(messages.filter((m) => m.role === "toolResult").map((m) => m.toolCallId));
+    const completedCallIds = batch.filter((id) => id !== currentId && resolved.has(id));
+    return { batchToolCallIds: batch, completedCallIds };
+}

package/dist/core/runner/prepare-policy-chain.d.ts

@@ -0,0 +1,208 @@
+/**
+ * design/390 §1.2 M17 (design/238 P21) — prepareTask's POLICY-CHAIN phase, verbatim from the driver: the caller policy
+ * and its name audit (advisory once per deployment; the two hard refusals), the session / ancestor / frozen-projection /
+ * skill-scope deny-narrowing layers and their fold, the resume-edit base policy, the hook record with its timeout seat
+ * and observational half, the same-instance arbitration machinery (the caller slot's first-decision record), the
+ * inherited-unavailable marker channel, the RB-40 grant record, the sandbox-admission mode's arming and its three
+ * sideband maps, the source-identity and risk-axes factories, the two permission-rule lanes and the rule-offer
+ * factory, the approved-edit re-check, the inherited-constraint wrappers (the same-instance adapter and the true
+ * wrapper), the rewrite-emitter index and the instrumented chain, the integrity guards, the fold, and the final-form
+ * re-check that is the effective policy. The advised-names dedupe pair only this section reads moved with it.
+ * The interface is the dependency list the segment had implicitly (design/238 R-1).
+ *
+ * ASYNC PHASE: the stretch awaits the session-policy store (the task's own rules and each ancestor's live re-read)
+ * exactly where the segment did; the closures it builds await at tool-call time. The phase boundary adds one
+ * continuation between its last await and the driver's next read — the accepted class under {@link RunInternals}
+ * `@contract prepare.deps-read-stable`.
+ *
+ * NOT CHANGED HERE: the ask-origin vocabulary. This phase is a mint site for `AskOrigin` words (through the inherited
+ * arms' `judgeInheritedClassifier` / `inheritedAskCarry`), and it carries them verbatim — the closed set, its fence and
+ * every spelling are exactly the driver's.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { ExecutionEnv } from "../../internal/harness.js";
+import { type AskClass } from "../ask-class.js";
+import type { AutoModeDecider } from "../auto-mode.js";
+import { type Hooks } from "../hooks.js";
+import type { LockedPreflight } from "../locked-config.js";
+import type { SessionPermissionRules } from "../session-policy-store.js";
+import { type OnAsk, type ToolPolicy } from "../tool-policy.js";
+import type { RunnerDeps, RuntimeCaps, TaskSpec, ToolEffect } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import type { ReadDenyMatcher } from "../../tools/fs/read-deny.js";
+import { type ActiveSkillScope } from "./active-skill-scope.js";
+import type { InheritedGate, IrreversibilityTier, PrepareResume, RunInternals } from "./contracts.js";
+import { type StopForDenialLimit } from "./denial-limit-arms.js";
+import { createRuleOffersOf, type PermissionRuleLanes } from "./permission-rule-lanes.js";
+export interface PreparePolicyChainInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `sessionId` / `principal` (the session-rule read and the lanes' identity),
+     *  `hooks` (spec over deps), `durableApproval` / `checkpointStore` (the mandate-park facility test and the sandbox arming's park prerequisites), `taskId` (the late-ask observer's detail).
+     *  Never mutated. */
+    spec: Pick<TaskSpec, "sessionId" | "principal" | "hooks" | "durableApproval" | "taskId" | "checkpointStore">;
+    /** borrowed-readonly — the deployment seats: `sessionPolicyStore` (the rule reads), `hooks` (the fallback record),
+     *  `permissionRuleStore` / `localOwnerRules` (the lanes and the offer factory), `onError` / `onNotice` (the advisories,
+     *  the refusal disclosures, the late-ask observer), `tracer` (the admission and rule-store frames), `checkpointStore` (the park facility). Receiver preserved;
+     *  the advisory dedupe is KEYED on this object's identity. */
+    deps: Pick<RunnerDeps, "sessionPolicyStore" | "hooks" | "permissionRuleStore" | "localOwnerRules" | "onError" | "onNotice" | "tracer" | "checkpointStore">;
+    /** borrowed-readonly — the trusted spawn-side channel: `parentTaskId` (the from-subagent bit), `explicitAgentName` /
+     *  `agentName` (the source agent name) — the ask source identity's local, trusted facts. */
+    internals: Pick<RunInternals, "parentTaskId" | "explicitAgentName" | "agentName"> | undefined;
+    /** borrowed-readonly — the acquired session id (every operator line's attribution; the ask source's task id). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (the late-ask observer's detail). */
+    runId: string;
+    /** borrowed-readonly — the per-task identity (the trace frames' taskId; the rule-store disclosure). */
+    hostTaskId: string;
+    /** borrowed-readonly — the FINAL task root (path rules resolve against it; the lanes' and the offers' root). */
+    taskRootFinal: string;
+    /** borrowed-readonly — the run's resolved env (path rules resolve in it; the sandbox declaration is read off it). */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the frozen preflight: `toolPolicy` (the caller slot) and `basePolicyForResumeEdit` (the lock-aware
+     *  resume-edit override). */
+    lockedPreflight: Pick<LockedPreflight, "toolPolicy" | "basePolicyForResumeEdit">;
+    /** borrowed-readonly — the run's ONE tool roster, read only here (the name audit's universe: names + aliases). */
+    tools: ReadonlyArray<AgentTool>;
+    /** borrowed-readonly — the harness list (placeholders keep their deferred names), the audit universe's second half. */
+    harnessTools: ReadonlyArray<AgentTool>;
+    /** borrowed-readonly — the effect collection, read by the narrowing layers (path-confinable write tools). */
+    toolEffects: ReadonlyMap<string, ToolEffect>;
+    /** borrowed-readonly — the egress mark set (the risk axes, the boundary predicate, the offer factory). */
+    egressTools: ReadonlySet<string>;
+    /** borrowed-readonly — the folded irreversibility tiers (the risk axes, the offer factory). */
+    irreversibilityTier: IrreversibilityTier;
+    /** borrowed-readonly — the explicit negative declarations per tool (the risk axes' "engine judged it false"). */
+    axisExplicitNegatives: ReadonlyMap<string, {
+        irreversible?: false;
+        egress?: false;
+    }>;
+    /** borrowed-readonly — the caller tools' names, the first-await snapshot (the sandbox boundary predicate: a caller tool
+     *  is never contained by the hand tools' env). */
+    ownToolNames: ReadonlySet<string>;
+    /** borrowed-readonly — whether the shell tool is under an operator `shellGate:"always"` (the offer factory's mandate term). */
+    shellGatedBash: boolean;
+    /** borrowed-readonly — the tracked-cwd seat, read per call by the lanes and the offer factory (never written here). */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the compiled read-deny judge, or undefined (the offer factory's directory negative control). */
+    readDenyMatcher: ReadDenyMatcher | undefined;
+    /** borrowed-readonly — whether the question tool mounted (the lanes' question-tool exclusion). */
+    questionToolMounted: boolean;
+    /** borrowed-readonly — the resolved per-principal entitlements; only `forceDurableGate` (the mandate-park facility and
+     *  the sandbox arming's prerequisite). */
+    runtimeCaps: Pick<RuntimeCaps, "forceDurableGate"> | undefined;
+    /** borrowed-readonly — the ancestors' session-rule snapshots (each re-read live-preferring, floor kept). */
+    inheritedAncestorRules: InheritedGate["ancestorRules"];
+    /** borrowed-readonly — the ancestors' caller-policy constraints, ancestors first (one wrapper each). */
+    inheritedParentConstraints: NonNullable<InheritedGate["parentConstraints"]>[number][] | undefined;
+    /** borrowed-readonly — the resumed leg's SEED half; only `constraintChain` (the frozen deny projections). */
+    seedInheritedGate: Pick<NonNullable<PrepareResume["seed"]["inheritedGate"]>, "constraintChain"> | undefined;
+    /** borrowed-readonly — whether any skill carries a manifest or the task inherited a frame (the skill-scope layer). */
+    hasSkillManifest: boolean;
+    /** borrowed-readonly — the live skill scope the Gate-3 layer judges over. */
+    skillScope: ActiveSkillScope;
+    /** borrowed-readonly — the FROZEN approver seat (the pass-through test's approver identity). */
+    frozenOnAsk: OnAsk | undefined;
+    /** borrowed-readonly — the identity of this task's hook-env source (the pass-through test's environment term). */
+    hookEnvSource: unknown;
+    /** borrowed-readonly — the own-hook crash reporter (the timeout seat's bad-value disclosure). */
+    notifyOwnHookCrash: (err: unknown) => void;
+    /** borrowed-readonly — this task's own classifier instance, or undefined (the pass-through test's decider term). */
+    autoModeDecider: AutoModeDecider | undefined;
+    /** borrowed-readonly — the run's ONE typed stop for a denial-limit bound (the fallback settlements call it). */
+    stopForDenialLimit: StopForDenialLimit;
+    /** borrowed-readonly — the effective delegation facts; only `isDelegatedChild` (the ask source identity). */
+    delegation: {
+        isDelegatedChild: boolean;
+    };
+    /** borrowed-readonly — the run's abort controller; only `signal` (the default call signal of every closure here). */
+    abortController: Pick<AbortController, "signal">;
+    /** borrowed-readonly — the injectable wall-clock (the inherited arms' human-wait timing). */
+    now: () => number;
+    /** borrowed-mutable — the own session-rules snapshot seat (the inherited-gate phase mints it; `inheritedGateForChildren`
+     *  reads it late). Writer: THIS phase, once, when the store returns this task's own rules. */
+    ownSessionRulesRef: {
+        current?: {
+            sessionId: string;
+            principal?: string;
+            rev: number;
+            rules: SessionPermissionRules;
+        };
+    };
+}
+export interface PreparePolicyChainResult {
+    /** owned — the resolved hook record (`spec.hooks ?? deps.hooks`), or undefined. */
+    hooks: Hooks | undefined;
+    /** owned — the per-leg hook timeout, resolved and validated ONCE (`Prepared.hookTimeoutMs`). */
+    hookTimeoutMs: number;
+    /** owned — whether the deployment declared its screening face observational. */
+    preToolUseObservational: boolean;
+    /** owned — the screening face this task's OWN gate runs in phase 1 (the observational wrapper when declared). */
+    ownGatePreToolUse: Hooks["preToolUse"] | undefined;
+    /** owned — the resume-edit base policy (`Prepared.basePolicyForResumeEdit`), or undefined. */
+    basePolicyForResumeEdit: ToolPolicy | undefined;
+    /** owned — the deny-narrowing fold (`Prepared.denyNarrowingPolicy`), or undefined when no layer exists. */
+    denyNarrowingPolicy: ToolPolicy | undefined;
+    /** owned — the caller-facing policy layers (the wiring manifest reads their COUNT). */
+    policyLayers: ToolPolicy[];
+    /** owned — THE effective policy the gate station adjudicates with (the fold plus its final-form re-check), or undefined. */
+    effectivePolicy: ToolPolicy | undefined;
+    /** borrowed-mutable — the inherited-unavailable marker channel. Writers: the inherited arms here (mark); the gate station
+     *  (the lifecycle-end sweep) and the park lane's consumers (delete on consumption). */
+    inheritedUnavailableAsks: Set<string>;
+    /** borrowed-mutable — the RB-40 grant record. Writers: the inherited arms here (record a clean allow at a live approver);
+     *  the gate station (consume on reuse, sweep at settlement). */
+    inheritedAskGrants: Map<string, {
+        approver: unknown;
+        argsJson: string;
+        presented: unknown;
+        waitMs: number;
+    }>;
+    /** owned — the SINGLE AskRequest source-identity factory every resolveAsk construction site spreads. */
+    askSourceIdentity: () => {
+        principal?: string;
+        sourceTaskId?: string;
+        fromSubagent?: true;
+        sourceAgentName?: string;
+        isDelegatedChild?: true;
+    };
+    /** owned — the engine-judged risk axes for an ask, from the same resolved sources the safety tightens use. */
+    riskAxesOf: (toolName: string) => {
+        riskAxes?: {
+            irreversible?: boolean;
+            egress?: boolean;
+        };
+    };
+    /** owned — the ONE rule-offer factory for all five ask-mint sites. */
+    ruleOffersOf: ReturnType<typeof createRuleOffersOf>;
+    /** owned — the personal permission-rule lane, or undefined. */
+    permissionRuleLane: PermissionRuleLanes["personal"];
+    /** owned — the org permission-rule lane (`Prepared.permissionRuleOrg`), or undefined. */
+    permissionRuleOrgLane: PermissionRuleLanes["org"];
+    /** owned — whether the sandbox-admission mode armed (declared isolation with its park prerequisites). */
+    sandboxAdmissionArmed: boolean;
+    /** owned — the NOT-CONTAINED classification: a call the declared sandbox does not contain. */
+    sandboxBoundaryCapable: (toolName: string) => boolean;
+    /** owned — the admission disclosure's trace emitter (the gate station emits it once the fold settles). */
+    emitSandboxAdmitted: (info: {
+        toolCallId: string;
+        toolName: string;
+        askClasses: ReadonlyArray<{
+            cls: AskClass;
+            layer: string;
+        }>;
+        boundary: "sandbox_internal";
+    }) => void;
+    /** borrowed-mutable — the per-call fold ask-class record. Writers: the instrumented chain here (record); the gate station
+     *  (read for strict dominance, then sweep). */
+    foldAskClasses: Map<string, Array<{
+        cls: AskClass;
+        layer: string;
+    }>>;
+    /** borrowed-mutable — the ancestor arms' deferred sandbox admissions. Writers: the inherited arms here (record); the gate
+     *  station (emit once the fold settles, then sweep). */
+    ancestorSandboxAdmissions: Map<string, Array<{
+        cls: AskClass;
+        layer: string;
+    }>>;
+}
+/** The M17 phase body — prepareTask's policy-chain stretch, verbatim (see the module header). */
+export declare function preparePolicyChain(input: PreparePolicyChainInput): Promise<PreparePolicyChainResult>;