@myagentroam/agent 0.9.66 → 0.9.68

package/dist/prompts/subagent.d.ts

@@ -1,4 +1,4 @@
-export declare const subagentPrompt = "# Subagents\nUse your own direct tools by default. Delegate only when a bounded task can proceed independently and parallelism has real value; do not delegate ordinary local search, a known-file read, a single verification command, a small edit, or sequential debugging. Give each child a self-contained objective, relevant paths and constraints, expected evidence, and a clear read/write boundary. Subagents cannot recurse and share the real filesystem; do not assign conflicting writes or assume isolation. Track background agent IDs, wait or cancel them, inspect their actual workspace effects, and verify every claim before incorporating it. The parent retains responsibility for the final result.";
+export declare const subagentPrompt = "# Subagents\nUse your own direct tools by default. Delegate only when a bounded task can proceed independently and parallelism has real value; do not delegate ordinary local search, a known-file read, a single verification command, a small edit, or sequential debugging. Give each child a self-contained objective, relevant paths and constraints, expected evidence, and a clear read/write boundary. Subagents cannot recurse and share the real filesystem; do not assign conflicting writes or assume isolation. Track background agent IDs, wait or cancel them, inspect their actual workspace effects, and verify every claim before incorporating it. Continue meaningful non-overlapping work after starting a background child. Wait for completion only when the next critical-path action is blocked on the final result, and then prefer one long wait measured in minutes rather than repeated short waits. Wait for a public message only when a fresh progress update would change the next decision; do not use message waits as heartbeat checks or request progress merely to confirm that a child is still running. The parent retains responsibility for the final result.";
 export interface SubagentModelOption {
     readonly id: string;
     readonly name: string;

package/dist/prompts/subagent.js

@@ -1,4 +1,4 @@
-export const subagentPrompt = '# Subagents\nUse your own direct tools by default. Delegate only when a bounded task can proceed independently and parallelism has real value; do not delegate ordinary local search, a known-file read, a single verification command, a small edit, or sequential debugging. Give each child a self-contained objective, relevant paths and constraints, expected evidence, and a clear read/write boundary. Subagents cannot recurse and share the real filesystem; do not assign conflicting writes or assume isolation. Track background agent IDs, wait or cancel them, inspect their actual workspace effects, and verify every claim before incorporating it. The parent retains responsibility for the final result.';
+export const subagentPrompt = '# Subagents\nUse your own direct tools by default. Delegate only when a bounded task can proceed independently and parallelism has real value; do not delegate ordinary local search, a known-file read, a single verification command, a small edit, or sequential debugging. Give each child a self-contained objective, relevant paths and constraints, expected evidence, and a clear read/write boundary. Subagents cannot recurse and share the real filesystem; do not assign conflicting writes or assume isolation. Track background agent IDs, wait or cancel them, inspect their actual workspace effects, and verify every claim before incorporating it. Continue meaningful non-overlapping work after starting a background child. Wait for completion only when the next critical-path action is blocked on the final result, and then prefer one long wait measured in minutes rather than repeated short waits. Wait for a public message only when a fresh progress update would change the next decision; do not use message waits as heartbeat checks or request progress merely to confirm that a child is still running. The parent retains responsibility for the final result.';
 export function currentAgentModelPrompt(model) {
     if (!model)
         return '';

package/dist/sdk/agent.js

@@ -1841,6 +1841,11 @@ function isSubagentTaskSnapshot(value) {
         (value.reasoningEffort === undefined ||
             (typeof value.reasoningEffort === 'string' &&
                 ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'].includes(value.reasoningEffort))) &&
+        (value.waitOutcome === undefined ||
+            value.waitOutcome === 'snapshot' ||
+            value.waitOutcome === 'message' ||
+            value.waitOutcome === 'completion' ||
+            value.waitOutcome === 'timeout') &&
         (value.latestMessage === undefined ||
             (isRecord(value.latestMessage) &&
                 typeof value.latestMessage.itemId === 'string' &&

package/dist/session/context-gc-subagent.d.ts

@@ -37,6 +37,7 @@ export interface ContextGcSubagentSnapshot {
     readonly messageId?: string;
     readonly turnId?: string;
     readonly deliveryStatus?: 'accepted' | 'applied' | 'cancelled' | 'failed';
+    readonly waitOutcome?: 'snapshot' | 'message' | 'completion' | 'timeout';
 }
 export declare function normalizeContextGcSubagentSnapshot(modelContent: unknown, completedPayload: unknown, toolName: ContextGcSubagentToolName): ContextGcSubagentSnapshot | undefined;
 export declare function contextGcCompletedSubagentTurnId(snapshot: ContextGcSubagentSnapshot): string | undefined;

package/dist/session/context-gc-subagent.js

@@ -107,6 +107,7 @@ export function contextGcSubagentOutputReplacement(input) {
         ...(input.source.deliveryStatus === undefined
             ? {}
             : { deliveryStatus: input.source.deliveryStatus }),
+        ...(input.source.waitOutcome === undefined ? {} : { waitOutcome: input.source.waitOutcome }),
         ...(latestMessage === undefined
             ? {}
             : {
@@ -172,7 +173,8 @@ function parseContextGcSubagentSnapshot(value) {
             'errorMessage',
             'messageId',
             'turnId',
-            'deliveryStatus'
+            'deliveryStatus',
+            'waitOutcome'
         ].includes(key)) ||
         !isNonemptyString(parsed.agentId) ||
         !isNonemptyString(parsed.description) ||
@@ -195,6 +197,11 @@ function parseContextGcSubagentSnapshot(value) {
             parsed.deliveryStatus !== 'applied' &&
             parsed.deliveryStatus !== 'cancelled' &&
             parsed.deliveryStatus !== 'failed') ||
+        (parsed.waitOutcome !== undefined &&
+            parsed.waitOutcome !== 'snapshot' &&
+            parsed.waitOutcome !== 'message' &&
+            parsed.waitOutcome !== 'completion' &&
+            parsed.waitOutcome !== 'timeout') ||
         !isOptionalStringArray(parsed.changedFiles) ||
         !isOptionalStringArray(parsed.verification) ||
         !isOptionalSubagentEvidence(parsed.evidence))
@@ -233,6 +240,11 @@ function parseContextGcSubagentSnapshot(value) {
             ? {
                 deliveryStatus: parsed.deliveryStatus
             }
+            : {}),
+        ...(typeof parsed.waitOutcome === 'string'
+            ? {
+                waitOutcome: parsed.waitOutcome
+            }
             : {})
     };
 }

package/dist/subagent/scheduler.d.ts

@@ -58,7 +58,10 @@ export interface SubagentTaskSnapshot extends Record<string, unknown> {
     messageId?: string;
     turnId?: string;
     deliveryStatus?: 'accepted' | 'applied' | 'cancelled' | 'failed';
+    waitOutcome?: SubagentWaitOutcome;
 }
+export type SubagentWaitFor = 'completion' | 'message';
+export type SubagentWaitOutcome = 'snapshot' | 'message' | 'completion' | 'timeout';
 export interface SubagentMessageOptions {
     delivery?: 'append' | 'replace';
     signal?: AbortSignal;
@@ -69,6 +72,7 @@ export interface SubagentRunOptions {
 }
 export interface SubagentOutputOptions {
     waitMs?: number;
+    waitFor?: SubagentWaitFor;
     signal?: AbortSignal;
 }
 export interface SubagentController {
@@ -97,8 +101,100 @@ export declare class SubagentScheduler implements SubagentController {
     });
     beginExecution(runner: (task: SubagentTaskInput, signal: AbortSignal) => Promise<SubagentTaskResult>): void;
     run(input: SubagentTaskInput, options?: SubagentRunOptions): Promise<SubagentTaskSnapshot>;
-    output(agentId: string, options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;
-    outputAny(options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;
+    output(agentId: string, options?: SubagentOutputOptions): Promise<{
+        waitOutcome: "snapshot";
+        agentId: string;
+        description: string;
+        status: "queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted";
+        modelId?: string;
+        modelName?: string;
+        reasoningEffort?: MarAgentReasoningEffort;
+        latestMessage?: SubagentLatestMessage;
+        latestActivity?: SubagentLatestActivity;
+        summary?: string;
+        changedFiles?: string[];
+        verification?: string[];
+        evidence?: Array<{
+            path: string;
+            startLine?: number;
+            endLine?: number;
+        }>;
+        errorCode?: string;
+        errorMessage?: string;
+        messageId?: string;
+        turnId?: string;
+        deliveryStatus?: "accepted" | "applied" | "cancelled" | "failed";
+    } | {
+        waitOutcome: "timeout" | "completion";
+        agentId: string;
+        description: string;
+        status: "queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted";
+        modelId?: string;
+        modelName?: string;
+        reasoningEffort?: MarAgentReasoningEffort;
+        latestMessage?: SubagentLatestMessage;
+        latestActivity?: SubagentLatestActivity;
+        summary?: string;
+        changedFiles?: string[];
+        verification?: string[];
+        evidence?: Array<{
+            path: string;
+            startLine?: number;
+            endLine?: number;
+        }>;
+        errorCode?: string;
+        errorMessage?: string;
+        messageId?: string;
+        turnId?: string;
+        deliveryStatus?: "accepted" | "applied" | "cancelled" | "failed";
+    }>;
+    outputAny(options?: SubagentOutputOptions): Promise<{
+        waitOutcome: "snapshot";
+        agentId: string;
+        description: string;
+        status: "queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted";
+        modelId?: string;
+        modelName?: string;
+        reasoningEffort?: MarAgentReasoningEffort;
+        latestMessage?: SubagentLatestMessage;
+        latestActivity?: SubagentLatestActivity;
+        summary?: string;
+        changedFiles?: string[];
+        verification?: string[];
+        evidence?: Array<{
+            path: string;
+            startLine?: number;
+            endLine?: number;
+        }>;
+        errorCode?: string;
+        errorMessage?: string;
+        messageId?: string;
+        turnId?: string;
+        deliveryStatus?: "accepted" | "applied" | "cancelled" | "failed";
+    } | {
+        waitOutcome: "timeout" | "completion";
+        agentId: string;
+        description: string;
+        status: "queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted";
+        modelId?: string;
+        modelName?: string;
+        reasoningEffort?: MarAgentReasoningEffort;
+        latestMessage?: SubagentLatestMessage;
+        latestActivity?: SubagentLatestActivity;
+        summary?: string;
+        changedFiles?: string[];
+        verification?: string[];
+        evidence?: Array<{
+            path: string;
+            startLine?: number;
+            endLine?: number;
+        }>;
+        errorCode?: string;
+        errorMessage?: string;
+        messageId?: string;
+        turnId?: string;
+        deliveryStatus?: "accepted" | "applied" | "cancelled" | "failed";
+    }>;
     cancel(agentId: string): Promise<SubagentTaskSnapshot>;
     message(_agentId: string, _message: string): Promise<SubagentTaskSnapshot>;
     listSessionResources(): {

package/dist/subagent/scheduler.js

@@ -81,37 +81,43 @@ export class SubagentScheduler {
     }
     async output(agentId, options = {}) {
         options.signal?.throwIfAborted();
+        rejectUnsupportedMessageWait(options);
         const task = this.#tasks.get(agentId);
         if (!task)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent task was not found.');
-        if (options.waitMs !== undefined &&
-            (!Number.isInteger(options.waitMs) ||
-                options.waitMs < TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs ||
-                options.waitMs > TOOL_EXECUTION_LIMITS.agentWaitMaxWaitMs))
-            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Task wait is invalid.');
-        const waitMs = options.waitMs === undefined || options.waitMs === 0
-            ? undefined
-            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-        if (waitMs !== undefined && !['completed', 'failed', 'cancelled'].includes(task.status))
-            await this.#waitForCompletion(task, waitMs, options.signal);
-        return this.#public(task);
+        validateOutputOptions(options);
+        const terminal = ['completed', 'failed', 'cancelled'].includes(task.status);
+        if (options.waitMs === undefined || options.waitMs === 0)
+            return { ...this.#public(task), waitOutcome: 'snapshot' };
+        if (terminal)
+            return { ...this.#public(task), waitOutcome: 'completion' };
+        const waitMs = Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+        const completed = await this.#waitForCompletion(task, waitMs, options.signal);
+        options.signal?.throwIfAborted();
+        return {
+            ...this.#public(task),
+            waitOutcome: completed ? 'completion' : 'timeout'
+        };
     }
     async outputAny(options = {}) {
         options.signal?.throwIfAborted();
         validateOutputOptions(options);
+        rejectUnsupportedMessageWait(options);
         const tasks = [...this.#tasks.values()];
         if (tasks.length === 0)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent task was not found.');
         const live = tasks.filter((task) => task.status === 'queued' || task.status === 'running');
-        if (live.length === 0 || options.waitMs === 0)
-            return this.#public(live.at(-1) ?? tasks.at(-1));
-        const waitMs = options.waitMs === undefined
-            ? undefined
-            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-        if (waitMs !== undefined)
-            await this.#waitForAnyCompletion(live, waitMs, options.signal);
-        const completed = live.find((task) => task.status !== 'queued' && task.status !== 'running');
-        return this.#public(completed ?? live.at(-1));
+        if (options.waitMs === undefined || options.waitMs === 0)
+            return { ...this.#public(live.at(-1) ?? tasks.at(-1)), waitOutcome: 'snapshot' };
+        if (live.length === 0)
+            return { ...this.#public(tasks.at(-1)), waitOutcome: 'completion' };
+        const waitMs = Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+        const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal);
+        options.signal?.throwIfAborted();
+        return {
+            ...this.#public(completed ?? live.at(-1)),
+            waitOutcome: completed ? 'completion' : 'timeout'
+        };
     }
     async cancel(agentId) {
         const task = this.#tasks.get(agentId);
@@ -259,13 +265,20 @@ function waitForCompletionNotification(waiters, accepts, waitMs, signal) {
             signal?.removeEventListener('abort', abort);
             waiters.delete(notify);
             if (error === undefined)
-                resolve();
+                resolve(undefined);
             else
                 reject(error);
         };
         const notify = (value) => {
-            if (accepts(value))
-                finish();
+            if (accepts(value)) {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', abort);
+                waiters.delete(notify);
+                resolve(value);
+            }
         };
         const abort = () => finish(signal?.reason ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
         const timer = setTimeout(finish, waitMs);
@@ -277,12 +290,19 @@ function waitForCompletionNotification(waiters, accepts, waitMs, signal) {
     });
 }
 function validateOutputOptions(options) {
-    if (options.waitMs !== undefined &&
-        (!Number.isInteger(options.waitMs) ||
-            options.waitMs < TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs ||
-            options.waitMs > TOOL_EXECUTION_LIMITS.agentWaitMaxWaitMs))
+    if ((options.waitFor !== undefined &&
+        options.waitFor !== 'completion' &&
+        options.waitFor !== 'message') ||
+        (options.waitMs !== undefined &&
+            (!Number.isInteger(options.waitMs) ||
+                options.waitMs < TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs ||
+                options.waitMs > TOOL_EXECUTION_LIMITS.agentWaitMaxWaitMs)))
         throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Task wait is invalid.');
 }
+function rejectUnsupportedMessageWait(options) {
+    if (options.waitFor === 'message')
+        throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Message waits require a session-backed subagent controller.');
+}
 function linkAbort(signal, abort) {
     const listener = () => abort(signal.reason);
     signal.addEventListener('abort', listener, { once: true });

package/dist/subagent/session-controller.js

@@ -9,6 +9,8 @@ export class SubagentSessionController {
     #agents = new Map();
     #queue = [];
     #completionWaiters = new Set();
+    #activityWaiters = new Set();
+    #activityRevision = 0;
     #running = 0;
     #disposed = false;
     #createdInExecution = 0;
@@ -69,6 +71,9 @@ export class SubagentSessionController {
             description: source.description,
             role: input.role,
             status: 'queued',
+            messageRevision: 0,
+            observedMessageRevision: 0,
+            latestMessageActivityRevision: 0,
             changedFiles: [],
             verification: [],
             evidence: [],
@@ -121,19 +126,42 @@ export class SubagentSessionController {
     async output(agentId, options = {}) {
         options.signal?.throwIfAborted();
         const state = await this.#find(agentId);
-        if (options.waitMs !== undefined &&
-            (!Number.isInteger(options.waitMs) ||
-                options.waitMs < TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs ||
-                options.waitMs > TOOL_EXECUTION_LIMITS.agentWaitMaxWaitMs))
-            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Task wait is invalid.');
-        const waitMs = options.waitMs === undefined || options.waitMs === 0
-            ? undefined
-            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-        if (waitMs !== undefined &&
-            state.turn &&
-            (state.status === 'queued' || state.status === 'running'))
-            await this.#waitForCompletion(state, waitMs, options.signal);
-        return this.#snapshot(state);
+        options.signal?.throwIfAborted();
+        validateOutputOptions(options);
+        if (options.waitMs === undefined || options.waitMs === 0)
+            return { ...this.#snapshot(state), waitOutcome: 'snapshot' };
+        if (isTerminalState(state)) {
+            this.#observeLatestMessage(state);
+            return { ...this.#snapshot(state), waitOutcome: 'completion' };
+        }
+        const waitFor = options.waitFor ?? 'completion';
+        if (waitFor === 'message' && this.#hasUnreadMessage(state)) {
+            this.#observeLatestMessage(state);
+            return { ...this.#snapshot(state), waitOutcome: 'message' };
+        }
+        const waitMs = Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+        if (waitFor === 'completion') {
+            const completed = await this.#waitForCompletion(state, waitMs, options.signal);
+            options.signal?.throwIfAborted();
+            if (completed)
+                this.#observeLatestMessage(state);
+            return {
+                ...this.#snapshot(state),
+                waitOutcome: completed ? 'completion' : 'timeout'
+            };
+        }
+        const activity = await this.#waitForMessageOrCompletion([state], waitMs, options.signal);
+        options.signal?.throwIfAborted();
+        if (activity)
+            this.#observeLatestMessage(activity.state);
+        return {
+            ...this.#snapshot(activity?.state ?? state),
+            waitOutcome: activity?.kind === 'message'
+                ? 'message'
+                : activity?.kind === 'completion'
+                    ? 'completion'
+                    : 'timeout'
+        };
     }
     async outputAny(options = {}) {
         options.signal?.throwIfAborted();
@@ -142,16 +170,47 @@ export class SubagentSessionController {
         if (states.length === 0)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
         const live = states.filter((state) => state.status === 'queued' || state.status === 'running');
-        if (live.length === 0 || options.waitMs === 0)
-            return this.#snapshot(live.at(-1) ?? states.at(-1));
-        const waitMs = options.waitMs === undefined
-            ? undefined
-            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-        if (waitMs !== undefined) {
-            await this.#waitForAnyCompletion(live, waitMs, options.signal);
+        if (options.waitMs === undefined || options.waitMs === 0)
+            return {
+                ...this.#snapshot(live.at(-1) ?? states.at(-1)),
+                waitOutcome: 'snapshot'
+            };
+        if (live.length === 0) {
+            const state = states.at(-1);
+            this.#observeLatestMessage(state);
+            return { ...this.#snapshot(state), waitOutcome: 'completion' };
         }
-        const completed = live.find((state) => state.status !== 'queued' && state.status !== 'running');
-        return this.#snapshot(completed ?? live.at(-1));
+        const waitFor = options.waitFor ?? 'completion';
+        if (waitFor === 'message') {
+            const pending = this.#oldestUnreadMessage(live);
+            if (pending) {
+                this.#observeLatestMessage(pending);
+                return { ...this.#snapshot(pending), waitOutcome: 'message' };
+            }
+        }
+        const waitMs = Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+        if (waitFor === 'message') {
+            const activity = await this.#waitForMessageOrCompletion(live, waitMs, options.signal);
+            options.signal?.throwIfAborted();
+            if (activity)
+                this.#observeLatestMessage(activity.state);
+            return {
+                ...this.#snapshot(activity?.state ?? live.at(-1)),
+                waitOutcome: activity?.kind === 'message'
+                    ? 'message'
+                    : activity?.kind === 'completion'
+                        ? 'completion'
+                        : 'timeout'
+            };
+        }
+        const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal);
+        options.signal?.throwIfAborted();
+        if (completed)
+            this.#observeLatestMessage(completed);
+        return {
+            ...this.#snapshot(completed ?? live.at(-1)),
+            waitOutcome: completed ? 'completion' : 'timeout'
+        };
     }
     async message(agentId, message, options = {}) {
         const execution = this.#requireExecution();
@@ -340,8 +399,13 @@ export class SubagentSessionController {
     async #consumeTurn(state, turn) {
         try {
             const consume = (async () => {
-                for await (const event of turn.handle)
-                    observeAgentEvent(state, event);
+                for await (const event of turn.handle) {
+                    if (!observeAgentEvent(state, event))
+                        continue;
+                    state.messageRevision++;
+                    state.latestMessageActivityRevision = ++this.#activityRevision;
+                    this.#notifyActivity({ state, kind: 'message' });
+                }
             })();
             const result = await turn.handle.result();
             await consume;
@@ -402,6 +466,32 @@ export class SubagentSessionController {
     #notifyCompletion(state) {
         for (const waiter of this.#completionWaiters)
             waiter(state);
+        this.#notifyActivity({ state, kind: 'completion' });
+    }
+    #waitForMessageOrCompletion(candidates, waitMs, signal) {
+        return waitForNotification(this.#activityWaiters, (activity) => candidates.includes(activity.state), () => {
+            const pending = this.#oldestUnreadMessage(candidates);
+            if (pending)
+                return { state: pending, kind: 'message' };
+            const terminal = candidates.find(isTerminalState);
+            return terminal ? { state: terminal, kind: 'completion' } : undefined;
+        }, waitMs, signal);
+    }
+    #notifyActivity(activity) {
+        for (const waiter of this.#activityWaiters)
+            waiter(activity);
+    }
+    #hasUnreadMessage(state) {
+        return state.messageRevision > state.observedMessageRevision;
+    }
+    #oldestUnreadMessage(states) {
+        return states
+            .filter((state) => this.#hasUnreadMessage(state))
+            .sort((left, right) => left.latestMessageActivityRevision - right.latestMessageActivityRevision)
+            .at(0);
+    }
+    #observeLatestMessage(state) {
+        state.observedMessageRevision = state.messageRevision;
     }
     #closeReceipt(state) {
         if (state.receipt?.deliveryStatus === 'accepted' && state.receipt.turnId === state.turn?.turnId)
@@ -571,6 +661,9 @@ function restoreAgentState(session) {
         ...(isReasoningEffort(header?.reasoningEffort)
             ? { reasoningEffort: header.reasoningEffort }
             : {}),
+        messageRevision: 0,
+        observedMessageRevision: 0,
+        latestMessageActivityRevision: 0,
         changedFiles: [],
         verification: [],
         evidence: [],
@@ -581,8 +674,10 @@ function restoreAgentState(session) {
             !['message.completed', 'tool.started', 'tool.completed', 'tool.failed'].includes(eventType(record) ?? ''))
             continue;
         const event = record.payload;
-        observeAgentEvent(state, event);
+        if (observeAgentEvent(state, event))
+            state.messageRevision++;
     }
+    state.observedMessageRevision = state.messageRevision;
     if (state.status === 'completed' && state.latestMessage?.phase === 'final_answer')
         state.summary = truncateUtf8(state.latestMessage.text, TOOL_EXECUTION_LIMITS.subagentSummaryMaxBytes);
     if (state.status === 'failed' && terminal && isRecord(terminal.payload)) {
@@ -601,7 +696,7 @@ function observeAgentEvent(state, event) {
             timestamp: event.timestamp,
             phase: event.phase
         };
-        return;
+        return true;
     }
     if (event.type === 'tool.started') {
         state.latestActivity = {
@@ -610,7 +705,7 @@ function observeAgentEvent(state, event) {
             toolName: event.toolName,
             status: 'started'
         };
-        return;
+        return false;
     }
     if (event.type === 'tool.failed') {
         state.latestActivity = {
@@ -619,10 +714,10 @@ function observeAgentEvent(state, event) {
             toolName: event.toolName,
             status: 'failed'
         };
-        return;
+        return false;
     }
     if (event.type !== 'tool.completed')
-        return;
+        return false;
     state.latestActivity = {
         kind: 'tool',
         timestamp: event.timestamp,
@@ -664,6 +759,7 @@ function observeAgentEvent(state, event) {
     else if (event.toolName === 'exec' &&
         state.verification.length < TOOL_EXECUTION_LIMITS.subagentVerificationMaxItems)
         state.verification.push(truncateUtf8(event.summary, 2_000));
+    return false;
 }
 function eventType(record) {
     return record && isRecord(record.payload) && typeof record.payload.type === 'string'
@@ -738,13 +834,18 @@ function waitForCompletionNotification(waiters, accepts, waitMs, signal) {
             signal?.removeEventListener('abort', abort);
             waiters.delete(notify);
             if (error === undefined)
-                resolve();
+                resolve(undefined);
             else
                 reject(error);
         };
         const notify = (value) => {
-            if (accepts(value))
-                finish();
+            if (!accepts(value) || settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+            waiters.delete(notify);
+            resolve(value);
         };
         const abort = () => finish(signal?.reason ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
         const timer = setTimeout(finish, waitMs);
@@ -755,13 +856,55 @@ function waitForCompletionNotification(waiters, accepts, waitMs, signal) {
             abort();
     });
 }
+function waitForNotification(waiters, accepts, current, waitMs, signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (value, error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+            waiters.delete(notify);
+            if (error === undefined)
+                resolve(value);
+            else
+                reject(error);
+        };
+        const notify = (value) => {
+            if (accepts(value))
+                finish(value);
+        };
+        const abort = () => finish(undefined, signal?.reason ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
+        const timer = setTimeout(() => finish(), waitMs);
+        timer.unref();
+        waiters.add(notify);
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        else {
+            const pending = current();
+            if (pending !== undefined)
+                finish(pending);
+        }
+    });
+}
 function validateOutputOptions(options) {
-    if (options.waitMs !== undefined &&
-        (!Number.isInteger(options.waitMs) ||
-            options.waitMs < TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs ||
-            options.waitMs > TOOL_EXECUTION_LIMITS.agentWaitMaxWaitMs))
+    if ((options.waitFor !== undefined &&
+        options.waitFor !== 'completion' &&
+        options.waitFor !== 'message') ||
+        (options.waitMs !== undefined &&
+            (!Number.isInteger(options.waitMs) ||
+                options.waitMs < TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs ||
+                options.waitMs > TOOL_EXECUTION_LIMITS.agentWaitMaxWaitMs)))
         throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Task wait is invalid.');
 }
+function isTerminalState(state) {
+    return (state.status === 'completed' ||
+        state.status === 'failed' ||
+        state.status === 'cancelled' ||
+        state.status === 'interrupted');
+}
 function linkAbort(signal, abort) {
     const listener = () => abort();
     signal.addEventListener('abort', listener, { once: true });

package/dist/tools/agent-wait.js

@@ -3,11 +3,17 @@ import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 export const agentWaitToolDefinition = {
     name: 'agent_wait',
     parallelSafety: 'serial',
-    description: 'Read or wait a bounded time for a child agent result. Omit agentId to wait for whichever live child returns first, matching Codex-style untargeted waiting and avoiding UUID transcription; provide the exact agentId returned by agent_start only when observing a specific child. If no child is live, untargeted waiting reads the most recently created child. For an exec processId, use exec with action:"poll" instead. Omitting waitMs waits up to 30 seconds by default; waitMs=0 returns the current snapshot immediately. Positive waits range up to 5 minutes, and positive values below 10 seconds are raised to 10 seconds. Every result includes the real agentId and description. latestMessage is the most recent public assistant commentary/final message, never hidden reasoning or a tool result; latestActivity identifies whether the latest observed activity was a public message or a bounded tool started/completed/failed status. To request a fresh textual progress report, send an append agent_message and then wait. A queued or running result is not completion; wait again only when useful, or cancel if no longer needed. Terminal results include bounded summary, changedFiles, verification, and read evidence with path/line ranges; use that evidence to avoid repeating the full exploration, while independently checking consequential edits and claims. Avoid busy polling.',
+    description: 'Read or wait a bounded time for a child agent result. waitFor defaults to "completion"; use "message" only when a fresh public commentary/final message would change the next decision. Omit agentId to wait for whichever live child returns first, matching Codex-style untargeted waiting and avoiding UUID transcription; provide the exact agentId returned by agent_start only when observing a specific child. If no child is live, untargeted waiting reads the most recently created child. For an exec processId, use exec with action:"poll" instead. Omitting waitMs waits up to 30 seconds by default; waitMs=0 returns the current snapshot immediately. Positive waits range up to 5 minutes, and positive values below 10 seconds are raised to 10 seconds. When blocked on a live child result, prefer one 300000 ms completion wait rather than repeated short waits. Every result includes waitOutcome as snapshot, message, completion, or timeout plus the real agentId and description. latestMessage is the most recent public assistant commentary/final message, never hidden reasoning or a tool result; latestActivity identifies whether the latest observed activity was a public message or a bounded tool started/completed/failed status. A queued or running result is not completion. A message wait consumes only the latest unread public message in the current Session runtime; tool activity does not wake it, and parent cancellation preserves unread progress for a later Execution. Do not use message waits as heartbeat checks or request progress merely to confirm that a child is still running. Terminal results include bounded summary, changedFiles, verification, and read evidence with path/line ranges; use that evidence to avoid repeating the full exploration, while independently checking consequential edits and claims.',
     inputSchema: {
         type: 'object',
         properties: {
             agentId: { type: 'string' },
+            waitFor: {
+                type: 'string',
+                enum: ['completion', 'message'],
+                default: 'completion',
+                description: 'Wait for terminal completion or for the latest unread public message. Terminal state ends either wait.'
+            },
             waitMs: {
                 type: 'integer',
                 minimum: TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs,
@@ -26,6 +32,7 @@ export async function executeAgentWait(arguments_, context) {
         throw new MarAgentError('MAR_AGENT_SUBAGENT_RECURSION_DISABLED', 'Subagents cannot recurse.');
     const options = {
         waitMs: value.waitMs ?? TOOL_EXECUTION_LIMITS.agentWaitDefaultWaitMs,
+        waitFor: value.waitFor ?? 'completion',
         signal: context.signal
     };
     const task = value.agentId === undefined
@@ -37,18 +44,22 @@ function parseAgentWaitInput(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return invalidAgentWait();
     const input = value;
-    if (Object.keys(input).some((key) => !['agentId', 'waitMs'].includes(key)) ||
+    if (Object.keys(input).some((key) => !['agentId', 'waitFor', 'waitMs'].includes(key)) ||
         (input.agentId !== undefined &&
-            input.agentId !== null &&
             (typeof input.agentId !== 'string' || input.agentId.trim().length === 0)) ||
+        (input.waitFor !== undefined &&
+            input.waitFor !== 'completion' &&
+            input.waitFor !== 'message') ||
         (input.waitMs !== undefined &&
-            input.waitMs !== null &&
             (!Number.isInteger(input.waitMs) ||
                 input.waitMs < TOOL_EXECUTION_LIMITS.agentWaitMinWaitMs ||
                 input.waitMs > TOOL_EXECUTION_LIMITS.agentWaitMaxWaitMs)))
         return invalidAgentWait();
     return {
         ...(typeof input.agentId === 'string' ? { agentId: input.agentId.trim() } : {}),
+        ...(input.waitFor === 'completion' || input.waitFor === 'message'
+            ? { waitFor: input.waitFor }
+            : {}),
         ...(typeof input.waitMs === 'number' ? { waitMs: input.waitMs } : {})
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.9.66",
+  "version": "0.9.68",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",