@open-multi-agent/core 1.4.1 → 1.5.0

package/dist/llm/reasoning-fallback.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Shared `<thinking>` text fallback for {@link ReasoningBlock}
+ * round-tripping across adapter boundaries.
+ *
+ * When an outbound IR-to-native conversion encounters a {@link ReasoningBlock}
+ * that the target adapter cannot natively echo — either because the wire
+ * protocol does not accept reasoning input at all
+ * ({@link LLMAdapter.capabilities.echoesReasoning} `=== 'never'`) or because
+ * the block's {@link ReasoningBlock.provenance} does not match the target
+ * adapter for an `'own-issued'` adapter — this helper converts the block to
+ * an inline `<thinking>...</thinking>` text snippet that callers prepend to
+ * the next outgoing text part.
+ *
+ * SAFETY CONTRACT (one-way invariant):
+ *   The reverse direction — parsing `<thinking>` text back into a
+ *   {@link ReasoningBlock} — must never happen. A reconstructed block would
+ *   carry no verifiable signature and would be rejected if re-sent to
+ *   Anthropic / Bedrock / Gemini 3. `ReasoningBlock` instances are only ever
+ *   produced from native API extraction (and always stamped with
+ *   `provenance`), never from text parsing.
+ *
+ * Wiring (post #223 Phase 2): every adapter outbound path consults
+ * {@link ReasoningOutboundOptions} resolved from
+ * {@link AgentConfig.preserveReasoningAsText} +
+ * {@link AgentConfig.compressReasoningText}. When opt-in is off, reasoning
+ * blocks that can't be native-echoed are dropped silently (preserving
+ * pre-Phase-2 behaviour). When opt-in is on, they pass through
+ * {@link reasoningBlockToInlineText} and become inline `<thinking>` text.
+ */
+import type { ReasoningBlock } from '../types.js';
+/**
+ * Default maximum character budget per `<thinking>` block after truncation.
+ * Aligned with the value used by the OpenAI-family private replay helper
+ * shipped in #234 so the Phase 2 consolidation is behaviour-preserving.
+ */
+export declare const DEFAULT_REASONING_FALLBACK_MAX_CHARS = 1200;
+/**
+ * Sentinel value the resolver returns when the caller explicitly disables
+ * truncation (`compressReasoningText: false`). Exported so the special-case
+ * branch in {@link resolveMaxChars} stays searchable — removing the branch
+ * would silently re-introduce truncation for users who opted out.
+ *
+ * Equal to `Number.POSITIVE_INFINITY`; the resolver maps it to
+ * `Number.MAX_SAFE_INTEGER` so `text.length <= maxChars` is always true.
+ */
+export declare const NO_TRUNCATION: number;
+export interface ReasoningFallbackOptions {
+    /**
+     * Hard upper bound on the inner text length (the `<thinking>` wrapper
+     * itself is not counted). Special values:
+     *   - `undefined` → defaults to {@link DEFAULT_REASONING_FALLBACK_MAX_CHARS}.
+     *   - {@link NO_TRUNCATION} (`Number.POSITIVE_INFINITY`) → no truncation;
+     *     the entire reasoning text passes through unchanged. This is the
+     *     sentinel returned by {@link resolveReasoningOutboundMaxChars} when
+     *     the caller sets `compressReasoningText: false`.
+     *   - Any other non-finite value (`NaN`, `-Infinity`) → clamped to 1
+     *     (defensive — these values are invalid input).
+     *   - Finite values below 1 → clamped to 1.
+     *   - Finite values ≥ 1 → used as-is (floored).
+     */
+    readonly maxChars?: number;
+}
+/**
+ * Outbound-conversion options derived from {@link AgentConfig}'s reasoning
+ * fields. Threaded through every adapter's outbound IR-to-native conversion
+ * so each can opt the user into the cross-provider `<thinking>` text
+ * fallback (see #223). Internal to the LLM layer — adapters pick the values
+ * out of {@link LLMChatOptions} themselves.
+ */
+export interface ReasoningOutboundOptions {
+    /** Mirrors {@link LLMChatOptions.preserveReasoningAsText}. */
+    readonly preserveReasoningAsText?: boolean;
+    /** Mirrors {@link LLMChatOptions.compressReasoningText}. */
+    readonly compressReasoningText?: boolean | {
+        readonly minChars?: number;
+    };
+    /**
+     * Adapter name to use for native `reasoning_content` echo on outbound
+     * assistant messages inside a tool-calling conversation. Wired by adapters
+     * whose {@link LLMAdapter.capabilities.echoesReasoning} is `'tool-use-only'`
+     * (currently DeepSeek V4 thinking-mode — see PR #251 / DeepSeek API spec).
+     *
+     * When set, each assistant message is scanned for {@link ReasoningBlock}s
+     * whose {@link ReasoningBlock.provenance} matches this value. The collected
+     * reasoning is attached as a `reasoning_content` field on the outbound
+     * payload (a non-standard OpenAI-compat field) IF AND ONLY IF the overall
+     * conversation contains at least one `tool_use` block somewhere in its
+     * history. Non-tool conversations skip the attachment entirely.
+     *
+     * Foreign-provenance blocks fall through to the {@link preserveReasoningAsText}
+     * `<thinking>` text path when that flag is on, so the two mechanisms
+     * compose: native echo for own-provenance + tool-use; text fallback for
+     * everything else.
+     *
+     * Adapters that don't need this leave it unset (default `'never'` and
+     * `'own-issued'` capability paths).
+     */
+    readonly nativeReasoningEchoProvider?: string;
+}
+/**
+ * Resolve {@link ReasoningOutboundOptions} to the `maxChars` value accepted
+ * by {@link reasoningBlockToInlineText}. Encodes the
+ * default-on-when-preserve-on semantics documented in #223:
+ *
+ *   - `preserve=false`           → returns `undefined` (fallback never runs;
+ *                                  callers must check `preserve` themselves)
+ *   - `compress=undefined`/`true`→ returns `undefined` so the helper applies
+ *                                  its own default head+tail budget
+ *   - `compress=false`           → returns {@link NO_TRUNCATION}; the helper
+ *                                  treats this as a no-op cap (full text)
+ *   - `compress={minChars: N}`   → `N` (the threshold value also serves as
+ *                                  the truncation cap)
+ */
+export declare function resolveReasoningOutboundMaxChars(options: ReasoningOutboundOptions | undefined): number | undefined;
+/**
+ * Convert a {@link ReasoningBlock} into its `<thinking>...</thinking>` text
+ * representation for outbound replay through adapters that cannot natively
+ * echo reasoning.
+ *
+ * Behaviour:
+ *   - `redactedData` non-empty → returns {@link REDACTED_PLACEHOLDER} exactly.
+ *     Plaintext is unavailable so emitting the original `text` (which is
+ *     conventionally empty for redacted blocks) would yield an empty
+ *     `<thinking></thinking>` and confuse the next model; the placeholder
+ *     signals that reasoning occurred without leaking any content.
+ *   - Empty non-redacted text → returns the empty string. Callers should
+ *     skip emitting an assistant-message slot rather than pushing an empty
+ *     payload.
+ *   - Otherwise → returns `<thinking>${truncate(text)}</thinking>`.
+ */
+export declare function reasoningBlockToInlineText(block: ReasoningBlock, options?: ReasoningFallbackOptions): string;
+//# sourceMappingURL=reasoning-fallback.d.ts.map

