@myagentroam/node 0.11.42 → 0.11.44

package/dist/application/node-lifecycle.js

@@ -75,30 +75,53 @@ export class NodeLifecycle {
     async stopResources(handoff) {
         let snapshot;
         let failure;
+        let stage = 'waitForRecovery';
+        const failed = (error) => {
+            failure ??= { error };
+            try {
+                this.shutdown.diagnose(stage, error);
+            }
+            catch {
+                // Diagnostics must not replace the shutdown failure or prevent cleanup.
+            }
+        };
         try {
             await this.shutdown.waitForRecovery();
+            stage = 'drainInput';
             await this.shutdown.drainInput();
         }
         catch (error) {
-            failure = error;
+            failed(error);
         }
         try {
+            stage = 'closeResume';
             await this.shutdown.closeResume();
-            if (failure === undefined && handoff)
+            if (failure === undefined && handoff) {
+                stage = 'capture';
                 snapshot = this.shutdown.capture();
+            }
         }
         catch (error) {
-            failure ??= error;
+            failed(error);
         }
         try {
+            stage = 'dispose';
             await this.shutdown.dispose();
         }
         catch (error) {
-            failure ??= error;
+            failed(error);
         }
         if (failure !== undefined)
-            throw failure;
-        if (snapshot !== undefined)
-            await this.shutdown.publish(snapshot);
+            throw failure.error;
+        if (snapshot !== undefined) {
+            try {
+                await this.shutdown.publish(snapshot);
+            }
+            catch (error) {
+                stage = 'publish';
+                failed(error);
+                throw error;
+            }
+        }
     }
 }

package/dist/connector.js

@@ -197,7 +197,11 @@ export class NodeConnector {
         closeResume: () => this.externalSessionResumeService.close(),
         capture: () => (this.config?.nodeId ? this.restartHandoff.capture() : undefined),
         dispose: () => this.disposeRuntime(),
-        publish: (snapshot) => this.restartHandoff.publish(snapshot)
+        publish: (snapshot) => this.restartHandoff.publish(snapshot),
+        diagnose: (stage, error) => nodeLog('node.shutdown.failed', {
+            stage,
+            errorCode: safeErrorCode(error, 'NODE_SHUTDOWN_FAILED')
+        })
     });
     get stopped() {
         return this.lifecycle.stopped;
@@ -647,10 +651,17 @@ export class NodeConnector {
                 }),
                 resources: async (signal) => {
                     signal.throwIfAborted();
-                    const run = this.runtime.activeSessionRun(sessionId);
+                    const currentSessionId = this.runtime.getAgentSessionById(sessionId)?.id;
+                    if (!currentSessionId)
+                        return [];
+                    const run = this.runtime.activeSessionRun(currentSessionId);
                     if (!run || !run.initiatedByUserId)
                         return [];
-                    const result = await this.agentNetworkService.list({ sessionId, runId: run.id, requestUserId: run.initiatedByUserId }, { scope: 'children', limit: 100 });
+                    const result = await this.agentNetworkService.list({
+                        sessionId: currentSessionId,
+                        runId: run.id,
+                        requestUserId: run.initiatedByUserId
+                    }, { scope: 'children', limit: 100 });
                     signal.throwIfAborted();
                     const data = result;
                     if (!data.sessions?.length && !data.truncated)

package/dist/hosting/hosted-conversation-node-service.js

@@ -943,8 +943,7 @@ function modelSummary(model, index) {
             : { responsesTransport: model.responsesTransport }),
         responsesPreviousResponseId: model.responsesPreviousResponseId,
         enabled: model.enabled,
-        sortOrder: index,
-        apiKeyConfigured: true
+        sortOrder: index
     };
 }
 function terminalHostedTurnStatus(status) {

package/dist/main.js

@@ -45,10 +45,17 @@ if (command === 'run') {
             clearTimeout(deadline);
             releaseOwner();
             process.exit(exitCode);
-        }, () => {
+        }, (error) => {
             clearTimeout(deadline);
-            nodeLog('node.restart.diagnostic', { code: 'RESTART_HANDOFF_SHUTDOWN_FAILED' });
-            process.exit(1);
+            try {
+                nodeLog('node.restart.diagnostic', {
+                    code: 'RESTART_HANDOFF_SHUTDOWN_FAILED',
+                    errorCode: safeErrorCode(error, 'NODE_SHUTDOWN_FAILED')
+                });
+            }
+            finally {
+                process.exit(1);
+            }
         });
     };
     const supervisorHandoff = new SupervisorUpgradeHandoff();

