@sema-agent/core 2.0.1 → 2.1.0

package/dist/agents/observer.js

@@ -157,10 +157,15 @@ export class ObserverDigestTap {
                     this.flushText();
                     this.pending.push({ type: "tool_result", content: truncateDigestPayload(digestTextOf(e.output)) });
                     return;
-                case "steering_injected":
+                case "steering_injected": {
                     this.flushText();
-                    this.pending.push({ type: "user_message", text: e.message ?? "(steering)" });
+                    const injected = e.preview.trim();
+                    this.pending.push({
+                        type: "user_message",
+                        text: injected ? `[injected: ${e.source}]\n${injected}` : `[injected: ${e.source}] (empty preview)`,
+                    });
                     return;
+                }
                 case "turn_end":
                     this.flushSegment();
                     return;
@@ -326,7 +331,7 @@ export function createObserverReportToolSpec(opts) {
         name: OBSERVER_REPORT_TOOL_NAME,
         contract: { contractId: "core.observer_report@1", implementationRevision: "1" },
         description: OBSERVER_REPORT_DESCRIPTION,
-        effect: "idempotent",
+        effect: "write",
         parameters: Type.Object({
             report: Type.String({
                 minLength: 1,

package/dist/agents/send-message-tool.js

@@ -2,13 +2,34 @@ import { Type } from "typebox";
 import { defineTool } from "../core/tools.js";
 import { normalizeAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
 import { canAccessAgentRecord } from "../core/background-agent-store.js";
-import { isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
+import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
 export const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 let uplinkSeqGlobal = Date.now();
 const UPLINK_RESULT_MAX = 8000;
+const TEAMMATE_MESSAGE_TAG = "teammate-message";
+function frameTeammateMessage(args) {
+    const summaryAttr = args.summary !== undefined ? ` summary="${escapeAttributeValue(args.summary)}"` : "";
+    const body = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, args.text);
+    return `<${TEAMMATE_MESSAGE_TAG} teammate_id="${escapeAttributeValue(args.from)}"${summaryAttr}>\n${body}\n</${TEAMMATE_MESSAGE_TAG}>`;
+}
 const REVIVE_LEASE_TTL_MS = 5 * 60_000;
+const sendMessageTargetLanes = new Map();
+function withTargetLane(key, fn) {
+    const prev = sendMessageTargetLanes.get(key) ?? Promise.resolve();
+    const run = prev.then(fn, fn);
+    const tail = run.then(() => undefined, () => undefined);
+    sendMessageTargetLanes.set(key, tail);
+    void tail.then(() => {
+        if (sendMessageTargetLanes.get(key) === tail)
+            sendMessageTargetLanes.delete(key);
+    });
+    return run;
+}
+function targetLaneKey(scope, targetId) {
+    return JSON.stringify([scope ?? "", targetId]);
+}
 export function createSendMessageTool(opts) {
     const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
     return defineTool({
@@ -244,7 +265,9 @@ export function createSendMessageTool(opts) {
                             details: { error: "mailbox_leased", to },
                         };
                     }
-                    const revivePrompt = lease.messages.map((m) => `<teammate-message teammate_id="${m.from ?? "main"}">\n${m.content}\n</teammate-message>`).join("\n");
+                    const revivePrompt = lease.messages
+                        .map((m) => frameTeammateMessage({ from: m.from ?? "main", text: m.content }))
+                        .join("\n");
                     let spawned;
                     try {
                         spawned = await opts.reviveSpawn({ row: claimed, rev: claimedRev, prompt: revivePrompt });
@@ -354,40 +377,45 @@ export function createSendMessageTool(opts) {
                 return { content: `Message not sent: ${targetId} is a ${row.type} task, not a background agent.`, details: { error: "wrong_type", to }, isError: true };
             }
             if (row.status === "running" || row.status === "pending") {
-                const s2Summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
-                const fromLabel = opts.senderName ?? senderId ?? "main";
-                const teammateXml = `<teammate-message teammate_id="${fromLabel}"${s2Summary !== undefined ? ` summary=${JSON.stringify(s2Summary)}` : ""}>\n${message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${message.length} chars total]` : message}\n</teammate-message>`;
-                const delivered = await opts.registry.deliverToRunningAgent(targetId, resolvedAccess, {
-                    task_id: senderId ?? "main",
-                    task_type: "background_agent",
-                    status: "event",
-                    summary: `message from ${fromLabel}${s2Summary !== undefined ? `: ${s2Summary}` : ""}`,
-                    result: teammateXml,
-                    seq: ++uplinkSeqGlobal,
-                }, { priority: "next" });
-                if (delivered.ok) {
-                    const receiptText = delivered.disposition === "parked"
-                        ? `Message parked for ${who}: the agent finished before reading it — it will be delivered when the agent is next continued. You will be notified of its completion; continue with other work.`
-                        : delivered.disposition === "pending"
-                            ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. You will be notified of the agent's completion either way; resend then if it went unanswered.`
-                            : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — you will be notified of its completion either way; resend then if it went unanswered. Continue with other work; do not poll.`;
-                    return {
-                        content: receiptText,
-                        details: { type: "send-message", status: "delivered_running", disposition: delivered.disposition, to, task_id: targetId, ...(s2Summary !== undefined ? { summary: s2Summary } : {}) },
-                    };
-                }
-                if (delivered.reason === "no_channel") {
+                return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
+                    const s2Summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
+                    const fromLabel = opts.senderName ?? senderId ?? "main";
+                    const s2Clipped = message.length > UPLINK_RESULT_MAX
+                        ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${message.length} chars total]`
+                        : message;
+                    const teammateXml = frameTeammateMessage({ from: fromLabel, ...(s2Summary !== undefined ? { summary: s2Summary } : {}), text: s2Clipped });
+                    const delivered = await opts.registry.deliverToRunningAgent(targetId, resolvedAccess, {
+                        task_id: senderId ?? "main",
+                        task_type: "background_agent",
+                        status: "event",
+                        summary: `message from ${fromLabel}${s2Summary !== undefined ? `: ${s2Summary}` : ""}`,
+                        result: teammateXml,
+                        seq: ++uplinkSeqGlobal,
+                    }, { priority: "next" });
+                    if (delivered.ok) {
+                        const receiptText = delivered.disposition === "parked"
+                            ? `Message parked for ${who}: the agent finished before reading it — it will be delivered when the agent is next continued. You will be notified of its completion; continue with other work.`
+                            : delivered.disposition === "pending"
+                                ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. You will be notified of the agent's completion either way; resend then if it went unanswered.`
+                                : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — you will be notified of its completion either way; resend then if it went unanswered. Continue with other work; do not poll.`;
+                        return {
+                            content: receiptText,
+                            details: { type: "send-message", status: "delivered_running", disposition: delivered.disposition, to, task_id: targetId, ...(s2Summary !== undefined ? { summary: s2Summary } : {}) },
+                        };
+                    }
+                    if (delivered.reason === "no_channel") {
+                        return {
+                            content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it.`,
+                            details: { error: "still_running", to },
+                            isError: true,
+                        };
+                    }
                     return {
-                        content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it.`,
-                        details: { error: "still_running", to },
+                        content: `Message not sent: ${who} just finished (delivery raced its completion). Send again to continue it from its transcript.`,
+                        details: { error: "settle_race", to },
                         isError: true,
                     };
-                }
-                return {
-                    content: `Message not sent: ${who} just finished (delivery raced its completion). Send again to continue it from its transcript.`,
-                    details: { error: "settle_race", to },
-                    isError: true,
-                };
+                });
             }
             if (row.status === "killed") {
                 const by = opts.registry.getStopAttribution(targetId);
@@ -409,61 +437,64 @@ export function createSendMessageTool(opts) {
                     return revived;
             }
             const ledger = (knows(sessionLedger) ? sessionLedger : undefined) ?? (knows(runLedger) ? runLedger : undefined) ?? (knows(siblingLedger) ? siblingLedger : undefined) ?? runLedger ?? sessionLedger ?? siblingLedger;
-            if (!ledger || row.toolUseId === undefined) {
+            const resumeToolUseId = row.toolUseId;
+            if (!ledger || resumeToolUseId === undefined) {
                 return {
                     content: `Message not sent: ${who}'s session was not retained (this run did not enable retainSubagentSessions), so it cannot be continued — relaunch a new agent with the needed context instead.`,
                     details: { error: "not_retained", to },
                     isError: true,
                 };
             }
-            const resume = createSubagentResume({
-                ledger,
-                parentToolCallId: row.toolUseId,
-                runner: opts.runner,
-                ...(opts.notify ? { notify: opts.notify } : {}),
-                ...(opts.sink ? { sink: opts.sink } : {}),
-                registry: opts.registry,
-                taskId: targetId,
-                taskAccess: resolvedAccess,
-                ...((ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent) ? { bgSink: ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent } : {}),
-                sessionScoped: row.sessionScoped === true,
-                ...(row.description !== undefined ? { rowDescription: row.description } : {}),
-                ...(row.name !== undefined ? { rowName: row.name } : {}),
-                ...(row.agentType !== undefined ? { rowAgentType: row.agentType } : {}),
-                ...(row.owner !== undefined ? { rowOwner: row.owner } : {}),
-                ...(row.scope !== undefined ? { rowScope: row.scope } : {}),
-                ...(row.parentTaskId !== undefined ? { rowParentTaskId: row.parentTaskId } : {}),
-                ...(row.parentSessionId !== undefined ? { rowParentSessionId: row.parentSessionId } : {}),
-                ...(row.rootSessionId !== undefined ? { rowRootSessionId: row.rootSessionId } : {}),
-                ...(opts.notify ? { currentParentNotify: opts.notify } : {}),
+            return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
+                const resume = createSubagentResume({
+                    ledger,
+                    parentToolCallId: resumeToolUseId,
+                    runner: opts.runner,
+                    ...(opts.notify ? { notify: opts.notify } : {}),
+                    ...(opts.sink ? { sink: opts.sink } : {}),
+                    registry: opts.registry,
+                    taskId: targetId,
+                    taskAccess: resolvedAccess,
+                    ...((ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent) ? { bgSink: ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent } : {}),
+                    sessionScoped: row.sessionScoped === true,
+                    ...(row.description !== undefined ? { rowDescription: row.description } : {}),
+                    ...(row.name !== undefined ? { rowName: row.name } : {}),
+                    ...(row.agentType !== undefined ? { rowAgentType: row.agentType } : {}),
+                    ...(row.owner !== undefined ? { rowOwner: row.owner } : {}),
+                    ...(row.scope !== undefined ? { rowScope: row.scope } : {}),
+                    ...(row.parentTaskId !== undefined ? { rowParentTaskId: row.parentTaskId } : {}),
+                    ...(row.parentSessionId !== undefined ? { rowParentSessionId: row.parentSessionId } : {}),
+                    ...(row.rootSessionId !== undefined ? { rowRootSessionId: row.rootSessionId } : {}),
+                    ...(opts.notify ? { currentParentNotify: opts.notify } : {}),
+                });
+                const summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
+                const fromPrefix = ctx.parentTaskId !== undefined ? `(message from teammate "${opts.senderName ?? senderId ?? "unknown"}")\n` : "";
+                try {
+                    const marker = await resume(`${fromPrefix}${summary ? `[${summary}] ${message}` : message}`);
+                    return {
+                        content: `Message sent — ${who} resumed in the background with its prior context intact (correlation marker [${marker}]).\n` +
+                            `You will be notified automatically when it completes; its reply will carry [${marker}]. Continue with other work — do not poll.`,
+                        details: { type: "send-message", status: "resumed", to, task_id: targetId, marker, ...(summary !== undefined ? { summary } : {}) },
+                    };
+                }
+                catch (e) {
+                    const code = e?.code;
+                    const text = code === "resume.retain_off"
+                        ? `${who}'s session was not retained (retainSubagentSessions is off) — relaunch a new agent instead.`
+                        : code === "resume.evicted"
+                            ? `${who}'s retained session was evicted (retain TTL / capacity / parent run ended) — relaunch a new agent instead.`
+                            : code === "resume.session_not_found"
+                                ? `${who}'s session no longer exists — relaunch a new agent instead.`
+                                : code === "resume.cap"
+                                    ? `${who} reached its resume cap (${SUBAGENT_RESUME_CAP} follow-ups per agent) — relaunch a new agent instead.`
+                                    : code === "steering.still_running"
+                                        ? `${who} (or a prior follow-up to it) is still running — wait for its completion notification.`
+                                        : code === "resume.row_gone"
+                                            ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
+                                            : `${e instanceof Error ? e.message : String(e)}`;
+                    return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to }, isError: true };
+                }
             });
-            const summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
-            const fromPrefix = ctx.parentTaskId !== undefined ? `(message from teammate "${opts.senderName ?? senderId ?? "unknown"}")\n` : "";
-            try {
-                const marker = await resume(`${fromPrefix}${summary ? `[${summary}] ${message}` : message}`);
-                return {
-                    content: `Message sent — ${who} resumed in the background with its prior context intact (correlation marker [${marker}]).\n` +
-                        `You will be notified automatically when it completes; its reply will carry [${marker}]. Continue with other work — do not poll.`,
-                    details: { type: "send-message", status: "resumed", to, task_id: targetId, marker, ...(summary !== undefined ? { summary } : {}) },
-                };
-            }
-            catch (e) {
-                const code = e?.code;
-                const text = code === "resume.retain_off"
-                    ? `${who}'s session was not retained (retainSubagentSessions is off) — relaunch a new agent instead.`
-                    : code === "resume.evicted"
-                        ? `${who}'s retained session was evicted (retain TTL / capacity / parent run ended) — relaunch a new agent instead.`
-                        : code === "resume.session_not_found"
-                            ? `${who}'s session no longer exists — relaunch a new agent instead.`
-                            : code === "resume.cap"
-                                ? `${who} reached its resume cap (${SUBAGENT_RESUME_CAP} follow-ups per agent) — relaunch a new agent instead.`
-                                : code === "steering.still_running"
-                                    ? `${who} (or a prior follow-up to it) is still running — wait for its completion notification.`
-                                    : code === "resume.row_gone"
-                                        ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
-                                        : `${e instanceof Error ? e.message : String(e)}`;
-                return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to }, isError: true };
-            }
         },
     });
 }

