@sema-agent/core 2.0.1 → 2.2.0

package/dist/agents/subagent.js

@@ -19,12 +19,9 @@ import { BG_AGENT_REAP_STOP_ERROR } from "../core/task-registry.js";
 import { extractErrorCode } from "../brain/errors.js";
 import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
 export { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
-import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger, getOrCreateSessionRetainLedger, releaseSessionRetainLedger, ensureSessionReapHook, createResumePrompt, } from "./retain-ledger.js";
-export { SubagentRetainLedger, getSessionRetainLedger, releaseSessionRetainLedger };
-export { AGENT_TRANSCRIPT_TOOL_NAME, createAgentTranscriptTool } from "./agent-transcript-tool.js";
-export { SEND_MESSAGE_TOOL_NAME, createSendMessageTool } from "./send-message-tool.js";
+import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getOrCreateSessionRetainLedger, ensureSessionReapHook, createResumePrompt, } from "./retain-ledger.js";
 import { recordRosterSpawn } from "./roster-store.js";
-import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
+import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
 import { SubagentStepRecorder } from "./subagent-steps.js";
 const BG_AGENT_RESULT_MAX = 4_000;
 const BG_AGENT_RESULT_FULL_MAX = 200_000;
@@ -68,6 +65,7 @@ export function inheritedManifestScopeFor(snapshot) {
 export const DEFAULT_SUBAGENT_TOOL_NAME = "Agent";
 export const LEGACY_SUBAGENT_TOOL_NAME = "Task";
 export const EXTRA_TOOLS_MAX_FACTORY_CALLS_PER_TREE = 64;
+export const DEFAULT_SUBAGENT_MAX_DEPTH = 3;
 export const EXTRA_TOOLS_FAILED_NOTE = "note: extraTools evaluation failed — the injected tool set was skipped for this spawn.";
 export const EXTRA_TOOLS_BUDGET_NOTE = `note: extraTools evaluation was skipped — this spawn tree exhausted its factory-call budget (${EXTRA_TOOLS_MAX_FACTORY_CALLS_PER_TREE}); no dynamic tools were injected for this spawn.`;
 function countArgLines(v) {
@@ -131,6 +129,9 @@ function createToolStatsCounter(delegationToolName) {
         snapshot() {
             return t.readCount + t.searchCount + t.bashCount + t.editFileCount + t.otherToolCount > 0 ? { ...t } : undefined;
         },
+        total() {
+            return t.readCount + t.searchCount + t.bashCount + t.editFileCount + t.otherToolCount;
+        },
     };
 }
 export const FORK_SUBAGENT_TYPE = "fork";
@@ -580,6 +581,9 @@ function adaptLegacyForkArgs(args) {
     }
     return args;
 }
