@sema-agent/core 2.1.0 → 2.2.0

package/dist/agents/observer.d.ts

@@ -68,6 +68,15 @@ export declare class ObserverDigestTap {
     finish(reason: string): void;
 }
 export type ObserverPairingState = "armed" | "denied" | "stopped" | "retired" | "blocked";
+export declare const OBSERVER_STOPPED_BY_USER_ERROR_NAME = "AgentStoppedByUserError";
+export declare const OBSERVER_RESUME_STATE_ERROR_NAME = "ResumeAgentStateError";
+export declare class ObserverStoppedByUserError extends Error {
+    constructor(message: string);
+}
+export declare class ObserverResumeStateError extends Error {
+    constructor(message: string);
+}
+export declare const OBSERVER_FRESH_START_NOTE = "[Note: your previous observation context was lost; this is a fresh start mid-task.]";
 export interface ObserverSpawner {
     spawnFirstRun(args: {
         framingPrompt: string;
@@ -76,6 +85,10 @@ export interface ObserverSpawner {
     deliver(args: {
         digest: string;
     }): Promise<void>;
+    restartFresh?(args: {
+        framingPrompt: string;
+        digest: string;
+    }): Promise<void>;
 }
 export declare class ObserverPairing {
     state: ObserverPairingState;
@@ -102,6 +115,7 @@ export declare class ObserverPairing {
     private safeOnError;
     drain(): Promise<void>;
     private pump;
+    private deliverBatch;
     retire(state: Exclude<ObserverPairingState, "armed">): void;
 }
 export declare function markObserverTaskId(taskId: string): void;

package/dist/agents/observer.js

@@ -209,6 +209,24 @@ export class ObserverDigestTap {
         this.safeFlush(slice);
     }
 }
+export const OBSERVER_STOPPED_BY_USER_ERROR_NAME = "AgentStoppedByUserError";
+export const OBSERVER_RESUME_STATE_ERROR_NAME = "ResumeAgentStateError";
+export class ObserverStoppedByUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = OBSERVER_STOPPED_BY_USER_ERROR_NAME;
+    }
+}
+export class ObserverResumeStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = OBSERVER_RESUME_STATE_ERROR_NAME;
+    }
+}
+function errorName(err) {
+    return err instanceof Error ? err.name : undefined;
+}
+export const OBSERVER_FRESH_START_NOTE = "[Note: your previous observation context was lost; this is a fresh start mid-task.]";
 export class ObserverPairing {
     state = "armed";
     observedEnvelopeName;
@@ -278,18 +296,22 @@ export class ObserverPairing {
                 const batch = this.buffer.splice(0, this.buffer.length);
                 try {
                     const digest = renderObserverDigestBatch(this, batch);
-                    if (!this.firstRunDone) {
-                        await this.spawner.spawnFirstRun({ framingPrompt: this.framingPrompt, digest });
-                        this.firstRunDone = true;
-                    }
-                    else {
-                        await this.spawner.deliver({ digest });
-                    }
+                    await this.deliverBatch(digest);
                 }
                 catch (err) {
-                    this.state = "stopped";
-                    this.buffer = [];
+                    if (errorName(err) === OBSERVER_STOPPED_BY_USER_ERROR_NAME) {
+                        this.state = "stopped";
+                        this.buffer = [];
+                        this.safeOnError(err);
+                        return;
+                    }
                     this.safeOnError(err);
+                    if (this.buffer.length > 0) {
+                        const strandedCount = this.buffer.length;
+                        this.buffer = [];
+                        this.safeOnError(new Error(`observer delivery: ${strandedCount} segment(s) enqueued mid-fault were stranded and dropped (never attempted) after: ${err instanceof Error ? err.message : String(err)}`));
+                    }
+                    return;
                 }
             }
         }
@@ -297,6 +319,33 @@ export class ObserverPairing {
             this.delivering = false;
         }
     }