package/dist/agents/subagent.d.ts

@@ -5,16 +5,14 @@ import type { RunInternals } from "../core/runner/prepare-task.js";
 import type { TaskNotificationPayload } from "../core/task-notification.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 { SubagentRetainLedger, getSessionRetainLedger, releaseSessionRetainLedger, type SubagentRetainEntry } from "./retain-ledger.js";
-export { SubagentRetainLedger, getSessionRetainLedger, releaseSessionRetainLedger, type SubagentRetainEntry };
-export { AGENT_TRANSCRIPT_TOOL_NAME, createAgentTranscriptTool, type AgentTranscriptToolOptions } from "./agent-transcript-tool.js";
-export { SEND_MESSAGE_TOOL_NAME, createSendMessageTool, type SendMessageToolOptions } from "./send-message-tool.js";
+import { SubagentRetainLedger } from "./retain-ledger.js";
 export type { SubagentStep, SubagentEditedFile } from "./subagent-steps.js";
 export declare function notifyResultField(result: string | undefined): string | undefined;
 export declare function inheritedManifestScopeFor(snapshot: readonly unknown[] | undefined): RunInternals["inheritedManifestScope"];
 export declare const DEFAULT_SUBAGENT_TOOL_NAME = "Agent";
 export declare const LEGACY_SUBAGENT_TOOL_NAME = "Task";
 export declare const EXTRA_TOOLS_MAX_FACTORY_CALLS_PER_TREE = 64;