package/dist/marctl-guidance.js

@@ -5,7 +5,7 @@ export function hasMarctlContext(environment) {
         !!environment['MAR_CTL_NODE_ID'] &&
         !!environment['MAR_CTL_WORKSPACE_ID']);
 }
-export const marctlManagementDescription = 'Use marctl for model and effort configuration, renaming, persistent prompts, schedules, authorized Node discovery, remote commands, and file transfer.';
+export const marctlManagementDescription = 'Use marctl to manage MAR Agent session settings (model, effort, title, persistent prompts, and schedules), discover authorized MAR Nodes, and execute commands or transfer files on those Nodes. Use native agent_* tools for other Agent lifecycle and collaboration operations.';
 const marctlSafety = 'Acceptance is not completion. If a request result is unknown, inspect history before retrying. Session IDs and parent relationships do not grant authorization.';
 export const marctlManagementInstructions = [
     '## MAR Workspace management',
@@ -21,8 +21,10 @@ export const marctlInstructions = [
     'Run marctl from the shell. Commands use the authenticated Node and Workspace; marctl help agents, nodes, ssh or scp shows options.',
     'Use agents start --title <title> -m <text> [--runner <runner>] [--model <id>] [--effort <effort>] [--goal <objective>]. An Agent must supply a nonblank title; a manual terminal may omit it. The default Runner is the current Session Runner; a terminal without a current Session must specify --runner or an explicit --parent. Start returns without waiting.',
     'Use agents send <id> -m <text> [--steer|--queue], agents wait [<id>] [--wait-for message|completion] [--timeout <duration>], agents stop <id> --execution <execution-id>, agents list [--scope children|descendants|workspace|profile], and agents view <id> [--history]. Wait defaults to direct-child completion for 30 seconds; --timeout 0ms takes a snapshot. Stop clears the target Session Goal.',
+    'Prefer agents send <id> --steer -m <text> for timely communication or course correction. Use --queue only for deliberately deferred input: it is consumed after current work and earlier queued inputs finish, and with an active Goal it is not consumed until that Goal exits. Acceptance is not a guarantee of immediate processing.',
     'Start and send accept repeated --image <local-path> for PNG, JPEG, GIF or WebP; limits are five images, 5 MiB each and 10 MiB total. Send can update a Goal alone with --goal <objective> or --clear-goal; omitted Goal leaves it unchanged. Decide a direct child approval with send <id> --approval <approval-id> --decision approve|reject.',
     'List accepts --agent <id> for a relation root, --query, --parent, --limit and --cursor. Use --scope profile [--runner <runner>] for Runner models; configured profiles do not guarantee account availability.',
+    'Only direct-child updates are collected automatically. Sending to a non-child never subscribes; an explicit wait observes it only for that call.',
     'Use agents config, rename, prompt and schedule for management. marctl nodes, ssh and scp use authorized Nodes.',
     marctlSafety
 ].join('\n\n');

package/dist/runner/abstract-runner.js

@@ -40,8 +40,8 @@ export class AbstractRunner {
     childModels() {
         return this.profileForValidation().models;
     }
-    assertChildModel(modelId) {
-        void modelId;
+    assertChildModel(modelId, executionContext) {
+        void [modelId, executionContext];
     }
     presentSession(session, capabilities, context) {
         void [session, capabilities, context];

package/dist/runner/claude/managed-run-controller.js

@@ -462,7 +462,7 @@ export class ClaudeManagedRunController {
                             const tool = toolInputs.get(result.toolUseId);
                             if (tool === undefined)
                                 continue;
-                            const normalized = normalizeClaudeTool(tool.name, tool.input, result.output, result.failed, tool.inputTruncated || result.truncated, knownSubagents, result.claudeResult);
+                            const normalized = normalizeClaudeTool(tool.name, tool.input, result.output, result.failed, tool.inputTruncated || result.truncated, knownSubagents, result.claudeResult, result.truncated);
                             this.host.emitItem(runId, {
                                 itemId: boundedConversationItemId('claude-tool', result.toolUseId),
                                 kind,

package/dist/runner/claude/native-transcript.js

@@ -339,7 +339,7 @@ export const claudeNativeTranscriptAdapter = {
         return {
             userText: (text) => publicGoalHistoryText(stripClaudePlanTag(text)),
             planText: claudePlanText,
-            normalizeTool: (entry) => normalizeClaudeTool(entry.toolName, entry.input, entry.outputSummary, entry.failed, entry.inputTruncated || entry.outputTruncated, titles, claudeNativeToolResultMetadata(entry.subagentResult)),
+            normalizeTool: (entry) => normalizeClaudeTool(entry.toolName, entry.input, entry.outputSummary, entry.failed, entry.inputTruncated || entry.outputTruncated, titles, claudeNativeToolResultMetadata(entry.subagentResult), entry.outputTruncated),
             userInputQuestions: (entry) => entry.toolName === 'AskUserQuestion' && isPlainRecord(entry.input)
                 ? claudeUserInputQuestions(entry.input)
                 : []

package/dist/runner/claude/tool-normalizer.js

@@ -1,6 +1,6 @@
 import { claudeContentBlocks } from './message-parsers.js';
-import { compactRunnerText, compactRunnerValue } from '../normalization.js';
-import { publicOutputSnapshot, shellExecution } from '../execution-presentation.js';
+import { compactRunnerText, compactRunnerValue, publicOutputSnapshot } from '../normalization.js';
+import { shellExecution } from '../execution-presentation.js';
 import { RunnerUsageTracker, usageToken, usageTokenSum } from '../../service/runner-usage-tracker.js';
 export class ClaudeUsageNormalizer {
     tracker;
@@ -69,7 +69,16 @@ export function extractClaudeToolResults(message) {
         return [];
     const blocks = claudeContentBlocks(message).filter((block) => block.type === 'tool_result' && typeof block.tool_use_id === 'string');
     return blocks.map((block) => {
-        const output = compactRunnerValue(block.content, 10_000);
+        const textBlocks = Array.isArray(block.content)
+            ? block.content.flatMap((part) => {
+                const value = record(part);
+                return value?.type === 'text' && typeof value.text === 'string' ? [value.text] : [];
+            })
+            : [];
+        const content = Array.isArray(block.content) && textBlocks.length === block.content.length
+            ? textBlocks.join('\n')
+            : block.content;
+        const output = publicOutputSnapshot(content);
         // A message-level structured result cannot be assigned to multiple calls.
         const structured = blocks.length === 1 ? structuredRecord(message.tool_use_result) : undefined;
         const fields = structured ?? structuredRecord(block.content);
@@ -90,27 +99,27 @@ export function extractClaudeToolResults(message) {
         };
     });
 }
-export function normalizeClaudeTool(toolName, input, output, failed, truncated, knownSubagents = new Map(), resultMetadata) {
+export function normalizeClaudeTool(toolName, input, output, failed, truncated, knownSubagents = new Map(), resultMetadata, sourceOutputTruncated = output === null ? false : truncated) {
     const values = record(input);
     const normalizedToolName = compactRunnerText(toolName, 128) || 'unknown';
     const normalizedOutput = output === null ? null : compactRunnerText(output, 10_000);
-    const outputTruncated = truncated || (output?.length ?? 0) > 10_000;
+    const outputTruncated = sourceOutputTruncated || (output?.length ?? 0) > 10_000;
     const subagent = claudeSubagentProjection(toolName, input, resultMetadata ?? output, knownSubagents);
     if (isCommandTool(toolName))
         return {
             kind: 'command_execution',
             payload: {
+                toolName: normalizedToolName,
                 command: compactRunnerText(typeof values?.command === 'string' ? values.command : normalizedToolName, 10_000),
                 cwd: null,
                 outputPreview: normalizedOutput ?? '',
-                outputRef: null,
                 exitCode: null,
                 durationMs: null,
-                truncated: outputTruncated,
+                truncated: truncated || outputTruncated,
                 ...(output === null || output === undefined
                     ? {}
-                    : { output: publicOutputSnapshot(output, truncated) }),
-                toolPresentation: shellExecution(output ?? undefined, truncated)
+                    : { output: publicOutputSnapshot(output, outputTruncated) }),
+                toolPresentation: shellExecution(output ?? undefined, outputTruncated)
             }
         };
     if (isFileTool(toolName)) {
@@ -132,8 +141,7 @@ export function normalizeClaudeTool(toolName, input, output, failed, truncated,
                             path: normalizedPath,
                             change: 'MODIFIED',
                             additions: null,
-                            deletions: null,
-                            diffAvailable: false
+                            deletions: null
                         }
                     ]
             }
@@ -147,9 +155,10 @@ export function normalizeClaudeTool(toolName, input, output, failed, truncated,
             title: compactRunnerText(toolName, 500) || normalizedToolName,
             inputSummary: compactRunnerValue(input, 10_000).text || null,
             outputSummary: normalizedOutput,
+            ...(output === null ? {} : { output: publicOutputSnapshot(output, outputTruncated) }),
             progressLabel: null,
             errorCode: failed ? 'TOOL_EXECUTION_FAILED' : null,
-            truncated: outputTruncated,
+            truncated: truncated || outputTruncated,
             ...(toolName === 'Read'
                 ? {
                     toolPresentation: {

package/dist/runner/codex/conversation-parser.js

@@ -131,7 +131,8 @@ import { runnerErrorProjection } from '../runner-error.js';
 import { conversationImageAttachmentSchema } from '@myagentroam/protocol';
 import { parseCodexComposerImageMarkers } from './composer-image-markers.js';
 import { normalizeCodexTool } from './tool-normalizer.js';
-import { publicOutputSnapshot, shellExecution } from '../execution-presentation.js';
+import { shellExecution } from '../execution-presentation.js';
+import { publicOutputSnapshot } from '../normalization.js';
 import { publicGoalHistoryText } from '../../service/goal-runtime.js';
 const MAX_COMPOSER_ATTACHMENT_BYTES = 5 * 1024 * 1024;
 const MAX_COMPOSER_ATTACHMENTS_BYTES = 10 * 1024 * 1024;
@@ -553,6 +554,7 @@ export function mergeCodexCustomToolItems(invocation, result) {
                 outputPreview: resultPayload.outputPreview ??
                     resultPayload.outputSummary ??
                     invocationPayload.outputPreview,
+                ...(resultPayload.output === undefined ? {} : { output: resultPayload.output }),
                 exitCode: resultPayload.exitCode ?? invocationPayload.exitCode,
                 durationMs: resultPayload.durationMs ?? invocationPayload.durationMs,
                 truncated: invocationPayload.truncated === true || resultPayload.truncated === true,
@@ -572,6 +574,7 @@ export function mergeCodexCustomToolItems(invocation, result) {
         payload: {
             ...invocationPayload,
             outputSummary: resultPayload.outputSummary ?? invocationPayload.outputSummary,
+            ...(resultPayload.output === undefined ? {} : { output: resultPayload.output }),
             errorCode: resultPayload.errorCode ?? invocationPayload.errorCode,
             truncated: invocationPayload.truncated === true || resultPayload.truncated === true,
             ...(resultPayload.attachments === undefined ? {} : { attachments: resultPayload.attachments })
@@ -718,7 +721,6 @@ export function codexOfficialItem(session, nativeTurnId, value, turnSequence, it
                     : '(No command provided)',
                 cwd: typeof value.cwd === 'string' ? compactRunnerText(value.cwd, 4_096) : null,
                 outputPreview: publicOutputSnapshot(output).text,
-                outputRef: null,
                 exitCode: typeof value.exitCode === 'number' && Number.isInteger(value.exitCode)
                     ? value.exitCode
                     : null,
@@ -756,6 +758,7 @@ export function codexOfficialItem(session, nativeTurnId, value, turnSequence, it
                 toolName: typeof value.tool === 'string' ? value.tool : '',
                 inputSummary: codexCompactJson(value.arguments),
                 outputSummary: codexCompactJson(value.result),
+                ...(value.result == null ? {} : { output: publicOutputSnapshot(value.result) }),
                 ...(value.error === undefined ? {} : { errorCode: codexCompactJson(value.error) })
             }
         };
@@ -800,12 +803,16 @@ export function codexOfficialItem(session, nativeTurnId, value, turnSequence, it
             : typeof value.name === 'string'
                 ? value.name
                 : 'tool';
+        const outputValue = value.contentItems ?? value.output;
+        const output = outputValue == null ? undefined : publicOutputSnapshot(codexToolOutput(outputValue));
         const normalized = normalizeCodexTool({
             name,
             namespace: typeof value.namespace === 'string' ? value.namespace : 'codex',
             rawInput: value.arguments ?? value.input,
             inputSummary: codexCompactJson(value.arguments ?? value.input),
-            outputSummary: codexToolOutputSummary(value.contentItems ?? value.output),
+            outputSummary: output?.text ?? null,
+            outputTruncated: output?.truncated ?? false,
+            truncated: output?.truncated ?? false,
             outputOnly: value.type === 'custom_tool_call_output' ||
                 value.type === 'function_call_output' ||
                 value.type === 'customToolCallOutput' ||
@@ -900,7 +907,6 @@ export function codexLiveConversationItem(value, completed, imageAttachments = [
                     : '(No command provided)',
                 cwd: typeof value.cwd === 'string' ? compactRunnerText(value.cwd, 4_096) : null,
                 outputPreview: publicOutputSnapshot(output).text,
-                outputRef: null,
                 exitCode: typeof value.exitCode === 'number' && Number.isInteger(value.exitCode)
                     ? value.exitCode
                     : null,
@@ -937,6 +943,7 @@ export function codexLiveConversationItem(value, completed, imageAttachments = [
                 title: compactRunnerText(`${server}.${tool}`, 500),
                 inputSummary: input.text || null,
                 outputSummary: output.text || null,
+                ...(value.result == null ? {} : { output: publicOutputSnapshot(value.result) }),
                 progressLabel: null,
                 errorCode: error.text || null,
                 truncated: input.truncated || output.truncated || error.truncated
@@ -1013,7 +1020,8 @@ export function codexLiveConversationItem(value, completed, imageAttachments = [
                 ? value.name
                 : 'tool';
         const input = compactRunnerValue(value.arguments ?? value.input, 10_000);
-        const output = compactRunnerValue(codexToolOutput(value.contentItems ?? value.output), 10_000);
+        const outputValue = value.contentItems ?? value.output;
+        const output = outputValue == null ? undefined : publicOutputSnapshot(codexToolOutput(outputValue));
         const outputOnly = value.type === 'custom_tool_call_output' ||
             value.type === 'function_call_output' ||
             value.type === 'customToolCallOutput' ||
@@ -1023,8 +1031,9 @@ export function codexLiveConversationItem(value, completed, imageAttachments = [
             namespace: typeof value.namespace === 'string' ? value.namespace : 'codex',
             rawInput: value.arguments ?? value.input,
             inputSummary: input.text || null,
-            outputSummary: output.text || null,
-            truncated: input.truncated || output.truncated,
+            outputSummary: output?.text ?? null,
+            truncated: input.truncated || output?.truncated === true,
+            outputTruncated: output?.truncated ?? false,
             outputOnly,
             attachments: imageAttachments
         });
@@ -1067,8 +1076,7 @@ function normalizeCodexFileChanges(changes) {
                 path,
                 change,
                 additions: nonnegativeIntegerOrNull(value.additions),
-                deletions: nonnegativeIntegerOrNull(value.deletions),
-                diffAvailable: value.diffAvailable === true
+                deletions: nonnegativeIntegerOrNull(value.deletions)
             }
         ];
     });

package/dist/runner/codex/managed-run-controller.js

@@ -1,7 +1,7 @@
 import { NODE_MCP } from '../../mcp/naming.js';
 import { nodeExecutionEnvironment } from '../../node-execution-environment.js';
 import { extractId } from './conversation-parser.js';
-import { publicOutputSnapshot } from '../execution-presentation.js';
+import { publicOutputSnapshot } from '../normalization.js';
 import { normalizeCodexApproval } from './tool-normalizer.js';
 import { parseSecretEnvironment } from '../../mcp/secret-environment.js';
 import { safeErrorCode } from '../../util/safe-error.js';

package/dist/runner/codex/tool-normalizer.js

@@ -1,5 +1,5 @@
-import { compactRunnerText } from '../normalization.js';
-import { publicOutputSnapshot, shellExecution } from '../execution-presentation.js';
+import { compactRunnerText, publicOutputSnapshot } from '../normalization.js';
+import { shellExecution } from '../execution-presentation.js';
 export function normalizeCodexApproval(method) {
     return method === 'item/commandExecution/requestApproval'
         ? { toolName: 'command_execution', reason: 'Command execution requires approval.' }
@@ -9,6 +9,7 @@ export function normalizeCodexTool(input) {
     const name = compactRunnerText(input.name, 128) || 'tool';
     const rawInput = input.rawInput;
     const attachments = input.attachments ?? [];
+    const outputTruncated = input.outputTruncated ?? (input.outputSummary != null && input.truncated === true);
     const subagent = codexSubagentProjection(input.namespace, name, rawInput, input.outputSummary);
     if (isCommandTool(name)) {
         const outputPreview = compactRunnerText(input.outputSummary ?? '', 10_000);
@@ -16,12 +17,13 @@ export function normalizeCodexTool(input) {
             return {
                 kind: 'command_execution',
                 payload: {
+                    toolName: name,
                     outputPreview,
                     truncated: input.truncated === true || (input.outputSummary?.length ?? 0) > 10_000,
                     ...(input.outputSummary == null
                         ? {}
-                        : { output: publicOutputSnapshot(input.outputSummary, input.truncated === true) }),
-                    toolPresentation: shellExecution(input.outputSummary ?? undefined, input.truncated === true),
+                        : { output: publicOutputSnapshot(input.outputSummary, outputTruncated) }),
+                    toolPresentation: shellExecution(input.outputSummary ?? undefined, outputTruncated),
                     ...(attachments.length === 0 ? {} : { attachments })
                 }
             };
@@ -36,16 +38,16 @@ export function normalizeCodexTool(input) {
         return {
             kind: 'command_execution',
             payload: {
+                toolName: name,
                 command: compactRunnerText(command, 10_000),
                 cwd: typeof values?.cwd === 'string' ? compactRunnerText(values.cwd, 4_096) : null,
                 outputPreview,
-                outputRef: null,
                 exitCode: null,
                 durationMs: null,
-                toolPresentation: shellExecution(input.outputSummary ?? undefined, input.truncated === true),
+                toolPresentation: shellExecution(input.outputSummary ?? undefined, outputTruncated),
                 ...(input.outputSummary == null
                     ? {}
-                    : { output: publicOutputSnapshot(input.outputSummary, input.truncated === true) }),
+                    : { output: publicOutputSnapshot(input.outputSummary, outputTruncated) }),
                 truncated: input.truncated === true ||
                     command.length > 10_000 ||
                     (input.outputSummary?.length ?? 0) > 10_000,
@@ -57,7 +59,10 @@ export function normalizeCodexTool(input) {
         return {
             kind: 'tool_call',
             payload: {
-                outputSummary: input.outputSummary ?? null,
+                outputSummary: input.outputSummary == null ? null : compactRunnerText(input.outputSummary, 10_000),
+                ...(input.outputSummary == null
+                    ? {}
+                    : { output: publicOutputSnapshot(input.outputSummary, outputTruncated) }),
                 ...subagent,
                 ...(attachments.length === 0 ? {} : { attachments })
             }
@@ -69,7 +74,10 @@ export function normalizeCodexTool(input) {
             namespace: compactRunnerText(input.namespace ?? 'codex', 128),
             toolName: name,
             inputSummary: input.inputSummary ?? null,
-            outputSummary: input.outputSummary ?? null,
+            outputSummary: input.outputSummary == null ? null : compactRunnerText(input.outputSummary, 10_000),
+            ...(input.outputSummary == null
+                ? {}
+                : { output: publicOutputSnapshot(input.outputSummary, outputTruncated) }),
             progressLabel: null,
             errorCode: null,
             truncated: input.truncated === true,

package/dist/runner/execution-presentation.js

@@ -6,9 +6,6 @@ function tail(text, limit) {
     const first = result.charCodeAt(0);
     return first >= 0xdc00 && first <= 0xdfff ? result.slice(1) : result;
 }
-export function publicOutputSnapshot(text, truncated = false) {
-    return { text: tail(text, 10_000), truncated: truncated || text.length > 10_000 };
-}
 /** Keep public execution output bounded without copying an unbounded source. */
 export function boundExecutionPresentation(execution) {
     let truncated = (execution.output?.length ?? 0) > 4;

package/dist/runner/mar-agent/agent-network-extension.js

@@ -52,7 +52,7 @@ const tools = [
     },
     {
         action: 'send',
-        description: 'Send input, decide a child approval or update a Goal; goal:null leaves it unchanged, goal:{clear:true} clears it.',
+        description: 'Send input, decide an approval or update a Goal; goal:null leaves it unchanged, goal:{clear:true} clears it. Prefer REPLACE_CURRENT for timely communication or course correction. QUEUE is consumed only after current work and earlier queued inputs finish; an active Goal must exit first. Sending to a non-child does not subscribe to its updates.',
         properties: {
             agentId: text,
             content: { type: 'string' },
@@ -72,7 +72,7 @@ const tools = [
     },
     {
         action: 'wait',
-        description: 'Wait for completion or messages; defaults to direct children, completion and 30 seconds. Use waitMs 0 for a snapshot.',
+        description: 'Wait for completion or messages; defaults to direct children, completion and 30 seconds. Use waitMs 0 for a snapshot. Non-child targets are observed only during this call.',
         properties: {
             agentId: text,
             agentIds: { type: 'array', items: text, minItems: 1, maxItems: 8 },