@botbotgo/agent-harness 0.0.464 → 0.0.466

package/dist/contracts/workspace.d.ts

@@ -211,6 +211,10 @@ export type CompiledBuiltinToolsConfig = {
 };
 export type CompiledExecutionContract = {
     requiresPlan?: boolean;
+    recoveryEvidenceTool?: {
+        name: string;
+        args?: Record<string, unknown>;
+    };
 };
 export type LangChainAgentParams = {
     model: CompiledModel;

package/dist/package-version.d.ts

@@ -1,2 +1,2 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.464";
+export declare const AGENT_HARNESS_VERSION = "0.0.466";
 export declare const AGENT_HARNESS_RELEASE_DATE = "2026-05-04";

package/dist/package-version.js

@@ -1,2 +1,2 @@
-export const AGENT_HARNESS_VERSION = "0.0.464";
+export const AGENT_HARNESS_VERSION = "0.0.466";
 export const AGENT_HARNESS_RELEASE_DATE = "2026-05-04";

package/dist/runtime/adapter/flow/stream-runtime.js

@@ -137,6 +137,26 @@ function hasIncompletePlanOutput(value) {
     }
     return null;
 }
+function hasFailedTodos(value) {
+    if (Array.isArray(value)) {
+        return value.some((todo) => hasFailedTodos(todo));
+    }
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const typed = value;
+    if (typeof typed.status === "string" && typed.status.trim().toLowerCase() === "failed") {
+        return true;
+    }
+    return hasFailedTodos(typed.todos)
+        || hasFailedTodos(typed.update)
+        || hasFailedTodos(typed.data)
+        || hasFailedTodos(typed.output)
+        || hasFailedTodos(typed.summary);
+}
+function hasFailedPlanStateInExecutedToolResults(executedToolResults) {
+    return executedToolResults.some((item) => isPlanToolName(item.toolName) && hasFailedTodos(item.output));
+}
 function normalizePlanToolName(toolName) {
     return typeof toolName === "string" ? toolName.trim().toLowerCase().replace(/[\s-]+/gu, "_") : "";
 }
