@sema-agent/core 1.279.0

package/dist/core/runner/prepare-task.js

@@ -0,0 +1,2087 @@
+import { createHash, randomBytes } from "node:crypto";
+import { AgentHarness, DEFAULT_CHARS_PER_TOKEN, estimateContextTokens } from "../../internal/harness.js";
+const PROMPT_HASH_SALT = randomBytes(16);
+import { createAutoModeDecider } from "../auto-mode.js";
+import { buildAutoModePrompt, renderAutoModeAction, renderAutoModeWindow } from "../auto-mode-prompt.js";
+import { resolveModel, resolveTaskModel, roleModelIfSet } from "../roles.js";
+import { primaryActivityArg } from "../arg-summary.js";
+import { materializeMcpTools } from "../mcp.js";
+import { brainToRuntime } from "../runtime.js";
+import { MemoryEngine } from "../memory-engine/engine.js";
+import { deriveControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
+import { assertScopeContractPlacement, parseScopeKey, resolveProjectId } from "../memory-engine/scope-contract.js";
+import { classifyScopePlanes, derivePersonalControlDir, derivePersonalMemoryDir, mergeHarvestReports, mergeInjections, needsDualRoots, parsedProjectPlane } from "../memory-engine/dual-root.js";
+import { FileMemoryEngineBackend } from "../memory-engine/file-backend.js";
+import { Session, isSessionConflict, hasSessionFork } from "../session.js";
+import { createAgentTranscriptTool, createSendMessageTool, createSubagentWorktreeHelper, forkGovernanceDenial, AGENT_TRANSCRIPT_TOOL_NAME, SEND_MESSAGE_TOOL_NAME, SubagentRetainLedger } from "../../agents/subagent.js";
+import { combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, resolveAsk } from "../tool-policy.js";
+import { ActiveSkillScope, createActiveSkillScopePolicy } from "./active-skill-scope.js";
+import { computeCallCap, createCallCapRef, softExecDeadlineMs } from "./call-cap.js";
+import { CHANGED_FILES_MTIME_EPS_MS } from "./turn-attachments.js";
+import { emitTrace } from "../trace.js";
+import { createSessionRulePolicy } from "./session-rule-policy.js";
+import { cloneObserverInput, formatHookFeedback, runToolGate } from "../hooks.js";
+import { reconcileInterruptedSession } from "../session-reconcile.js";
+import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
+import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
+import { defineTool } from "../tools.js";
+import { pathToUri } from "../lsp-protocol.js";
+import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, isVolatileOffloadStore, OFFLOAD_TOOL_NAME, makeReadToolResultTool, withToolResultOffload, } from "../tool-result-store.js";
+import { OUTPUT_TOOL_NAME, SKILL_TOOL_NAME, buildSkillsBlock, makeOutputTool, makeReportBlockedTool, makeSkillTool, normalizeSkills } from "./synthetic-tools.js";
+import { compileOutputSchema } from "./strict-output-schema.js";
+import { TOOL_SEARCH_NAME, buildDeferredRegistry, classifyDeferred, extractDiscoveredToolNames, makePlaceholderTool, makeToolSearchTool, } from "./tool-disclosure.js";
+import { composeMemoryBlock, normalizeMemorySpec } from "../memory.js";
+import {} from "./memory-consolidation.js";
+import { composeSystemPrompt, composeConstitution, defaultPromptProvider, buildEnvironmentContext, buildGitSnapshot, formatLocalDate, isValidTimeZone, CYBER_RISK, URL_SAFETY, DEFAULT_SYSTEM_PROMPT, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
+import { clearStaleToolResults, dropEmptyFailureAssistants, editBudget } from "../context-edit.js";
+import { capAggregateToolResults } from "../tool-result-budget.js";
+import { capAggregateMediaBytes, AGGREGATE_MEDIA_BUDGET_BYTES } from "../media-byte-cap.js";
+import { dropOrphanToolResults, guardBudget, trimToBudget } from "../context-guard.js";
+import { StubExecutionEnv } from "../stub-env.js";
+import { hasDestroy, isIsolated, isRemoteExecutionEnv, isSuspendable } from "../remote-env.js";
+import { hasBackgroundShell } from "../background-shell.js";
+import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
+import { createMonitorTool } from "../../tools/monitor.js";
+import { createWorktreeTools } from "../../tools/worktree.js";
+import { bashReversibilityProbe, createHandsToolkit, seedReadFileStateFromContext, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
+import { decodeTextBytes } from "../../tools/fs/encoding.js";
+import { createAskUserQuestionTool } from "../ask-question.js";
+import { createSchedulerTools } from "../../tools/scheduler-tools.js";
+import { createPresentPlanTool, createEnterPlanModeTool, PRESENT_PLAN_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME } from "../present-plan-tool.js";
+import { isSelfOrchestrationActive, selfOrchestrationFailClosedReason } from "../../orchestration/workflow-script-runner.js";
+import { createRunWorkflowTool, RUN_WORKFLOW_TOOL_NAME } from "../../orchestration/run-workflow-tool.js";
+import { createLspTool, gitCheckIgnoreFilter } from "../lsp.js";
+import { resolveKey } from "../../tools/fs/safety.js";
+import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, RESOURCE_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, remainingBudgetMicroUsd, } from "../checkpoint-store.js";
+import { boundInputHashOf } from "../canonical-json.js";
+const RECONCILE_MAX_RETRIES = 3;
+const DEFAULT_MAX_SUSPENDS = 5;
+const DEFAULT_MAX_SLICES = 100;
+const ULTRA_REASONING_TIERS = new Set(["xhigh", "max"]);
+const DEFAULT_RESOURCE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const DEFAULT_UNATTENDED_APPROVAL_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const ungatedWarnedShapes = new WeakMap();
+export const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
+function batchContextAt(messages, currentId) {
+    let batch = [];
+    for (const m of messages) {
+        if (m.role === "assistant") {
+            const ids = 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 };
+}
+function detectConflicts(storage, ref) {
+    const guard = (fn) => async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (err) {
+            if (isSessionConflict(err)) {
+                ref.hit = true;
+            }
+            throw err;
+        }
+    };
+    return new Proxy(storage, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function") {
+                return value;
+            }
+            const bound = value.bind(target);
+            return prop === "appendEntry" || prop === "setLeafId"
+                ? guard(bound)
+                : bound;
+        },
+    });
+}
+function raceAbort(p, signal, onAbort) {
+    if (signal.aborted)
+        return Promise.resolve(onAbort());
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbortEvent);
+            resolve(v);
+        };
+        const onAbortEvent = () => finish(onAbort());
+        signal.addEventListener("abort", onAbortEvent, { once: true });
+        p.then(finish, () => finish(onAbort()));
+    });
+}
+async function forgetQuietly(sessions, sessionId) {
+    try {
+        if (sessions.forget)
+            await sessions.forget(sessionId);
+    }
+    catch {
+    }
+}
+export async function prepareTask(spec, deps, sessions, resume, _memorySelector, internals, runnerSelf) {
+    if (spec.resumeAt !== undefined) {
+        if (resume) {
+            const e = new Error("resumeAt cannot be combined with a durable resume");
+            e.code = "resume_at.conflicts_resume";
+            throw e;
+        }
+        if (!spec.sessionId) {
+            const e = new Error("resumeAt requires a sessionId (the session to branch)");
+            e.code = "resume_at.no_session";
+            throw e;
+        }
+    }
+    const resolvedRole = resolveTaskModel(spec, deps);
+    const model = resolvedRole.model;
+    const thinking = spec.thinking ?? resolvedRole.thinking ?? model.defaultThinking;
+    const compModel = spec.compactionModel
+        ? resolveModel(spec.compactionModel, deps.models)
+        : roleModelIfSet("summarize", spec, deps);
+    const toolEffects = new Map();
+    const egressTools = new Set();
+    const irreversibleTools = new Set();
+    const irreversibilityTier = new Map();
+    const reversibilityProbes = new Map();
+    let shellGatedBash = false;
+    let shellGatedMonitor = false;
+    for (const t of spec.tools ?? []) {
+        if (t.name.includes("__")) {
+            const e = new Error(`Tool name "${t.name}" is invalid: "__" is reserved for the MCP namespace (mcp__<server>__<tool>) and must not appear in a caller tool name.`);
+            e.code = "config.tool_name_invalid";
+            throw e;
+        }
+        if (t.effect) {
+            toolEffects.set(t.name, t.effect);
+        }
+        const tier = t.irreversibility ?? (t.reversibilityProbe ? "maybe" : undefined);
+        if (tier !== undefined) {
+            irreversibilityTier.set(t.name, tier);
+            if (tier === "always" || tier === "maybe")
+                irreversibleTools.add(t.name);
+        }
+        if (t.reversibilityProbe)
+            reversibilityProbes.set(t.name, t.reversibilityProbe);
+        if (t.egress) {
+            if (t.effect !== undefined && t.effect !== "write") {
+                const e = new Error(`Tool "${t.name}" declares egress:true with effect:"${t.effect}" — an egress tool (external write) must have effect:"write" (or omit effect; write is the default).`);
+                e.code = "config.egress_requires_write_effect";
+                throw e;
+            }
+            egressTools.add(t.name);
+        }
+    }
+    toolEffects.set(OFFLOAD_TOOL_NAME, "read");
+    if (deps.executionEnvFactory || deps.executionEnv) {
+        for (const [name, effect] of Object.entries(HAND_TOOL_EFFECTS))
+            toolEffects.set(name, effect);
+        if (spec.handsReadOnly === true)
+            toolEffects.set("Bash", "read");
+    }
+    if (spec.enablePlanMode === true) {
+        toolEffects.set(PRESENT_PLAN_TOOL_NAME, "read");
+        toolEffects.set(ENTER_PLAN_MODE_TOOL_NAME, "read");
+    }
+    if (spec.requireExistingSession && !spec.sessionId) {
+        const e = new Error(`requireExistingSession requires a sessionId — cannot require an existing session without one (design/114 Phase3)`);
+        e.code = "resume.session_not_found";
+        throw e;
+    }
+    let acquired;
+    let session;
+    let conflictRef;
+    for (let attempt = 0;; attempt++) {
+        try {
+            acquired = await sessions.acquire(spec.sessionId, spec.requireExistingSession ? { requireExisting: true } : undefined);
+        }
+        catch (err) {
+            if (spec.requireExistingSession && err?.code === "not_found") {
+                const e = new Error(`requireExistingSession: session "${spec.sessionId}" does not exist — refusing a silent fresh run (design/114 Phase3)`);
+                e.code = "resume.session_not_found";
+                throw e;
+            }
+            throw err;
+        }
+        conflictRef = { hit: false };
+        session = new Session(detectConflicts(acquired.session.getStorage(), conflictRef));
+        if (!spec.sessionId) {
+            break;
+        }
+        try {
+            if (resume) {
+                await session.getStorage().setLeafId(resume.leafId);
+            }
+            else if (spec.resumeAt !== undefined) {
+                const entry = await session.getEntry(spec.resumeAt);
+                if (!entry) {
+                    const e = new Error(`resumeAt entry "${spec.resumeAt}" not found in session "${spec.sessionId}"`);
+                    e.code = "resume_at.not_found";
+                    throw e;
+                }
+                if (entry.type !== "message" && entry.type !== "custom_message") {
+                    const e = new Error(`resumeAt entry "${spec.resumeAt}" is a "${entry.type}" entry; resume-at requires a message boundary`);
+                    e.code = "resume_at.not_a_message";
+                    throw e;
+                }
+                if (entry.type === "message") {
+                    const msg = entry.message;
+                    if (msg?.role === "toolResult") {
+                        const e = new Error(`resumeAt entry "${spec.resumeAt}" is a tool-result (mid-turn); resume-at requires a settled turn boundary (a user message or a finished assistant turn)`);
+                        e.code = "resume_at.not_a_message";
+                        throw e;
+                    }
+                    if (msg?.role === "assistant" && Array.isArray(msg.content) && msg.content.some((p) => p?.type === "toolCall")) {
+                        const e = new Error(`resumeAt entry "${spec.resumeAt}" ends a turn mid-tool-call; resume-at requires a settled turn boundary`);
+                        e.code = "resume_at.not_a_message";
+                        throw e;
+                    }
+                }
+                await session.getStorage().setLeafId(spec.resumeAt);
+            }
+            await reconcileInterruptedSession(session, toolEffects, resume?.suspendedBatch);
+            break;
+        }
+        catch (err) {
+            if (isSessionConflict(err) && attempt < RECONCILE_MAX_RETRIES) {
+                if (sessions.forget) {
+                    await Promise.resolve(sessions.forget(spec.sessionId)).catch(() => undefined);
+                }
+                continue;
+            }
+            await Promise.resolve(sessions.forget ? sessions.forget(acquired.sessionId) : undefined).catch(() => undefined);
+            throw err;
+        }
+    }
+    const sessionId = acquired.sessionId;
+    const hostTaskId = spec.taskId ?? sessionId;
+    const taskScope = spec.principal ?? "default";
+    defaultTaskRegistry.maybeGc();
+    const forgetOnThrow = () => forgetQuietly(sessions, sessionId);
+    const extraBodyCollisions = reservedCollisions(model.extraBody, reservedFor(model.api));
+    if (extraBodyCollisions.length > 0) {
+        deps.onError?.(new Error(`model.extraBody contains reserved key(s) [${extraBodyCollisions.join(", ")}] that core owns and sets itself — they are ignored. Remove them from extraBody.`), { phase: "config", sessionId });
+    }
+    const nestedStats = { tokens: 0, turns: 0, tasks: 0, costUsd: 0, costMicroUsd: 0 };
+    if (resume) {
+        nestedStats.tokens = resume.seed.nestedStats.tokens;
+        nestedStats.turns = resume.seed.nestedStats.turns;
+        nestedStats.tasks = resume.seed.nestedStats.tasks;
+        nestedStats.costUsd = resume.seed.nestedStats.costUsd;
+        nestedStats.costMicroUsd = resume.seed.nestedStats.costMicroUsd;
+    }
+    const reportUsage = (u) => {
+        nestedStats.tokens += u.tokens;
+        nestedStats.turns += u.turns;
+        nestedStats.tasks += u.tasks;
+        nestedStats.costUsd += u.costUsd ?? 0;
+        nestedStats.costMicroUsd += u.costMicroUsd ?? 0;
+    };
+    const explicitGlobalThreshold = spec.toolResultThresholdChars ?? deps.toolResultThresholdChars;
+    const offloadThreshold = explicitGlobalThreshold ?? DEFAULT_TOOL_RESULT_THRESHOLD_CHARS;
+    const offloadEnabled = Number.isFinite(offloadThreshold) && offloadThreshold > 0;
+    const rawOffloadStore = offloadEnabled ? (deps.toolResultStore ?? new InMemoryToolResultStore()) : undefined;
+    const offloadStore = rawOffloadStore instanceof RunnerSharedToolResultStore
+        ? new ScopedToolResultStore(rawOffloadStore, taskScope)
+        : rawOffloadStore;
+    const maybeOffload = (tool, perTool) => {
+        if (!offloadStore || perTool?.offload === false)
+            return tool;
+        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId);
+    };
+    const firstPartyOffload = (tool) => {
+        const policy = firstPartyOffloadPolicy(tool.name);
+        if (policy.offload === false)
+            return maybeOffload(tool, policy);
+        return maybeOffload(tool, explicitGlobalThreshold === undefined ? policy : undefined);
+    };
+    const mcpOffload = (tool) => {
+        if (explicitGlobalThreshold !== undefined)
+            return maybeOffload(tool);
+        return maybeOffload(tool, { offloadThresholdChars: tool.mcpMaxResultSizeChars ?? 50_000 });
+    };
+    if (offloadStore && (spec.tools ?? []).some((t) => t.name === OFFLOAD_TOOL_NAME)) {
+        const e = new Error(`Tool name "${OFFLOAD_TOOL_NAME}" is reserved when large-result offload is enabled.`);
+        e.code = "config.reserved_tool_name";
+        await forgetOnThrow();
+        throw e;
+    }
+    let ownedEnv;
+    let mcp;
+    try {
+        ownedEnv = deps.executionEnvFactory
+            ? await deps.executionEnvFactory({
+                sessionId,
+                taskId: spec.taskId,
+                ...(internals?.isolation ? { isolation: internals.isolation } : {}),
+                ...(internals?.parentCwd ? { parentCwd: internals.parentCwd } : {}),
+            })
+            : undefined;
+    }
+    catch (factoryErr) {
+        await forgetOnThrow();
+        throw factoryErr;
+    }
+    const executionEnv = ownedEnv ?? deps.executionEnv ?? new StubExecutionEnv();
+    const handsEnabled = ownedEnv !== undefined || deps.executionEnv !== undefined;
+    const taskRootPath = internals?.isolation === "worktree" || !deps.rootPath ? executionEnv.cwd : deps.rootPath;
+    const abortController = new AbortController();
+    if (spec.signal?.aborted)
+        abortController.abort();
+    try {
+        if (resume?.workspaceHandle !== undefined) {
+            const failResume = (message, cause) => {
+                const e = new Error(message, cause ? { cause } : undefined);
+                e.code = "resume.env_failed";
+                throw e;
+            };
+            const handle = resume.workspaceHandle;
+            if (ownedEnv === undefined || !isRemoteExecutionEnv(ownedEnv)) {
+                failResume("resume needs a RemoteExecutionEnv from executionEnvFactory to restore the workspace snapshot");
+            }
+            else if (handle.snapshotId === undefined) {
+                if (handle.restoreMode !== "park_only" && isSuspendable(ownedEnv)) {
+                    failResume("checkpoint workspaceHandle has no snapshotId and is not a park_only handle, but the resumed env is suspendable — refusing to resume on a possibly-unrestored workspace (corrupt checkpoint?)");
+                }
+            }
+            else {
+                const restoreSignal = spec.signal
+                    ? AbortSignal.any([abortController.signal, spec.signal])
+                    : abortController.signal;
+                const restored = await ownedEnv.resumeVM(handle.snapshotId, { abortSignal: restoreSignal });
+                if (!restored.ok) {
+                    failResume(`resumeVM failed (${restored.error.code}): ${restored.error.message}`, restored.error);
+                }
+                const init = await ownedEnv.postResumeInit();
+                if (!init.ok) {
+                    failResume(`postResumeInit failed (${init.error.code}): ${init.error.message}`, init.error);
+                }
+            }
+        }
+        const rewindTarget = spec.resumeAt !== undefined ? (spec.rewindFiles ? spec.resumeAt : undefined) : spec.rewindFilesTo;
+        if (rewindTarget !== undefined && deps.fileSnapshotStore && handsEnabled) {
+            const restoreRoot = taskRootPath;
+            const restoreSignal = spec.signal ? AbortSignal.any([abortController.signal, spec.signal]) : abortController.signal;
+            const restored = await deps.fileSnapshotStore.restore(sessionId, rewindTarget, executionEnv, restoreRoot, restoreSignal);
+            if (!restored.ok) {
+                if (restored.error.code === "not_found") {
+                    try {
+                        deps.onError?.(new Error(`rewind-files: no snapshot for entry "${rewindTarget}" — files left unchanged`), { phase: "rewind", sessionId });
+                    }
+                    catch {
+                    }
+                }
+                else {
+                    const e = new Error(`rewind-files restore failed (${restored.error.code}): ${restored.error.message}`);
+                    e.code = "rewind.restore_failed";
+                    throw e;
+                }
+            }
+        }
+        const harnessRef = {};
+        const skillScope = new ActiveSkillScope();
+        const forwardSink = internals?.onForwardEvent;
+        const forwardEvent = forwardSink
+            ? (e) => {
+                if (e.type === "task_progress")
+                    forwardSink(e);
+                else if (spec.forwardSubagentEvents === true &&
+                    (e.type === "text_delta" || e.type === "reasoning_delta" || e.type === "tool_start" || e.type === "tool_end")) {
+                    forwardSink(e);
+                }
+            }
+            : undefined;
+        const reviewRequestRef = {};
+        const requestReview = (opts) => {
+            if (reviewRequestRef.pending === undefined) {
+                reviewRequestRef.pending = opts?.reason !== undefined ? { reason: opts.reason } : {};
+            }
+        };
+        const requestStopAfterTurn = () => {
+            harnessRef.current?.requestStopAfterTurn();
+        };
+        const planModeRef = { active: false };
+        const enterPlanMode = () => {
+            planModeRef.active = true;
+        };
+        const subagentRetain = spec.retainSubagentSessions ? new SubagentRetainLedger(spec.retainSubagentSessions) : undefined;
+        const worktreeIsolation = spec.handsReadOnly !== true ? createSubagentWorktreeHelper(executionEnv, taskRootPath) : undefined;
+        let agentForkDenial;
+        let observersActive = false;
+        let autoModeDecider;
+        const tools = (spec.tools ?? []).map((t) => maybeOffload(defineTool({
+            ...t,
+            execute: (args, ctx) => t.execute(args, {
+                ...ctx,
+                reportUsage,
+                model: harnessRef.current?.getModel(),
+                thinkingLevel: harnessRef.current?.getThinkingLevel(),
+                principal: spec.principal,
+                clientContext: spec.clientContext,
+                parentCwd: taskRootPath,
+                activeSkillScope: () => skillScope.active(),
+                taskId: hostTaskId,
+                sessionId,
+                ...(spec.backgroundScope !== undefined ? { backgroundScope: spec.backgroundScope } : {}),
+                ...(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 } : {}),
+            }),
+        }), t));
+        const blockedRef = {};
+        if (spec.enableBlockedReport !== false) {
+            tools.push(makeReportBlockedTool(blockedRef));
+        }
+        if (spec.enablePlanMode === true) {
+            tools.push(defineTool(createPresentPlanTool(requestReview)));
+            if ((spec.checkpointStore ?? deps.checkpointStore) !== undefined) {
+                tools.push(defineTool(createEnterPlanModeTool(enterPlanMode)));
+            }
+        }
+        let runtimeCaps;
+        if (deps.runtimeCapsResolver) {
+            try {
+                runtimeCaps = (await deps.runtimeCapsResolver(spec.principal)) ?? undefined;
+            }
+            catch (err) {
+                deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+                runtimeCaps = { allowWorkflows: false, allowFork: false };
+            }
+        }
+        agentForkDenial = forkGovernanceDenial(spec.enableFork, runtimeCaps?.allowFork);
+        observersActive = runtimeCaps?.allowObservers === true;
+        if (runtimeCaps?.autoMode === true && deps.autoMode !== undefined) {
+            const am = deps.autoMode;
+            let classifierModel;
+            try {
+                classifierModel = resolveTaskModel({ modelRole: "classifier" }, deps).model;
+            }
+            catch {
+                classifierModel = model;
+            }
+            const classifierSystemPrompt = buildAutoModePrompt(am);
+            const classifierRuntime = brainToRuntime(deps.brain);
+            autoModeDecider = createAutoModeDecider({
+                ...(am.timeoutMs !== undefined ? { timeoutMs: am.timeoutMs } : {}),
+                ...(am.failureThreshold !== undefined ? { failureThreshold: am.failureThreshold } : {}),
+                ...(am.onBreakerOpen !== undefined ? { onBreakerOpen: am.onBreakerOpen } : {}),
+                classify: async (input, signal) => {
+                    const ctx = await session.buildContext();
+                    const known = ctx.messages.filter((m) => m.role === "user" || m.role === "assistant" || m.role === "toolResult");
+                    const userPrompt = renderAutoModeWindow(known, am.window) + renderAutoModeAction(input);
+                    const response = await classifierRuntime.completeSimple(classifierModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, { signal });
+                    return response.content
+                        .filter((c) => c.type === "text")
+                        .map((c) => c.text)
+                        .join("");
+                },
+            });
+        }
+        const deploymentWorkflowReady = runnerSelf !== undefined && isSelfOrchestrationActive(spec, deps);
+        const selfOrchestrationActive = deploymentWorkflowReady && runtimeCaps?.allowWorkflows !== false;
+        if (deploymentWorkflowReady && runtimeCaps?.allowWorkflows === false) {
+            deps.onError?.(new Error(`self-orchestration DENIED for principal "${spec.principal ?? ""}" by runtimeCaps.allowWorkflows=false ` +
+                `(per-principal entitlement governance, not a misconfiguration — the run_workflow tool is not mounted)`), { phase: "config", sessionId });
+        }
+        let workflowToolsActive = false;
+        if (selfOrchestrationActive && runnerSelf && deps.workflowScriptRunner && deps.workflowGovernanceBaseline) {
+            workflowToolsActive = true;
+            toolEffects.set(RUN_WORKFLOW_TOOL_NAME, "write");
+            tools.push(await createRunWorkflowTool({
+                runner: runnerSelf,
+                scriptRunner: deps.workflowScriptRunner,
+                governanceBaseline: deps.workflowGovernanceBaseline,
+                models: deps.models,
+                agents: deps.agents,
+                builtinAgents: deps.builtinAgents,
+                store: deps.workflowRunStore,
+                journalStore: deps.workflowJournalStore,
+                scriptStore: deps.workflowScriptStore,
+                builtinWorkflows: deps.builtinWorkflows,
+                onAgentSpawn: deps.onWorkflowAgentSpawn,
+                scope: taskScope,
+                notifier: deps.workflowCompletionNotifier,
+                originatingSessionId: sessionId,
+                taskRegistry: defaultTaskRegistry,
+                taskNotification: internals?.onTaskNotification,
+                taskOwner: hostTaskId,
+                limits: deps.workflowLimits,
+                sourceTaskId: hostTaskId,
+                principal: spec.principal,
+                workflowDepth: internals?.workflowDepth,
+                parentCwd: taskRootPath,
+                parentThinking: () => harnessRef.current?.getThinkingLevel() ?? thinking,
+            }));
+        }
+        const suspendRef = {};
+        const reviewRef = {};
+        const suspendLoopRef = { hit: false };
+        const compactionReuseRef = { consecutive: 0 };
+        const trimPressureRef = { droppedMessages: false };
+        const liveSpendRef = {};
+        const now = deps.now ?? Date.now;
+        const humanReviewRef = {
+            count: resume?.priorHumanReview?.count ?? 0,
+            totalWaitMs: resume?.priorHumanReview?.totalWaitMs ?? 0,
+            gates: resume?.priorHumanReview?.gates ? [...resume.priorHumanReview.gates] : [],
+        };
+        const priorSuspendCount = resume?.priorSuspendCount ?? 0;
+        const maxSuspends = spec.maxSuspends ?? deps.maxSuspends ?? DEFAULT_MAX_SUSPENDS;
+        const maxSlices = spec.resourceSuspend?.maxSlices ?? DEFAULT_MAX_SLICES;
+        const priorLedger = resume?.priorLedger;
+        const resourceTotal = spec.resourceSuspend
+            ? {
+                totalBudgetMicroUsd: spec.resourceSuspend.totalBudgetUsd !== undefined ? Math.round(spec.resourceSuspend.totalBudgetUsd * 1e6) : undefined,
+            }
+            : undefined;
+        const budgetSnapshot = {
+            resourceRemainingMicroUsd: priorLedger
+                ? remainingBudgetMicroUsd(priorLedger)
+                : resourceTotal?.totalBudgetMicroUsd,
+            resourceSpentMicroUsd: priorLedger?.spentMicroUsd ?? 0,
+            suspendCount: priorSuspendCount,
+        };
+        let readFileStateForCheckpoint;
+        let seedContextFiles;
+        let handsCwdRef;
+        let worktreeSessionRef;
+        let backgroundTaskToolsActive = false;
+        let suspendForResource;
+        let suspendForReview;
+        const outputRef = {};
+        if (resume?.seed.outputRef) {
+            outputRef.value = resume.seed.outputRef.value;
+            outputRef.set = resume.seed.outputRef.set;
+        }
+        if (spec.outputSchema) {
+            if ((spec.tools ?? []).some((t) => t.name === OUTPUT_TOOL_NAME)) {
+                const e = new Error(`Tool name "${OUTPUT_TOOL_NAME}" is reserved when TaskSpec.outputSchema is set.`);
+                e.code = "config.reserved_tool_name";
+                throw e;
+            }
+            const compiled = compileOutputSchema(spec.outputSchema);
+            if ("error" in compiled) {
+                const e = new Error(`TaskSpec.outputSchema is not a valid JSON Schema: ${compiled.error}`);
+                e.code = "config.invalid_output_schema";
+                throw e;
+            }
+            if (!compiled.strict) {
+                try {
+                    deps.onError?.(new Error(`structured-output: strict schema derivation fell back to non-strict (${compiled.fallbackReason}) — the schema is served to the model as-is`), { phase: "config", sessionId });
+                }
+                catch {
+                }
+            }
+            tools.push(makeOutputTool(outputRef, spec.outputSchema, compiled.strict ? compiled.modelSchema : undefined));
+        }
+        mcp = spec.mcp?.length
+            ? await materializeMcpTools(spec.mcp, spec.principal, deps.onElicit, deps.mcpImageResizer)
+            : { tools: [], toolAxes: [], warnings: [], serverInstructions: [], instructionsDelta: { pendingAdds: [], pendingRemovals: [] }, statuses: [], dispose: async () => { } };
+        for (const w of mcp.warnings)
+            deps.onError?.(w, { phase: "mcp", sessionId });
+        {
+            const callerNames = new Set((spec.tools ?? []).flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+            const clash = mcp.tools.find((t) => [t.name, ...(t.aliases ?? [])].some((name) => callerNames.has(name)));
+            if (clash) {
+                await mcp.dispose();
+                const e = new Error(`Tool name "${clash.name}" is reserved by an injected MCP tool — a caller tool of the same name would silently shadow it.`);
+                e.code = "config.reserved_tool_name";
+                throw e;
+            }
+        }
+        tools.push(...mcp.tools.map((t) => mcpOffload(t)));
+        for (const axis of mcp.toolAxes) {
+            if (axis.irreversibility === "always") {
+                irreversibilityTier.set(axis.name, "always");
+                irreversibleTools.add(axis.name);
+            }
+            if (axis.egress) {
+                if (axis.effect !== undefined && axis.effect !== "write") {
+                    const e = new Error(`MCP tool "${axis.name}" resolves to egress:true with effect:"${axis.effect}" — an egress tool (external write) must have effect:"write". Clear egress (toolAxes egress:false) if it is a pure read, or set effect:"write".`);
+                    e.code = "config.egress_requires_write_effect";
+                    throw e;
+                }
+                egressTools.add(axis.name);
+            }
+            if (!toolEffects.has(axis.name))
+                toolEffects.set(axis.name, axis.effect ?? "write");
+        }
+        const callCapOn = spec.limits?.callCapByDeadline !== false;
+        const callCapRef = spec.limits?.timeoutSec &&
+            spec.limits.timeoutSec > 0 &&
+            (callCapOn || spec.limits.gracefulFinalize !== false)
+            ? createCallCapRef()
+            : undefined;
+        if (callCapRef) {
+            callCapRef.staticCapTokens =
+                spec.limits?.maxOutputTokens !== undefined && spec.limits.maxOutputTokens > 0
+                    ? spec.limits.maxOutputTokens
+                    : model.maxTokens;
+        }
+        const execClamp = callCapRef
+            ? {
+                deadlineMs: () => softExecDeadlineMs(callCapRef),
+                onClamp: () => {
+                    callCapRef.toolClamps = (callCapRef.toolClamps ?? 0) + 1;
+                },
+            }
+            : undefined;
+        const memoryWriteGateRef = {};
+        const additionalRootsCanonical = [];
+        if (handsEnabled) {
+            const rootRaw = taskRootPath;
+            const canon = await executionEnv.canonicalPath(rootRaw);
+            const rootCanonical = canon.ok ? canon.value : rootRaw;
+            for (const dir of spec.additionalDirectories ?? []) {
+                if (!dir || !dir.trim())
+                    continue;
+                const c = await executionEnv.canonicalPath(dir);
+                if (c.ok) {
+                    additionalRootsCanonical.push(c.value);
+                }
+                else {
+                    deps.onError?.(new Error(`additionalDirectories entry skipped (cannot canonicalize): ${dir}`), {
+                        phase: "config",
+                        sessionId,
+                    });
+                }
+            }
+            const readFileState = new Map(resume?.seed.readFileState ?? []);
+            readFileStateForCheckpoint = readFileState;
+            seedContextFiles = async (files) => {
+                for (const f of files) {
+                    const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, additionalRootsCanonical);
+                    if (rk.ok)
+                        seedReadFileStateFromContext(readFileState, rk.key, f.content);
+                }
+            };
+            const handsIncludeShell = !(executionEnv instanceof StubExecutionEnv);
+            const handsReadOnly = spec.handsReadOnly === true;
+            backgroundTaskToolsActive = handsIncludeShell && !handsReadOnly && hasBackgroundShell(executionEnv);
+            if (handsIncludeShell && !handsReadOnly) {
+                handsCwdRef = { current: rootCanonical };
+                if (resume?.seed.handsCwd !== undefined)
+                    handsCwdRef.current = resume.seed.handsCwd;
+            }
+            const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
+                ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
+                includeShell: handsIncludeShell,
+                readOnly: handsReadOnly,
+                ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
+                taskRegistry: defaultTaskRegistry,
+                taskOwner: hostTaskId,
+                taskScope,
+                ...(sessionId !== undefined ? { sessionId } : {}),
+                ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
+                ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
+                ...(execClamp !== undefined ? { execClamp } : {}),
+                pdfModelCapabilities: pdfModelCapabilitiesOf(model),
+                ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
+                ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
+                ...(deps.hands?.readImageDownsampler !== undefined ? { readImageDownsampler: deps.hands.readImageDownsampler } : {}),
+                beforeWrite: async (w) => {
+                    const deploymentGate = deps.hands?.beforeWrite;
+                    if (deploymentGate) {
+                        const verdict = await deploymentGate(w);
+                        if (verdict !== undefined && verdict.ok === false)
+                            return verdict;
+                    }
+                    return memoryWriteGateRef.current?.(w);
+                },
+                mountBackgroundTaskTools: false,
+            });
+            {
+                const bandNames = new Set(band.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+                const shadowed = (spec.tools ?? []).filter((t) => [t.name, ...(t.aliases ?? [])].some((n) => bandNames.has(n)));
+                if (shadowed.length > 0) {
+                    const names = shadowed.map((t) => `"${t.name}"`).join(", ");
+                    deps.onError?.(new Error(`spec.tools ${shadowed.length > 1 ? "entries" : "entry"} ${names} collide${shadowed.length > 1 ? "" : "s"} with the built-in hands tool band — the built-in wins (registered later; the harness tool Map is last-write-wins) and the caller tool never dispatches this task. Rename the caller tool, or don't inject executionEnv if you intend to replace the band.`), { phase: "config", sessionId });
+                }
+            }
+            tools.push(...band.map((t) => firstPartyOffload(t)));
+            const shellGate = spec.shellGate ?? "off";
+            if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
+                shellGatedBash = !egressTools.has("Bash") && !irreversibilityTier.has("Bash");
+                irreversibilityTier.set("Bash", shellGate === "always" ? "always" : "maybe");
+                irreversibleTools.add("Bash");
+                if (shellGate === "classify")
+                    reversibilityProbes.set("Bash", bashReversibilityProbe());
+                if (backgroundTaskToolsActive) {
+                    shellGatedMonitor = !egressTools.has("Monitor") && !irreversibilityTier.has("Monitor");
+                    irreversibilityTier.set("Monitor", shellGate === "always" ? "always" : "maybe");
+                    irreversibleTools.add("Monitor");
+                    if (shellGate === "classify")
+                        reversibilityProbes.set("Monitor", bashReversibilityProbe());
+                }
+            }
+        }
+        if (backgroundTaskToolsActive || workflowToolsActive) {
+            toolEffects.set("TaskOutput", "read");
+            toolEffects.set("TaskStop", "write");
+            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore })));
+            if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
+                tools.push(firstPartyOffload(createSendMessageTool({
+                    runner: runnerSelf,
+                    registry: defaultTaskRegistry,
+                    ...(subagentRetain ? { retain: subagentRetain } : {}),
+                    owner: hostTaskId,
+                    scope: taskScope,
+                    ...(sessionId !== undefined ? { sessionId } : {}),
+                    ...(internals?.onTaskNotification !== undefined ? { notify: internals.onTaskNotification } : {}),
+                    ...(internals?.onSubagentSpawn !== undefined ? { sink: internals.onSubagentSpawn } : {}),
+                })));
+                if (!(spec.tools ?? []).some((t) => t.name === AGENT_TRANSCRIPT_TOOL_NAME)) {
+                    tools.push(firstPartyOffload(createAgentTranscriptTool({
+                        runner: runnerSelf,
+                        registry: defaultTaskRegistry,
+                        owner: hostTaskId,
+                        scope: taskScope,
+                        ...(sessionId !== undefined ? { sessionId } : {}),
+                    })));
+                }
+            }
+        }
+        if (backgroundTaskToolsActive) {
+            toolEffects.set("Monitor", "write");
+            tools.push(firstPartyOffload(createMonitorTool(executionEnv, {
+                registry: defaultTaskRegistry,
+                owner: hostTaskId,
+                scope: taskScope,
+                ...(sessionId !== undefined ? { sessionId } : {}),
+                ...(internals?.onTaskNotification !== undefined ? { onTaskNotification: internals.onTaskNotification } : {}),
+                ...(handsCwdRef !== undefined ? { cwdRef: handsCwdRef } : {}),
+            })));
+        }
+        if (handsCwdRef !== undefined) {
+            toolEffects.set("EnterWorktree", "write");
+            toolEffects.set("ExitWorktree", "write");
+            worktreeSessionRef = { ...(resume?.seed.activeWorktree ? { current: { ...resume.seed.activeWorktree } } : {}) };
+            tools.push(...createWorktreeTools(executionEnv, { repoRoot: taskRootPath, cwdRef: handsCwdRef, session: worktreeSessionRef }).map((t) => firstPartyOffload(t)));
+        }
+        if (offloadStore)
+            tools.push(makeReadToolResultTool(offloadStore));
+        const onQuestion = spec.onQuestion ?? deps.onQuestion;
+        if (onQuestion)
+            tools.push(createAskUserQuestionTool(onQuestion, { principal: spec.principal, sourceTaskId: sessionId }));
+        if (spec.handsReadOnly !== true) {
+            const schedScope = sessionId ?? spec.principal ?? spec.taskId ?? "default";
+            tools.push(...createSchedulerTools(executionEnv, {
+                scope: schedScope,
+                ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
+                ...(sessionId !== undefined ? { sessionId } : {}),
+                requestStopAfterTurn,
+            }));
+        }
+        if (internals?.insideFork !== true &&
+            runnerSelf &&
+            sessionId !== undefined &&
+            hasSessionFork(runnerSelf.sessions) &&
+            agentForkDenial === "principal") {
+            deps.onError?.(new Error(`Fork DENIED for principal "${spec.principal ?? ""}" by runtimeCaps.allowFork=false ` +
+                `(per-principal entitlement governance, not a misconfiguration — Agent(subagent_type:"fork") will refuse honestly)`), { phase: "config", sessionId });
+        }
+        const lspManager = spec.lspManager ?? deps.lspManager;
+        if (lspManager) {
+            const lspRoot = taskRootPath;
+            tools.push(createLspTool(lspManager, { isPathIgnored: gitCheckIgnoreFilter(executionEnv, lspRoot), env: executionEnv }));
+        }
+        const lspDiagnostics = spec.lspDiagnostics !== false && lspManager?.diagnostics !== undefined && handsEnabled && spec.handsReadOnly !== true
+            ? lspManager.diagnostics
+            : undefined;
+        const nudgeLspOnEdit = lspDiagnostics
+            ? (rawPath) => {
+                const baseDir = handsCwdRef?.current ?? taskRootPath;
+                const isAbsForm = rawPath.startsWith("/") || /^[A-Za-z]:[\\/]/.test(rawPath);
+                const joinSep = baseDir.includes("\\") ? "\\" : "/";
+                const normalizeSegments = (pth) => {
+                    const isUnc = pth.startsWith("\\\\");
+                    const drive = /^[A-Za-z]:/.exec(pth)?.[0] ?? "";
+                    const rest = pth.slice(drive.length + (isUnc ? 2 : 0));
+                    const sep = pth.includes("\\") ? "\\" : "/";
+                    const abs = rest.startsWith("/") || rest.startsWith("\\");
+                    const outSegs = [];
+                    for (const seg of rest.split(/[\\/]+/)) {
+                        if (!seg || seg === ".")
+                            continue;
+                        if (seg === "..") {
+                            if (outSegs.length > 0 && outSegs[outSegs.length - 1] !== "..")
+                                outSegs.pop();
+                            else if (!abs)
+                                outSegs.push("..");
+                            continue;
+                        }
+                        outSegs.push(seg);
+                    }
+                    return (isUnc ? sep + sep : "") + drive + (abs ? sep : "") + outSegs.join(sep);
+                };
+                const filePath = normalizeSegments(isAbsForm ? rawPath : baseDir.replace(/[\\/]+$/, "") + joinSep + rawPath);
+                lspDiagnostics.fileEdited(pathToUri(filePath));
+                void lspManager
+                    .sessionFor(filePath, undefined, executionEnv)
+                    .then((session) => session?.notifyFileChanged?.(filePath))
+                    .catch(() => undefined);
+            }
+            : undefined;
+        const memorySpec = normalizeMemorySpec(spec.memory);
+        const useMemoryEngine = Boolean(memorySpec && memorySpec.enabled && deps.memoryBackend);
+        let memoryEngineSession;
+        if (useMemoryEngine && memorySpec) {
+            try {
+                const backend = deps.memoryBackend;
+                const pinned = backend.directoryRoot;
+                const engineRoot = resolveMemoryEngineRoot(deps.memoryEngineDir);
+                const repoRoot = deps.rootPath ?? taskRootPath;
+                let identityKey;
+                if (memorySpec.scopeContract === "v2" && repoRoot) {
+                    const consumesProjectIdentity = [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])]
+                        .map(parseScopeKey)
+                        .some((k) => k.kind === "proj" || k.kind === "userproj");
+                    let marker = null;
+                    try {
+                        marker = resolveProjectId(repoRoot);
+                    }
+                    catch (err) {
+                        if (consumesProjectIdentity)
+                            throw err;
+                        deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+                    }
+                    if (marker) {
+                        identityKey = marker.projectId;
+                        const firstSwitch = lookupProjectIdHint(engineRoot, repoRoot) !== marker.projectId;
+                        recordProjectIdHint(engineRoot, repoRoot, marker.projectId);
+                        if (firstSwitch) {
+                            try {
+                                const oldCtl = deriveControlPlaneDir(engineRoot, repoRoot);
+                                const newCtl = deriveProjectControlDir(engineRoot, marker.projectId);
+                                const drained = drainMemoryAnnouncements(oldCtl);
+                                for (const ann of drained.queue)
+                                    enqueueMemoryAnnouncement(newCtl, ann);
+                            }
+                            catch {
+                            }
+                        }
+                        if (memorySpec.writeScope !== null) {
+                            const w = parseScopeKey(memorySpec.writeScope);
+                            if ((w.kind === "proj" || w.kind === "userproj") && w.projectId !== marker.projectId) {
+                                const e = new Error(`memory scope contract v2: writeScope ${memorySpec.writeScope} targets projectId ${w.projectId}, ` +
+                                    `but this checkout's marker (.sema/project) declares ${marker.projectId} — refusing a mis-addressed write.`);
+                                e.code = "config.memory_project_identity";
+                                throw e;
+                            }
+                        }
+                    }
+                    else {
+                        const hint = lookupProjectIdHint(engineRoot, repoRoot);
+                        if (hint !== undefined) {
+                            deps.onError?.(new Error(`memory project marker missing but recoverable: ${repoRoot} previously carried projectId ${hint} ` +
+                                `(.sema/project deleted?). Restore the marker to keep the identity-keyed memory mount; this session ` +
+                                `falls back to the path-derived key.`), { phase: "config", sessionId });
+                        }
+                    }
+                }
+                const memoryDir = typeof pinned === "string" && pinned
+                    ? pinned
+                    : identityKey !== undefined
+                        ? deriveProjectMemoryDir(engineRoot, identityKey)
+                        : deriveRepoMemoryDir(engineRoot, repoRoot);
+                const planes = memorySpec.scopeContract === "v2" ? classifyScopePlanes(memorySpec.scopes, memorySpec.writeScope) : undefined;
+                const dual = planes !== undefined && needsDualRoots(planes);
+                const personalOnly = planes !== undefined && !dual && planes.project.length === 0 && planes.writePlane !== "project" && (planes.personal.length > 0 || planes.writePlane === "personal");
+                if (memorySpec.scopeContract === "v2" && !personalOnly) {
+                    assertScopeContractPlacement({
+                        parsedScopes: dual
+                            ? parsedProjectPlane(planes, memorySpec.writeScope)
+                            : [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])].map(parseScopeKey),
+                        memoryDir,
+                        repoRoot,
+                    });
+                }
+                const personalMemoryDir = derivePersonalMemoryDir(engineRoot);
+                const personalControlDir = derivePersonalControlDir(engineRoot);
+                const makePersonalEngine = () => new MemoryEngine({
+                    backend: typeof pinned === "string" && pinned
+                        ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir })
+                        : backend,
+                    memoryDir: personalMemoryDir,
+                    controlDir: personalControlDir,
+                });
+                let writeEngine;
+                let writeHandle;
+                let injectFn;
+                let harvestBoth;
+                if (dual) {
+                    const projectEngine = new MemoryEngine({
+                        backend,
+                        memoryDir,
+                        controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveControlPlaneDir(engineRoot, repoRoot),
+                    });
+                    const personalEngine = makePersonalEngine();
+                    const p = planes;
+                    const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null);
+                    const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null);
+                    const writeIsPersonal = p.writePlane === "personal";
+                    writeEngine = writeIsPersonal ? personalEngine : projectEngine;
+                    writeHandle = writeIsPersonal ? personalHandle : projectHandle;
+                    injectFn = () => mergeInjections(projectEngine.inject(projectHandle), personalEngine.inject(personalHandle));
+                    harvestBoth = async () => {
+                        const writeFirst = writeIsPersonal ? [personalEngine, personalHandle] : [projectEngine, projectHandle];
+                        const readOther = writeIsPersonal ? [projectEngine, projectHandle] : [personalEngine, personalHandle];
+                        const writeReport = await writeFirst[0].harvest(writeFirst[1]);
+                        let readReport;
+                        let readFailure;
+                        try {
+                            readReport = await readOther[0].harvest(readOther[1]);
+                        }
+                        catch (err) {
+                            readFailure = err instanceof Error ? err.message : String(err);
+                        }
+                        const merged = readReport !== undefined ? mergeHarvestReports(writeReport, readReport) : writeReport;
+                        if (readFailure !== undefined)
+                            merged.warnings.push(`read-plane harvest failed (write-plane yield committed): ${readFailure}`);
+                        return merged;
+                    };
+                }
+                else if (personalOnly) {
+                    const personalEngine = makePersonalEngine();
+                    const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope);
+                    writeEngine = personalEngine;
+                    writeHandle = handle;
+                    injectFn = () => personalEngine.inject(handle);
+                    harvestBoth = () => personalEngine.harvest(handle);
+                }
+                else {
+                    const engine = new MemoryEngine({
+                        backend,
+                        memoryDir,
+                        controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveControlPlaneDir(engineRoot, repoRoot),
+                    });
+                    const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope);
+                    writeEngine = engine;
+                    writeHandle = handle;
+                    injectFn = () => engine.inject(handle);
+                    harvestBoth = () => engine.harvest(handle);
+                }
+                memoryWriteGateRef.current = (w) => writeEngine.gateWrite(writeHandle, w.key, w.content);
+                const harvestSafe = async (phase = "terminal") => {
+                    try {
+                        const report = await harvestBoth();
+                        if (!report.ok && report.incident) {
+                            deps.onError?.(new Error(`memory harvest refused (${report.incident.kind}): ${report.incident.detail}`), { phase: "memory", sessionId });
+                        }
+                        try {
+                            deps.onMemoryHarvestReport?.(report, { sessionId, phase });
+                        }
+                        catch {
+                        }
+                        return report;
+                    }
+                    catch (err) {
+                        try {
+                            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
+                        }
+                        catch {
+                        }
+                        return undefined;
+                    }
+                };
+                memoryEngineSession = { engine: writeEngine, handle: writeHandle, inject: injectFn, harvest: harvestSafe };
+            }
+            catch (err) {
+                if (typeof err.code === "string" && (err.code.startsWith("config.memory_scope") || err.code.startsWith("config.memory_project"))) {
+                    throw err;
+                }
+                deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
+            }
+        }
+        let memoryBlock;
+        if (memorySpec && memorySpec.enabled && !useMemoryEngine) {
+            const detail = deps.memoryStore
+                ? "RunnerDeps.memoryStore is retired (design/138 S4): the legacy remember/recall tools and <user_memory> injection no longer run. Configure RunnerDeps.memoryBackend (memory engine) instead; this task runs memory-less."
+                : "TaskSpec.memory is enabled but RunnerDeps.memoryBackend is not configured; memory is inactive for this task (the legacy memoryStore fallback was retired in design/138 S4).";
+            deps.onError?.(new Error(detail), { phase: "config", sessionId });
+        }
+        if (memoryEngineSession) {
+            const injection = memoryEngineSession.inject();
+            if (injection.block.trim())
+                memoryBlock = injection.block;
+        }
+        if (deps.loadProjectMemory) {
+            let loaded = null;
+            try {
+                loaded = await Promise.resolve(deps.loadProjectMemory({
+                    cwd: taskRootPath,
+                    handsEnabled,
+                    isSubagent: internals?.parentTaskId !== undefined,
+                    ...(internals?.agentName ? { agentName: internals.agentName } : {}),
+                }));
+            }
+            catch (err) {
+                deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+            }
+            const projectMem = loaded !== null && typeof loaded === "object" ? loaded.content : loaded;
+            const seededFiles = loaded !== null && typeof loaded === "object" ? loaded.seededFiles : undefined;
+            if (seededFiles?.length && seedContextFiles) {
+                try {
+                    await seedContextFiles(seededFiles);
+                }
+                catch (err) {
+                    deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+                }
+            }
+            if (projectMem != null && projectMem.trim()) {
+                const projectBlock = `${PROJECT_CONTEXT_FRAMING}\n\n${composeMemoryBlock(projectMem, "project")}`;
+                memoryBlock = memoryBlock ? `${memoryBlock}\n\n${projectBlock}` : projectBlock;
+            }
+        }
+        const skillSpecs = normalizeSkills(spec.skills);
+        const inheritedFrames = internals?.inheritedManifestScope ?? [];
+        for (const frame of inheritedFrames) {
+            skillScope.push(frame);
+        }
+        const hasSkillManifest = skillSpecs.some((s) => s.manifest !== undefined) || inheritedFrames.length > 0;
+        if (skillSpecs.length > 0) {
+            if (tools.some((t) => t.name === SKILL_TOOL_NAME)) {
+                const e = new Error(`Tool name "${SKILL_TOOL_NAME}" is reserved when spec.skills is present.`);
+                e.code = "config.reserved_tool_name";
+                throw e;
+            }
+            tools.push(makeSkillTool(skillSpecs, skillScope));
+        }
+        const skillsBlock = buildSkillsBlock(skillSpecs);
+        const provider = spec.promptProvider ?? deps.promptProvider ?? defaultPromptProvider;
+        const promptPolicyEnabled = Boolean(spec.toolPolicy ?? deps.toolPolicy);
+        const promptHooks = spec.hooks ?? deps.hooks;
+        const promptHooksEnabled = Boolean(promptHooks?.preToolUse || promptHooks?.postToolUse);
+        const failClosedReason = selfOrchestrationFailClosedReason(spec, deps);
+        if (failClosedReason) {
+            deps.onError?.(new Error(failClosedReason), { phase: "config", sessionId });
+        }
+        const featureFlags = {
+            policyEnabled: promptPolicyEnabled,
+            hooksEnabled: promptHooksEnabled,
+            isolationEnabled: isIsolated(executionEnv),
+            orchestrationEnabled: selfOrchestrationActive,
+            goalEnabled: internals?.goalMode === true,
+            awarenessEnabled: thinking !== undefined && ULTRA_REASONING_TIERS.has(thinking),
+            worktreeIsolated: internals?.isolation === "worktree" && ownedEnv !== undefined,
+            withinTaskCompactionEnabled: (spec.compaction?.enabled ?? true) && (spec.compaction?.withinTask ?? true),
+        };
+        const userSystemPrompt = spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals?.defaultSystemPrompt;
+        const userAppendSystemPrompt = spec.appendSystemPrompt;
+        const mcpInstructionsBlock = mcp.serverInstructions.length
+            ? `# MCP Server Instructions\n${mcp.serverInstructions.map((s) => `## ${s.server}\n${s.text}`).join("\n\n")}`
+            : undefined;
+        const userTz = spec.clientContext?.timeZone;
+        const tzValid = userTz !== undefined && isValidTimeZone(userTz);
+        const envFacts = { date: formatLocalDate(new Date(), tzValid ? userTz : undefined), modelId: model.id };
+        if (tzValid)
+            envFacts.timeZone = userTz;
+        if (spec.clientContext?.userEmail)
+            envFacts.userEmail = spec.clientContext.userEmail;
+        const declaredCutoff = deps.modelKnowledgeCutoffs?.[model.id];
+        if (declaredCutoff)
+            envFacts.knowledgeCutoff = declaredCutoff;
+        if (spec.envFacts?.profile)
+            envFacts.sandboxProfile = spec.envFacts.profile;
+        if (spec.envFacts?.capabilities && spec.envFacts.capabilities.length > 0)
+            envFacts.sandboxCapabilities = [...spec.envFacts.capabilities];
+        if (spec.envFacts?.pkgSource)
+            envFacts.sandboxPkgSource = spec.envFacts.pkgSource;
+        if (spec.envFacts?.egress === "none" || spec.envFacts?.egress === "allowlist" || spec.envFacts?.egress === "full")
+            envFacts.sandboxEgress = spec.envFacts.egress;
+        if (spec.envFacts?.scratchpadDir)
+            envFacts.scratchpadDir = spec.envFacts.scratchpadDir;
+        if (handsEnabled) {
+            envFacts.cwd = taskRootPath;
+            if (additionalRootsCanonical.length > 0) {
+                envFacts.additionalDirectories = [...additionalRootsCanonical];
+            }
+            try {
+                const probe = await executionEnv.exec('uname -s; uname -r; (git rev-parse --is-inside-work-tree 2>/dev/null || echo false); (git symbolic-ref --short -q HEAD 2>/dev/null || echo "HEAD (detached)"); (git rev-parse --show-toplevel 2>/dev/null || echo); (test -n "$(git status --porcelain 2>/dev/null | head -1)" && echo dirty || echo clean); (s=$(ps -p $$ -o comm= 2>/dev/null); s=${s##*/}; echo "${s#-}"); (test "$(git rev-parse --git-dir 2>/dev/null)" != "$(git rev-parse --git-common-dir 2>/dev/null)" && echo linked || echo main)', { cwd: envFacts.cwd, timeout: 10 });
+                if (probe.ok && probe.value.exitCode === 0) {
+                    const lines = probe.value.stdout.split("\n");
+                    if (lines.length >= 6) {
+                        const [osName, osVer, git, branch, worktreeRoot, dirty] = lines;
+                        if (osName?.trim())
+                            envFacts.platform = osName.trim();
+                        if (osVer?.trim())
+                            envFacts.osVersion = osVer.trim();
+                        envFacts.isGitRepo = (git ?? "").trim() === "true";
+                        if (envFacts.isGitRepo) {
+                            const b = (branch ?? "").trim();
+                            if (b)
+                                envFacts.gitBranch = b;
+                            const root = (worktreeRoot ?? "").trim();
+                            if (root)
+                                envFacts.gitWorktreeRoot = root;
+                            const d = (dirty ?? "").trim();
+                            if (d === "dirty" || d === "clean")
+                                envFacts.gitDirty = d === "dirty";
+                        }
+                        const sh = (lines[6] ?? "").trim();
+                        if (sh)
+                            envFacts.shell = sh;
+                        if (envFacts.isGitRepo && (lines[7] ?? "").trim() === "linked")
+                            envFacts.isLinkedWorktree = true;
+                    }
+                }
+            }
+            catch {
+            }
+            if (envFacts.isGitRepo === true) {
+                const SEP = "@@SEMA_ENV_GIT_SPLIT@@";
+                try {
+                    const snap = await executionEnv.exec(`(m=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null); m=\${m#origin/}; for s in "$m" main master; do if [ -n "$s" ] && git show-ref --verify --quiet "refs/remotes/origin/$s"; then echo "$s"; break; fi; done) || true; echo "${SEP}"; (git config user.name 2>/dev/null || true); echo "${SEP}"; gs=$(git --no-optional-locks status --short) || exit 41; printf '%s\\n' "$gs"; echo "${SEP}"; gl=$(git --no-optional-locks log --oneline -n 5) || exit 42; printf '%s\\n' "$gl"`, { cwd: envFacts.cwd, timeout: 10 });
+                    if (snap.ok && snap.value.exitCode === 0) {
+                        const parts = snap.value.stdout.split(`${SEP}\n`);
+                        if (parts.length === 4) {
+                            envFacts.gitSnapshot = buildGitSnapshot({
+                                branch: envFacts.gitBranch ?? "HEAD",
+                                mainBranch: parts[0].trim() || "main",
+                                ...(parts[1].trim() ? { userName: parts[1].trim() } : {}),
+                                status: parts[2],
+                                log: parts[3],
+                            });
+                        }
+                    }
+                    else {
+                        const reason = snap.ok
+                            ? snap.value.exitCode === 41
+                                ? "git status failed (exit 41)"
+                                : snap.value.exitCode === 42
+                                    ? "git log failed (exit 42)"
+                                    : `git exited ${snap.value.exitCode}`
+                            : `exec failed: ${snap.error.message}`;
+                        deps.onError?.(new Error(`env git snapshot skipped — ${reason}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
+                    }
+                }
+                catch (err) {
+                    deps.onError?.(new Error(`env git snapshot skipped — ${err instanceof Error ? err.message : String(err)}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
+                }
+            }
+        }
+        let systemPrompt;
+        let renderWithDate;
+        const promptCtx = { userSystemPrompt, userAppendSystemPrompt, tools, memoryEnabled: false, consolidationEnabled: false, ...featureFlags };
+        let promptConstitution = "core";
+        let promptBlocks = [];
+        const finishStable = (stableCore) => {
+            const stable = composeSystemPrompt(composeSystemPrompt(stableCore, skillsBlock), mcpInstructionsBlock);
+            if (skillsBlock?.trim())
+                promptBlocks.push({ id: "skills.block", text: skillsBlock });
+            if (mcpInstructionsBlock?.trim())
+                promptBlocks.push({ id: "mcp.instructions", text: mcpInstructionsBlock });
+            renderWithDate = (date) => composeSystemPrompt(composeSystemPrompt(stable, buildEnvironmentContext({ ...envFacts, date }) || undefined), memoryBlock);
+            systemPrompt = renderWithDate(envFacts.date);
+            const envBlock = buildEnvironmentContext({ ...envFacts, date: envFacts.date });
+            if (envBlock?.trim())
+                promptBlocks.push({ id: "env.context", text: envBlock });
+            if (memoryBlock?.trim())
+                promptBlocks.push({ id: "memory.tail", text: memoryBlock });
+        };
+        if (provider === defaultPromptProvider) {
+            const c = composeConstitution(userSystemPrompt ?? DEFAULT_SYSTEM_PROMPT, promptCtx);
+            promptBlocks = [...c.blocks];
+            finishStable(c.text);
+        }
+        else if (provider.stableSystem) {
+            const roleOut = provider.stableSystem(promptCtx);
+            if (provider.replaceAll) {
+                promptConstitution = "replaced";
+                promptBlocks = [{ id: "provider.replace_all", text: roleOut }];
+                finishStable(roleOut);
+            }
+            else if (roleOut.includes(CYBER_RISK) && roleOut.includes(URL_SAFETY) && roleOut.includes("# Harness")) {
+                promptConstitution = "provider-assembled";
+                promptBlocks = [{ id: "provider.assembled", text: roleOut }];
+                deps.onError?.(new Error("prompt-constitution: this PromptProvider returns an already-assembled prompt (constitution anchor found). Core now appends the constitution structurally — return ONLY the role base from stableSystem (or set replaceAll:true to own the whole base). Passed through un-doubled."), { phase: "prompt-constitution", sessionId });
+                finishStable(roleOut);
+            }
+            else {
+                const c = composeConstitution(roleOut, promptCtx);
+                promptBlocks = [...c.blocks];
+                finishStable(c.text);
+            }
+        }
+        else if (provider.system) {
+            systemPrompt = provider.system({ ...promptCtx, memoryBlock });
+            promptConstitution = "legacy";
+            promptBlocks = [{ id: "provider.legacy", text: systemPrompt }];
+            const memTrim = memoryBlock?.trim();
+            if (memTrim && systemPrompt.includes(memTrim) && !systemPrompt.trimEnd().endsWith(memTrim)) {
+                deps.onError?.(new Error("prompt-cache: the <user_memory> block is not at the END of the system prompt — the cacheable prefix changes every turn, so vLLM/Anthropic prefix caching will miss. Put memoryBlock LAST (STABLE→VARIABLE), or implement PromptProvider.stableSystem and let core place memory."), { phase: "prompt-cache", sessionId });
+            }
+        }
+        else {
+            const c = composeConstitution(userSystemPrompt ?? DEFAULT_SYSTEM_PROMPT, promptCtx);
+            promptBlocks = [...c.blocks];
+            finishStable(c.text);
+        }
+        if (model.promptGuidance && model.promptGuidance.length > 0) {
+            const guidance = model.promptGuidance.join("\n\n");
+            const baseRender = renderWithDate;
+            if (baseRender) {
+                renderWithDate = (date) => composeSystemPrompt(baseRender(date), guidance);
+                systemPrompt = renderWithDate(envFacts.date);
+            }
+            else {
+                systemPrompt = composeSystemPrompt(systemPrompt, guidance) ?? systemPrompt;
+            }
+            promptBlocks.push({ id: "model.guidance", text: guidance });
+        }
+        const promptManifest = {
+            constitution: promptConstitution,
+            blocks: promptBlocks.map((b) => ({ id: b.id, chars: b.text.length, hash: createHash("sha256").update(PROMPT_HASH_SALT).update(b.text).digest("hex").slice(0, 12) })),
+        };
+        const userToolNames = (spec.tools ?? []).map((t) => t.name);
+        const mcpToolNames = mcp.tools.map((t) => t.name);
+        const deferred = classifyDeferred({
+            specs: spec.tools ?? [],
+            mcpToolNames,
+            fullTools: tools.filter((t) => userToolNames.includes(t.name) || mcpToolNames.includes(t.name)),
+            deferMode: deps.deferMode,
+            model,
+        });
+        const activeTools = new Set();
+        const fpRef = {};
+        let harnessTools = tools;
+        let toolsDeltaRef;
+        if (deferred.size > 0) {
+            if (deferred.has(TOOL_SEARCH_NAME) || tools.some((t) => t.name === TOOL_SEARCH_NAME)) {
+                const e = new Error(`Tool name "${TOOL_SEARCH_NAME}" is reserved when deferred tools are present.`);
+                e.code = "config.reserved_tool_name";
+                throw e;
+            }
+            const registry = buildDeferredRegistry(deferred, tools);
+            const placeholders = new Map([...registry.values()].map((i) => [i.name, makePlaceholderTool(i)]));
+            const { messages } = await session.buildContext();
+            for (const n of extractDiscoveredToolNames(messages, registry)) {
+                if (deferred.has(n))
+                    activeTools.add(n);
+            }
+            if (resume) {
+                for (const n of resume.seed.activeTools)
+                    if (deferred.has(n))
+                        activeTools.add(n);
+            }
+            let toolSearch;
+            const buildToolList = (active) => {
+                const list = tools.map((t) => (deferred.has(t.name) && !active.has(t.name) ? placeholders.get(t.name) : t));
+                list.push(toolSearch);
+                return list;
+            };
+            const announcedTools = new Set(activeTools);
+            toolsDeltaRef = { pending: [] };
+            const deltaRef = toolsDeltaRef;
+            const rematerialize = async (active) => {
+                const list = buildToolList(active);
+                await harnessRef.current.setTools(list);
+                if (fpRef.current)
+                    fpRef.current.tools = toolsToFingerprintInputs(list);
+                for (const n of active) {
+                    if (!announcedTools.has(n)) {
+                        announcedTools.add(n);
+                        deltaRef.pending.push(n);
+                    }
+                }
+            };
+            toolSearch = makeToolSearchTool({ registry, active: activeTools, rematerialize });
+            harnessTools = buildToolList(activeTools);
+        }
+        const agentListingSpec = (spec.tools ?? []).find((t) => t.agentListing !== undefined && t.agentListing.length > 0);
+        const agentListing = agentListingSpec
+            ? { entries: agentListingSpec.agentListing, toolName: agentListingSpec.name, seedAnnounced: resume !== undefined }
+            : undefined;
+        let promptDate = envFacts.date;
+        let renderedPrompt = systemPrompt;
+        const liveSystemPrompt = renderWithDate
+            ? () => {
+                const today = formatLocalDate(new Date(), tzValid ? userTz : undefined);
+                if (today !== promptDate) {
+                    promptDate = today;
+                    renderedPrompt = renderWithDate(today);
+                    if (fpRef.current)
+                        fpRef.current.systemPrompt = renderedPrompt;
+                }
+                return renderedPrompt;
+            }
+            : undefined;
+        const harness = new AgentHarness({
+            ...(spec.limits?.maxOutputTokens !== undefined && spec.limits.maxOutputTokens > 0
+                ? { maxOutputTokens: spec.limits.maxOutputTokens }
+                : {}),
+            ...(callCapRef !== undefined && callCapOn
+                ? {
+                    maxOutputTokensPerCall: () => {
+                        if (callCapRef.reasoningObserved === true)
+                            return undefined;
+                        const cap = computeCallCap(callCapRef, Date.now(), (thinking ?? "off") !== "off");
+                        if (cap !== undefined)
+                            callCapRef.shrinks = (callCapRef.shrinks ?? 0) + 1;
+                        return cap;
+                    },
+                }
+                : {}),
+            ...(callCapRef !== undefined
+                ? { callDeadlineMsPerCall: () => softExecDeadlineMs(callCapRef) }
+                : {}),
+            ...(spec.resilience !== undefined ? { resilience: spec.resilience } : {}),
+            loopTrace: (step) => {
+                if (step.kind !== "continue")
+                    return;
+                if (step.reason === "next_turn" || step.reason === "steer_injected" || step.reason === "follow_up_injected")
+                    return;
+                emitTrace(deps.tracer, () => ({
+                    kind: "loop.recovery",
+                    version: 1,
+                    taskId: spec.taskId ?? sessionId,
+                    reason: step.reason,
+                    ts: Date.now(),
+                }));
+            },
+            ...(spec.streamingToolExecution === true ? { streamingToolExecution: true } : {}),
+            followUpMode: "all",
+            env: executionEnv,
+            session,
+            tools: harnessTools,
+            model,
+            thinkingLevel: thinking ?? "off",
+            systemPrompt: liveSystemPrompt ?? systemPrompt,
+            getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
+            runtime: brainToRuntime(deps.brain),
+        });
+        harnessRef.current = harness;
+        let releaseSignal = () => undefined;
+        if (spec.signal) {
+            if (spec.signal.aborted) {
+                abortController.abort();
+            }
+            else {
+                const sig = spec.signal;
+                const onExternalAbort = () => {
+                    abortController.abort();
+                    void harness.abort();
+                };
+                sig.addEventListener("abort", onExternalAbort, { once: true });
+                releaseSignal = () => sig.removeEventListener("abort", onExternalAbort);
+            }
+        }
+        const policy = spec.toolPolicy ?? deps.toolPolicy;
+        let sessionRulePolicy;
+        if (deps.sessionPolicyStore && spec.sessionId) {
+            const rules = await deps.sessionPolicyStore.getRules(spec.sessionId, spec.principal);
+            if (rules) {
+                sessionRulePolicy = createSessionRulePolicy(rules, { env: executionEnv, rootPath: taskRootPath, toolEffects });
+            }
+        }
+        const skillScopePolicy = hasSkillManifest
+            ? createActiveSkillScopePolicy({
+                scope: skillScope,
+                env: executionEnv,
+                rootPath: taskRootPath,
+                toolEffects,
+            })
+            : undefined;
+        const narrowingLayers = [sessionRulePolicy, skillScopePolicy].filter((p) => p !== undefined);
+        const denyNarrowingPolicy = narrowingLayers.length === 0 ? undefined : narrowingLayers.length === 1 ? narrowingLayers[0] : combinePolicies(...narrowingLayers);
+        const policyLayers = policy !== undefined ? [...narrowingLayers, policy, ...narrowingLayers] : narrowingLayers;
+        const integrityGuardLayers = [createTranscriptIntegrityPolicy(), createUnverifiableDeletePolicy()];
+        const guardedPolicyLayers = policy !== undefined ? [...integrityGuardLayers, ...policyLayers, ...integrityGuardLayers] : [...integrityGuardLayers, ...policyLayers];
+        const effectivePolicy = guardedPolicyLayers.length === 1 ? guardedPolicyLayers[0] : combinePolicies(...guardedPolicyLayers);
+        const hooks = spec.hooks ?? deps.hooks;
+        const onAsk = spec.onAsk ?? deps.onAsk;
+        const handWriteTools = handsEnabled
+            ? Object.keys(HAND_TOOL_EFFECTS).filter((name) => {
+                const eff = HAND_TOOL_EFFECTS[name];
+                return eff === "write" || eff === "idempotent";
+            })
+            : [];
+        const hasEffectAwareGate = Boolean(policyLayers.length > 0 || hooks?.preToolUse);
+        const destructiveMcpUngated = mcp.tools.some((t) => !irreversibleTools.has(t.name) && !egressTools.has(t.name) && (toolEffects.get(t.name) ?? "write") !== "read");
+        const firstPartyWriteUngated = (spec.tools ?? [])
+            .map((t) => t.name)
+            .filter((name) => !irreversibleTools.has(name) && !egressTools.has(name) && toolEffects.get(name) === "write");
+        if (!hasEffectAwareGate && (handWriteTools.length > 0 || destructiveMcpUngated || firstPartyWriteUngated.length > 0)) {
+            const what = [
+                handWriteTools.length > 0 ? `hand tools [${handWriteTools.join(", ")}]` : undefined,
+                destructiveMcpUngated ? "MCP write tools" : undefined,
+                firstPartyWriteUngated.length > 0 ? `write tools [${firstPartyWriteUngated.join(", ")}]` : undefined,
+            ]
+                .filter(Boolean)
+                .join(" + ");
+            if (!ungatedWarnedShapes.get(deps)?.has(what)) {
+                let shapes = ungatedWarnedShapes.get(deps);
+                if (!shapes) {
+                    shapes = new Set();
+                    ungatedWarnedShapes.set(deps, shapes);
+                }
+                shapes.add(what);
+                deps.onError?.(new Error(`write-capable ${what} are present but UNGATED — wire an effect-aware tool policy (or a PreToolUse hook). ` +
+                    `bash/MCP irreversible actions are otherwise unadjudicated; the deployment sandbox/egress boundary is the only protection (design/77 §4, design/53 §2.H). ` +
+                    `(This warning fires once per deployment per tool-set shape.)`), { phase: "config", sessionId });
+            }
+        }
+        const preToolContexts = new Map();
+        const blockedToolCalls = new Set();
+        const blockedTracked = Boolean(hooks?.postToolUse || hooks?.preToolUse || hooks?.postToolUseFailure || hooks?.postToolBatch);
+        const resourceSuspendEligible = spec.resourceSuspend !== undefined &&
+            (spec.checkpointStore ?? deps.checkpointStore) !== undefined &&
+            !(offloadStore !== undefined && isVolatileOffloadStore(offloadStore)) &&
+            (ownedEnv === undefined || isRemoteExecutionEnv(ownedEnv));
+        if (spec.resourceSuspend !== undefined && !resourceSuspendEligible) {
+            const why = (spec.checkpointStore ?? deps.checkpointStore) === undefined
+                ? "no CheckpointStore is wired"
+                : offloadStore !== undefined && isVolatileOffloadStore(offloadStore)
+                    ? "tool-result offload uses the in-memory store (a resume needs durable results)"
+                    : "the per-task execution env is not a RemoteExecutionEnv (it would be destroyed on suspend)";
+            deps.onError?.(new Error(`resourceSuspend is set but INACTIVE: ${why}; resource limits will hard-fail, not suspend`), {
+                phase: "config",
+                sessionId,
+            });
+        }
+        if (effectivePolicy || hooks?.preToolUse || egressTools.size > 0 || irreversibleTools.size > 0 || resourceSuspendEligible || spec.enablePlanMode === true) {
+            const adjudicate = effectivePolicy
+                ? (req) => raceAbort(Promise.resolve(effectivePolicy.check({ ...req, budget: budgetSnapshot }, abortController.signal)), abortController.signal, () => ({
+                    action: "deny",
+                    reason: "policy check aborted (task timed out or cancelled)",
+                }))
+                : undefined;
+            const resolveAskBound = async (decision, req) => {
+                const t0 = now();
+                const resolved = await resolveAsk({
+                    toolName: req.toolName,
+                    toolCallId: req.toolCallId,
+                    args: req.args,
+                    message: decision.message ?? decision.reason ?? `approval required for "${req.toolName}"`,
+                    principal: spec.principal,
+                    sourceTaskId: sessionId,
+                }, onAsk, abortController.signal);
+                const waitMs = Math.max(0, now() - t0);
+                humanReviewRef.count += 1;
+                humanReviewRef.totalWaitMs += waitMs;
+                const toolArg = primaryActivityArg(req.args);
+                humanReviewRef.gates.push({
+                    kind: "human",
+                    waitMs,
+                    decision: resolved.action === "allow" ? "allow" : "deny",
+                    toolName: req.toolName,
+                    ...(toolArg !== undefined ? { toolArg } : {}),
+                });
+                return resolved;
+            };
+            const hooksWithPermissionDenied = hooks?.permissionDenied ? hooks : undefined;
+            const notifyPermissionDenied = hooksWithPermissionDenied
+                ? async (payload) => {
+                    try {
+                        await hooksWithPermissionDenied.permissionDenied(payload);
+                    }
+                    catch (err) {
+                        try {
+                            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "hook", sessionId });
+                        }
+                        catch {
+                        }
+                    }
+                }
+                : undefined;
+            const checkpointStore = spec.checkpointStore ?? deps.checkpointStore;
+            const durableApproval = spec.durableApproval ??
+                (runtimeCaps?.forceDurableGate ? { scope: spec.principal || DEFAULT_IRREVERSIBLE_SCOPE } : undefined);
+            const serializeCheckpointState = (workspaceHandle) => ({
+                activeTools: [...activeTools],
+                outputRef: { value: outputRef.value, set: outputRef.set },
+                nestedStats: { ...nestedStats },
+                consolidationNotes: undefined,
+                readFileState: readFileStateForCheckpoint ? [...readFileStateForCheckpoint.entries()] : undefined,
+                repairBundle: internals?.repairBundle !== undefined
+                    ? structuredClone(internals.repairBundle)
+                    : resume?.seed.repairBundle !== undefined
+                        ? structuredClone(resume.seed.repairBundle)
+                        : undefined,
+                workspaceHandle,
+                handsCwd: handsCwdRef?.current,
+                activeWorktree: worktreeSessionRef?.current ? { ...worktreeSessionRef.current } : undefined,
+                runningBackgroundTasks: (() => {
+                    const live = defaultTaskRegistry
+                        .list({ owner: hostTaskId, scope: taskScope, sessionId })
+                        .filter((t) => t.status === "pending" || t.status === "running")
+                        .map((t) => ({ id: t.task_id, ...(t.description !== undefined ? { description: t.description } : {}) }));
+                    return live.length > 0 ? live : undefined;
+                })(),
+                pendingSteer: undefined,
+            });
+            const commitSuspendSaga = async (token, cp, remoteEnv, remoteHandle) => {
+                if (!checkpointStore)
+                    return false;
+                if (memoryEngineSession)
+                    await memoryEngineSession.harvest("checkpoint");
+                try {
+                    await checkpointStore.put(token, cp);
+                    return true;
+                }
+                catch (putErr) {
+                    deps.onError?.(putErr, { phase: "config", sessionId });
+                    if (remoteEnv !== undefined && remoteHandle?.snapshotId !== undefined) {
+                        const back = await remoteEnv.resumeVM(remoteHandle.snapshotId, { abortSignal: abortController.signal });
+                        if (back.ok) {
+                            const init = await remoteEnv.postResumeInit();
+                            if (init.ok)
+                                return false;
+                            deps.onError?.(init.error, { phase: "config", sessionId });
+                        }
+                        else {
+                            deps.onError?.(back.error, { phase: "config", sessionId });
+                        }
+                        abortController.abort();
+                        void harness.abort();
+                        return false;
+                    }
+                    return false;
+                }
+            };
+            const publishCommittedSuspend = (token, gate, scope) => {
+                const ref = gate.kind === "needs_review" || gate.kind === "plan_review" ? reviewRef : suspendRef;
+                ref.token = token;
+                ref.gate = gate;
+                ref.scope = scope;
+            };
+            const suspendLoopCapHit = (count, cap, detail) => {
+                if (count + 1 <= cap)
+                    return false;
+                suspendLoopRef.hit = true;
+                abortController.abort();
+                void harness.abort();
+                try {
+                    deps.onError?.(new Error(`suspend loop: task already suspended ${count} time(s) (max ${cap}); refusing to suspend again${detail}`), { phase: "config", sessionId });
+                }
+                catch {
+                }
+                return true;
+            };
+            const suspendableEnv = ownedEnv !== undefined && isSuspendable(ownedEnv) ? ownedEnv : undefined;
+            const parkOnlyRemoteEnv = suspendableEnv === undefined && ownedEnv !== undefined && isRemoteExecutionEnv(ownedEnv) ? ownedEnv : undefined;
+            const parkOnlyHandle = (env) => {
+                const { snapshotId: _lineage, ...identity } = env.workspaceHandle();
+                return { ...identity, restoreMode: "park_only" };
+            };
+            suspendForResource = resourceSuspendEligible
+                ? async (reason, sliceSpend) => {
+                    const rs = spec.resourceSuspend;
+                    if (!checkpointStore || !rs)
+                        return false;
+                    if (abortController.signal.aborted)
+                        return false;
+                    if (suspendLoopCapHit(priorLedger?.sliceCount ?? 0, maxSlices, " (resource slice limit)"))
+                        return false;
+                    const leafId = await session.getLeafId();
+                    if (!leafId)
+                        return false;
+                    if (abortController.signal.aborted)
+                        return false;
+                    let remoteHandle;
+                    if (suspendableEnv !== undefined) {
+                        if (hasBackgroundShell(suspendableEnv))
+                            await suspendableEnv.disposeBackgroundShells();
+                        const snap = await suspendableEnv.suspendVM({ abortSignal: abortController.signal });
+                        if (!snap.ok) {
+                            deps.onError?.(new Error(`resource suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error }), { phase: "config", sessionId });
+                            return false;
+                        }
+                        remoteHandle = { ...suspendableEnv.workspaceHandle(), snapshotId: snap.value };
+                    }
+                    else if (parkOnlyRemoteEnv !== undefined) {
+                        if (hasBackgroundShell(parkOnlyRemoteEnv))
+                            await parkOnlyRemoteEnv.disposeBackgroundShells();
+                        remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+                    }
+                    const token = mintCheckpointToken();
+                    const gate = { kind: "resource_limit", reason };
+                    const cp = {
+                        token,
+                        version: RESOURCE_CHECKPOINT_VERSION,
+                        scope: rs.scope,
+                        sessionId,
+                        leafId,
+                        gate,
+                        pendingAction: { kind: "resource_limit", reason },
+                        state: serializeCheckpointState(remoteHandle),
+                        status: "pending",
+                        createdAt: Date.now(),
+                        deadline: Date.now() + (rs.ttlMs ?? DEFAULT_RESOURCE_TTL_MS),
+                        suspendCount: priorSuspendCount,
+                        humanReview: humanReviewRef.count > 0
+                            ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                            : undefined,
+                        resourceLedger: debitLedger(priorLedger, sliceSpend, resourceTotal),
+                    };
+                    if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)))
+                        return false;
+                    publishCommittedSuspend(token, gate, rs.scope);
+                    try {
+                        await sessions.pin?.(sessionId);
+                    }
+                    catch (pinErr) {
+                        deps.onError?.(pinErr, { phase: "config", sessionId });
+                    }
+                    harness.requestStopAfterTurn();
+                    return true;
+                }
+                : undefined;
+            suspendForReview = checkpointStore
+                ? async (reason) => {
+                    if (!checkpointStore)
+                        return false;
+                    if (abortController.signal.aborted)
+                        return false;
+                    if (suspendLoopCapHit(priorSuspendCount, maxSuspends, " for a plan_review (likely a resume/restart loop)."))
+                        return false;
+                    const leafId = await session.getLeafId();
+                    if (!leafId) {
+                        try {
+                            deps.onError?.(new Error("plan_review park skipped: no committed session leaf (the plan-review request was dropped; the run continues without pausing)"), { phase: "config", sessionId });
+                        }
+                        catch {
+                        }
+                        return false;
+                    }
+                    if (abortController.signal.aborted)
+                        return false;
+                    let remoteHandle;
+                    if (suspendableEnv !== undefined) {
+                        if (hasBackgroundShell(suspendableEnv))
+                            await suspendableEnv.disposeBackgroundShells();
+                        const snap = await suspendableEnv.suspendVM({ abortSignal: abortController.signal });
+                        if (!snap.ok) {
+                            deps.onError?.(new Error(`plan_review suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error }), { phase: "config", sessionId });
+                            return false;
+                        }
+                        remoteHandle = { ...suspendableEnv.workspaceHandle(), snapshotId: snap.value };
+                    }
+                    else if (parkOnlyRemoteEnv !== undefined) {
+                        if (hasBackgroundShell(parkOnlyRemoteEnv))
+                            await parkOnlyRemoteEnv.disposeBackgroundShells();
+                        remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+                    }
+                    const token = mintCheckpointToken();
+                    const scope = spec.durableApproval?.scope ?? (spec.principal || DEFAULT_IRREVERSIBLE_SCOPE);
+                    const gate = { kind: "plan_review", reason: reason ?? `plan review requested` };
+                    const cp = {
+                        token,
+                        version: BINDING_CHECKPOINT_VERSION,
+                        scope,
+                        sessionId,
+                        leafId,
+                        gate,
+                        pendingAction: { kind: "plan_review" },
+                        state: serializeCheckpointState(remoteHandle),
+                        status: "pending",
+                        createdAt: Date.now(),
+                        suspendedAt: now(),
+                        deadline: Date.now() + (spec.durableApproval?.ttlMs ?? DEFAULT_RESOURCE_TTL_MS),
+                        suspendCount: priorSuspendCount + 1,
+                        humanReview: humanReviewRef.count > 0
+                            ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                            : undefined,
+                        resourceLedger: priorLedger,
+                        sourceTaskId: sessionId,
+                        ...(spec.principal ? { principal: spec.principal } : {}),
+                    };
+                    if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)))
+                        return false;
+                    publishCommittedSuspend(token, gate, scope);
+                    try {
+                        await sessions.pin?.(sessionId);
+                    }
+                    catch (pinErr) {
+                        deps.onError?.(pinErr, { phase: "config", sessionId });
+                    }
+                    abortController.abort();
+                    void harness.abort();
+                    return true;
+                }
+                : undefined;
+            const suspendAsk = checkpointStore && (durableApproval || irreversibleTools.size > 0 || egressTools.size > 0)
+                ? async (req, postHookArgs, safety) => {
+                    let token;
+                    let gate;
+                    let cp;
+                    let remoteHandle;
+                    const remoteEnv = suspendableEnv;
+                    try {
+                        if (offloadStore && isVolatileOffloadStore(offloadStore) && !offloadStore.isEmpty()) {
+                            throw new Error("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 Error("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 Error("cannot suspend: session has no committed leaf to resume from");
+                        }
+                        const { messages } = await session.buildContext();
+                        const { batchToolCallIds, completedCallIds } = batchContextAt(messages, req.toolCallId);
+                        if (abortController.signal.aborted) {
+                            return undefined;
+                        }
+                        if (suspendLoopCapHit(priorSuspendCount, maxSuspends, ` for tool "${req.toolName}" — likely a resume/restart loop.`))
+                            return undefined;
+                        if (remoteEnv !== undefined) {
+                            if (hasBackgroundShell(remoteEnv))
+                                await remoteEnv.disposeBackgroundShells();
+                            const snap = await remoteEnv.suspendVM({ abortSignal: abortController.signal });
+                            if (!snap.ok) {
+                                throw new Error(`suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error });
+                            }
+                            remoteHandle = { ...remoteEnv.workspaceHandle(), snapshotId: snap.value };
+                        }
+                        else if (parkOnlyRemoteEnv !== undefined) {
+                            if (hasBackgroundShell(parkOnlyRemoteEnv))
+                                await parkOnlyRemoteEnv.disposeBackgroundShells();
+                            remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+                        }
+                        token = mintCheckpointToken();
+                        const riskDescriptor = buildRiskDescriptor({
+                            toolName: req.toolName,
+                            args: postHookArgs,
+                            safety,
+                            shellGated: (req.toolName === "Bash" && shellGatedBash) || (req.toolName === "Monitor" && shellGatedMonitor),
+                        });
+                        gate =
+                            safety !== undefined
+                                ? {
+                                    kind: "irreversible_ask",
+                                    reason: `human approval required before safety-tightened tool "${req.toolName}"`,
+                                    toolName: req.toolName,
+                                    safetyAxis: safety,
+                                    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 ?? (spec.principal || DEFAULT_IRREVERSIBLE_SCOPE);
+                        const ttlMs = durableApproval?.ttlMs;
+                        const checkpointState = serializeCheckpointState(remoteHandle);
+                        cp = {
+                            token,
+                            version: BINDING_CHECKPOINT_VERSION,
+                            scope,
+                            sessionId,
+                            leafId,
+                            gate,
+                            pendingAction: {
+                                kind: "tool_approval",
+                                toolCallId: req.toolCallId,
+                                toolName: req.toolName,
+                                args: postHookArgs,
+                                boundInputHash: boundInputHashOf(postHookArgs),
+                                batchToolCallIds,
+                                completedCallIds,
+                            },
+                            state: checkpointState,
+                            deadline: ttlMs !== undefined
+                                ? Date.now() + ttlMs
+                                : durableApproval !== undefined
+                                    ? undefined
+                                    : Date.now() + DEFAULT_UNATTENDED_APPROVAL_TTL_MS,
+                            status: "pending",
+                            createdAt: Date.now(),
+                            suspendedAt: now(),
+                            humanReview: humanReviewRef.count > 0
+                                ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                                : undefined,
+                            suspendCount: priorSuspendCount + 1,
+                            resourceLedger: debitLedger(priorLedger, liveSpendRef.get?.() ?? { costMicroUsd: 0, tokens: 0, turns: 0 }, resourceTotal, { countSlice: false }),
+                            sourceTaskId: sessionId,
+                            ...(spec.principal ? { principal: spec.principal } : {}),
+                        };
+                    }
+                    catch (err) {
+                        deps.onError?.(err, { phase: "config", sessionId });
+                        return undefined;
+                    }
+                    if (!(await commitSuspendSaga(token, cp, remoteEnv, remoteHandle))) {
+                        return undefined;
+                    }
+                    publishCommittedSuspend(token, gate, cp.scope);
+                    try {
+                        await sessions.pin?.(sessionId);
+                    }
+                    catch (pinErr) {
+                        deps.onError?.(pinErr, { phase: "config", sessionId });
+                    }
+                    abortController.abort();
+                    void harness.abort();
+                    return { token, gate };
+                }
+                : undefined;
+            for (const t of tools) {
+                const eff = t.effect;
+                if (eff !== undefined && !toolEffects.has(t.name))
+                    toolEffects.set(t.name, eff);
+            }
+            if (effectivePolicy || hooks?.preToolUse || egressTools.size > 0 || irreversibleTools.size > 0 || spec.enablePlanMode === true) {
+                harness.on("tool_call", async (e) => {
+                    blockedToolCalls.delete(e.toolCallId);
+                    if (planModeRef.active && (toolEffects.get(e.toolName) ?? "write") !== "read") {
+                        if (blockedTracked)
+                            blockedToolCalls.add(e.toolCallId);
+                        const planDenyReason = `Plan mode is active — "${e.toolName}" is a write/mutating tool and is read-only-blocked. ` +
+                            `Research with read-only tools, then call ${PRESENT_PLAN_TOOL_NAME} with your plan to get it approved before acting.`;
+                        if (notifyPermissionDenied) {
+                            await notifyPermissionDenied({ toolName: e.toolName, input: cloneObserverInput(e.input), toolCallId: e.toolCallId, reason: planDenyReason, source: "planMode" });
+                        }
+                        return {
+                            block: true,
+                            reason: formatHookFeedback(planDenyReason),
+                            preToolContext: [],
+                        };
+                    }
+                    const result = await runToolGate({
+                        event: e,
+                        preToolUse: hooks?.preToolUse,
+                        adjudicate,
+                        resolveAsk: resolveAskBound,
+                        suspendAsk,
+                        egress: egressTools.has(e.toolName),
+                        irreversibility: irreversibilityTier.get(e.toolName),
+                        reversibilityProbe: reversibilityProbes.get(e.toolName),
+                        abortSignal: abortController.signal,
+                        ...(notifyPermissionDenied ? { permissionDenied: notifyPermissionDenied } : {}),
+                        shellGated: (e.toolName === "Bash" && shellGatedBash) || (e.toolName === "Monitor" && shellGatedMonitor),
+                        ...(autoModeDecider ? { autoMode: { decider: autoModeDecider } } : {}),
+                    });
+                    if (!result.block && !result.suspend && result.preToolContext.length > 0) {
+                        preToolContexts.set(e.toolCallId, result.preToolContext);
+                    }
+                    if (blockedTracked && (result.block || result.suspend)) {
+                        blockedToolCalls.add(e.toolCallId);
+                    }
+                    return result.block
+                        ? { block: true, reason: result.reason }
+                        : result.updatedInput !== undefined
+                            ? { updatedInput: result.updatedInput }
+                            : undefined;
+                });
+            }
+        }
+        if (hooks?.postToolUse || hooks?.preToolUse || hooks?.postToolUseFailure) {
+            harness.on("tool_result", async (e) => {
+                if (blockedToolCalls.delete(e.toolCallId)) {
+                    return undefined;
+                }
+                let content = e.content;
+                let changed = false;
+                if (e.isError) {
+                    if (hooks?.postToolUseFailure) {
+                        let clonedDetails = e.details;
+                        try {
+                            clonedDetails = structuredClone(e.details);
+                        }
+                        catch {
+                        }
+                        const patch = await hooks.postToolUseFailure(e.toolName, 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: e.toolName });
+                        if (patch?.additionalContext) {
+                            content = [...content, { type: "text", text: formatHookFeedback(patch.additionalContext) }];
+                            changed = true;
+                        }
+                    }
+                }
+                else if (hooks?.postToolUse) {
+                    const patch = await hooks.postToolUse(e.toolName, e.input, { content: e.content, details: e.details, isError: e.isError }, { toolCallId: e.toolCallId, toolName: e.toolName });
+                    if (patch?.updatedOutput) {
+                        content = patch.updatedOutput;
+                        changed = true;
+                    }
+                    if (patch?.additionalContext) {
+                        content = [...content, { type: "text", text: formatHookFeedback(patch.additionalContext) }];
+                        changed = true;
+                    }
+                }
+                const pre = preToolContexts.get(e.toolCallId);
+                if (pre) {
+                    preToolContexts.delete(e.toolCallId);
+                    content = [...content, ...pre.map((t) => ({ type: "text", text: formatHookFeedback(t) }))];
+                    changed = true;
+                }
+                return changed ? { content } : undefined;
+            });
+        }
+        const editAt = editBudget(model);
+        const guardAt = guardBudget(model);
+        const charsPerToken = model.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+        harness.on("context", async ({ messages }) => {
+            const healed = dropEmptyFailureAssistants(messages);
+            const capped = await capAggregateToolResults(healed, {
+                store: offloadStore,
+                sessionId,
+                onCapped: (info) => emitTrace(deps.tracer, () => ({
+                    kind: "tool_result.capped",
+                    version: 1,
+                    taskId: spec.taskId ?? sessionId,
+                    ...(info.tool !== undefined ? { tool: info.tool } : {}),
+                    sizeChars: info.sizeChars,
+                    storeFallback: info.storeFallback,
+                    ts: Date.now(),
+                })),
+            });
+            const mediaCapped = capAggregateMediaBytes(capped, {
+                limitBytes: deps.mediaByteCapBytes ?? AGGREGATE_MEDIA_BUDGET_BYTES,
+                onStripped: deps.onMediaStripped,
+            });
+            const edited = clearStaleToolResults(mediaCapped, {
+                budgetTokens: editAt,
+                anchoredTotalTokens: estimateContextTokens(mediaCapped, charsPerToken).tokens,
+                charsPerToken,
+                ...(offloadStore
+                    ? {
+                        offload: {
+                            persist: (toolCallId, fullText) => {
+                                const ref = `tr_${sessionId}_${toolCallId}`;
+                                void offloadStore.put(ref, fullText);
+                                return ref;
+                            },
+                        },
+                    }
+                    : {}),
+            });
+            const trimmed = trimToBudget(edited, guardAt, estimateContextTokens(edited, charsPerToken).tokens, charsPerToken);
+            if (trimmed.length < edited.length) {
+                trimPressureRef.droppedMessages = true;
+                emitTrace(deps.tracer, () => ({
+                    kind: "context.trim",
+                    version: 1,
+                    taskId: spec.taskId ?? sessionId,
+                    dropped: edited.length - trimmed.length,
+                    ts: Date.now(),
+                }));
+            }
+            const swept = dropOrphanToolResults(trimmed);
+            if (swept.dropped.length > 0) {
+                try {
+                    deps.onError?.(new Error(`context belt: dropped ${swept.dropped.length} orphan toolResult(s) whose tool-call assistant was not in the request view — ` +
+                        swept.dropped
+                            .map((d) => `toolCallId=${d.toolCallId} at index ${d.index} (prev=${d.prevRole}, next=${d.nextRole})`)
+                            .join("; ")), { phase: "hook", sessionId });
+                }
+                catch {
+                }
+            }
+            return { messages: swept.messages };
+        });
+        const cacheBreakDetector = deps.cacheBreakDetection === false ? undefined : new CacheBreakDetector();
+        const cacheFingerprint = cacheBreakDetector
+            ? { systemPrompt, tools: toolsToFingerprintInputs(harnessTools) }
+            : undefined;
+        fpRef.current = cacheFingerprint;
+        const promptOverheadTokens = Math.ceil((systemPrompt.length +
+            harnessTools.reduce((a, t) => a + t.name.length + (t.description?.length ?? 0) + JSON.stringify(t.parameters ?? {}).length, 0)) / charsPerToken);
+        const readTaskFile = handsEnabled
+            ? async (path) => {
+                try {
+                    const r = await executionEnv.readBinaryFile(path);
+                    if (!r.ok)
+                        return null;
+                    const d = decodeTextBytes(r.value);
+                    return d.malformed ? null : d.text;
+                }
+                catch {
+                    return null;
+                }
+            }
+            : undefined;
+        const recentlyReadFiles = handsEnabled && readFileStateForCheckpoint
+            ? () => [...readFileStateForCheckpoint.entries()]
+                .sort((a, b) => (b[1].lastReadAt ?? 0) - (a[1].lastReadAt ?? 0))
+                .map(([path]) => path)
+            : undefined;
+        const detectExternalChanges = handsEnabled && readFileStateForCheckpoint
+            ? async (maxFiles) => {
+                const candidates = [...readFileStateForCheckpoint.entries()]
+                    .filter(([, e]) => e.lastReadAt !== undefined)
+                    .sort((a, b) => (b[1].lastReadAt ?? 0) - (a[1].lastReadAt ?? 0))
+                    .slice(0, Math.max(0, maxFiles));
+                const changed = [];
+                const evicted = [];
+                for (const [path, entry] of candidates) {
+                    try {
+                        const info = await executionEnv.fileInfo(path, abortController.signal);
+                        if (!info.ok) {
+                            if (info.error.code === "not_found") {
+                                readFileStateForCheckpoint.delete(path);
+                                evicted.push(path);
+                            }
+                            continue;
+                        }
+                        if (info.value.mtimeMs > (entry.lastReadAt ?? 0) + CHANGED_FILES_MTIME_EPS_MS) {
+                            changed.push({ path, mtimeMs: info.value.mtimeMs });
+                        }
+                    }
+                    catch {
+                    }
+                }
+                return { changed, evicted };
+            }
+            : undefined;
+        const listBackgroundTasks = () => defaultTaskRegistry
+            .list({ owner: hostTaskId, scope: taskScope, sessionId })
+            .filter((t) => t.status === "pending" || t.status === "running")
+            .map((t) => ({ id: t.task_id, ...(t.description !== undefined ? { description: t.description } : {}), status: t.status }));
+        return { harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, cwdRef: handsCwdRef, denyNarrowingPolicy, releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, activeTools, ownedEnv, suspendRef, reviewRef, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), listBackgroundTasks };
+    }
+    catch (prepareErr) {
+        if (mcp) {
+            try {
+                await mcp.dispose();
+            }
+            catch {
+            }
+        }
+        if (ownedEnv && hasDestroy(ownedEnv)) {
+            try {
+                await ownedEnv.destroy();
+            }
+            catch {
+            }
+        }
+        await forgetOnThrow();
+        throw prepareErr;
+    }
+}
+//# sourceMappingURL=prepare-task.js.map