package/dist/llm/reasoning-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-fallback.d.ts","sourceRoot":"","sources":["../../src/llm/reasoning-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,OAAO,CAAA;AAExD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAA2B,CAAA;AAQrD,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAA;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,GAAG;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACzE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,MAAM,CAAA;CAC9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,wBAAwB,GAAG,SAAS,GAC5C,MAAM,GAAG,SAAS,CAQpB;AA0BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,wBAAwB,GACjC,MAAM,CAOR"}

package/dist/llm/reasoning-fallback.js

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Shared `<thinking>` text fallback for {@link ReasoningBlock}
+ * round-tripping across adapter boundaries.
+ *
+ * When an outbound IR-to-native conversion encounters a {@link ReasoningBlock}
+ * that the target adapter cannot natively echo — either because the wire
+ * protocol does not accept reasoning input at all
+ * ({@link LLMAdapter.capabilities.echoesReasoning} `=== 'never'`) or because
+ * the block's {@link ReasoningBlock.provenance} does not match the target
+ * adapter for an `'own-issued'` adapter — this helper converts the block to
+ * an inline `<thinking>...</thinking>` text snippet that callers prepend to
+ * the next outgoing text part.
+ *
+ * SAFETY CONTRACT (one-way invariant):
+ *   The reverse direction — parsing `<thinking>` text back into a
+ *   {@link ReasoningBlock} — must never happen. A reconstructed block would
+ *   carry no verifiable signature and would be rejected if re-sent to
+ *   Anthropic / Bedrock / Gemini 3. `ReasoningBlock` instances are only ever
+ *   produced from native API extraction (and always stamped with
+ *   `provenance`), never from text parsing.
+ *
+ * Wiring (post #223 Phase 2): every adapter outbound path consults
+ * {@link ReasoningOutboundOptions} resolved from
+ * {@link AgentConfig.preserveReasoningAsText} +
+ * {@link AgentConfig.compressReasoningText}. When opt-in is off, reasoning
+ * blocks that can't be native-echoed are dropped silently (preserving
+ * pre-Phase-2 behaviour). When opt-in is on, they pass through
+ * {@link reasoningBlockToInlineText} and become inline `<thinking>` text.
+ */
+/**
+ * Default maximum character budget per `<thinking>` block after truncation.
+ * Aligned with the value used by the OpenAI-family private replay helper
+ * shipped in #234 so the Phase 2 consolidation is behaviour-preserving.
+ */
+export const DEFAULT_REASONING_FALLBACK_MAX_CHARS = 1200;
+/**
+ * Sentinel value the resolver returns when the caller explicitly disables
+ * truncation (`compressReasoningText: false`). Exported so the special-case
+ * branch in {@link resolveMaxChars} stays searchable — removing the branch
+ * would silently re-introduce truncation for users who opted out.
+ *
+ * Equal to `Number.POSITIVE_INFINITY`; the resolver maps it to
+ * `Number.MAX_SAFE_INTEGER` so `text.length <= maxChars` is always true.
+ */
+export const NO_TRUNCATION = Number.POSITIVE_INFINITY;
+/** Marker inserted between head and tail when reasoning text is truncated. */
+const TRUNCATION_MARKER = '...[truncated]...';
+/** Placeholder emitted in place of opaque encrypted (redacted) reasoning. */
+const REDACTED_PLACEHOLDER = '<thinking>[redacted]</thinking>';
+/**
+ * Resolve {@link ReasoningOutboundOptions} to the `maxChars` value accepted
+ * by {@link reasoningBlockToInlineText}. Encodes the
+ * default-on-when-preserve-on semantics documented in #223:
+ *
+ *   - `preserve=false`           → returns `undefined` (fallback never runs;
+ *                                  callers must check `preserve` themselves)
+ *   - `compress=undefined`/`true`→ returns `undefined` so the helper applies
+ *                                  its own default head+tail budget
+ *   - `compress=false`           → returns {@link NO_TRUNCATION}; the helper
+ *                                  treats this as a no-op cap (full text)
+ *   - `compress={minChars: N}`   → `N` (the threshold value also serves as
+ *                                  the truncation cap)
+ */
+export function resolveReasoningOutboundMaxChars(options) {
+    if (options?.preserveReasoningAsText !== true)
+        return undefined;
+    const compress = options.compressReasoningText;
+    if (compress === false)
+        return NO_TRUNCATION;
+    if (compress === undefined || compress === true) {
+        return undefined; // helper applies its own default when maxChars omitted
+    }
+    return compress.minChars; // undefined → helper default, number → that cap
+}
+function resolveMaxChars(value) {
+    if (value === undefined)
+        return DEFAULT_REASONING_FALLBACK_MAX_CHARS;
+    if (value === NO_TRUNCATION)
+        return Number.MAX_SAFE_INTEGER;
+    if (!Number.isFinite(value))
+        return 1;
+    const floored = Math.floor(value);
+    if (floored < 1)
+        return 1;
+    return floored;
+}
+/**
+ * Truncate `text` to at most `maxChars` characters via a head+tail excerpt
+ * with a `...[truncated]...` marker. The head receives ~70% of the budget
+ * so the model sees more of the leading reasoning steps. When `maxChars` is
+ * smaller than the marker itself, falls back to a simple head slice.
+ */
+function truncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    if (TRUNCATION_MARKER.length >= maxChars)
+        return text.slice(0, maxChars);
+    const budget = maxChars - TRUNCATION_MARKER.length;
+    const head = Math.ceil(budget * 0.7);
+    const tail = budget - head;
+    return `${text.slice(0, head)}${TRUNCATION_MARKER}${text.slice(text.length - tail)}`;
+}
+/**
+ * Convert a {@link ReasoningBlock} into its `<thinking>...</thinking>` text
+ * representation for outbound replay through adapters that cannot natively
+ * echo reasoning.
+ *
+ * Behaviour:
+ *   - `redactedData` non-empty → returns {@link REDACTED_PLACEHOLDER} exactly.
+ *     Plaintext is unavailable so emitting the original `text` (which is
+ *     conventionally empty for redacted blocks) would yield an empty
+ *     `<thinking></thinking>` and confuse the next model; the placeholder
+ *     signals that reasoning occurred without leaking any content.
+ *   - Empty non-redacted text → returns the empty string. Callers should
+ *     skip emitting an assistant-message slot rather than pushing an empty
+ *     payload.
+ *   - Otherwise → returns `<thinking>${truncate(text)}</thinking>`.
+ */
+export function reasoningBlockToInlineText(block, options) {
+    if (typeof block.redactedData === 'string' && block.redactedData.length > 0) {
+        return REDACTED_PLACEHOLDER;
+    }
+    if (block.text.length === 0)
+        return '';
+    const max = resolveMaxChars(options?.maxChars);
+    return `<thinking>${truncate(block.text, max)}</thinking>`;
+}
+//# sourceMappingURL=reasoning-fallback.js.map