@@ -199,6 +219,9 @@ function buildExecutionRecoveryEvidence(params) {
         hasNonTodoToolResultEvidence: hasNonTodoToolEvidence(executedToolResults) || projectionState.emittedNonTodoToolResult || projectionState.emittedToolError,
         hasSuccessfulNonTodoToolResultEvidence: hasSuccessfulNonTodoToolEvidence(executedToolResults) || projectionState.emittedSuccessfulNonTodoToolResult,
         hasIncompletePlanState: projectionState.hasIncompletePlanState || hasIncompletePlanStateInExecutedToolResults(executedToolResults),
+        hasFailedPlanState: (projectionState.hasFailedPlanState || hasFailedPlanStateInExecutedToolResults(executedToolResults))
+            && !projectionState.emittedSuccessfulNonTodoToolResult
+            && !hasSuccessfulNonTodoToolEvidence(executedToolResults),
         hasPlanStateEvidence: projectionState.sawPlanState || hasIncompletePlanStateInExecutedToolResults(executedToolResults),
         hasOpenTaskDelegation: projectionState.openTaskDelegations > 0,
         hasFailedTaskDelegation: projectionState.hasFailedTaskDelegation
@@ -213,6 +236,7 @@ function buildExecutionRecoveryEvidence(params) {
 }
 function hasUnresolvedExecution(evidence) {
     return (evidence.hasIncompletePlanState
+        || evidence.hasFailedPlanState
         || evidence.hasFailedTaskDelegation
         || evidence.hasOpenTaskDelegation);
 }
@@ -389,6 +413,9 @@ function createUnresolvedExecutionError(evidence) {
     if (evidence.hasIncompletePlanState) {
         reasons.push("plan state still has unfinished work");
     }
+    if (evidence.hasFailedPlanState) {
+        reasons.push("plan state failed before non-TODO evidence returned");
+    }
     if (evidence.hasFailedTaskDelegation) {
         reasons.push("delegated task failed before surfacing final findings");
     }
@@ -471,7 +498,8 @@ function projectLocalToolExecutionProfileChunks(executedToolResults, prefix) {
 }
 export async function* streamRuntimeExecution(options) {
     let request = buildInvocationRequest(options.binding, options.history, options.input, options.runtimeOptions);
-    if (requiresPlanEvidence(options.binding)) {
+    if (requiresPlanEvidence(options.binding)
+        && options.runtimeOptions.suppressInitialRequiredPlanInstruction !== true) {
         request = withPromptedJsonToolPolicy(appendToolRecoveryInstruction(request, buildInitialRequiredPlanInstruction(options.primaryTools)), "planning");
     }
     let emittedUnsafeStreamSideEffects = false;
@@ -480,6 +508,14 @@ export async function* streamRuntimeExecution(options) {
     const deferredStreamContent = [];
     let sawRetrySafeInvalidToolSelectionError = false;
     const projectionState = createStreamEventProjectionState();
+    if (options.runtimeOptions.externalPlanEvidence === true) {
+        projectionState.sawPlanState = true;
+        yield {
+            kind: "commentary",
+            content: `${options.binding.agent.id}: TODO evidence observed.`,
+            agentId: options.binding.agent.id,
+        };
+    }
     const requestId = options.runtimeOptions.requestId ?? options.sessionId;
     const buildRunnableConfig = (extra) => ({
         ...(options.resolveInvocationConfig
@@ -523,6 +559,7 @@ export async function* streamRuntimeExecution(options) {
             try {
                 const rawStreamInput = buildRawModelMessages(options.binding, options.getSystemPrompt(options.binding), options.history, options.input, options.runtimeOptions.memoryContext);
                 const streamInput = requiresPlanEvidence(options.binding)
+                    && options.runtimeOptions.suppressInitialRequiredPlanInstruction !== true
                     ? withPromptedJsonToolPolicy(rawStreamInput, "planning")
                     : rawStreamInput;
                 stream = await options.withTimeout(() => options.langChainStreamModel.stream(streamInput), computeRemainingTimeoutMs(options.streamDeadlineAt, options.invokeTimeoutMs), "model stream start", "stream");
@@ -865,6 +902,35 @@ export async function* streamRuntimeExecution(options) {
                         const recoveredToolResults = Array.isArray(recovered.metadata?.executedToolResults)
                             ? recovered.metadata.executedToolResults
                             : [];
+                        const originalExecutionEvidence = buildExecutionRecoveryEvidence({ projectionState });
+                        const recoveredExecutionEvidence = buildExecutionRecoveryEvidence({
+                            projectionState: createStreamEventProjectionState(),
+                            executedToolResults: recoveredToolResults,
+                        });
+                        const recoveredCarriesExecutionEvidence = recoveredExecutionEvidence.hasSuccessfulNonTodoToolResultEvidence
+                            || recoveredExecutionEvidence.hasOpenTaskDelegation
+                            || recoveredExecutionEvidence.hasDelegatedExecutionToolEvidence;
+                        const recoveredHasUnresolvedExecution = hasUnresolvedExecution(recoveredExecutionEvidence)
+                            || hasMissingDelegatedExecutionEvidence(recoveredExecutionEvidence)
+                            || hasMissingDelegatedFindings(recoveredExecutionEvidence)
+                            || (!recoveredCarriesExecutionEvidence
+                                && (hasUnresolvedExecution(originalExecutionEvidence)
+                                    || hasMissingDelegatedExecutionEvidence(originalExecutionEvidence)
+                                    || hasMissingDelegatedFindings(originalExecutionEvidence)));
+                        if (recoveredHasUnresolvedExecution) {
+                            const effectiveRecoveryEvidence = recoveredCarriesExecutionEvidence
+                                ? recoveredExecutionEvidence
+                                : {
+                                    ...recoveredExecutionEvidence,
+                                    hasIncompletePlanState: originalExecutionEvidence.hasIncompletePlanState,
+                                    hasFailedPlanState: originalExecutionEvidence.hasFailedPlanState,
+                                    hasFailedTaskDelegation: originalExecutionEvidence.hasFailedTaskDelegation,
+                                    hasOpenTaskDelegation: originalExecutionEvidence.hasOpenTaskDelegation,
+                                    hasDelegatedAgentWithConfiguredTools: originalExecutionEvidence.hasDelegatedAgentWithConfiguredTools,
+                                    hasDelegatedExecutionToolEvidence: originalExecutionEvidence.hasDelegatedExecutionToolEvidence,
+                                };
+                            throw createUnresolvedExecutionError(effectiveRecoveryEvidence);
+                        }
                         for (const toolResult of recoveredToolResults) {
                             yield {
                                 kind: "tool-result",
@@ -997,7 +1063,7 @@ export async function* streamRuntimeExecution(options) {
                 }
                 const retriedVisibleOutput = retried.output ? toVisibleContent(retried.output) : "";
                 const retriedIsDelegationFailureFinalReport = isDelegationFailureFinalReport(originalExecutionEvidence, executedToolResults, retriedVisibleOutput);
-                const retriedCarriesExecutionEvidence = retriedExecutionEvidence.hasToolResultEvidence
+                const retriedCarriesExecutionEvidence = retriedExecutionEvidence.hasSuccessfulNonTodoToolResultEvidence
                     || retriedExecutionEvidence.hasOpenTaskDelegation
                     || retriedExecutionEvidence.hasDelegatedExecutionToolEvidence;
                 const retriedHasUnresolvedExecution = !retriedIsDelegationFailureFinalReport
@@ -1013,6 +1079,7 @@ export async function* streamRuntimeExecution(options) {
                     : {
                         ...retriedExecutionEvidence,
                         hasIncompletePlanState: originalExecutionEvidence.hasIncompletePlanState,
+                        hasFailedPlanState: originalExecutionEvidence.hasFailedPlanState,
                         hasFailedTaskDelegation: originalExecutionEvidence.hasFailedTaskDelegation,
                         hasOpenTaskDelegation: originalExecutionEvidence.hasOpenTaskDelegation,
                         hasDelegatedAgentWithConfiguredTools: originalExecutionEvidence.hasDelegatedAgentWithConfiguredTools,
@@ -1254,6 +1321,7 @@ export async function* streamRuntimeExecution(options) {
                 : {
                     ...recoveredExecutionEvidence,
                     hasIncompletePlanState: originalExecutionEvidence.hasIncompletePlanState,
+                    hasFailedPlanState: originalExecutionEvidence.hasFailedPlanState,
                     hasFailedTaskDelegation: originalExecutionEvidence.hasFailedTaskDelegation,
                     hasOpenTaskDelegation: originalExecutionEvidence.hasOpenTaskDelegation,
                     hasDelegatedAgentWithConfiguredTools: originalExecutionEvidence.hasDelegatedAgentWithConfiguredTools,

package/dist/runtime/adapter/local-tool-invocation.js

@@ -13,8 +13,10 @@ const TOOL_FOLLOW_UP_INSTRUCTION = "One or more tool results are already availab
 const DEFAULT_MAX_TOOL_ITERATIONS = 10_000;
 const MAX_REPEATED_RECOVERY_WITHOUT_PROGRESS = 2;
 const MAX_REPEATED_PLAN_ONLY_AFTER_PLAN = 2;
+const MAX_REPEATED_INVALID_EXTERNAL_PLAN_EVIDENCE_SELECTION = 2;
 const REQUIRED_PLAN_CONTRACT_MARKER = "This agent has a required visible planning contract.";
 const INITIAL_WRITE_TODOS_MARKER = "Your first action for this request must be write_todos";
+const REQUIRED_SINGLE_EXTERNAL_PLAN_EVIDENCE_TOOL_INSTRUCTION = "The TODO board already exists. The next action must be exactly one non-planning evidence tool call. Do not call write_todos or read_todos, and do not call multiple tools in the same response.";
 function resolveSingleBootstrapEvidenceTool(primaryTools) {
     const evidenceTools = primaryTools
         .map((tool) => typeof tool.name === "string" ? tool.name.trim() : "")
@@ -142,6 +144,10 @@ function isPlanToolName(toolName) {
         || normalized === "call_write_todos"
         || normalized === "call_read_todos";
 }
+function isPlanToolCall(toolCall, toolNameMapping, primaryTools) {
+    const resolvedToolName = resolveModelFacingToolName(String(toolCall.name ?? ""), toolNameMapping, primaryTools);
+    return isPlanToolName(toolCall.name) || isPlanToolName(resolvedToolName);
+}
 function isFallbackTodoCompletionToolCall(toolCall) {
     return typeof toolCall.id === "string"
         && toolCall.id.startsWith("fallback-complete-")
@@ -222,7 +228,11 @@ function extractLatestUserInput(request) {
     const messages = Array.isArray(typedRequest.messages) ? typedRequest.messages : [];
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const candidate = messages[index];
-        if (candidate?.role !== "user" || typeof candidate.content !== "string") {
+        const role = typeof candidate?.role === "string" ? candidate.role.trim().toLowerCase() : "";
+        const messageType = typeof candidate?._getType === "function" ? String(candidate._getType()).trim().toLowerCase() : "";
+        const constructorType = Array.isArray(candidate?.id) ? String(candidate.id.at(-1)).trim().toLowerCase() : "";
+        const isUserMessage = role === "user" || role === "human" || messageType === "human" || constructorType === "humanmessage";
+        if (!isUserMessage || typeof candidate?.content !== "string") {
             continue;
         }
         const normalized = candidate.content.trim();
@@ -284,6 +294,7 @@ export async function runLocalToolInvocationLoop({ binding, request, primaryTool
     let lastRecoveryExecutedCount = -1;
     let repeatedRecoveryWithoutProgress = 0;
     let repeatedPlanOnlyAfterPlan = 0;
+    let repeatedInvalidExternalPlanEvidenceSelection = 0;
     let pendingResult;
     let result;
     const toolCatalog = new Map();
@@ -422,6 +433,26 @@ export async function runLocalToolInvocationLoop({ binding, request, primaryTool
             activeRequest = appendToolRecoveryInstruction(activeRequest, missingPlanRecoveryInstruction);
             continue;
         }
+        if (requiresPlanEvidence(binding)
+            && externalPlanEvidence === true
+            && hasPlanStateEvidence(executedToolResults, externalPlanEvidence)
+            && !hasNonTodoToolEvidence(executedToolResults)
+            && toolCalls.length > 0
+            && (toolCalls.length !== 1 || isPlanToolCall(toolCalls[0], toolNameMapping, primaryTools))) {
+            repeatedInvalidExternalPlanEvidenceSelection += 1;
+            if (repeatedInvalidExternalPlanEvidenceSelection >= MAX_REPEATED_INVALID_EXTERNAL_PLAN_EVIDENCE_SELECTION) {
+                throw createToolLoopError({
+                    reason: "model did not select exactly one non-planning evidence tool during delegated plan evidence recovery",
+                    iteration,
+                    maxToolIterations,
+                    toolCalls,
+                    executedToolResults,
+                });
+            }
+            activeRequest = appendToolRecoveryInstruction(activeRequest, REQUIRED_SINGLE_EXTERNAL_PLAN_EVIDENCE_TOOL_INSTRUCTION);
+            pendingResult = undefined;
+            continue;
+        }
         if (requiresPlanEvidence(binding)
             && hasPlanStateEvidence(executedToolResults, externalPlanEvidence)
             && !hasNonTodoToolEvidence(executedToolResults)
@@ -429,6 +460,12 @@ export async function runLocalToolInvocationLoop({ binding, request, primaryTool
             && toolCalls.every((toolCall) => isPlanToolName(toolCall.name))) {
             repeatedPlanOnlyAfterPlan += 1;
             if (repeatedPlanOnlyAfterPlan >= MAX_REPEATED_PLAN_ONLY_AFTER_PLAN) {
+                if (hasNonTodoToolEvidence(executedToolResults)) {
+                    return {
+                        result: buildDeterministicFinalFromToolEvidence(executedToolResults),
+                        executedToolResults,
+                    };
+                }
                 throw createToolLoopError({
                     reason: "model repeatedly selected only planning tools after the todo board already existed and before any non-planning evidence tool returned",
                     iteration,
@@ -438,6 +475,12 @@ export async function runLocalToolInvocationLoop({ binding, request, primaryTool
                 });
             }
             if (iteration + 1 === maxToolIterations) {
+                if (hasNonTodoToolEvidence(executedToolResults)) {
+                    return {
+                        result: buildDeterministicFinalFromToolEvidence(executedToolResults),
+                        executedToolResults,
+                    };
+                }
                 throw createToolLoopError({
                     reason: "maximum iterations reached",
                     iteration,
@@ -452,6 +495,7 @@ export async function runLocalToolInvocationLoop({ binding, request, primaryTool
         }
         repeatedRecoveryWithoutProgress = 0;
         repeatedPlanOnlyAfterPlan = 0;
+        repeatedInvalidExternalPlanEvidenceSelection = 0;
         const canReplayToolCalls = usedExternalPlanEvidenceToolThisIteration
             || canReplayToolCallsLocally(binding, toolCalls, primaryTools, toolNameMapping, executableTools, builtinExecutableTools);
         debugLocalToolReplay({

package/dist/runtime/adapter/runtime-adapter-support.js

@@ -69,6 +69,13 @@ function readTodoContent(todo) {
     }
     return "";
 }
+function isLowSignalTodoContent(content) {
+    const normalized = content.trim().toLowerCase();
+    if (!normalized) {
+        return true;
+    }
+    return /^\d+$/.test(normalized) || /^step\s*\d+$/.test(normalized) || /^todo\s*\d+$/.test(normalized);
+}
 function normalizeTodoStatus(value) {
     if (typeof value !== "string") {
         return "pending";
@@ -90,6 +97,9 @@ export function summarizeBuiltinWriteTodosArgs(args) {
             return [];
         }
         const content = readTodoContent(todo);
+        if (isLowSignalTodoContent(content)) {
+            return [];
+        }
         const status = normalizeTodoStatus(todo.status);
         const metadata = isRecord(todo.metadata) ? todo.metadata : undefined;
         return content ? [{

package/dist/runtime/adapter/stream-event-projection.d.ts

@@ -17,6 +17,7 @@ export type StreamEventProjectionState = {
     emittedDelegatedTerminalOutput: boolean;
     sawPlanState: boolean;
     hasIncompletePlanState: boolean;
+    hasFailedPlanState: boolean;
     openTaskDelegations: number;
     openToolCapableTaskDelegations: number;
     taskDelegationHasToolsStack: boolean[];

package/dist/runtime/adapter/stream-event-projection.js

@@ -19,6 +19,7 @@ export function createStreamEventProjectionState() {
         emittedDelegatedTerminalOutput: false,
         sawPlanState: false,
         hasIncompletePlanState: false,
+        hasFailedPlanState: false,
         openTaskDelegations: 0,
         openToolCapableTaskDelegations: 0,
         taskDelegationHasToolsStack: [],
@@ -153,6 +154,16 @@ function readSummaryCounts(summary) {
         inProgress: typeof typed.inProgress === "number" ? typed.inProgress : 0,
     };
 }
+function readSummaryFailureCount(summary) {
+    if (typeof summary !== "object" || summary === null) {
+        return null;
+    }
+    const typed = summary;
+    if (typeof typed.total === "number" && typed.total <= 0) {
+        return null;
+    }
+    return typeof typed.failed === "number" ? typed.failed : null;
+}
 function hasIncompleteTodosArray(value) {
     if (!Array.isArray(value)) {
         return null;
@@ -168,6 +179,20 @@ function hasIncompleteTodosArray(value) {
         return status === "pending" || status === "in_progress";
     });
 }
+function hasFailedTodosArray(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    if (value.length === 0) {
+        return null;
+    }
+    return value.some((item) => {
+        if (typeof item !== "object" || item === null) {
+            return false;
+        }
+        return item.status === "failed";
+    });
+}
 function getPlanStateCompleteness(value) {
     if (typeof value !== "object" || value === null) {
         return null;
@@ -207,6 +232,45 @@ function getPlanStateCompleteness(value) {
     }
     return null;
 }
+function getPlanStateFailure(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const typed = value;
+    const summaryFailed = readSummaryFailureCount(typed.summary);
+    if (summaryFailed !== null) {
+        return summaryFailed > 0;
+    }
+    if (typeof typed.summary === "object" && typed.summary !== null) {
+        const nestedSummary = getPlanStateFailure(typed.summary);
+        if (nestedSummary !== null) {
+            return nestedSummary;
+        }
+    }
+    const directTodos = hasFailedTodosArray(typed.todos);
+    if (directTodos !== null) {
+        return directTodos;
+    }
+    if (typeof typed.update === "object" && typed.update !== null) {
+        const nestedTodos = hasFailedTodosArray(typed.update.todos);
+        if (nestedTodos !== null) {
+            return nestedTodos;
+        }
+    }
+    if (typeof typed.output === "object" && typed.output !== null) {
+        const nestedOutput = getPlanStateFailure(typed.output);
+        if (nestedOutput !== null) {
+            return nestedOutput;
+        }
+    }
+    if (typeof typed.data === "object" && typed.data !== null) {
+        const nestedData = getPlanStateFailure(typed.data);
+        if (nestedData !== null) {
+            return nestedData;
+        }
+    }
+    return null;
+}
 function parseMaybeJsonString(value) {
     const trimmed = value.trim();
     if (!trimmed || (!trimmed.startsWith("{") && !trimmed.startsWith("["))) {
@@ -435,6 +499,11 @@ export function projectRuntimeStreamEvent(params) {
         state.sawPlanState = true;
         state.hasIncompletePlanState = planStateCompleteness;
     }
+    const planStateFailure = getPlanStateFailure(event);
+    if (planStateFailure !== null) {
+        state.sawPlanState = true;
+        state.hasFailedPlanState = planStateFailure;
+    }
     const eventAgentId = typeof event === "object" && event !== null && typeof event.agentId === "string"
         ? event.agentId.trim()
         : "";

package/dist/runtime/adapter/tool/tool-arguments.js

@@ -86,6 +86,19 @@ function readSchemaDescription(schemaPart) {
     }
     return readSchemaDescription(def?.innerType);
 }
+function schemaPartExpectsString(schemaPart) {
+    if (!isObject(schemaPart)) {
+        return false;
+    }
+    if (schemaPart.type === "string") {
+        return true;
+    }
+    const def = schemaPart._def ?? schemaPart.def;
+    if (def?.typeName === "ZodString" || def?.type === "string") {
+        return true;
+    }
+    return schemaPartExpectsString(def?.innerType);
+}
 function fillLatestUserInputForQueryLikeFields(args, shape, latestUserInput) {
     const userInput = typeof latestUserInput === "string" ? latestUserInput.trim() : "";
     if (!userInput) {
@@ -100,7 +113,7 @@ function fillLatestUserInputForQueryLikeFields(args, shape, latestUserInput) {
         const description = readSchemaDescription(schemaPart);
         const keyIsQueryLike = ["query", "question", "prompt", "input", "text"].includes(normalizedKey);
         const descriptionIsQueryLike = /\b(?:query|question|prompt|input|text)\b/iu.test(description);
-        if (!keyIsQueryLike && !descriptionIsQueryLike) {
+        if ((!keyIsQueryLike && !descriptionIsQueryLike) || !schemaPartExpectsString(schemaPart)) {
             continue;
         }
         next = {
@@ -110,6 +123,27 @@ function fillLatestUserInputForQueryLikeFields(args, shape, latestUserInput) {
     }
     return next;
 }
+function fillLatestUserInputForResourceArrayFields(args, shape, latestUserInput) {
+    const userInput = typeof latestUserInput === "string" ? latestUserInput.trim() : "";
+    if (!userInput || !hasExplicitResourceReference(userInput)) {
+        return args;
+    }
+    const resourceRefs = extractExplicitResourceReferences(userInput);
+    if (resourceRefs.length === 0) {
+        return args;
+    }
+    let next = args;
+    for (const [key, schemaPart] of Object.entries(shape)) {
+        if (key in next || !schemaPartExpectsArray(schemaPart)) {
+            continue;
+        }
+        const mapped = resourceRefs.map((ref) => inferDiscriminatedArrayObjectFromString(schemaPart, ref));
+        if (mapped.length > 0 && mapped.every((item) => item !== null)) {
+            next = { ...next, [key]: mapped };
+        }
+    }
+    return next;
+}
 function mapCommonArgumentAliases(args, shape) {
     let next = args;
     if ("args" in shape && !("args" in next) && Array.isArray(next.argv)) {
@@ -133,10 +167,96 @@ function schemaPartExpectsArray(schemaPart) {
     }
     return schemaPartExpectsArray(def?.innerType);
 }
+function readObjectShape(schemaPart) {
+    if (!isObject(schemaPart)) {
+        return undefined;
+    }
+    const def = schemaPart._def ?? schemaPart.def;
+    if (!def) {
+        return undefined;
+    }
+    const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+    return isRecord(shape) ? shape : readObjectShape(def.innerType);
+}
+function readLiteralValue(schemaPart) {
+    if (!isObject(schemaPart)) {
+        return undefined;
+    }
+    const def = schemaPart._def ?? schemaPart.def;
+    if ((def?.typeName === "ZodLiteral" || def?.type === "literal") && typeof def.value === "string") {
+        return def.value;
+    }
+    if ((def?.typeName === "ZodLiteral" || def?.type === "literal") && Array.isArray(def.values) && typeof def.values[0] === "string") {
+        return def.values[0];
+    }
+    return readLiteralValue(def?.innerType);
+}
+function readArrayElementSchema(schemaPart) {
+    if (!isObject(schemaPart)) {
+        return undefined;
+    }
+    const def = schemaPart._def ?? schemaPart.def;
+    if (def?.typeName === "ZodArray" || def?.type === "array") {
+        return def.element ?? def.type;
+    }
+    return readArrayElementSchema(def?.innerType);
+}
+function inferDiscriminatedArrayObjectFromString(schemaPart, value) {
+    const raw = value.trim();
+    if (!raw) {
+        return null;
+    }
+    const elementSchema = readArrayElementSchema(schemaPart);
+    if (!isObject(elementSchema)) {
+        return null;
+    }
+    const def = elementSchema._def ?? elementSchema.def;
+    const options = Array.isArray(def?.options)
+        ? def.options
+        : Array.isArray(elementSchema.options)
+            ? elementSchema.options
+            : undefined;
+    if (def?.typeName !== "ZodDiscriminatedUnion"
+        && !(def?.type === "union" && typeof def.discriminator === "string")) {
+        return null;
+    }
+    if (typeof def.discriminator !== "string" || !options) {
+        return null;
+    }
+    const looksLikeUrl = /^https?:\/\/\S+$/iu.test(raw);
+    for (const option of options) {
+        const optionShape = readObjectShape(option);
+        if (!optionShape) {
+            continue;
+        }
+        const discriminatorValue = readLiteralValue(optionShape[def.discriminator]);
+        if (!discriminatorValue) {
+            continue;
+        }
+        if (looksLikeUrl && "url" in optionShape) {
+            return { [def.discriminator]: discriminatorValue, url: raw };
+        }
+        const looksLikePath = /^(?:\.{1,2}\/|\/|~\/|[A-Za-z]:[\\/])|\\|\.[A-Za-z0-9]{1,12}$/u.test(raw);
+        if (!looksLikeUrl && looksLikePath && "path" in optionShape && !raw.includes("\n")) {
+            return { [def.discriminator]: discriminatorValue, path: raw };
+        }
+        if ("text" in optionShape) {
+            return { [def.discriminator]: discriminatorValue, text: raw };
+        }
+    }
+    return null;
+}
 function mapStringArrayFields(args, shape) {
     let next = args;
     for (const [key, schemaPart] of Object.entries(shape)) {
         const value = next[key];
+        if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+            const mapped = value.map((item) => inferDiscriminatedArrayObjectFromString(schemaPart, item));
+            if (mapped.length > 0 && mapped.every((item) => item !== null)) {
+                next = { ...next, [key]: mapped };
+            }
+            continue;
+        }
         if (typeof value !== "string") {
             continue;
         }
@@ -175,6 +295,9 @@ function mapDelimitedListLikeArgs(args) {
     }
     return next;
 }
+function stripArgsToShape(args, shape) {
+    return Object.fromEntries(Object.entries(args).filter(([key]) => key in shape));
+}
 function dropDelimitedScalarPathArgs(args, shape) {
     let next = args;
     for (const [key, schemaPart] of Object.entries(shape)) {
@@ -199,7 +322,10 @@ function dropDelimitedScalarPathArgs(args, shape) {
     return next;
 }
 export function normalizeToolArgsForSchema(args, schema, rawArgsInput, options = {}) {
-    const schemaDef = isObject(schema) ? schema._def : undefined;
+    const schemaDef = isObject(schema)
+        ? (schema._def
+            ?? schema.def)
+        : undefined;
     const zodShape = schemaDef
         ? isRecord(schemaDef.shape)
             ? schemaDef.shape
@@ -210,38 +336,47 @@ export function normalizeToolArgsForSchema(args, schema, rawArgsInput, options =
     const jsonShape = isObject(schema) && isRecord(schema.properties)
         ? (schema.properties ?? undefined)
         : undefined;
-    const shape = zodShape && isRecord(zodShape) ? zodShape : jsonShape;
+    const plainShape = isObject(schema)
+        && !("_def" in schema)
+        && !("properties" in schema)
+        && Object.values(schema).every((value) => isObject(value))
+        ? schema
+        : undefined;
+    const shape = zodShape && isRecord(zodShape) ? zodShape : jsonShape ?? plainShape;
     if (!shape || !isRecord(shape)) {
         return mapDelimitedListLikeArgs(args);
     }
-    const aliasMappedArgs = dropDelimitedScalarPathArgs(mapStringArrayFields(mapCommonArgumentAliases(args, shape), shape), shape);
+    const stripUnknownArgs = plainShape !== undefined && !zodShape && !jsonShape;
+    const aliasMappedArgs = dropDelimitedScalarPathArgs(fillLatestUserInputForResourceArrayFields(mapStringArrayFields(mapCommonArgumentAliases(args, shape), shape), shape, options.latestUserInput), shape);
     const keys = Object.keys(shape);
     if (keys.length !== 1) {
-        return fillLatestUserInputForQueryLikeFields(aliasMappedArgs, shape, options.latestUserInput);
+        const filled = fillLatestUserInputForQueryLikeFields(aliasMappedArgs, shape, options.latestUserInput);
+        return stripUnknownArgs ? stripArgsToShape(filled, shape) : filled;
     }
     const [expectedKey] = keys;
     if (expectedKey in aliasMappedArgs) {
-        return aliasMappedArgs;
+        return stripUnknownArgs ? stripArgsToShape(aliasMappedArgs, shape) : aliasMappedArgs;
     }
     const scalarMappedArgs = mapSingleFieldScalarArg(aliasMappedArgs, expectedKey, rawArgsInput);
     if (expectedKey in scalarMappedArgs) {
-        return scalarMappedArgs;
+        return stripUnknownArgs ? stripArgsToShape(scalarMappedArgs, shape) : scalarMappedArgs;
     }
     if (Object.keys(scalarMappedArgs).length === 0 && typeof options.latestUserInput === "string") {
         const userInput = options.latestUserInput.trim();
         const resourceRefs = extractExplicitResourceReferences(userInput);
         if (resourceRefs.length === 1 && hasExplicitResourceReference(userInput)) {
-            return {
+            const filled = {
                 ...scalarMappedArgs,
                 [expectedKey]: resourceRefs[0],
             };
+            return stripUnknownArgs ? stripArgsToShape(filled, shape) : filled;
         }
     }
     const genericScalarMappedArgs = mapSingleRemainingScalarArg(scalarMappedArgs, expectedKey);
     if (expectedKey in genericScalarMappedArgs) {
-        return genericScalarMappedArgs;
+        return stripUnknownArgs ? stripArgsToShape(genericScalarMappedArgs, shape) : genericScalarMappedArgs;
     }
-    return genericScalarMappedArgs;
+    return stripUnknownArgs ? stripArgsToShape(genericScalarMappedArgs, shape) : genericScalarMappedArgs;
 }
 export function extractToolCallsFromResult(result) {
     const capturedToolCalls = readCapturedPromptedJsonToolCalls(result);

package/dist/runtime/agent-runtime-adapter.d.ts

@@ -62,6 +62,11 @@ export declare class AgentRuntimeAdapter {
         toolRuntimeContext?: Record<string, unknown>;
         suppressInitialRequiredPlanInstruction?: boolean;
         externalPlanEvidence?: boolean;
+        externalPlanEvidenceTools?: Array<{
+            name: string;
+            args?: Record<string, unknown>;
+            id?: string;
+        }>;
     }): Promise<RequestResult>;
     private tryDelegateWithCompactRouter;
     private buildCompactDelegationReport;
@@ -75,6 +80,13 @@ export declare class AgentRuntimeAdapter {
         memoryContext?: string;
         profiling?: boolean;
         toolRuntimeContext?: Record<string, unknown>;
+        suppressInitialRequiredPlanInstruction?: boolean;
+        externalPlanEvidence?: boolean;
+        externalPlanEvidenceTools?: Array<{
+            name: string;
+            args?: Record<string, unknown>;
+            id?: string;
+        }>;
     }): AsyncGenerator<RuntimeStreamChunk | string>;
 }
 export { AgentRuntimeAdapter as RuntimeAdapter, AGENT_INTERRUPT_SENTINEL_PREFIX, AGENT_INTERRUPT_SENTINEL_PREFIX as INTERRUPT_SENTINEL_PREFIX, buildDeepAgentCreateParams, buildLangChainCreateParams, DEFAULT_DEEPAGENT_RECURSION_LIMIT, materializeModelExposedBuiltinMiddlewareTools, resolveLangChainInvocationConfig, resolveRunnableCheckpointer, resolveRunnableInterruptOn, RuntimeOperationTimeoutError, };

package/dist/runtime/agent-runtime-adapter.js

@@ -8,7 +8,9 @@ import { extractMessageText } from "../utils/message-content.js";
 import { AGENT_INTERRUPT_SENTINEL_PREFIX, buildDeepAgentCreateParams, buildDeepAgentSystemPromptWithCapabilityCatalog, buildLangChainCreateParams, DEFAULT_DEEPAGENT_RECURSION_LIMIT, materializeModelExposedBuiltinMiddlewareTools, resolveLangChainInvocationConfig, resolveRunnableCheckpointer, resolveRunnableInterruptOn, shouldAttachDeepAgentBackend, shouldAttachDeepAgentCheckpointer, shouldAttachDeepAgentStore, } from "./agent-runtime-assembly.js";
 import { resolveDeepAgentSkillSourcePaths, resolveDeepAgentSkillSourceRootPaths, } from "./adapter/compat/deepagent-compat.js";
 import { buildToolNameMapping, } from "./adapter/tool/tool-name-mapping.js";
+import { PROMPTED_JSON_TOOL_POLICY_KEY } from "./adapter/model/prompted-json-tool-policy.js";
 import { executeRequestInvocation } from "./adapter/flow/invocation-flow.js";
+import { extractExplicitResourceReferences } from "./harness/system/runtime-memory-policy.js";
 import { streamRuntimeExecution } from "./adapter/flow/stream-runtime.js";
 import { resolveDeterministicFinalOutput } from "./adapter/invocation-result.js";
 import { applyToolRecoveryInstruction as applyToolRecoveryInstructionHelper, applyStrictToolJsonInstruction as applyStrictToolJsonInstructionHelper, callRuntimeWithToolParseRecovery as callRuntimeWithToolParseRecoveryHelper, createModelFallbackRunnable as createModelFallbackRunnableHelper, invokeWithProviderRetry as invokeWithProviderRetryHelper, iterateWithTimeout as iterateWithTimeoutHelper, materializeModelStream as materializeModelStreamHelper, RuntimeOperationTimeoutError, withRuntimeTimeout, } from "./adapter/runtime-shell.js";
@@ -243,6 +245,9 @@ function isDelegationOnlyDeepAgentBinding(binding) {
         && getBindingSkills(binding).length === 0;
 }
 function hasDelegatedPlanEvidence(result) {
+    if (result?.metadata?.externalPlanEvidence === true) {
+        return true;
+    }
     const toolResults = result?.metadata?.executedToolResults;
     return Array.isArray(toolResults)
         && toolResults.some((item) => isPlanToolName(item.toolName));
@@ -264,14 +269,62 @@ function hasIncompleteDelegatedTodos(value) {
         || hasIncompleteDelegatedTodos(record.stateSnapshot)
         || hasIncompleteDelegatedTodos(record.metadata);
 }
+function hasFailedDelegatedTodos(value) {
+    if (Array.isArray(value)) {
+        return value.some((item) => hasFailedDelegatedTodos(item));
+    }
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    const status = typeof record.status === "string" ? record.status.trim().toLowerCase() : "";
+    if (status === "failed") {
+        return true;
+    }
+    return hasFailedDelegatedTodos(record.todos)
+        || hasFailedDelegatedTodos(record.update)
+        || hasFailedDelegatedTodos(record.stateSnapshot)
+        || hasFailedDelegatedTodos(record.metadata);
+}
 function hasIncompleteDelegatedPlanState(result) {
     const toolResults = result?.metadata?.executedToolResults;
     return Array.isArray(toolResults)
         && toolResults.some((item) => isPlanToolName(item.toolName) && hasIncompleteDelegatedTodos(item.output));
 }
+function hasFailedDelegatedPlanState(result) {
+    const toolResults = result?.metadata?.executedToolResults;
+    return Array.isArray(toolResults)
+        && toolResults.some((item) => isPlanToolName(item.toolName) && hasFailedDelegatedTodos(item.output));
+}
+function hasDelegatedNonPlanToolEvidence(result) {
+    const toolResults = result?.metadata?.executedToolResults;
+    return Array.isArray(toolResults)
+        && toolResults.some((item) => typeof item.toolName === "string" && !isPlanToolName(item.toolName) && item.isError !== true);
+}
+function hasNonPlanToolEvidenceItems(items) {
+    return items.some((item) => typeof item.toolName === "string" && !isPlanToolName(item.toolName) && item.isError !== true);
+}
+function buildDelegatedExternalPlanEvidenceSummary(items) {
+    const evidence = items
+        .filter((item) => typeof item.toolName === "string" && !isPlanToolName(item.toolName) && item.isError !== true)
+        .map((item) => {
+        const output = typeof item.output === "string" ? item.output : JSON.stringify(item.output ?? "");
+        return `## ${String(item.toolName)}\n${output}`;
+    });
+    return [
+        "Status: completed",
+        "Summary:",
+        "- Completed delegated recovery after collecting non-planning tool evidence.",
+        "",
+        "Evidence:",
+        evidence.length > 0 ? evidence.join("\n\n") : "(no non-planning tool evidence captured)",
+    ].join("\n");
+}
 function needsDelegatedPlanRecovery(binding, result) {
     return binding?.harnessRuntime.executionContract?.requiresPlan === true
-        && (!hasDelegatedPlanEvidence(result) || hasIncompleteDelegatedPlanState(result));
+        && (!hasDelegatedPlanEvidence(result)
+            || hasIncompleteDelegatedPlanState(result)
+            || (hasFailedDelegatedPlanState(result) && !hasDelegatedNonPlanToolEvidence(result)));
 }
 function readUpstreamToolEvidence(event) {
     if (typeof event !== "object" || event === null) {
@@ -334,11 +387,78 @@ const DELEGATED_PLAN_EVIDENCE_RETRY_INSTRUCTION = [
     "Then continue the task to completion, update TODO statuses after evidence steps, and close every TODO as completed or failed before the final answer.",
 ].join("\n");
 const DELEGATED_PLAN_EVIDENCE_FINAL_RETRY_INSTRUCTION = [
-    "The delegated task still has no visible TODO planning evidence.",
-    "Use the actual write_todos tool interface now. Do not print JSON, markdown, or a tool-call transcript as text.",
-    "The next runtime event must be the write_todos tool call result, not an assistant message describing the call.",
-    "After write_todos succeeds, continue the delegated task and close every TODO as completed or failed.",
+    "The delegated task has already attempted TODO planning but still has no successful non-planning tool evidence.",
+    "Do not call write_todos or read_todos next.",
+    "The next runtime event must be one available non-planning evidence tool call.",
+    "After that tool returns, update or close the TODO board and provide the final answer required by the agent response format.",
 ].join("\n");
+function buildDelegatedPlanEvidenceRecoveryOptions(binding, baseOptions, requestText = "") {
+    const nonPlanningTools = binding
+        ? getBindingPrimaryTools(binding).filter((tool) => !isPlanToolName(tool.name))
+        : [];
+    const configuredRecoveryTool = resolveConfiguredRecoveryEvidenceTool(binding, nonPlanningTools, requestText);
+    const externalPlanEvidenceTools = configuredRecoveryTool
+        ? [configuredRecoveryTool]
+        : nonPlanningTools.length === 1
+            ? [{
+                    name: nonPlanningTools[0].name,
+                    args: buildExternalPlanEvidenceArgs(nonPlanningTools[0], requestText),
+                    id: "delegated-plan-evidence-tool-1",
+                }]
+            : undefined;
+    return {
+        ...baseOptions,
+        suppressInitialRequiredPlanInstruction: true,
+        externalPlanEvidence: true,
+        ...(externalPlanEvidenceTools ? { externalPlanEvidenceTools } : {}),
+        state: {
+            ...(typeof baseOptions.state === "object" && baseOptions.state !== null ? baseOptions.state : {}),
+            [PROMPTED_JSON_TOOL_POLICY_KEY]: "nonPlanningEvidence",
+        },
+    };
+}
+function resolveConfiguredRecoveryEvidenceTool(binding, nonPlanningTools, requestText) {
+    const configured = binding?.harnessRuntime.executionContract?.recoveryEvidenceTool;
+    const configuredName = typeof configured?.name === "string" ? configured.name.trim() : "";
+    if (!configuredName) {
+        return undefined;
+    }
+    const tool = nonPlanningTools.find((candidate) => candidate.name === configuredName);
+    if (!tool) {
+        return undefined;
+    }
+    return {
+        name: tool.name,
+        args: configured?.args ?? buildExternalPlanEvidenceArgs(tool, requestText),
+        id: "delegated-plan-evidence-tool-1",
+    };
+}
+function buildExternalPlanEvidenceArgs(tool, requestText) {
+    const properties = tool?.modelSchema && typeof tool.modelSchema === "object"
+        && tool.modelSchema !== null
+        && typeof tool.modelSchema.properties === "object"
+        && tool.modelSchema.properties !== null
+        ? tool.modelSchema.properties
+        : {};
+    const refs = extractExplicitResourceReferences(requestText);
+    const args = {};
+    const firstUrl = refs.find((ref) => /^https?:\/\//iu.test(ref));
+    if ("url" in properties && firstUrl) {
+        args.url = firstUrl;
+    }
+    if ("sources" in properties && refs.length > 0) {
+        args.sources = refs.map((ref) => /^https?:\/\//iu.test(ref)
+            ? { type: "url", url: ref }
+            : { type: "text", text: ref });
+    }
+    if ("question" in properties) {
+        args.question = requestText;
+    }
+    else if ("query" in properties) {
+        args.query = requestText;
+    }
+    return args;
+}
 function looksLikeRawCommandTranscript(value) {
     const normalized = value.trim();
     return /^(?:stdout|stderr)\s*:/iu.test(normalized)
@@ -505,18 +625,21 @@ export class AgentRuntimeAdapter {
         if (!this.options.functionToolContextResolver) {
             return undefined;
         }
+        const publicRequestId = typeof options.requestId === "string" && options.requestId.includes(":")
+            ? options.requestId.split(":")[0]
+            : options.requestId;
         const backend = this.resolveBuiltinMiddlewareBackend(binding, options);
         return {
             ...this.options.functionToolContextResolver({
                 binding,
                 sessionId: options.sessionId,
-                requestId: options.requestId,
+                requestId: publicRequestId,
             }),
             backend,
             invocation: {
                 ...(options.context ? { context: options.context } : {}),
                 ...(options.sessionId ? { sessionId: options.sessionId } : {}),
-                ...(options.requestId ? { requestId: options.requestId } : {}),
+                ...(publicRequestId ? { requestId: publicRequestId } : {}),
             },
         };
     }
@@ -1195,13 +1318,25 @@ export class AgentRuntimeAdapter {
         if (!selectedBinding) {
             return null;
         }
-        const runDelegatedRequest = (text, requestSuffix = "", delegatedOptions = {}) => this.invoke(selectedBinding, text, sessionId, `${requestId}:${subagentType}${requestSuffix}`, undefined, [], {
-            context: options.context,
-            state: options.state,
-            files: options.files,
-            memoryContext: options.memoryContext,
-            ...delegatedOptions,
-        });
+        const runDelegatedRequest = async (text, requestSuffix = "", delegatedOptions = {}) => {
+            const result = await this.invoke(selectedBinding, text, sessionId, `${requestId}:${subagentType}${requestSuffix}`, undefined, [], {
+                context: options.context,
+                state: options.state,
+                files: options.files,
+                memoryContext: options.memoryContext,
+                ...delegatedOptions,
+            });
+            if (delegatedOptions.externalPlanEvidence === true) {
+                return {
+                    ...result,
+                    metadata: {
+                        ...(result.metadata ?? {}),
+                        externalPlanEvidence: true,
+                    },
+                };
+            }
+            return result;
+        };
         let delegatedResult;
         try {
             delegatedResult = await runDelegatedRequest(requestText);
@@ -1261,6 +1396,25 @@ export class AgentRuntimeAdapter {
                 };
             }
         }
+        if (needsDelegatedPlanRecovery(selectedBinding, delegatedResult)) {
+            const previousDelegatedResult = delegatedResult;
+            try {
+                delegatedResult = mergeDelegatedResultToolEvidence(await runDelegatedRequest([requestText, DELEGATED_PLAN_EVIDENCE_FINAL_RETRY_INSTRUCTION].filter(Boolean).join("\n\n"), ":plan-evidence-final-retry", buildDelegatedPlanEvidenceRecoveryOptions(selectedBinding, options, requestText)), previousDelegatedResult);
+            }
+            catch (error) {
+                const output = error instanceof Error ? error.message : String(error);
+                return {
+                    toolOutput: output,
+                    delegatedSubagentType: subagentType,
+                    delegatedResult: {
+                        ...delegatedResult,
+                        state: "failed",
+                        output,
+                        finalMessageText: output,
+                    },
+                };
+            }
+        }
         if (needsDelegatedPlanRecovery(selectedBinding, delegatedResult)) {
             const output = buildDelegatedPlanEvidenceBlocker(selectedBinding.agent.id);
             return {
@@ -1318,9 +1472,10 @@ export class AgentRuntimeAdapter {
         const state = compactDelegation.delegatedResult?.state === "failed" ? "failed" : "completed";
         const uniqueToolNames = [...new Set(delegatedToolNames)];
         const toolEvidence = uniqueToolNames.length > 0 ? uniqueToolNames.join(", ") : "none";
+        const hasPlanEvidence = hasDelegatedPlanEvidence(compactDelegation.delegatedResult);
         const fallbackTodoTrace = [
             `1) TODO observed: delegated to ${delegatedSubagentType}.`,
-            uniqueToolNames.some((toolName) => isPlanToolName(toolName))
+            hasPlanEvidence
                 ? `2) ${delegatedSubagentType}: TODO evidence observed; delegated specialist invoked write_todos.`
                 : `2) ${delegatedSubagentType}: TODO evidence missing; delegated specialist did not expose write_todos in returned metadata.`,
             state === "failed"
@@ -1563,7 +1718,7 @@ export class AgentRuntimeAdapter {
                 content: `Planned delegation tree: ${executableDelegations.map((item) => item.subagentType).join(" -> ")}.`,
                 agentId: binding.agent.id,
             };
-            const runPlannedDelegation = async function* (subagentType, text, requestIdSuffix = "") {
+            const runPlannedDelegation = async function* (subagentType, text, requestIdSuffix = "", delegatedOptions = {}) {
                 const selectedBinding = this.options.bindingResolver?.(subagentType);
                 if (!selectedBinding) {
                     const output = `Configured subagent '${subagentType}' could not be resolved.`;
@@ -1582,11 +1737,14 @@ export class AgentRuntimeAdapter {
                 try {
                     for await (const chunk of this.stream(selectedBinding, text, sessionId, [], {
                         context: options.context,
-                        state: options.state,
+                        state: delegatedOptions.state ?? options.state,
                         files: options.files,
                         requestId: `${requestId}:${subagentType}${requestIdSuffix}`,
                         memoryContext: options.memoryContext,
                         profiling: options.profiling,
+                        suppressInitialRequiredPlanInstruction: delegatedOptions.suppressInitialRequiredPlanInstruction,
+                        externalPlanEvidence: delegatedOptions.externalPlanEvidence,
+                        externalPlanEvidenceTools: delegatedOptions.externalPlanEvidenceTools,
                     })) {
                         if (typeof chunk === "string") {
                             output += chunk;
@@ -1621,17 +1779,26 @@ export class AgentRuntimeAdapter {
                         state: "failed",
                         output,
                         finalMessageText: output,
-                        metadata: { executedToolResults },
+                        metadata: {
+                            executedToolResults,
+                            ...(delegatedOptions.externalPlanEvidence === true ? { externalPlanEvidence: true } : {}),
+                        },
                     };
                 }
+                const finalOutput = delegatedOptions.externalPlanEvidence === true && hasNonPlanToolEvidenceItems(executedToolResults)
+                    ? buildDelegatedExternalPlanEvidenceSummary(executedToolResults)
+                    : sanitizeVisibleText(output);
                 return {
                     sessionId,
                     requestId: `${requestId}:${subagentType}${requestIdSuffix}`,
                     agentId: selectedBinding.agent.id,
                     state: "completed",
-                    output: sanitizeVisibleText(output),
-                    finalMessageText: sanitizeVisibleText(output),
-                    metadata: { executedToolResults },
+                    output: finalOutput,
+                    finalMessageText: finalOutput,
+                    metadata: {
+                        executedToolResults,
+                        ...(delegatedOptions.externalPlanEvidence === true ? { externalPlanEvidence: true } : {}),
+                    },
                 };
             }.bind(this);
             for (const [index, planned] of executableDelegations.entries()) {
@@ -1658,7 +1825,7 @@ export class AgentRuntimeAdapter {
                 }
                 if (needsDelegatedPlanRecovery(selectedBinding, delegatedResult)) {
                     const previousDelegatedResult = delegatedResult;
-                    delegatedResult = mergeDelegatedResultToolEvidence(yield* runPlannedDelegation(planned.subagentType, [delegatedText, DELEGATED_PLAN_EVIDENCE_FINAL_RETRY_INSTRUCTION].filter(Boolean).join("\n\n"), ":plan-evidence-final-retry"), previousDelegatedResult);
+                    delegatedResult = mergeDelegatedResultToolEvidence(yield* runPlannedDelegation(planned.subagentType, [delegatedText, DELEGATED_PLAN_EVIDENCE_FINAL_RETRY_INSTRUCTION].filter(Boolean).join("\n\n"), ":plan-evidence-final-retry", buildDelegatedPlanEvidenceRecoveryOptions(selectedBinding, options, delegatedText)), previousDelegatedResult);
                 }
                 if (needsDelegatedPlanRecovery(selectedBinding, delegatedResult)) {
                     const output = buildDelegatedPlanEvidenceBlocker(selectedBinding?.agent.id ?? planned.subagentType);
@@ -1789,17 +1956,20 @@ export class AgentRuntimeAdapter {
             agentId: selectedBinding.agent.id,
         };
         const childRequestId = `${requestId}:${subagentType}`;
-        const runDelegatedStreamAttempt = async function* (text, requestIdSuffix = "") {
+        const runDelegatedStreamAttempt = async function* (text, requestIdSuffix = "", delegatedOptions = {}) {
             const executedToolResults = [];
             let output = "";
             try {
                 for await (const chunk of this.stream(selectedBinding, text, sessionId, [], {
                     context: options.context,
-                    state: options.state,
+                    state: delegatedOptions.state ?? options.state,
                     files: options.files,
                     requestId: `${childRequestId}${requestIdSuffix}`,
                     memoryContext: options.memoryContext,
                     profiling: options.profiling,
+                    suppressInitialRequiredPlanInstruction: delegatedOptions.suppressInitialRequiredPlanInstruction,
+                    externalPlanEvidence: delegatedOptions.externalPlanEvidence,
+                    externalPlanEvidenceTools: delegatedOptions.externalPlanEvidenceTools,
                 })) {
                     if (typeof chunk === "string") {
                         output += chunk;
@@ -1834,17 +2004,26 @@ export class AgentRuntimeAdapter {
                     state: "failed",
                     output,
                     finalMessageText: output,
-                    metadata: { executedToolResults },
+                    metadata: {
+                        executedToolResults,
+                        ...(delegatedOptions.externalPlanEvidence === true ? { externalPlanEvidence: true } : {}),
+                    },
                 };
             }
+            const finalOutput = delegatedOptions.externalPlanEvidence === true && hasNonPlanToolEvidenceItems(executedToolResults)
+                ? buildDelegatedExternalPlanEvidenceSummary(executedToolResults)
+                : sanitizeVisibleText(output);
             return {
                 sessionId,
                 requestId: `${childRequestId}${requestIdSuffix}`,
                 agentId: selectedBinding.agent.id,
                 state: "completed",
-                output: sanitizeVisibleText(output),
-                finalMessageText: sanitizeVisibleText(output),
-                metadata: { executedToolResults },
+                output: finalOutput,
+                finalMessageText: finalOutput,
+                metadata: {
+                    executedToolResults,
+                    ...(delegatedOptions.externalPlanEvidence === true ? { externalPlanEvidence: true } : {}),
+                },
             };
         }.bind(this);
         const delegatedText = buildDelegatedOwnedTaskInstruction({
@@ -1859,7 +2038,7 @@ export class AgentRuntimeAdapter {
         }
         if (needsDelegatedPlanRecovery(selectedBinding, delegatedResult)) {
             const previousDelegatedResult = delegatedResult;
-            delegatedResult = mergeDelegatedResultToolEvidence(yield* runDelegatedStreamAttempt([delegatedText, DELEGATED_PLAN_EVIDENCE_FINAL_RETRY_INSTRUCTION].filter(Boolean).join("\n\n"), ":plan-evidence-final-retry"), previousDelegatedResult);
+            delegatedResult = mergeDelegatedResultToolEvidence(yield* runDelegatedStreamAttempt([delegatedText, DELEGATED_PLAN_EVIDENCE_FINAL_RETRY_INSTRUCTION].filter(Boolean).join("\n\n"), ":plan-evidence-final-retry", buildDelegatedPlanEvidenceRecoveryOptions(selectedBinding, options, delegatedText)), previousDelegatedResult);
         }
         if (needsDelegatedPlanRecovery(selectedBinding, delegatedResult)) {
             const output = buildDelegatedPlanEvidenceBlocker(selectedBinding.agent.id);

package/dist/workspace/agent-binding-compiler.js

@@ -282,8 +282,30 @@ function resolveExecutionContract(agent) {
     if (!value) {
         return undefined;
     }
+    const recoveryEvidenceTool = typeof value.recoveryEvidenceTool === "string" && value.recoveryEvidenceTool.trim().length > 0
+        ? { name: value.recoveryEvidenceTool.trim() }
+        : typeof value.recoveryEvidenceTool === "object" && value.recoveryEvidenceTool && !Array.isArray(value.recoveryEvidenceTool)
+            ? value.recoveryEvidenceTool
+            : undefined;
+    const recoveryEvidenceToolName = recoveryEvidenceTool && typeof recoveryEvidenceTool.name === "string" && recoveryEvidenceTool.name.trim().length > 0
+        ? recoveryEvidenceTool.name.trim()
+        : undefined;
+    const recoveryEvidenceToolArgs = recoveryEvidenceTool
+        && typeof recoveryEvidenceTool.args === "object"
+        && recoveryEvidenceTool.args
+        && !Array.isArray(recoveryEvidenceTool.args)
+        ? recoveryEvidenceTool.args
+        : undefined;
     return {
         ...(value.requiresPlan === true ? { requiresPlan: true } : {}),
+        ...(recoveryEvidenceToolName
+            ? {
+                recoveryEvidenceTool: {
+                    name: recoveryEvidenceToolName,
+                    ...(recoveryEvidenceToolArgs ? { args: recoveryEvidenceToolArgs } : {}),
+                },
+            }
+            : {}),
     };
 }
 function resolveCompiledMiddleware(agent, models) {

package/dist/workspace/framework-contract-validation.js

@@ -50,6 +50,16 @@ function readExecutionContractConfig(agent) {
         ? value
         : undefined;
 }
+function readRecoveryEvidenceToolName(value) {
+    if (typeof value === "string") {
+        return value.trim();
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return "";
+    }
+    const name = value.name;
+    return typeof name === "string" ? name.trim() : "";
+}
 function collectAgentToolNames(agent, tools, ownsDelegation) {
     const names = new Set(FRAMEWORK_EXECUTION_TOOL_NAMES);
     if (ownsDelegation) {
@@ -208,6 +218,13 @@ function validateAgentContract(agent, referencedSubagentIds, tools, refs, issues
     if (executionContract?.requiresPlan === true && builtinTools?.todos === false) {
         addIssue(issues, "agent.execution_contract.plan_without_todos", `Agent ${agent.id} requires plan evidence but disables todo tools. Enable todo tools or remove config.executionContract.requiresPlan.`);
     }
+    const recoveryEvidenceToolName = readRecoveryEvidenceToolName(executionContract?.recoveryEvidenceTool);
+    if (recoveryEvidenceToolName) {
+        const toolNames = collectAgentToolNames(agent, tools, ownsDelegation);
+        if (FRAMEWORK_EXECUTION_TOOL_NAMES.has(recoveryEvidenceToolName) || !toolNames.has(recoveryEvidenceToolName)) {
+            addIssue(issues, "agent.execution_contract.invalid_recovery_evidence_tool", `Agent ${agent.id} config.executionContract.recoveryEvidenceTool must name one declared non-planning tool.`);
+        }
+    }
     if (ownsDelegation) {
         if (hasTools) {
             addIssue(issues, "agent.orchestrator.mixed_tool_surface", `Delegating agent ${agent.id} defines both subagents and direct tools. Keep routing agents focused on delegation, and move execution tools to specialist agents.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.464",
+  "version": "0.0.466",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",