+    async deliverBatch(digest) {
+        if (!this.firstRunDone) {
+            await this.spawner.spawnFirstRun({ framingPrompt: this.framingPrompt, digest });
+            this.firstRunDone = true;
+            return;
+        }
+        try {
+            await this.spawner.deliver({ digest });
+        }
+        catch (err) {
+            if (errorName(err) !== OBSERVER_RESUME_STATE_ERROR_NAME)
+                throw err;
+            const restart = this.spawner.restartFresh?.bind(this.spawner);
+            if (restart === undefined)
+                throw err;
+            try {
+                await restart({ framingPrompt: `${this.framingPrompt}\n\n${OBSERVER_FRESH_START_NOTE}`, digest });
+                this.firstRunDone = true;
+            }
+            catch (restartErr) {
+                this.firstRunDone = false;
+                throw restartErr instanceof Error
+                    ? new Error(`${restartErr.message} (after resume-state loss: ${err instanceof Error ? err.message : String(err)})`, { cause: restartErr })
+                    : restartErr;
+            }
+        }
+    }
     retire(state) {
         if (this.state !== "armed")
             return;

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

@@ -37,6 +37,7 @@ export function createSendMessageTool(opts) {
         contract: { contractId: "core.send_message@1", implementationRevision: "1" },
         executionMode: "parallel",
         description: `Send a follow-up message to a previously spawned background agent. ` +
+            `Your plain text output is NOT visible to other agents — to communicate, you MUST call this tool. Messages addressed to you are delivered automatically; you don't check an inbox. ` +
             `'to' is the agent's name (set at spawn via Agent({name})) or its task_id (a…). A RUNNING agent receives the ` +
             `message at its next turn (queued — never interrupts its current work); a FINISHED agent resumes as a new ` +
             `background run with its full prior conversation preserved, so don't re-explain what it already knows. Names ` +
@@ -50,7 +51,7 @@ export function createSendMessageTool(opts) {
         parameters: Type.Object({
             to: Type.String({ description: 'Recipient: the agent\'s name, or its task_id (a…) returned by the Agent tool with run_in_background. "main" is reserved for the spawning conversation.' }),
             message: Type.String({ description: "The follow-up request. The agent continues from its full prior context." }),
-            summary: Type.Optional(Type.String({ maxLength: 200, description: "A short (3-5 word) description of the follow-up." })),
+            summary: Type.Optional(Type.String({ maxLength: 200, description: "A 5-10 word summary shown as a preview in the UI (required when message is a string)" })),
         }),
         execute: async (args, ctx) => {
             const a = args;
@@ -60,6 +61,28 @@ export function createSendMessageTool(opts) {
                 return { content: "Message not sent: 'to' was empty. Pass the agent's task_id (a…).", details: { error: "empty to" }, isError: true };
             if (!message)
                 return { content: "Message not sent: 'message' was empty.", details: { error: "empty message" }, isError: true };
+            if (to === "*") {
+                return {
+                    content: 'Message not sent: broadcast (to: "*") is no longer supported — send a message per recipient.',
+                    details: { error: "broadcast_unsupported", to },
+                    isError: true,
+                };
+            }
+            if (to.includes("@")) {
+                return {
+                    content: "Message not sent: to must be a bare teammate name — there is only one team per session.",
+                    details: { error: "qualified_name_unsupported", to },
+                    isError: true,
+                };
+            }
+            const summaryArg = typeof a.summary === "string" ? a.summary.trim() : "";
+            if (summaryArg === "") {
+                return {
+                    content: "Message not sent: summary is required when message is a string — pass a 5-10 word summary of the follow-up.",
+                    details: { error: "summary_required", to },
+                    isError: true,
+                };
+            }
             const senderId = ctx.taskId ?? opts.owner;
             if (senderId !== undefined && isObserverTaskId(senderId)) {
                 return { content: OBSERVER_SENDMESSAGE_SENDER_REFUSAL, details: { error: "observer_sender" }, isError: true };
@@ -89,6 +112,17 @@ export function createSendMessageTool(opts) {
                         details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeqGlobal },
                     };
                 }
+                const hasParent = ctx.parentTaskId !== undefined ||
+                    opts.uplink !== undefined ||
+                    opts.senderName !== undefined ||
+                    opts.siblingRetain !== undefined;
+                if (!hasParent) {
+                    return {
+                        content: `You are the main conversation — "main" addresses you. Send to a named agent instead.`,
+                        details: { error: "main_is_self", to },
+                        isError: true,
+                    };
+                }
                 return {
                     content: `Message not sent: "main" (the spawning conversation) is not a deliverable target here. ` +
                         `Your completion is reported to it automatically — finish your task and your final report will be relayed.`,
@@ -126,10 +160,10 @@ export function createSendMessageTool(opts) {
                 if (row.name === undefined || row.agentType === "fork")
                     return undefined;
                 const whoT3 = handle === to ? `agent ${handle}` : `agent "${to}" (${handle})`;
-                if (row.status === "killed") {
+                if (row.status === "killed" && row.stoppedBy === "user") {
                     return {
-                        content: `Message not sent: ${whoT3} was stopped${row.stoppedBy !== undefined ? ` (by ${row.stoppedBy})` : ""} — a stopped agent is not revived. Launch a new agent with the needed context instead.`,
-                        details: { error: "killed", to, ...(row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}) },
+                        content: `Message not sent: ${whoT3} was stopped by the user and was not resumed. Treat its work as cancelled; only start a new agent for it if the user explicitly asks.`,
+                        details: { error: "killed", to, stoppedBy: row.stoppedBy },
                         isError: true,
                     };
                 }
@@ -419,11 +453,13 @@ export function createSendMessageTool(opts) {
             }
             if (row.status === "killed") {
                 const by = opts.registry.getStopAttribution(targetId);
-                return {
-                    content: `Message not sent: ${who} was stopped${by ? ` (by ${by})` : ""} — a stopped agent is not resumable. Launch a new agent with the needed context instead.`,
-                    details: { error: "killed", to, ...(by !== undefined ? { stoppedBy: by } : {}) },
-                    isError: true,
-                };
+                if (by === "user") {
+                    return {
+                        content: `Message not sent: ${who} was stopped by the user and was not resumed. Treat its work as cancelled; only start a new agent for it if the user explicitly asks.`,
+                        details: { error: "killed", to, stoppedBy: by },
+                        isError: true,
+                    };
+                }
             }
             const runLedger = ctx.subagentRetain ?? opts.retain;
             const smLedgerSessionId = ctx.sessionId ?? opts.sessionId;
@@ -445,6 +481,13 @@ export function createSendMessageTool(opts) {
                     isError: true,
                 };
             }
+            if (ledger.get(resumeToolUseId)?.running === true) {
+                return {
+                    content: `Message not sent: ${who} (or a prior follow-up to it) is still running — wait for its completion notification.`,
+                    details: { error: "steering.still_running", to },
+                    isError: true,
+                };
+            }
             return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
                 const resume = createSubagentResume({
                     ledger,
@@ -470,7 +513,9 @@ export function createSendMessageTool(opts) {
                 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}`);
+                    const safeSummary = summary !== undefined ? escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, summary) : undefined;
+                    const safeMessage = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, message);
+                    const marker = await resume(`${fromPrefix}${safeSummary ? `[${safeSummary}] ${safeMessage}` : safeMessage}`);
                     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.`,

package/dist/agents/subagent.d.ts

@@ -133,6 +133,7 @@ export declare function asyncLaunchedReceipt(p: {
     taskId: string;
     workingLine: string;
     notify: boolean;
+    oneShot?: boolean;
     notes?: (string | undefined)[];
 }): string;
 export declare function createSubagentTool(opts: SubagentToolOptions): ToolSpec;

package/dist/agents/subagent.js

@@ -21,7 +21,7 @@ import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_
 export { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 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;
@@ -129,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";
@@ -622,15 +625,20 @@ export function forkWorktreeTranslationNote(parentCwd, worktreeDir) {
 }
 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` +
-        (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`) +
+        (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("") +
-        (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.`));
+        (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;
@@ -1105,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, {
@@ -1139,7 +1155,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 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 = {
@@ -1163,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,
@@ -1209,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);
@@ -1240,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 = "";
@@ -1736,6 +1779,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             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,
@@ -2366,6 +2410,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         taskId,
                         workingLine: `The agent is working in the background.`,
                         notify: Boolean(notify),
+                        oneShot: ctx.oneShot === true,
                         notes: [
                             modelNote,
                             extraToolsNote,
@@ -2381,6 +2426,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 };
             }
             let child;
+            const syncStartedAt = Date.now();
             let retainEntry;
             if (ctx.onSubagentSpawn || observerPairing) {
                 retainEntry = ctx.onSubagentSpawn ? await tryRetainChild(ctx.subagentRetain) : undefined;
@@ -2488,9 +2534,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 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.`
@@ -2521,6 +2571,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : "(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/runner/prepare-task.d.ts

@@ -114,6 +114,7 @@ export interface Prepared {
         apply: (committedArtifactDigest?: string) => void;
     } | undefined;
     activeTools: Set<string>;
+    deferredToolNames?: ReadonlySet<string>;
     memoryEngineSession?: {
         engine: MemoryEngine;
         handle: MemorySessionHandle;

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

@@ -93,6 +93,9 @@ export function resolveModelPromptTraits(model, spec, internals) {
         fableMitigations: isFableFamilyModelId(model.id),
     };
 }
+function isDelegatedNonForkChild(internals) {
+    return internals?.isDelegatedChild === true && internals?.insideFork !== true;
+}
 export function batchContextAt(messages, currentId) {
     let batch = [];
     for (const m of messages) {
@@ -742,6 +745,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             model: harnessRef.current?.getModel(),
             thinkingLevel: harnessRef.current?.getThinkingLevel(),
             principal: spec.principal,
+            oneShot: spec.oneShot,
             clientContext: spec.clientContext,
             excludeTools: toolFaceSnapshot.exclude,
             deferTools: toolFaceSnapshot.defer,
@@ -1164,6 +1168,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 taskRegistry: defaultTaskRegistry,
                 taskOwner: hostTaskId,
                 taskScope,
+                oneShot: spec.oneShot,
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
                 ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
@@ -1212,7 +1217,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         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, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
+            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
             if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
                 const delegationForRevive = (spec.tools ?? []).find((t) => t.agentListing !== undefined);
                 const reviveSpawn = delegationForRevive !== undefined && deps.backgroundAgentStore !== undefined && deps.mailboxStore !== undefined
@@ -1405,7 +1410,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 loaded = await Promise.resolve(deps.loadProjectMemory({
                     cwd: taskRootPath,
                     handsEnabled,
-                    isSubagent: internals?.parentTaskId !== undefined,
+                    isSubagent: isDelegatedNonForkChild(internals),
                     ...(internals?.agentName ? { agentName: internals.agentName } : {}),
                     sessionId,
                     phase: projectMemoryPhase,
@@ -1432,6 +1437,10 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 memoryBlock = memoryBlock ? `${memoryBlock}\n\n${projectBlock}` : projectBlock;
             }
         }
+        const declaredSkillRank = new Map();
+        for (const s of spec.skills ?? [])
+            if (!declaredSkillRank.has(s.name))
+                declaredSkillRank.set(s.name, declaredSkillRank.size);
         const skillSpecs = normalizeSkills(spec.skills ?? []).filter((s) => {
             if (s.content.length <= SKILL_CONTENT_MAX_CHARS)
                 return true;
@@ -1457,6 +1466,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     name: s.name,
                     description: s.description,
                     ...(s.files !== undefined ? { files: s.files.map((f) => ({ path: f.path })) } : {}),
+                    ...(declaredSkillRank.get(s.name) !== undefined ? { declaredRank: declaredSkillRank.get(s.name) } : {}),
                 })),
                 seedAnnounced: resume !== undefined || spec.sessionId !== undefined,
             }
@@ -1485,7 +1495,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             awarenessEnabled: thinking !== undefined && ULTRA_REASONING_TIERS.has(thinking),
             worktreeIsolated: internals?.isolation === "worktree" && ownedEnv !== undefined,
             withinTaskCompactionEnabled: (spec.compaction?.enabled ?? true) && (spec.compaction?.withinTask ?? true),
-            isSubagent: internals?.isDelegatedChild === true && internals?.insideFork !== true,
+            isSubagent: isDelegatedNonForkChild(internals),
         };
         const userSystemPrompt = spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals?.defaultSystemPrompt;
         const userAppendSystemPrompt = spec.appendSystemPrompt;
@@ -2382,7 +2392,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : foldedPolicy;
         const hooks = spec.hooks ?? deps.hooks;
         const onAsk = spec.onAsk ?? deps.onAsk;
-        const handWriteTools = handsEnabled
+        const handWriteTools = handsEnabled && spec.handsReadOnly !== true
             ? Object.keys(HAND_TOOL_EFFECTS).filter((name) => {
                 const eff = HAND_TOOL_EFFECTS[name];
                 return eff === "write" || eff === "idempotent";
@@ -3167,15 +3177,29 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const onCompactionApplied = handsEnabled && readFileStateForCheckpoint
             ? (attachedComplete, preserveReadState) => applyCompactionToReadFileState(readFileStateForCheckpoint, attachedComplete, preserveReadState)
             : undefined;
+        const changedFilesReadDenied = denyNarrowingPolicy === undefined
+            ? undefined
+            : async (path) => {
+                try {
+                    const d = await denyNarrowingPolicy.check({ toolName: "Read", args: { file_path: path }, toolCallId: "changed-files-visibility-probe" }, abortController.signal);
+                    return d.action === "deny";
+                }
+                catch {
+                    return false;
+                }
+            };
         const detectExternalChanges = handsEnabled && readFileStateForCheckpoint
             ? async (maxFiles) => {
                 const candidates = [...readFileStateForCheckpoint.entries()]
                     .filter(([, e]) => e.lastReadAt !== undefined)
+                    .filter(([, e]) => e.truncated !== true)
                     .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) {
+                    if (changedFilesReadDenied !== undefined && (await changedFilesReadDenied(path)))
+                        continue;
                     try {
                         const info = await executionEnv.fileInfo(path, abortController.signal);
                         if (!info.ok) {
@@ -3249,7 +3273,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         overheadState.promptChars = systemPrompt.length;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ownedEnv, suspendRef, reviewRef, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;