package/dist/llm/reasoning-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-fallback.js","sourceRoot":"","sources":["../../src/llm/reasoning-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,IAAI,CAAA;AAExD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,iBAAiB,CAAA;AAErD,8EAA8E;AAC9E,MAAM,iBAAiB,GAAG,mBAAmB,CAAA;AAE7C,6EAA6E;AAC7E,MAAM,oBAAoB,GAAG,iCAAiC,CAAA;AAuD9D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gCAAgC,CAC9C,OAA6C;IAE7C,IAAI,OAAO,EAAE,uBAAuB,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,qBAAqB,CAAA;IAC9C,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,aAAa,CAAA;IAC5C,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,SAAS,CAAA,CAAE,uDAAuD;IAC3E,CAAC;IACD,OAAO,QAAQ,CAAC,QAAQ,CAAA,CAAE,gDAAgD;AAC5E,CAAC;AAED,SAAS,eAAe,CAAC,KAAyB;IAChD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,oCAAoC,CAAA;IACpE,IAAI,KAAK,KAAK,aAAa;QAAE,OAAO,MAAM,CAAC,gBAAgB,CAAA;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACjC,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,CAAC,CAAA;IACzB,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,QAAgB;IAC9C,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAA;IACxC,IAAI,iBAAiB,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;IACxE,MAAM,MAAM,GAAG,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAA;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAA;IACpC,MAAM,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IAC1B,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;AACtF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAqB,EACrB,OAAkC;IAElC,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5E,OAAO,oBAAoB,CAAA;IAC7B,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACtC,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAC9C,OAAO,aAAa,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,aAAa,CAAA;AAC5D,CAAC"}