+export declare const DEFAULT_SUBAGENT_MAX_DEPTH = 3;
 export declare const EXTRA_TOOLS_FAILED_NOTE = "note: extraTools evaluation failed \u2014 the injected tool set was skipped for this spawn.";
 export declare const EXTRA_TOOLS_BUDGET_NOTE = "note: extraTools evaluation was skipped \u2014 this spawn tree exhausted its factory-call budget (64); no dynamic tools were injected for this spawn.";
 export interface SubagentToolStats {
@@ -127,8 +125,16 @@ export interface SubagentSpawnContext {
     agentType?: string;
     depth: number;
 }
+export declare function normalizeSubagentType(value: string): string;
 export declare const SUBAGENT_SYSTEM_NOTE: string;
 export declare const FORK_DIRECTIVE_FRAME = "<fork-boilerplate>\nYou are a worker fork. The transcript above is the parent's history \u2014 inherited reference, not your situation. You are NOT a continuation of that agent. Execute ONE directive, then stop.\n\nHard rules:\n- Do NOT spawn subagents with the Agent tool. The \"default to forking\" guidance is for the parent; you ARE the fork, execute directly.\n- One shot: report once and stop. No follow-up questions, no proposed next steps, no waiting for the user.\n\nGuidelines (your directive may override any of these):\n- Stay in scope. Other forks may be handling adjacent work; if you spot something outside your directive, note it in a sentence and move on.\n- Open with one line restating your task, so the parent can spot scope drift at a glance.\n- Be concise \u2014 as short as the answer allows, no shorter. Plain text, no preamble, no meta-commentary.\n- If you committed changes, list the paths and commit hashes in your report.\n</fork-boilerplate>\n\nYour directive: ";
+export declare function forkWorktreeTranslationNote(parentCwd: string | undefined, worktreeDir: string): string;
+export declare function asyncLaunchedReceipt(p: {
+    taskId: string;
+    workingLine: string;
+    notify: boolean;
+    notes?: (string | undefined)[];
+}): string;
 export declare function createSubagentTool(opts: SubagentToolOptions): ToolSpec;
 export declare function agentToolsNote(def: {
     allowTools?: string[];

package/dist/agents/subagent.js

@@ -19,10 +19,7 @@ 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 { SubagentStepRecorder } from "./subagent-steps.js";
@@ -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) {
@@ -580,6 +578,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 +612,26 @@ 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 !== "");
+    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` +
+        (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("") +
+        (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 +704,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 +721,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 +849,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) {
@@ -1074,19 +1119,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();
                 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) => ({
@@ -1125,7 +1182,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)
@@ -1440,7 +1497,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 +1732,21 @@ 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),
+                            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,25 +2362,21 @@ 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),
+                        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 },
                 };
             }

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>;