+export function normalizeSubagentType(value) {
+    return value.normalize("NFKC").toLowerCase().replace(/[\p{White_Space}\p{Pd}_]+/gu, "");
+}
 function foldGeneralPurposeAlias(args, shadowed) {
     if (shadowed)
         return args;
@@ -611,6 +615,31 @@ Guidelines (your directive may override any of these):
 </fork-boilerplate>
 
 Your directive: `;
+export function forkWorktreeTranslationNote(parentCwd, worktreeDir) {
+    const where = parentCwd !== undefined ? parentCwd : "a different working directory";
+    return (`You've inherited the conversation context above from a parent agent working in ${where}. ` +
+        `You are operating in an isolated git worktree at ${worktreeDir} — same repository, same relative file structure, separate working copy. ` +
+        `Paths in the inherited context refer to the parent's working directory; translate them to your worktree root. ` +
+        `Re-read files before editing if the parent may have modified them since they appear in the context. ` +
+        `Your changes stay in this worktree and will not affect the parent's files.`);
+}
+export function asyncLaunchedReceipt(p) {
+    const noteLines = (p.notes ?? []).filter((n) => n !== undefined && n !== "");
+    const oneShotBlocked = p.notify && p.oneShot === true;
+    return (`Async agent launched successfully. (This tool result is internal metadata — never quote or paste any part of it, including the task_id below, into a user-facing reply.)\n` +
+        `task_id: ${p.taskId} (internal ID - do not mention to user. Use SendMessage with to: '${p.taskId}', summary: '<5-10 word recap>' to continue this agent.)\n` +
+        (oneShotBlocked
+            ? `${p.workingLine} This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput(task_id: "${p.taskId}", block: true). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.\n`
+            : p.notify
+                ? `${p.workingLine} You will be notified automatically when it completes. You know nothing about its results until that notification arrives — do not report, assume, or predict them; continue other work or respond to the user in the meantime.\n`
+                : `${p.workingLine} Its result is NOT pushed automatically — retrieve progress and results with TaskOutput(task_id) where mounted.\n`) +
+        noteLines.map((n) => `${n}\n`).join("") +
+        (oneShotBlocked
+            ? `In your own words, briefly tell the user what you launched — do not echo this tool result. Do not assume a later message will deliver the result: this submission ends after this turn, so retrieve it now with the blocking TaskOutput wait above before writing your final answer.`
+            : p.notify
+                ? `In your own words, briefly tell the user what you launched — do not echo this tool result. Agent results will arrive in a subsequent message. If the user asks for progress, say the agent is still running.`
+                : `In your own words, briefly tell the user what you launched — do not echo this tool result. The result will NOT arrive on its own — retrieve it with TaskOutput(task_id) where mounted before relying on it.`));
+}
 export function createSubagentTool(opts) {
     const catalog = opts.runner.agentCatalog;
     if (opts.agents === undefined && catalog?.agents)
@@ -683,7 +712,7 @@ export function agentWhenToUseText(def, lean = true) {
     return (leanText || def.whenToUse) || undefined;
 }
 function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
-    const maxDepth = opts.maxDepth ?? 5;
+    const maxDepth = opts.maxDepth ?? DEFAULT_SUBAGENT_MAX_DEPTH;
     const toolName = opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME;
     const deploymentNames = new Set((opts.agents ?? []).map((a) => a.name));
     const builtins = opts.builtinAgents === false ? [] : builtinAgentDefinitions(toolName).filter((d) => !deploymentNames.has(d.name));
@@ -700,6 +729,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
     ];
     const rosterNames = opts.models ? Object.keys(opts.models) : undefined;
     const agentListing = [
+        ...(generalPurposeShadowed
+            ? []
+            : [{
+                    name: GENERAL_PURPOSE_SUBAGENT_TYPE,
+                    description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.",
+                    tools: "All tools",
+                }]),
         ...available.map((a) => ({ name: a.name, description: agentWhenToUseText(a) ?? "", tools: agentToolsNote(a) })),
         ...(forkOffered
             ? [{
@@ -821,12 +857,29 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     details: { error: "unknown subagent_type" },
                 };
             }
-            const rawType = a.subagent_type ?? "";
+            const requestedType = a.subagent_type ?? "";
+            let rawType = requestedType;
+            if (requestedType !== "") {
+                const accepted = acceptedSubagentTypes();
+                if (!accepted.includes(requestedType)) {
+                    const wanted = normalizeSubagentType(requestedType);
+                    const hits = wanted === "" ? [] : accepted.filter((n) => normalizeSubagentType(n) === wanted);
+                    if (hits.length > 1) {
+                        return {
+                            isError: true,
+                            content: `Sub-agent not started: subagent_type "${requestedType}" is ambiguous — it matches ${hits.join(", ")}. Use the exact name.`,
+                            details: { error: "ambiguous subagent_type" },
+                        };
+                    }
+                    if (hits.length === 1)
+                        rawType = hits[0];
+                }
+            }
             const wantsFork = forkOffered && rawType === FORK_SUBAGENT_TYPE;
             if (reviveClaim !== undefined && wantsFork) {
                 return { isError: true, content: `Sub-agent not revived: a "${FORK_SUBAGENT_TYPE}" agent cannot be revived — launch a new agent with the needed context instead.`, details: { error: "revive.fork_unsupported" } };
             }
-            const omitted = rawType === "";
+            const omitted = rawType === "" || (!generalPurposeShadowed && rawType === GENERAL_PURPOSE_SUBAGENT_TYPE);
             const def = hasAgents && !wantsFork && !omitted ? agentMap.get(rawType) : undefined;
             const spawnAgentType = wantsFork ? FORK_SUBAGENT_TYPE : omitted ? GENERAL_PURPOSE_SUBAGENT_TYPE : rawType;
             if (!def && !wantsFork && !omitted) {
@@ -1060,9 +1113,17 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             let observerTap;
             let observerSessionId;
             let observerFailure;
+            let observerDegradedCount = 0;
+            let observerDegradedFirst;
             const noteObserverFailure = (err) => {
-                if (observerFailure === undefined) {
-                    observerFailure = (err instanceof Error ? err.message : String(err)).slice(0, REPORT_FIELD_MAX);
+                const msg = (err instanceof Error ? err.message : String(err)).slice(0, REPORT_FIELD_MAX);
+                if (observerPairing !== undefined && observerPairing.state === "armed") {
+                    observerDegradedCount++;
+                    if (observerDegradedFirst === undefined)
+                        observerDegradedFirst = msg;
+                }
+                else if (observerFailure === undefined) {
+                    observerFailure = msg;
                 }
                 try {
                     opts.onObserverError?.(err, {
@@ -1074,19 +1135,31 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
             };
             const observedSteerRef = {};
+            let pendingTrigger = [];
+            const takePendingTrigger = () => {
+                if (pendingTrigger.length === 0)
+                    return undefined;
+                const joined = pendingTrigger.join("\n\n");
+                pendingTrigger = [];
+                return joined;
+            };
+            const injectObservedRequest = async (text, origin) => {
+                const steer = observedSteerRef.steer;
+                if (!steer)
+                    throw new Error("observed child has no steer lane (report undeliverable)");
+                if (origin !== "observer")
+                    pendingTrigger.push(text);
+                await steer(text);
+            };
             if (observerArm) {
+                pendingTrigger.push(prompt);
                 const observerDef = observerArm.observerDefinition;
                 const envelopeName = observerSlug(childAgentName ?? def.name);
-                const sid = uuidv7();
+                let sid = uuidv7();
                 observerSessionId = sid;
                 markObserverTaskId(sid);
                 const reportOpts = {
-                    queueReport: async (framed) => {
-                        const steer = observedSteerRef.steer;
-                        if (!steer)
-                            throw new Error("observed child has no steer lane (report undeliverable)");
-                        await steer(framed);
-                    },
+                    queueReport: async (framed) => injectObservedRequest(framed, "observer"),
                 };
                 const reportTool = createObserverReportToolSpec(reportOpts);
                 const observerSpec = (objectiveText, resume) => ({
@@ -1106,15 +1179,36 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 });
                 const runObserverLeg = async (spec) => {
                     if (!isObserverTaskId(sid))
-                        throw new Error("observer identity revoked — delivery refused");
+                        throw new ObserverStoppedByUserError("observer identity revoked — delivery refused");
                     const r = await opts.runner.runTask(spec);
                     if (r.status !== "completed") {
+                        if (r.errorCode === "resume.session_not_found") {
+                            throw new ObserverResumeStateError(`observer session no longer exists${r.errorMessage ? `: ${r.errorMessage}` : ""}`);
+                        }
                         throw new Error(`observer run ended ${r.status}${r.errorMessage ? `: ${r.errorMessage}` : ""}`);
                     }
                 };
                 const spawner = {
                     spawnFirstRun: ({ framingPrompt, digest }) => runObserverLeg(observerSpec(`${framingPrompt}\n\n${digest}`, false)),
                     deliver: ({ digest }) => runObserverLeg(observerSpec(digest, true)),
+                    restartFresh: async ({ framingPrompt, digest }) => {
+                        const dead = sid;
+                        const fresh = uuidv7();
+                        markObserverTaskId(fresh);
+                        sid = fresh;
+                        observerSessionId = fresh;
+                        try {
+                            await runObserverLeg(observerSpec(`${framingPrompt}\n\n${digest}`, false));
+                        }
+                        finally {
+                            unmarkObserverTaskId(dead);
+                            try {
+                                await opts.runner.sessions.release(dead);
+                            }
+                            catch {
+                            }
+                        }
+                    },
                 };
                 observerPairing = new ObserverPairing({
                     observedEnvelopeName: envelopeName,
@@ -1125,7 +1219,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     onError: noteObserverFailure,
                 });
                 reportOpts.pairing = observerPairing;
-                observerTap = new ObserverDigestTap((activity) => observerPairing.enqueueSegment(activity));
+                observerTap = new ObserverDigestTap((activity) => observerPairing.enqueueSegment(activity, takePendingTrigger()));
             }
             const closeObserverWindow = (status) => {
                 if (observerTap)
@@ -1152,9 +1246,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         t.unref?.();
                     });
                     const outcome = await Promise.race([observerPairing.drain().then(() => "drained"), timeout]);
+                    observerPairing.retire(outcome === "timeout" ? "stopped" : "retired");
                     if (outcome === "timeout")
                         noteObserverFailure(new Error("observer unresponsive at settle (delivery drain timed out)"));
-                    observerPairing.retire(outcome === "timeout" ? "stopped" : "retired");
                     if (observerSessionId !== undefined) {
                         try {
                             await opts.runner.sessions.release(observerSessionId);
@@ -1183,7 +1277,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     clearTimeout(timer);
                 return outcome;
             };
-            const observerNoteFor = (outcome) => observerFailure !== undefined ? " [observer: failed]" : outcome === "still_draining" ? " [observer: still draining]" : "";
+            const observerNoteFor = (outcome) => observerFailure !== undefined
+                ? " [observer: failed]"
+                : outcome === "still_draining"
+                    ? " [observer: still draining]"
+                    : observerDegradedCount > 0
+                        ? ` [observer: degraded, ${observerDegradedCount} digest batch(es) lost]`
+                        : "";
             const stepRecorder = new SubagentStepRecorder(ctx.toolCallId);
             const toolStatsCounter = createToolStatsCounter(opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME);
             let assistantTextTail = "";
@@ -1440,7 +1540,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 const forkInternals = { ...childInternals, insideFork: true };
                 stepRecorder.lockTo(forkedId);
-                const forkObjective = `${FORK_DIRECTIVE_FRAME}${prompt}`;
+                const forkWorktreeNote = worktreeDir !== undefined ? forkWorktreeTranslationNote(ctx.parentCwd, worktreeDir) : undefined;
+                const forkObjective = `${FORK_DIRECTIVE_FRAME}${prompt}${forkWorktreeNote !== undefined ? `\n\n${forkWorktreeNote}` : ""}`;
                 if (wantsBackground) {
                     const bg = opts.background;
                     const notify = ctx.onTaskNotification ?? bg.notify;
@@ -1674,25 +1775,22 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                     });
                     return {
-                        content: `Async agent launched successfully.
-task_id: ${taskId}
-` +
-                            `The forked agent inherits your full current context and works on its prompt in the background. ${notify ? "You will be notified automatically when it completes." : "Its result is NOT pushed automatically — retrieve progress and results with TaskOutput(task_id) where mounted."}
-` +
-                            (modelNote ? `${modelNote}\n` : "") +
-                            (extraToolsNote ? `${extraToolsNote}\n` : "") +
-                            (worktreeDir !== undefined
-                                ? `worktree: ${worktreeDir} (the agent works in its own detached worktree; auto-removed when it settles unchanged, kept when it made changes)
-`
-                                : "") +
-                            (sessionScopedBg
-                                ? `It is session-scoped: it keeps running even after this task ends.
-`
-                                : `Note: it is stopped automatically (killed) if still running when this task ends — do not promise the user results beyond this task.
-`) +
-                            (notify
-                                ? `Briefly tell the user what you launched and end your response. Do not generate any other text — agent results will arrive in a subsequent message.`
-                                : `Briefly tell the user what you launched. The result will NOT arrive on its own — retrieve it with TaskOutput(task_id) where mounted before relying on it.`),
+                        content: asyncLaunchedReceipt({
+                            taskId,
+                            workingLine: `The forked agent inherits your full current context and works on its prompt in the background.`,
+                            notify: Boolean(notify),
+                            oneShot: ctx.oneShot === true,
+                            notes: [
+                                modelNote,
+                                extraToolsNote,
+                                worktreeDir !== undefined
+                                    ? `worktree: ${worktreeDir} (the agent works in its own detached worktree; auto-removed when it settles unchanged, kept when it made changes)`
+                                    : undefined,
+                                sessionScopedBg
+                                    ? `It is session-scoped: it keeps running even after this task ends.`
+                                    : `Note: it is stopped automatically (killed) if still running when this task ends — do not promise the user results beyond this task.`,
+                            ],
+                        }),
                         details: { type: "agent", subagent_type: FORK_SUBAGENT_TYPE, status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt },
                     };
                 }
@@ -2308,29 +2406,27 @@ task_id: ${taskId}
                     }
                 }
                 return {
-                    content: `Async agent launched successfully.
-task_id: ${taskId}
-` +
-                        `The agent is working in the background. ${notify ? "You will be notified automatically when it completes." : "Its result is NOT pushed automatically — retrieve progress and results with TaskOutput(task_id) where mounted."}
-` +
-                        (modelNote ? `${modelNote}\n` : "") +
-                        (extraToolsNote ? `${extraToolsNote}\n` : "") +
-                        (worktreeDir !== undefined
-                            ? `worktree: ${worktreeDir} (the agent works in its own detached worktree; auto-removed when it settles unchanged, kept when it made changes)
-`
-                            : "") +
-                        (sessionScopedBg
-                            ? `It is session-scoped: it keeps running even after this task ends.
-`
-                            : `Note: it is stopped automatically (killed) if still running when this task ends — do not promise the user results beyond this task.
-`) +
-                        (notify
-                            ? `Briefly tell the user what you launched and end your response. Do not generate any other text — agent results will arrive in a subsequent message.`
-                            : `Briefly tell the user what you launched. The result will NOT arrive on its own — retrieve it with TaskOutput(task_id) where mounted before relying on it.`),
+                    content: asyncLaunchedReceipt({
+                        taskId,
+                        workingLine: `The agent is working in the background.`,
+                        notify: Boolean(notify),
+                        oneShot: ctx.oneShot === true,
+                        notes: [
+                            modelNote,
+                            extraToolsNote,
+                            worktreeDir !== undefined
+                                ? `worktree: ${worktreeDir} (the agent works in its own detached worktree; auto-removed when it settles unchanged, kept when it made changes)`
+                                : undefined,
+                            sessionScopedBg
+                                ? `It is session-scoped: it keeps running even after this task ends.`
+                                : `Note: it is stopped automatically (killed) if still running when this task ends — do not promise the user results beyond this task.`,
+                        ],
+                    }),
                     details: { type: "agent", status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt },
                 };
             }
             let child;
+            const syncStartedAt = Date.now();
             let retainEntry;
             if (ctx.onSubagentSpawn || observerPairing) {
                 retainEntry = ctx.onSubagentSpawn ? await tryRetainChild(ctx.subagentRetain) : undefined;
@@ -2438,9 +2534,13 @@ task_id: ${taskId}
                 child.blockedReason ? `blocked_reason: ${inlineUntrusted(child.blockedReason, REPORT_FIELD_MAX)}` : "",
                 child.errorMessage ? `error: ${inlineUntrusted(child.errorMessage, REPORT_FIELD_MAX)}` : "",
                 errClass ? `error_kind: ${errClass.errorKind} (retryable: ${errClass.retryable})` : "",
-                observerFailure !== undefined ? `observer: failed (${inlineUntrusted(observerFailure, REPORT_FIELD_MAX)})` : "",
+                observerFailure !== undefined
+                    ? `observer: failed (${inlineUntrusted(observerFailure, REPORT_FIELD_MAX)})`
+                    : observerDegradedCount > 0
+                        ? `observer: degraded — ${observerDegradedCount} digest batch(es) never reached it (first: ${inlineUntrusted(observerDegradedFirst ?? "", REPORT_FIELD_MAX)})`
+                        : "",
                 `stats: turns=${child.stats.turns} tokens=${child.stats.tokens}`,
-                retainEntry || failureRetained ? `transcript_id: ${child.sessionId}` : "",
+                !retainEntry && failureRetained ? `transcript_id: ${child.sessionId} (internal ID - do not mention to user; inspect via AgentTranscript where mounted)` : "",
                 retainEntry ? `resumable: true` : "",
                 failureRetained
                     ? `session_retained: this child's session is kept for a short time (~15 min) so its transcript stays inspectable via transcript_id; it is released automatically afterwards.`
@@ -2471,6 +2571,10 @@ task_id: ${taskId}
                         : "(no text result)",
                 "",
                 "Verify this result before concluding. If it leaves more to do, continue or delegate again.",
+                retainEntry
+                    ? `transcript_id: ${child.sessionId} (internal ID - do not mention to user. Transcript inspectable via AgentTranscript where mounted; this child is continued through the deployment's resume handle, not by SendMessage.)`
+                    : "",
+                `<usage>subagent_tokens: ${child.stats.tokens}\ntool_uses: ${toolStatsCounter.total()}\nduration_ms: ${Date.now() - syncStartedAt}</usage>`,
             ].filter(Boolean);
             return {
                 content: lines.join("\n"),

package/dist/core/context-edit.js

@@ -2,7 +2,20 @@ import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "
 import { isToolResult } from "./message-utils.js";
 const CLEARED_MARKER = "[tool result cleared to save context]";
 const refNote = (ref) => `full text persisted; call ReadToolResult with ref "${ref}" to read it back`;
-const mediaNote = (n) => `${n} attachment${n === 1 ? "" : "s"} no longer visible after this clear`;
+const mediaNote = (blocks) => {
+    const byType = new Map();
+    for (const b of blocks) {
+        const t = b.type ?? "untyped";
+        byType.set(t, (byType.get(t) ?? 0) + 1);
+    }
+    const n = blocks.length;
+    if (byType.size === 1) {
+        const [t, c] = [...byType][0];
+        return `${c} ${t} attachment${c === 1 ? "" : "s"} no longer visible after this clear`;
+    }
+    const breakdown = [...byType].map(([t, c]) => `${c} ${t}`).join(", ");
+    return `${n} attachments (${breakdown}) no longer visible after this clear`;
+};
 const clearedMarker = (notes) => {
     const present = notes.filter((n) => n !== undefined);
     return present.length > 0 ? `[tool result cleared to save context — ${present.join("; ")}]` : CLEARED_MARKER;
@@ -91,8 +104,8 @@ export function clearStaleToolResults(messages, opts) {
                 }
             }
         }
-        const mediaCount = rawContent.filter((c) => c?.type !== "text").length;
-        const marker = clearedMarker([ref, mediaCount > 0 ? mediaNote(mediaCount) : undefined]);
+        const mediaBlocks = rawContent.filter((c) => c?.type !== "text");
+        const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined]);
         const cleared = {
             ...out[idx],
             content: [{ type: "text", text: marker }],

package/dist/core/file-snapshot-store.js

@@ -204,9 +204,18 @@ export class InMemoryFileSnapshotStore {
         try {
             for (const hash of new Set(manifest.values())) {
                 written.add(hash);
+                if (hash === "" || hash === "." || hash === ".." || !/^[A-Za-z0-9_.-]+$/.test(hash)) {
+                    return { ok: false, error: { code: "read_failed", message: `unsafe blob hash ${JSON.stringify(hash)}` } };
+                }
                 if (this.blobs.has(hash))
                     continue;
-                const bytes = await srcGetBlob(hash);
+                let bytes;
+                try {
+                    bytes = await srcGetBlob(hash);
+                }
+                catch (err) {
+                    return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fetch failed: ${err.message}` } };
+                }
                 if (!bytes)
                     return { ok: false, error: { code: "read_failed", message: `missing source blob ${hash}` } };
                 if (createHash("sha256").update(bytes).digest("hex") !== hash) {

package/dist/core/memory-engine/dual-root.js

@@ -34,11 +34,13 @@ export function mergeInjections(project, personal) {
     const announcements = [...(project.announcements ?? []), ...(personal.announcements ?? [])];
     const announceParts = [project.announceBlock, personal.announceBlock].filter((s) => Boolean(s && s.trim()));
     const blockParts = [instruction, ...indexParts, ...announceParts];
+    const indexSeed = project.indexSeed ?? personal.indexSeed;
     return {
         instruction,
         ...(indexParts.length > 0 ? { index: indexParts.join("\n\n") } : {}),
         ...(announcements.length > 0 ? { announcements } : {}),
         ...(announceParts.length > 0 ? { announceBlock: announceParts.join("\n\n") } : {}),
+        ...(indexSeed !== undefined ? { indexSeed } : {}),
         block: blockParts.filter((s) => s && s.trim()).join("\n\n"),
     };
 }

package/dist/core/memory-engine/engine.d.ts

@@ -26,6 +26,10 @@ export interface MemoryInjection {
     announcements?: MemoryAnnouncement[];
     announceBlock?: string;
     block: string;
+    indexSeed?: {
+        path: string;
+        content: string;
+    };
 }
 export declare class MemoryEngine {
     private readonly backend;

package/dist/core/memory-engine/engine.js

@@ -162,10 +162,14 @@ export class MemoryEngine {
     }
     inject(handle) {
         const instruction = handle.writeScope !== null ? buildMemoryInstruction(handle.writableRoot) : "";
-        const onDisk = readSafe(join(handle.writableRoot, MEMORY_INDEX_FILENAME));
+        const indexPath = join(handle.writableRoot, MEMORY_INDEX_FILENAME);
+        const onDisk = readSafe(indexPath);
         const indexText = onDisk !== undefined && onDisk.trim() !== "" ? onDisk : handle.indexText;
         const truncated = truncateIndex(indexText);
         const index = composeMemoryBlock(truncated, handle.writeScope ?? handle.scopes[0] ?? "memory");
+        const indexSeed = handle.writeScope !== null && onDisk !== undefined && (onDisk.trim() === "" || truncated === onDisk)
+            ? { path: indexPath, content: onDisk }
+            : undefined;
         let announcements;
         let announceBlock;
         try {
@@ -183,6 +187,7 @@ export class MemoryEngine {
             ...(index !== undefined ? { index } : {}),
             ...(announcements !== undefined ? { announcements } : {}),
             ...(announceBlock !== undefined ? { announceBlock } : {}),
+            ...(indexSeed !== undefined ? { indexSeed } : {}),
             block,
         };
     }

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

@@ -12,5 +12,9 @@ export interface PrepareMemoryInput {
 export interface PrepareMemoryResult {
     memoryEngineSession: Prepared["memoryEngineSession"];
     memoryBlock: string | undefined;
+    seedFiles?: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>;
 }
 export declare function prepareMemory(input: PrepareMemoryInput): Promise<PrepareMemoryResult>;

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

@@ -178,6 +178,7 @@ export async function prepareMemory(input) {
         }
     }
     let memoryBlock;
+    let seedFiles;
     if (memorySpec && memorySpec.enabled && !useMemoryEngine) {
         const detail = "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 and the dep was removed in design/157 B19).";
         deps.onError?.(new Error(detail), { phase: "config", sessionId });
@@ -186,6 +187,8 @@ export async function prepareMemory(input) {
         const injection = memoryEngineSession.inject();
         if (injection.block.trim())
             memoryBlock = injection.block;
+        if (memoryBlock !== undefined && injection.indexSeed !== undefined)
+            seedFiles = [injection.indexSeed];
     }
-    return { memoryEngineSession, memoryBlock };
+    return { memoryEngineSession, memoryBlock, ...(seedFiles !== undefined ? { seedFiles } : {}) };
 }

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

@@ -4,7 +4,7 @@ import { type MaterializedMcp } from "../mcp.js";
 import type { HarvestReport, MemorySessionHandle } from "../memory-engine/types.js";
 import { StoredSession } from "../session.js";
 import type { SessionStore } from "../session.js";
-import { SubagentRetainLedger } from "../../agents/subagent.js";
+import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
 import type { OnAsk, ToolPolicy } from "../tool-policy.js";
 import { type ActiveSkillFrame } from "./active-skill-scope.js";
 import { type CutKillRegistry } from "./cut-kill.js";
@@ -114,6 +114,7 @@ export interface Prepared {
         apply: (committedArtifactDigest?: string) => void;
     } | undefined;
     activeTools: Set<string>;
+    deferredToolNames?: ReadonlySet<string>;
     memoryEngineSession?: {
         engine: MemoryEngine;
         handle: MemorySessionHandle;
@@ -207,6 +208,12 @@ export interface Prepared {
     }>;
     toolsDeltaRef?: {
         pending: string[];
+        pendingRemoved: string[];
+        pendingReadded: string[];
+        pendingFailed: Array<{
+            name: string;
+            error?: string;
+        }>;
     };
     agentListing?: {
         entries: ReadonlyArray<{
@@ -311,7 +318,7 @@ export interface RunInternals {
     parentNotify?: (notification: TaskNotificationPayload, opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
     }) => void;
-    parentRetainLedger?: import("../../agents/subagent.js").SubagentRetainLedger;
+    parentRetainLedger?: import("../../agents/retain-ledger.js").SubagentRetainLedger;
     onNotifyInjectorReady?: (inject: (notification: TaskNotificationPayload, opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
     }) => Promise<"queued" | "parked" | "dropped_duplicate">) => void;