package/dist/orchestrator/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator/orchestrator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator/orchestrator.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/orchestrator.js

@@ -46,6 +46,7 @@ import { emitTrace, generateRunId } from '../utils/trace.js';
 import { ToolRegistry } from '../tool/framework.js';
 import { ToolExecutor } from '../tool/executor.js';
 import { registerBuiltInTools } from '../tool/built-in/index.js';
+import { defaultWorkspaceDir } from '../tool/built-in/path-safety.js';
 import { Team } from '../team/team.js';
 import { TaskQueue } from '../task/queue.js';
 import { createTask } from '../task/task.js';
@@ -321,6 +322,21 @@ function parseTaskSpecs(raw) {
         return null;
     }
 }
+function buildRevealCoordinatorLines(revealContext, assignee) {
+    return [
+        '## Team context',
+        `Goal: ${revealContext.goal}`,
+        `Team: ${revealContext.rosterNames.join(', ')}`,
+        `Your role in this team: ${assignee}`,
+        'Assignment: You are responsible for the prompt below in this team run.',
+        '',
+    ];
+}
+function prependRevealCoordinatorContext(prompt, revealContext, assignee) {
+    return revealContext
+        ? [...buildRevealCoordinatorLines(revealContext, assignee), prompt].join('\n')
+        : prompt;
+}
 /**
  * Build {@link TeamInfo} for tool context, including nested `runDelegatedAgent`
  * that respects pool capacity to avoid semaphore deadlocks.
@@ -365,6 +381,7 @@ function buildTaskAgentTeamInfo(ctx, taskId, traceBase, delegationDepth, delegat
             provider: targetConfig.provider ?? ctx.config.defaultProvider,
             baseURL: targetConfig.baseURL ?? ctx.config.defaultBaseURL,
             apiKey: targetConfig.apiKey ?? ctx.config.defaultApiKey,
+            cwd: targetConfig.cwd === undefined ? ctx.config.defaultCwd : targetConfig.cwd,
         };
         const tempAgent = buildAgent(effective, { includeDelegateTool: true });
         const nestedTeam = buildTaskAgentTeamInfo(ctx, taskId, traceBase, delegationDepth + 1, [...delegationChain, targetAgent]);
@@ -374,7 +391,7 @@ function buildTaskAgentTeamInfo(ctx, taskId, traceBase, delegationDepth, delegat
             taskId,
             team: nestedTeam,
         };
-        return pool.runEphemeral(tempAgent, prompt, childOpts);
+        return pool.runEphemeral(tempAgent, prependRevealCoordinatorContext(prompt, ctx.revealCoordinatorContext, targetAgent), childOpts);
     };
     return {
         name: ctx.team.name,
@@ -469,7 +486,7 @@ async function executeQueue(queue, ctx) {
                 data: task,
             });
             // Build the prompt: task description + dependency-only context by default.
-            const prompt = await buildTaskPrompt(task, team, queue);
+            const prompt = await buildTaskPrompt(task, team, queue, ctx.revealCoordinatorContext);
             // Trace + abort + team tool context (delegate_to_agent)
             const traceBase = {
                 ...(config.onTrace
@@ -622,17 +639,23 @@ async function executeQueue(queue, ctx) {
  * Build the agent prompt for a specific task.
  *
  * Injects:
+ *  - Optional team-context block at the top when `revealContext` is provided
+ *    (set via `RunTeamOptions.revealCoordinator`)
  *  - Task title and description
  *  - Direct dependency task results by default (clean slate when none)
  *  - Optional full shared-memory context when `task.memoryScope === 'all'`
  *  - Any messages addressed to this agent from the team bus
  */
