@botbotgo/agent-harness 0.0.346 → 0.0.348

package/dist/runtime/harness/run/stream-run.js

@@ -2,6 +2,7 @@ import { resolveDeterministicFinalOutput, } from "../../adapter/invocation-resul
 import { AGENT_INTERRUPT_SENTINEL_PREFIX, RuntimeOperationTimeoutError } from "../../agent-runtime-adapter.js";
 import { ExecutionReconciliationError } from "../../adapter/flow/stream-runtime.js";
 import { buildRequestPlanState, summarizeBuiltinWriteTodosArgs } from "../../adapter/runtime-adapter-support.js";
+import { mapTerminalStatusToPlanItemStatus, mapTerminalStatusToRequestState, readTerminalExecutionStatus, } from "../../adapter/terminal-status.js";
 import { sanitizeVisibleText } from "../../parsing/output-parsing.js";
 import { describeRuntimeError, renderRuntimeFailure, renderToolFailure } from "../../support/harness-support.js";
 import { getBindingPrimaryModel } from "../../support/compiled-binding.js";
@@ -37,27 +38,6 @@ function planStateHasActiveItems(planState) {
     }
     return planState.summary.pending > 0 || planState.summary.inProgress > 0;
 }
-function readTerminalStructuredStatus(value) {
-    if (typeof value === "string") {
-        try {
-            return readTerminalStructuredStatus(JSON.parse(value));
-        }
-        catch {
-            return /^\s*Status:\s*completed\b/im.test(value) ? "completed" : null;
-        }
-    }
-    if (typeof value !== "object" || value === null) {
-        return null;
-    }
-    const typed = value;
-    if (typed.status === "completed") {
-        return typed.status;
-    }
-    return (readTerminalStructuredStatus(typed.structuredResponse)
-        ?? readTerminalStructuredStatus(typed.content)
-        ?? readTerminalStructuredStatus(typed.output)
-        ?? readTerminalStructuredStatus(typed.data));
-}
 function isSubstantiveTerminalAssistantOutput(value) {
     const normalized = sanitizeVisibleText(value).trim();
     if (normalized.length < 80) {
@@ -898,10 +878,10 @@ export async function* streamHarnessRun(options) {
                     }
                 }
                 const terminalStructuredStatus = normalizedChunk.toolName === "task"
-                    ? readTerminalStructuredStatus(normalizedChunk.output)
+                    ? readTerminalExecutionStatus(normalizedChunk.output)
                     : null;
                 if (terminalStructuredStatus && currentPlanState && planStateHasActiveItems(currentPlanState)) {
-                    const reconciledPlanState = reconcilePlanStateToTerminalStatus(currentPlanState, terminalStructuredStatus, new Date().toISOString());
+                    const reconciledPlanState = reconcilePlanStateToTerminalStatus(currentPlanState, mapTerminalStatusToPlanItemStatus(terminalStructuredStatus), new Date().toISOString());
                     const signature = buildPlanStateSignature(reconciledPlanState);
                     if (signature !== lastPlanStateSignature) {
                         const previousPlanState = currentPlanState;
@@ -1005,9 +985,9 @@ export async function* streamHarnessRun(options) {
                 }
             }
             currentPlanState = await refreshPlanStateFromPersistence(options, currentPlanState);
-            const terminalStructuredStatus = readTerminalStructuredStatus(actual.structuredResponse);
+            const terminalStructuredStatus = readTerminalExecutionStatus(actual.structuredResponse);
             if (terminalStructuredStatus && currentPlanState && planStateHasActiveItems(currentPlanState)) {
-                const reconciledPlanState = reconcilePlanStateToTerminalStatus(currentPlanState, terminalStructuredStatus, new Date().toISOString());
+                const reconciledPlanState = reconcilePlanStateToTerminalStatus(currentPlanState, mapTerminalStatusToPlanItemStatus(terminalStructuredStatus), new Date().toISOString());
                 const signature = buildPlanStateSignature(reconciledPlanState);
                 if (signature !== lastPlanStateSignature) {
                     const previousPlanState = currentPlanState;
@@ -1075,8 +1055,10 @@ export async function* streamHarnessRun(options) {
                 content: assistantOutput,
             };
         }
+        const terminalStatus = readTerminalExecutionStatus(assistantOutput);
+        const terminalRequestState = mapTerminalStatusToRequestState(terminalStatus);
         await options.appendAssistantMessage(options.sessionId, options.requestId, assistantOutput);
-        const completedEvent = await options.setRequestStateAndEmit(options.sessionId, options.requestId, 6, "completed", {
+        const completedEvent = await options.setRequestStateAndEmit(options.sessionId, options.requestId, 6, terminalRequestState, {
             previousState: "running",
         });
         yield {
@@ -1089,9 +1071,10 @@ export async function* streamHarnessRun(options) {
                 sessionId: options.sessionId,
                 requestId: options.requestId,
                 agentId: currentAgentId,
-                state: "completed",
+                state: terminalRequestState,
                 output: assistantOutput,
                 finalMessageText: assistantOutput,
+                ...(terminalStatus ? { metadata: { terminalStatus } } : {}),
             },
         };
     }
@@ -1101,9 +1084,9 @@ export async function* streamHarnessRun(options) {
             executedToolResults,
         });
         if (!assistantOutput && sawSuccessfulToolResult && deterministicToolEvidenceOutput) {
-            const terminalStructuredStatus = readTerminalStructuredStatus(deterministicToolEvidenceOutput);
+            const terminalStructuredStatus = readTerminalExecutionStatus(deterministicToolEvidenceOutput);
             if (terminalStructuredStatus && currentPlanState && planStateHasActiveItems(currentPlanState)) {
-                const reconciledPlanState = reconcilePlanStateToTerminalStatus(currentPlanState, terminalStructuredStatus, new Date().toISOString());
+                const reconciledPlanState = reconcilePlanStateToTerminalStatus(currentPlanState, mapTerminalStatusToPlanItemStatus(terminalStructuredStatus), new Date().toISOString());
                 const signature = buildPlanStateSignature(reconciledPlanState);
                 if (signature !== lastPlanStateSignature) {
                     const previousPlanState = currentPlanState;
@@ -1137,7 +1120,9 @@ export async function* streamHarnessRun(options) {
                 agentId: currentAgentId,
                 content: deterministicToolEvidenceOutput,
             };
-            const completedEvent = await options.setRequestStateAndEmit(options.sessionId, options.requestId, 6, "completed", {
+            const terminalStatus = readTerminalExecutionStatus(deterministicToolEvidenceOutput);
+            const terminalRequestState = mapTerminalStatusToRequestState(terminalStatus);
+            const completedEvent = await options.setRequestStateAndEmit(options.sessionId, options.requestId, 6, terminalRequestState, {
                 previousState: "running",
             });
             yield {
@@ -1150,11 +1135,12 @@ export async function* streamHarnessRun(options) {
                     sessionId: options.sessionId,
                     requestId: options.requestId,
                     agentId: currentAgentId,
-                    state: "completed",
+                    state: terminalRequestState,
                     output: deterministicToolEvidenceOutput,
                     finalMessageText: deterministicToolEvidenceOutput,
                     metadata: {
                         executedToolResults,
+                        ...(terminalStatus ? { terminalStatus } : {}),
                     },
                 },
             };

package/dist/runtime/parsing/output-recovery.d.ts

@@ -7,10 +7,10 @@ export declare function isRepairableWriteTodosEmptyFailure(error: unknown): bool
 export declare function isToolCallRecoveryFailure(error: unknown): boolean;
 export declare function isRetrySafeInvalidToolSelectionError(value: unknown): boolean;
 export declare function shouldValidateExecutionWithoutToolEvidence(request: unknown): boolean;
-export declare function shouldRequireVisibleTodoPlan(request: unknown): boolean;
 export declare function resolveMissingPlanRecoveryInstruction(params: {
     request: unknown;
     assistantText?: string;
+    requiresPlan?: boolean;
     hasPlanStateEvidence?: boolean;
     hasWriteTodosEvidence?: boolean;
     hasToolResultEvidence?: boolean;
@@ -23,6 +23,7 @@ export declare function resolveExecutionWithoutToolEvidenceTextInstruction(reque
     hasPlanStateEvidence?: boolean;
     hasOpenTaskDelegation?: boolean;
     hasMissingDelegatedExecutionEvidence?: boolean;
+    requiresPlan?: boolean;
 }): string | null;
 export declare function resolveToolCallRecoveryInstruction(error: unknown): string | null;
 export declare function appendToolRecoveryInstruction(input: unknown, instruction: string): unknown;

package/dist/runtime/parsing/output-recovery.js

@@ -111,34 +111,10 @@ export function shouldValidateExecutionWithoutToolEvidence(request) {
     }
     return readSystemInstructionText(request).length > 0;
 }
-export function shouldRequireVisibleTodoPlan(request) {
-    const userText = readLatestUserRequestText(request).toLowerCase();
-    if (!userText) {
-        return false;
-    }
-    return [
-        "investigate",
-        "investigation",
-        "issue",
-        "issues",
-        "rca",
-        "root cause",
-        "go deeper",
-        "deep research",
-        "debug",
-        "排查",
-        "调查",
-        "问题",
-        "根因",
-        "故障",
-        "集群",
-        "cluster",
-    ].some((keyword) => userText.includes(keyword));
-}
 export function resolveMissingPlanRecoveryInstruction(params) {
     const hasPlanEvidence = params.hasWriteTodosEvidence === true
         || params.hasPlanStateEvidence === true;
-    if (!shouldRequireVisibleTodoPlan(params.request) || hasPlanEvidence) {
+    if (params.requiresPlan !== true || hasPlanEvidence) {
         return null;
     }
     if (params.hasToolResultEvidence === true) {
@@ -158,6 +134,7 @@ export function resolveExecutionWithoutToolEvidenceTextInstruction(request, assi
     const missingPlanRecoveryInstruction = resolveMissingPlanRecoveryInstruction({
         request,
         assistantText: normalizedText,
+        requiresPlan: resultEvidence.requiresPlan,
         hasWriteTodosEvidence: resultEvidence.hasWriteTodosEvidence,
         hasPlanStateEvidence: resultEvidence.hasIncompletePlanState === true || resultEvidence.hasPlanStateEvidence === true,
         hasToolResultEvidence: resultEvidence.hasToolResultEvidence,

package/dist/runtime/prompts/runtime-prompts.d.ts

@@ -11,6 +11,7 @@ export declare const WRITE_TODOS_REQUIRED_PLAN_INSTRUCTION: string;
 export declare const EXECUTION_WITH_TOOL_EVIDENCE_INSTRUCTION: string;
 export declare const EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION: string;
 export declare const AUTONOMOUS_INVESTIGATION_RECOVERY_INSTRUCTION: string;
+export declare const DELEGATED_TASK_FAILURE_RECOVERY_INSTRUCTION: string;
 export declare const INTERNAL_RUNTIME_SPILL_PATH_INSTRUCTION: string;
 export declare const WORKSPACE_RELATIVE_PATH_INSTRUCTION: string;
 export declare function renderDurableMemoryContextPrompt(memoryContext: string): string;

package/dist/runtime/prompts/runtime-prompts.js

@@ -14,6 +14,7 @@ export const WRITE_TODOS_REQUIRED_PLAN_INSTRUCTION = readRuntimePrompt("write-to
 export const EXECUTION_WITH_TOOL_EVIDENCE_INSTRUCTION = readRuntimePrompt("execution-with-tool-evidence");
 export const EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION = readRuntimePrompt("execution-with-tool-evidence-retry");
 export const AUTONOMOUS_INVESTIGATION_RECOVERY_INSTRUCTION = readRuntimePrompt("autonomous-investigation-recovery");
+export const DELEGATED_TASK_FAILURE_RECOVERY_INSTRUCTION = readRuntimePrompt("delegated-task-failure-recovery");
 export const INTERNAL_RUNTIME_SPILL_PATH_INSTRUCTION = readRuntimePrompt("internal-runtime-spill-path");
 export const WORKSPACE_RELATIVE_PATH_INSTRUCTION = readRuntimePrompt("workspace-relative-path");
 export function renderDurableMemoryContextPrompt(memoryContext) {

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

@@ -199,6 +199,15 @@ function resolveResponseFormat(agent) {
 function resolveContextSchema(agent) {
     return getAgentExecutionConfigValue(agent, "contextSchema");
 }
+function resolveExecutionContract(agent) {
+    const value = getAgentExecutionObject(agent, "executionContract");
+    if (!value) {
+        return undefined;
+    }
+    return {
+        ...(value.requiresPlan === true ? { requiresPlan: true } : {}),
+    };
+}
 function resolveCompiledMiddleware(agent, models) {
     const middleware = getAgentExecutionConfigValue(agent, "middleware");
     return compileMiddlewareConfigs(middleware, models, agent.id);
@@ -399,6 +408,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
         : undefined;
     const runtimeGovernanceDefaults = asObject(runtimeDefaults?.governance);
     const runtimeObservabilityDefaults = asObject(runtimeDefaults?.observability);
+    const executionContract = resolveExecutionContract(agent);
     const compiledFilesystemConfig = agent.executionMode === "langchain-v1"
         ? mergeConfigObjects(runtimeFilesystemDefaults, getAgentExecutionObject(agent, "filesystem", { executionMode: "langchain-v1" }))
         : undefined;
@@ -417,6 +427,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             resilience,
             ...(runtimeGovernanceDefaults ? { governance: runtimeGovernanceDefaults } : {}),
             ...(runtimeObservabilityDefaults ? { observability: runtimeObservabilityDefaults } : {}),
+            ...(executionContract ? { executionContract } : {}),
             ...(agent.executionMode === "deepagent"
                 ? {
                     deepagent: {

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

@@ -1,8 +1,11 @@
-import { readFileSync } from "node:fs";
 import path from "node:path";
 import { validateSkillMetadata } from "../runtime/skills/skill-metadata.js";
 import { getAgentExecutionConfigValue } from "./support/agent-execution-config.js";
 import { resolvePromptValue } from "./support/workspace-ref-utils.js";
+const FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME = "general-purpose";
+const FRAMEWORK_AGENT_TOOL_NAMES = new Set(["task"]);
+const FRAMEWORK_EXECUTION_TOOL_NAMES = new Set(["write_todos", "read_todos"]);
+const TERMINAL_STATUS_VALUES = new Set(["completed", "blocked", "failed", "refused"]);
 function normalizeMode(mode) {
     if (mode === "warn" || mode === "error") {
         return mode;
@@ -29,7 +32,76 @@ function isWorkspaceOwnedPath(candidate, roots) {
 function addIssue(issues, code, message) {
     issues.push({ code, message });
 }
-function validateAgentContract(agent, referencedSubagentIds, issues) {
+function stripRefPrefix(value, prefix) {
+    return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+function resolveRefId(value) {
+    return stripRefPrefix(stripRefPrefix(value, "agent/"), "tool/");
+}
+function readBuiltinToolsConfig(agent) {
+    const value = getAgentExecutionConfigValue(agent, "builtinTools");
+    return typeof value === "object" && value && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function readExecutionContractConfig(agent) {
+    const value = getAgentExecutionConfigValue(agent, "executionContract");
+    return typeof value === "object" && value && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function collectAgentToolNames(agent, tools, ownsDelegation) {
+    const names = new Set(FRAMEWORK_EXECUTION_TOOL_NAMES);
+    if (ownsDelegation) {
+        for (const toolName of FRAMEWORK_AGENT_TOOL_NAMES) {
+            names.add(toolName);
+        }
+    }
+    for (const ref of agent.toolRefs) {
+        const tool = tools.get(resolveRefId(ref));
+        if (tool) {
+            names.add(tool.id);
+            names.add(tool.name);
+        }
+        names.add(resolveRefId(ref));
+    }
+    for (const binding of agent.toolBindings ?? []) {
+        const tool = tools.get(resolveRefId(binding.ref));
+        if (tool) {
+            names.add(tool.id);
+            names.add(tool.name);
+        }
+        names.add(resolveRefId(binding.ref));
+    }
+    for (const tool of agent.inlineTools ?? []) {
+        names.add(tool.id);
+        names.add(tool.name);
+    }
+    return names;
+}
+function hasDuplicateValues(values) {
+    return new Set(values).size !== values.length;
+}
+function readObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function validateResponseFormatTerminalStatus(agent, responseFormat, issues) {
+    const schema = readObject(responseFormat);
+    const properties = readObject(schema?.properties);
+    const statusProperty = readObject(properties?.status);
+    const required = Array.isArray(schema?.required) ? schema.required : [];
+    if (!statusProperty || !required.includes("status")) {
+        addIssue(issues, "agent.response_format.missing_terminal_status", `Agent ${agent.id} responseFormat must require a status field so parents can distinguish completed, blocked, failed, and refused terminal states.`);
+        return;
+    }
+    const statusEnum = Array.isArray(statusProperty.enum) ? statusProperty.enum : [];
+    if (!Array.from(TERMINAL_STATUS_VALUES).every((value) => statusEnum.includes(value))) {
+        addIssue(issues, "agent.response_format.incomplete_terminal_status_enum", `Agent ${agent.id} responseFormat status enum must include completed, blocked, failed, and refused.`);
+    }
+}
+function validateAgentContract(agent, referencedSubagentIds, tools, issues) {
     const description = agent.description.trim();
     const systemPrompt = resolvePromptValue(getAgentExecutionConfigValue(agent, "systemPrompt"), path.dirname(agent.sourcePath));
     const ownsDelegation = agent.subagentRefs.length > 0 || agent.subagentPathRefs.length > 0 || (agent.asyncSubagents?.length ?? 0) > 0;
@@ -38,45 +110,76 @@ function validateAgentContract(agent, referencedSubagentIds, issues) {
         || (agent.toolBindings?.length ?? 0) > 0
         || (agent.inlineTools?.length ?? 0) > 0;
     const responseFormat = getAgentExecutionConfigValue(agent, "responseFormat");
+    const builtinTools = readBuiltinToolsConfig(agent);
+    const executionContract = readExecutionContractConfig(agent);
+    const localSubagentNames = [
+        ...agent.subagentRefs.map(resolveRefId),
+        ...(agent.asyncSubagents ?? []).map((subagent) => subagent.name),
+    ];
+    if (agent.id === FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME) {
+        addIssue(issues, "agent.general_purpose.forbidden", `Agent ${agent.id} uses the reserved general-purpose subagent name. Define explicit specialists with narrow responsibilities instead.`);
+    }
+    for (const asyncSubagent of agent.asyncSubagents ?? []) {
+        if (asyncSubagent.name === FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME) {
+            addIssue(issues, "agent.general_purpose.forbidden", `Agent ${agent.id} defines async subagent ${asyncSubagent.name}. Define explicit specialists with narrow responsibilities instead.`);
+        }
+    }
+    if (localSubagentNames.includes(FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME)) {
+        addIssue(issues, "agent.general_purpose.forbidden", `Agent ${agent.id} references reserved subagent name ${FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME}. Define explicit specialists with narrow responsibilities instead.`);
+    }
+    if (hasDuplicateValues(localSubagentNames)) {
+        addIssue(issues, "agent.subagent.duplicate_name", `Agent ${agent.id} exposes duplicate subagent names. Each delegated capability must have one stable owner.`);
+    }
     if (description.length < 24) {
         addIssue(issues, "agent.description.too_short", `Agent ${agent.id} should use a more specific description that explains when it should be used.`);
     }
+    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.`);
+    }
     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.`);
+        }
+        const modelExposedBuiltins = builtinTools?.modelExposed;
+        const exposesOnlyTask = Array.isArray(modelExposedBuiltins)
+            && modelExposedBuiltins.length === 1
+            && modelExposedBuiltins[0] === "task";
+        if (modelExposedBuiltins !== false && !exposesOnlyTask) {
+            addIssue(issues, "agent.orchestrator.model_exposed_builtins", `Delegating agent ${agent.id} should expose only the task builtin or set config.builtinTools.modelExposed: false so raw built-in tools do not compete with specialist routing.`);
+        }
         if (!systemPrompt?.trim()) {
             addIssue(issues, "agent.orchestrator.missing_prompt", `Delegating agent ${agent.id} should define a systemPrompt that explains decomposition, delegation, synthesis, and stop conditions.`);
         }
-        if (!/(delegate|delegation|subagent|decompose|synthesi|answer directly|parallel)/i.test(description)) {
-            addIssue(issues, "agent.orchestrator.description_boundary", `Delegating agent ${agent.id} description should make its delegation boundary explicit, for example when it should answer directly versus delegate.`);
-        }
     }
     if (isSubagent) {
         if (!systemPrompt?.trim()) {
             addIssue(issues, "agent.subagent.missing_prompt", `Subagent ${agent.id} should define a systemPrompt that makes its operating boundary and output contract explicit.`);
         }
-        if (!/(use this when|when the task|for .*?(analysis|research|search|debug|review|triage|inspection|extraction|comparison|validation|implementation))/i.test(description)) {
-            addIssue(issues, "agent.subagent.description_trigger", `Subagent ${agent.id} description should clarify when it should be delegated to and what narrow task class it owns.`);
-        }
         if (agent.executionMode === "deepagent" && hasTools && responseFormat === undefined) {
             addIssue(issues, "agent.subagent.deepagent.missing_response_format", `DeepAgents subagent ${agent.id} exposes tools, so it should define config.responseFormat to guarantee a stable task result for its parent agent.`);
         }
+        if (agent.executionMode === "deepagent" && hasTools && responseFormat !== undefined) {
+            validateResponseFormatTerminalStatus(agent, responseFormat, issues);
+        }
+        if (hasTools && agent.skillPathRefs.length === 0) {
+            addIssue(issues, "agent.subagent.tools_without_skills", `Subagent ${agent.id} exposes execution tools but no skills. Add skills that describe tool-selection workflows and boundaries.`);
+        }
+    }
+    const toolNames = collectAgentToolNames(agent, tools, ownsDelegation);
+    for (const skillPath of agent.skillPathRefs) {
+        const metadata = validateSkillMetadata(skillPath);
+        for (const allowedTool of metadata.allowedTools ?? []) {
+            if (!toolNames.has(allowedTool)) {
+                addIssue(issues, "agent.skill.allowed_tool_unavailable", `Agent ${agent.id} attaches skill ${metadata.name}, but that skill allows tool ${allowedTool} which is not available to the agent.`);
+            }
+        }
     }
-}
-function stripFrontmatter(document) {
-    return document.replace(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/, "");
 }
 function validateSkillContract(skillRoot, issues) {
     const metadata = validateSkillMetadata(skillRoot);
-    const document = readFileSync(path.join(skillRoot, "SKILL.md"), "utf8");
-    const body = stripFrontmatter(document);
     const skillName = metadata.name || path.basename(skillRoot);
-    if (!/(Use this skill when|Use this when)/i.test(body)) {
-        addIssue(issues, "skill.missing_trigger", `Skill ${skillName} should explain when it should be used, preferably with a clear "Use this skill when..." trigger.`);
-    }
-    if (!/(## Workflow|^## Workflow|^\d+\.\s)/m.test(body)) {
-        addIssue(issues, "skill.missing_workflow", `Skill ${skillName} should define an explicit workflow instead of only background prose.`);
-    }
-    if (!/(## Rules|Do not|Output|Caveat|Caveats)/i.test(body)) {
-        addIssue(issues, "skill.missing_boundaries", `Skill ${skillName} should include execution boundaries such as rules, non-goals, caveats, or output expectations.`);
+    if (!metadata.description?.trim()) {
+        addIssue(issues, "skill.description.missing", `Skill ${skillName} must define a frontmatter description so agents can compare its boundary without reading the whole document.`);
     }
 }
 function validateToolContract(tool, issues) {
@@ -85,9 +188,6 @@ function validateToolContract(tool, issues) {
         addIssue(issues, "tool.description.too_short", `Tool ${tool.id} should use a more specific description that explains invocation boundaries and argument expectations.`);
         return;
     }
-    if (!/(Use this when|Do not use|Before calling)/i.test(description)) {
-        addIssue(issues, "tool.description.missing_boundary", `Tool ${tool.id} description should describe when to call it and, ideally, when not to call it or what must be true before calling it.`);
-    }
 }
 export function validateFrameworkContracts(input) {
     const mode = normalizeMode(input.mode);
@@ -95,12 +195,12 @@ export function validateFrameworkContracts(input) {
         return;
     }
     const issues = [];
-    const referencedSubagentIds = new Set(input.agents.flatMap((agent) => agent.subagentRefs.map((ref) => ref.replace(/^agent\//, ""))));
+    const referencedSubagentIds = new Set(input.agents.flatMap((agent) => agent.subagentRefs.map(resolveRefId)));
     for (const agent of input.agents) {
         if (!isWorkspaceOwnedPath(agent.sourcePath, input.ownedRoots)) {
             continue;
         }
-        validateAgentContract(agent, referencedSubagentIds, issues);
+        validateAgentContract(agent, referencedSubagentIds, input.tools, issues);
     }
     for (const [skillName, skillRoot] of input.skillRegistry) {
         if (!isWorkspaceOwnedPath(skillRoot, input.ownedRoots)) {

package/dist/workspace/object-loader.js

@@ -29,6 +29,7 @@ const CONSUMED_AGENT_CONFIG_KEYS = [
     "filesystem",
     "builtinTools",
     "interactionMode",
+    "executionContract",
 ];
 const NON_AGENT_CONFIG_ITEM_KEYS = [
     "id",
@@ -65,6 +66,7 @@ const MIGRATED_AGENT_CONFIG_KEYS = [
     "filesystem",
     "builtinTools",
     "interactionMode",
+    "executionContract",
 ];
 function normalizeAgentItemForMerge(item) {
     const normalized = { ...item };
@@ -267,6 +269,7 @@ function readSharedAgentConfig(config) {
         ...(config.includeAgentName === "inline" ? { includeAgentName: "inline" } : {}),
         ...(config.version === "v1" || config.version === "v2" ? { version: config.version } : {}),
         ...(typeof config.filesystem === "object" && config.filesystem ? { filesystem: config.filesystem } : {}),
+        ...(typeof config.executionContract === "object" && config.executionContract ? { executionContract: config.executionContract } : {}),
         ...(backend ? { backend } : {}),
         ...(store ? { store } : {}),
         ...(middleware ? { middleware } : {}),

package/package.json

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