-async function buildTaskPrompt(task, team, queue) {
-    const lines = [
-        `# Task: ${task.title}`,
-        '',
-        task.description,
-    ];
+async function buildTaskPrompt(task, team, queue, revealContext) {
+    const lines = [];
+    // `task.assignee` is belt-and-suspenders: `executeQueue` already fails any
+    // task without an assignee before reaching this function (see the assignee
+    // check in the dispatch loop). The guard here documents the precondition and
+    // protects against future refactors that move the call site.
+    if (revealContext && task.assignee) {
+        lines.push(...buildRevealCoordinatorLines(revealContext, task.assignee));
+    }
+    lines.push(`# Task: ${task.title}`, '', task.description);
     if (task.memoryScope === 'all') {
         // Explicit opt-in for full visibility (legacy/shared-memory behavior).
         const sharedMem = team.getSharedMemoryInstance();
@@ -698,6 +721,10 @@ export class OpenMultiAgent {
             defaultProvider: config.defaultProvider ?? 'anthropic',
             defaultBaseURL: config.defaultBaseURL,
             defaultApiKey: config.defaultApiKey,
+            // `defaultCwd === undefined` means "use the default sandbox rooted at
+            // <cwd>/.agent-workspace". An explicit `null` propagates through to
+            // disable the filesystem sandbox; a string sets a custom sandbox root.
+            defaultCwd: config.defaultCwd === undefined ? defaultWorkspaceDir() : config.defaultCwd,
             maxTokenBudget: config.maxTokenBudget,
             onApproval: config.onApproval,
             onPlanReady: config.onPlanReady,
@@ -748,6 +775,7 @@ export class OpenMultiAgent {
             provider: config.provider ?? this.config.defaultProvider,
             baseURL: config.baseURL ?? this.config.defaultBaseURL,
             apiKey: config.apiKey ?? this.config.defaultApiKey,
+            cwd: config.cwd === undefined ? this.config.defaultCwd : config.cwd,
             maxTokenBudget: effectiveBudget,
         };
         const agent = buildAgent(effective);
@@ -835,6 +863,7 @@ export class OpenMultiAgent {
                 provider: bestAgent.provider ?? this.config.defaultProvider,
                 baseURL: bestAgent.baseURL ?? this.config.defaultBaseURL,
                 apiKey: bestAgent.apiKey ?? this.config.defaultApiKey,
+                cwd: bestAgent.cwd === undefined ? this.config.defaultCwd : bestAgent.cwd,
                 maxTokenBudget: effectiveBudget,
             };
             const agent = buildAgent(effective);
@@ -907,6 +936,9 @@ export class OpenMultiAgent {
             toolPreset: coordinatorOverrides?.toolPreset,
             tools: coordinatorOverrides?.tools,
             disallowedTools: coordinatorOverrides?.disallowedTools,
+            cwd: coordinatorOverrides?.cwd === undefined
+                ? this.config.defaultCwd
+                : coordinatorOverrides.cwd,
             loopDetection: coordinatorOverrides?.loopDetection,
             timeoutMs: coordinatorOverrides?.timeoutMs,
         };
@@ -980,6 +1012,14 @@ export class OpenMultiAgent {
             budgetExceededTriggered: false,
             budgetExceededReason: undefined,
             taskMetrics,
+            ...(options?.revealCoordinator
+                ? {
+                    revealCoordinatorContext: {
+                        goal,
+                        rosterNames: agentConfigs.map((a) => a.name),
+                    },
+                }
+                : {}),
         };
         const planTasks = queue.list();
         const planReadyStartMs = Date.now();
@@ -1040,6 +1080,9 @@ export class OpenMultiAgent {
         // ------------------------------------------------------------------
         // Step 5: Coordinator synthesises final result
         // ------------------------------------------------------------------
+        if (options?.abortSignal?.aborted) {
+            return this.buildTeamRunResult(agentResults, goal, taskRecords);
+        }
         if (maxTokenBudget !== undefined
             && cumulativeUsage.input_tokens + cumulativeUsage.output_tokens > maxTokenBudget) {
             return this.buildTeamRunResult(agentResults, goal, taskRecords);
@@ -1290,6 +1333,12 @@ export class OpenMultiAgent {
      */
     loadSpecsIntoQueue(specs, agentConfigs, queue) {
         const agentNames = new Set(agentConfigs.map((a) => a.name));
+        const normalizeTitle = (title) => title.toLowerCase().trim();
+        const titleCounts = new Map();
+        for (const spec of specs) {
+            const key = normalizeTitle(spec.title);
+            titleCounts.set(key, (titleCounts.get(key) ?? 0) + 1);
+        }
         // First pass: create tasks (without dependencies) to get stable IDs.
         const titleToId = new Map();
         const createdTasks = [];
@@ -1305,7 +1354,10 @@ export class OpenMultiAgent {
                 retryDelayMs: spec.retryDelayMs,
                 retryBackoff: spec.retryBackoff,
             });
-            titleToId.set(spec.title.toLowerCase().trim(), task.id);
+            const titleKey = normalizeTitle(spec.title);
+            if ((titleCounts.get(titleKey) ?? 0) === 1) {
+                titleToId.set(titleKey, task.id);
+            }
             createdTasks.push(task);
         }
         // Second pass: resolve title-based dependsOn to IDs.
@@ -1317,20 +1369,29 @@ export class OpenMultiAgent {
                 continue;
             }
             const resolvedDeps = [];
+            const unresolvedDeps = [];
             for (const depRef of spec.dependsOn) {
                 // Accept both raw IDs and title strings
                 const byId = createdTasks.find((t) => t.id === depRef);
-                const byTitle = titleToId.get(depRef.toLowerCase().trim());
+                const depTitleKey = normalizeTitle(depRef);
+                const byTitle = titleToId.get(depTitleKey);
                 const resolvedId = byId?.id ?? byTitle;
                 if (resolvedId) {
                     resolvedDeps.push(resolvedId);
                 }
+                else {
+                    const count = titleCounts.get(depTitleKey) ?? 0;
+                    unresolvedDeps.push(count > 1 ? `${depRef} (ambiguous duplicate title)` : depRef);
+                }
             }
             const taskWithDeps = {
                 ...task,
                 dependsOn: resolvedDeps.length > 0 ? resolvedDeps : undefined,
             };
             queue.add(taskWithDeps);
+            if (unresolvedDeps.length > 0) {
+                queue.fail(task.id, `Unresolved dependency reference(s): ${unresolvedDeps.join(', ')}`);
+            }
         }
     }
     /** Build an {@link AgentPool} from a list of agent configurations. */
@@ -1343,6 +1404,7 @@ export class OpenMultiAgent {
                 provider: config.provider ?? this.config.defaultProvider,
                 baseURL: config.baseURL ?? this.config.defaultBaseURL,
                 apiKey: config.apiKey ?? this.config.defaultApiKey,
+                cwd: config.cwd === undefined ? this.config.defaultCwd : config.cwd,
             };
             pool.add(buildAgent(effective, { includeDelegateTool: true }));
         }