hammer-ai 0.2.9 → 0.2.11

package/dist/index.d.ts

@@ -2044,15 +2044,6 @@ declare function buildValidationErrorMessage(zodError: unknown): string;
  */
 declare function buildNoStructuredResponseFoundError(): string;
 
-/**
- * Build a user-feedback message to send to the LLM when its response failed
- * to parse. Gives more actionable guidance than a generic "parse failed" message.
- *
- * @param content     The raw LLM content that failed to parse
- * @param zodError    Optional Zod validation error for field-specific feedback
- * @returns           A feedback string to send as a user message
- */
-declare function buildParseFeedback(_content: string, zodError?: unknown): string;
 interface ParseResponseWithRecoveryOptions extends ParseAgentResponseOptions {
     /**
      * The LLM's `finishReason` string. When `"length"`, Tier 2 truncation
@@ -2249,6 +2240,65 @@ declare abstract class Tool implements ToolLike {
     toDefinition(): ToolDefinition;
 }
 
+/**
+ * SubAgentTool — a Tool that runs its own contained agentic loop.
+ *
+ * Subclasses define domain-specific logic in isolation so those rules
+ * stay OUT of the main agent's context window:
+ *
+ *   - `getSubAgentSystemPrompt()` — the sub-agent's dedicated system prompt
+ *   - `getSubAgentTools()`        — tools available within the sub-agent loop
+ *   - `getSubAgentLLMProvider()`  — LLM provider config for sub-agent inference
+ *
+ * The main agent calls a SubAgentTool like any other tool, passing a `task`
+ * string.  The sub-agent autonomously handles the task and returns the result.
+ */
+
+interface SubAgentToolOptions {
+    /** Maximum tool-call rounds before giving up. Default: 10. */
+    maxSteps?: number;
+    /** Temperature for LLM calls. Defaults to LLMClient's built-in default (0.2). */
+    temperature?: number;
+}
+/**
+ * A Tool that runs its own contained agentic loop.
+ *
+ * Domain-specific rules live in `getSubAgentSystemPrompt()` and are never
+ * injected into the main agent's context — only the short tool description
+ * is visible to the parent.
+ *
+ * @example
+ * ```ts
+ * class ImagePromptAgent extends SubAgentTool {
+ *   getName()  { return "GenerateImage" }
+ *   getDescription() { return "Generate a slide background photo." }
+ *   getSchema() { return { task: { type: "string", required: true, ... } } }
+ *
+ *   protected getSubAgentSystemPrompt() { return IMAGE_RULES_PROMPT }
+ *   protected getSubAgentTools()        { return [new RawGenerateImage()] }
+ *   protected getSubAgentLLMProvider()  { return getProviderConfig("qwen3.6-plus") }
+ * }
+ * ```
+ */
+declare abstract class SubAgentTool extends Tool {
+    protected readonly subAgentOptions: SubAgentToolOptions;
+    constructor(workspaceRoot?: string, options?: SubAgentToolOptions);
+    /** Domain-specific system prompt for this sub-agent's dedicated loop. */
+    protected abstract getSubAgentSystemPrompt(): string;
+    /** Tools available within this sub-agent's loop. */
+    protected abstract getSubAgentTools(): ToolLike[];
+    /** LLM provider config used for this sub-agent's inference calls. */
+    protected abstract getSubAgentLLMProvider(): LLMProviderConfig;
+    getSchema(): ToolSchema;
+    /**
+     * Build the task string from raw execute params.
+     * Override when `getSchema()` adds parameters beyond `task`.
+     */
+    protected buildSubAgentTask(params: Record<string, any>): string;
+    execute(params: Record<string, any>): Promise<ToolResult>;
+    protected runSubAgentLoop(task: string): Promise<ToolResult>;
+}
+
 /**
  * Shared ToolRegistry infrastructure.
  *
@@ -2404,4 +2454,4 @@ declare function runStructuredLLMCompaction<TMessage extends MemoryMessage, TSta
     parseState: (obj: Record<string, unknown>) => TState | null;
 }): Promise<TState | null>;
 
-export { AGENT_MACHINE_STATES, AgentLoop, type AgentLoopCallbacks, type AgentLoopDeps, type AgentMachineContext, type AgentMachineEvent, type AgentMachineState, type AgentMemoryCitation, type AgentMemoryConstraint, type AgentMemoryEvidence, type AgentMemoryFactoryOverrides, AgentMemoryLayer, type AgentMemoryLayerConfig, type AgentMemoryLogger, type AgentMemoryNote, type AgentMemoryTask, type AgentMessage, type AgentPhase, type AgentState, ApiError, type BackgroundBashAction, BackgroundBashRunCommand, BaseMemoryLayer, BaseValidationEnforcer, BashRunCommand, type BuildMemoryCompactionPromptOptions, CODE_QUALITY_RULE_LINE, CharTokenEstimator, type ChatMessage, type CommandRuntime, type CommandTargetInfo, type CompactionCursor, type CompactionLLMClient, type ConversationAdapter, type ConversationSink, type CreateWebRuntimeSetupOptions, DEFAULT_AGENT_FALLBACK_SYSTEM_PROMPT, DEFAULT_ALLOWED_RUN_TARGETS, DEFAULT_RUN_COMMAND_REGISTRY, DEFAULT_THREAD_AUTO_SCROLL_BOTTOM_THRESHOLD, DEFAULT_TOOL_MEMORY_EXTRACTOR, ERROR_RECOVERY_RULE_LINE, ERROR_TRUNCATED_RESPONSE, type EnforcerResult, type ExecuteWebLoopRunOptions, type FetchLike, type FetchResponseLike, type HammerAgentConfig, type HammerAgentProviderPreset, INCREMENTAL_TESTING_RULE_LINE, JUST_BASH_SCRIPT_EXECUTION_RESTRICTION_LINES, JUST_BASH_SHELL_NATIVE_WORKFLOW_COMMAND_EXAMPLES, LLMClient, type LLMClientResponse, type LLMProviderConfig, type LLMRequest, type LLMRequestOptions, type LLMResponse, LLMResponseSchema, type LoopOutcome, MAX_TOOL_RESULT_CHARS, type MemoryMessage, type MemoryProvenance, type MemoryStorage, PORT_CONFLICT_RULE_LINE, type ParseAgentResponseOptions, type ParsedAgentResponse, type ParsedBackgroundBashCommand, type ParsedStepInput, PendingAgentMessageBuffer, type PersistedMemoryData, type ProviderName, ProxyTool, type ProxyToolExecutor, ROOT_CAUSES_RULE_LINE, type RawMessage, RunCommand, type RunCommandParseResult, type RunCommandPromptAvailability, RunCommandRegistry, type RunInvocationTarget, type RuntimeController, type RuntimeSnapshotUpdater, type RuntimeStore, type RuntimeSubscriber, SHARED_TOOL_CALL_EXAMPLE_LINES, SHARED_TOOL_USAGE_RULE, SINGLE_TOOL_CALL_RUN_LINE_EXAMPLE, SKILL_INVOKE_READ_RULE_LINE, STANDARD_TOOL_CALL_FORMAT_RULES, SUPPORTED_RUN_TARGETS, type SkillSummaryLike, type StepResult, type StreamCallbacks, StreamingToolParser, type StreamingToolParserCallbacks, type SystemPromptBuildContext, type SystemPromptCustomizer, type SystemPromptSections, TODO_LIST_FIRST_RESPONSE_RULE_LINE, TOOL_CALL_SEPARATOR_RULE, type TodoItem, type TodoStatus, type TokenEstimator, Tool, type ToolCall, ToolCallSchema, type ToolDataPrimitive, type ToolDataSchema, type ToolDataValue, type ToolDefinition, type ToolDefinitionMetadata, type ToolExecutionResult, type ToolLike, ToolLoopAgentRuntime, type ToolLoopAgentRuntimeDeps, type ToolLoopRuntimeExecuteStepResult, type ToolLoopRuntimeHooks, type ToolLoopRuntimeInfrastructure, type ToolLoopRuntimeLLMRequest, type ToolLoopRuntimeLLMResponse, type ToolLoopRuntimeRunStepOptions, type ToolLoopRuntimeRunStepResult, type ToolLoopRuntimeSetup, type ToolLoopRuntimeStepContext, type ToolLoopStepExecutionResult, type ToolLoopStepExecutorCallbacks, type ToolLoopStepExecutorOptions, type ToolLoopStepExecutorResponse, type ToolMemoryCitationKind, type ToolMemoryEvidenceKind, type ToolMemoryEvidencePolicy, type ToolMemoryExtractor, type ToolMemoryMetadata, type ToolMemoryNoteKind, type ToolMemoryNotePolicy, type ToolMemoryNoteScope, type ToolMetadata, type ToolParameterDefinition, ToolRegistry, type ToolRegistryBeforeExecuteContext, type ToolRegistryMissingToolContext, type ToolRegistryOptions, type ToolResult, ToolRunCommand, type ToolSchema, type TruncatedToolInfo, VALIDATE_AFTER_CHANGES_RULE_LINE, type WebSearchToolActionInput, WebToolLoopAgentRuntime, type WebToolLoopAgentRuntimeConstructorOptions, type WebToolLoopRuntimeStateLike, WebValidationEnforcer, type WorkspaceCodingStaticRulesOptions, agentMachine, applyIdleWebAgentState, applyInitialWebAgentRunState, buildAgentIdentityLine, buildAgentSystemPrompt, buildCompactionEntry, buildCoreStaticRules, buildNoStructuredResponseFoundError, buildParseFeedback, buildSkillAwareStaticContext, buildSkillsSection, buildStepUserMessage, buildToolLogRevealFrames, buildToolUsageExample, buildValidationErrorMessage, buildWebRuntimeRules, buildWorkspaceCodingStaticRules, canonicalizeCompactionText, coerceToolCallToDefinition, configure, containsStandaloneStructuredInvocationStart, createAgentMemoryLayer, createAppendToolsSectionCustomizer, createBackgroundBashDefinition, createConversationSink, createCustomRunCommandRegistry, createInitialWebAgentState, createRunCommandRuntimeBindings, createRuntimeStore, createToolAgentMessage, createToolRegistry, createToolsSectionOverrideCustomizer, createWebAgentMessageIdGenerator, createWebSearchToolActions, createWebToolLoopCallbacks, decodeEscapedShellText, defineRuntimeController, enrichToolResultWithUnixMetadata, executeBackgroundUnixCommandString, executeToolCallWithRunCommands, executeToolLoopStep, executeToolSafe, executeUnixCommandString, extractPrimaryCommandMetadata, extractTruncatedToolInfo, formatToolCallAsUnixCommand, formatToolDefinitions, formatToolResultMessage, formatToolsSection, formatUnixToolSurface, formatZodValidationError, getDiagnosticSummaryLine, getProviderConfig, getRunCommandPromptAvailability, getToolLogSummaryLine, isBackgroundBashToolCall, isBashToolCall, limitEntriesByRecency, machineStateToWebAgentPhase, mapConversationRoleToAgentRole, parseAgentResponse, parseResponseWithRecovery, parseStructuredAgentText, parseToolResultMessage, parseUnixToolCommand, readDiagnosticLevel, readDiagnosticSource, resolveToolDefinitionForInvocation, runStructuredLLMCompaction, selectLatestByKey, shouldAutoScrollThread, shouldSkipStepUserMessage, stripDiagnosticMessagePrefix, suppressWebValidationLog, tokenizeUnixCommand, truncateToolResult };
+export { AGENT_MACHINE_STATES, AgentLoop, type AgentLoopCallbacks, type AgentLoopDeps, type AgentMachineContext, type AgentMachineEvent, type AgentMachineState, type AgentMemoryCitation, type AgentMemoryConstraint, type AgentMemoryEvidence, type AgentMemoryFactoryOverrides, AgentMemoryLayer, type AgentMemoryLayerConfig, type AgentMemoryLogger, type AgentMemoryNote, type AgentMemoryTask, type AgentMessage, type AgentPhase, type AgentState, ApiError, type BackgroundBashAction, BackgroundBashRunCommand, BaseMemoryLayer, BaseValidationEnforcer, BashRunCommand, type BuildMemoryCompactionPromptOptions, CODE_QUALITY_RULE_LINE, CharTokenEstimator, type ChatMessage, type CommandRuntime, type CommandTargetInfo, type CompactionCursor, type CompactionLLMClient, type ConversationAdapter, type ConversationSink, type CreateWebRuntimeSetupOptions, DEFAULT_AGENT_FALLBACK_SYSTEM_PROMPT, DEFAULT_ALLOWED_RUN_TARGETS, DEFAULT_RUN_COMMAND_REGISTRY, DEFAULT_THREAD_AUTO_SCROLL_BOTTOM_THRESHOLD, DEFAULT_TOOL_MEMORY_EXTRACTOR, ERROR_RECOVERY_RULE_LINE, ERROR_TRUNCATED_RESPONSE, type EnforcerResult, type ExecuteWebLoopRunOptions, type FetchLike, type FetchResponseLike, type HammerAgentConfig, type HammerAgentProviderPreset, INCREMENTAL_TESTING_RULE_LINE, JUST_BASH_SCRIPT_EXECUTION_RESTRICTION_LINES, JUST_BASH_SHELL_NATIVE_WORKFLOW_COMMAND_EXAMPLES, LLMClient, type LLMClientResponse, type LLMProviderConfig, type LLMRequest, type LLMRequestOptions, type LLMResponse, LLMResponseSchema, type LoopOutcome, MAX_TOOL_RESULT_CHARS, type MemoryMessage, type MemoryProvenance, type MemoryStorage, PORT_CONFLICT_RULE_LINE, type ParseAgentResponseOptions, type ParsedAgentResponse, type ParsedBackgroundBashCommand, type ParsedStepInput, PendingAgentMessageBuffer, type PersistedMemoryData, type ProviderName, ProxyTool, type ProxyToolExecutor, ROOT_CAUSES_RULE_LINE, type RawMessage, RunCommand, type RunCommandParseResult, type RunCommandPromptAvailability, RunCommandRegistry, type RunInvocationTarget, type RuntimeController, type RuntimeSnapshotUpdater, type RuntimeStore, type RuntimeSubscriber, SHARED_TOOL_CALL_EXAMPLE_LINES, SHARED_TOOL_USAGE_RULE, SINGLE_TOOL_CALL_RUN_LINE_EXAMPLE, SKILL_INVOKE_READ_RULE_LINE, STANDARD_TOOL_CALL_FORMAT_RULES, SUPPORTED_RUN_TARGETS, type SkillSummaryLike, type StepResult, type StreamCallbacks, StreamingToolParser, type StreamingToolParserCallbacks, SubAgentTool, type SubAgentToolOptions, type SystemPromptBuildContext, type SystemPromptCustomizer, type SystemPromptSections, TODO_LIST_FIRST_RESPONSE_RULE_LINE, TOOL_CALL_SEPARATOR_RULE, type TodoItem, type TodoStatus, type TokenEstimator, Tool, type ToolCall, ToolCallSchema, type ToolDataPrimitive, type ToolDataSchema, type ToolDataValue, type ToolDefinition, type ToolDefinitionMetadata, type ToolExecutionResult, type ToolLike, ToolLoopAgentRuntime, type ToolLoopAgentRuntimeDeps, type ToolLoopRuntimeExecuteStepResult, type ToolLoopRuntimeHooks, type ToolLoopRuntimeInfrastructure, type ToolLoopRuntimeLLMRequest, type ToolLoopRuntimeLLMResponse, type ToolLoopRuntimeRunStepOptions, type ToolLoopRuntimeRunStepResult, type ToolLoopRuntimeSetup, type ToolLoopRuntimeStepContext, type ToolLoopStepExecutionResult, type ToolLoopStepExecutorCallbacks, type ToolLoopStepExecutorOptions, type ToolLoopStepExecutorResponse, type ToolMemoryCitationKind, type ToolMemoryEvidenceKind, type ToolMemoryEvidencePolicy, type ToolMemoryExtractor, type ToolMemoryMetadata, type ToolMemoryNoteKind, type ToolMemoryNotePolicy, type ToolMemoryNoteScope, type ToolMetadata, type ToolParameterDefinition, ToolRegistry, type ToolRegistryBeforeExecuteContext, type ToolRegistryMissingToolContext, type ToolRegistryOptions, type ToolResult, ToolRunCommand, type ToolSchema, type TruncatedToolInfo, VALIDATE_AFTER_CHANGES_RULE_LINE, type WebSearchToolActionInput, WebToolLoopAgentRuntime, type WebToolLoopAgentRuntimeConstructorOptions, type WebToolLoopRuntimeStateLike, WebValidationEnforcer, type WorkspaceCodingStaticRulesOptions, agentMachine, applyIdleWebAgentState, applyInitialWebAgentRunState, buildAgentIdentityLine, buildAgentSystemPrompt, buildCompactionEntry, buildCoreStaticRules, buildNoStructuredResponseFoundError, buildSkillAwareStaticContext, buildSkillsSection, buildStepUserMessage, buildToolLogRevealFrames, buildToolUsageExample, buildValidationErrorMessage, buildWebRuntimeRules, buildWorkspaceCodingStaticRules, canonicalizeCompactionText, coerceToolCallToDefinition, configure, containsStandaloneStructuredInvocationStart, createAgentMemoryLayer, createAppendToolsSectionCustomizer, createBackgroundBashDefinition, createConversationSink, createCustomRunCommandRegistry, createInitialWebAgentState, createRunCommandRuntimeBindings, createRuntimeStore, createToolAgentMessage, createToolRegistry, createToolsSectionOverrideCustomizer, createWebAgentMessageIdGenerator, createWebSearchToolActions, createWebToolLoopCallbacks, decodeEscapedShellText, defineRuntimeController, enrichToolResultWithUnixMetadata, executeBackgroundUnixCommandString, executeToolCallWithRunCommands, executeToolLoopStep, executeToolSafe, executeUnixCommandString, extractPrimaryCommandMetadata, extractTruncatedToolInfo, formatToolCallAsUnixCommand, formatToolDefinitions, formatToolResultMessage, formatToolsSection, formatUnixToolSurface, formatZodValidationError, getDiagnosticSummaryLine, getProviderConfig, getRunCommandPromptAvailability, getToolLogSummaryLine, isBackgroundBashToolCall, isBashToolCall, limitEntriesByRecency, machineStateToWebAgentPhase, mapConversationRoleToAgentRole, parseAgentResponse, parseResponseWithRecovery, parseStructuredAgentText, parseToolResultMessage, parseUnixToolCommand, readDiagnosticLevel, readDiagnosticSource, resolveToolDefinitionForInvocation, runStructuredLLMCompaction, selectLatestByKey, shouldAutoScrollThread, shouldSkipStepUserMessage, stripDiagnosticMessagePrefix, suppressWebValidationLog, tokenizeUnixCommand, truncateToolResult };

package/dist/index.js

@@ -3559,12 +3559,6 @@ function shouldPreferBashToolLogRecovery(current, recovered) {
   }
   return currentCommand !== recoveredCommand && (currentToolCall.truncated === true || /\n\[(?:TOOL_LOG|stderr|meta|exit):?/i.test(currentCommand) || /\n\[(?:stderr|meta|exit)\]/i.test(currentCommand));
 }
-function buildParseFeedback(_content, zodError) {
-  if (zodError) {
-    return buildValidationErrorMessage(zodError);
-  }
-  return buildNoStructuredResponseFoundError();
-}
 function looksLikeStandaloneControlSegment(content, allowedRunTargets) {
   return containsStandaloneStructuredInvocationStart(content, allowedRunTargets);
 }
@@ -4545,20 +4539,6 @@ function buildCompactionEntry(options) {
     createMemoryMetadata(options.provenance)
   );
 }
-function sanitizeMemoryProvenance(value, fallback) {
-  if (!value || typeof value !== "object") {
-    return fallback;
-  }
-  const candidate = value;
-  const source = typeof candidate.source === "string" ? candidate.source : void 0;
-  if (!source || !MEMORY_PROVENANCE_SOURCES.has(source)) {
-    return fallback;
-  }
-  return {
-    source,
-    detail: typeof candidate.detail === "string" ? candidate.detail : fallback.detail
-  };
-}
 function cleanCompactionText(text) {
   return text.trim().replace(/\s+/g, " ").replace(/[.?!:;]+$/, "");
 }
@@ -4607,45 +4587,35 @@ function formatMemoryMetadataTag(metadata) {
   const detail = metadata.provenance.detail ? `/${metadata.provenance.detail}` : "";
   return ` [${metadata.provenance.source}${detail}]`;
 }
-function sanitizeCompactionEntries(input, options) {
-  if (!Array.isArray(input)) {
-    return [];
-  }
-  return input.flatMap((value) => {
-    if (typeof value === "string") {
-      const entry2 = options.fromString?.(value);
-      return entry2 ? [entry2] : [];
-    }
-    if (!value || typeof value !== "object") {
-      return [];
-    }
-    const entry = options.fromObject?.(value);
-    return entry ? [entry] : [];
-  });
-}
 function createEntrySanitizer(options) {
-  return (input, fallbackTurn, fallbackProvenance = options.defaultProvenance) => sanitizeCompactionEntries(input, {
-    fromString: options.fromString ? (value) => options.fromString(value, {
-      turn: fallbackTurn,
-      provenance: fallbackProvenance
-    }) : void 0,
-    fromObject: (value) => options.fromObject(value, {
-      turn: options.getTurn?.(value, fallbackTurn) ?? (typeof value.turn === "number" && Number.isFinite(value.turn) ? value.turn : fallbackTurn),
-      provenance: sanitizeMemoryProvenance(
-        options.getProvenance?.(value) ?? value.provenance,
-        fallbackProvenance
-      )
-    })
-  });
-}
-function parseCompactionJsonObject(raw) {
-  try {
-    const cleaned = raw.replace(/```json\n?|```\n?/gi, "").trim();
-    const parsed = JSON.parse(cleaned);
-    return parsed && typeof parsed === "object" ? parsed : null;
-  } catch {
-    return null;
-  }
+  return (input, fallbackTurn, fallbackProvenance = options.defaultProvenance) => {
+    if (!Array.isArray(input)) return [];
+    return input.flatMap((value) => {
+      if (typeof value === "string") {
+        const entry2 = options.fromString?.(value, { turn: fallbackTurn, provenance: fallbackProvenance });
+        return entry2 ? [entry2] : [];
+      }
+      if (!value || typeof value !== "object") return [];
+      const obj = value;
+      const rawProv = options.getProvenance?.(obj) ?? obj.provenance;
+      let provenance = fallbackProvenance;
+      if (rawProv && typeof rawProv === "object") {
+        const c = rawProv;
+        const source = typeof c.source === "string" ? c.source : void 0;
+        if (source && MEMORY_PROVENANCE_SOURCES.has(source)) {
+          provenance = {
+            source,
+            detail: typeof c.detail === "string" ? c.detail : fallbackProvenance.detail
+          };
+        }
+      }
+      const entry = options.fromObject(obj, {
+        turn: options.getTurn?.(obj, fallbackTurn) ?? (typeof obj.turn === "number" && Number.isFinite(obj.turn) ? obj.turn : fallbackTurn),
+        provenance
+      });
+      return entry ? [entry] : [];
+    });
+  };
 }
 async function runStructuredLLMCompaction(options) {
   if (!options.client) {
@@ -4665,7 +4635,14 @@ async function runStructuredLLMCompaction(options) {
     maxTokens: options.maxTokens ?? 4096,
     stream: false
   });
-  const parsed = parseCompactionJsonObject(result.content);
+  let parsed = null;
+  try {
+    const cleaned = result.content.replace(/```json\n?|```\n?/gi, "").trim();
+    const obj = JSON.parse(cleaned);
+    parsed = obj && typeof obj === "object" ? obj : null;
+  } catch {
+    parsed = null;
+  }
   return parsed ? options.parseState(parsed) : null;
 }
 
@@ -6688,7 +6665,7 @@ ${JSON.stringify(request.messages, null, 2)}`
     }
     if (!stepParsed) {
       const parseError = new Error(
-        buildParseFeedback(response.content)
+        buildNoStructuredResponseFoundError()
       );
       parseError.isWebParseFailure = true;
       parseError.rawContent = response.content;
@@ -7193,6 +7170,97 @@ var Tool = class {
   }
 };
 
+// src/sub-agent.ts
+var SubAgentTool = class extends Tool {
+  subAgentOptions;
+  constructor(workspaceRoot = "", options) {
+    super(workspaceRoot);
+    this.subAgentOptions = options ?? {};
+  }
+  // ---- default task schema (override to add extra params) ---------------
+  getSchema() {
+    return {
+      task: {
+        type: "string",
+        required: true,
+        positional: false,
+        description: "The task for the sub-agent to complete."
+      }
+    };
+  }
+  /**
+   * Build the task string from raw execute params.
+   * Override when `getSchema()` adds parameters beyond `task`.
+   */
+  buildSubAgentTask(params) {
+    return typeof params.task === "string" ? params.task.trim() : "";
+  }
+  // ---- execute ---------------------------------------------------------
+  async execute(params) {
+    const task = this.buildSubAgentTask(params);
+    if (!task) return { success: false, error: "task is required" };
+    return this.runSubAgentLoop(task);
+  }
+  // ---- core loop -------------------------------------------------------
+  async runSubAgentLoop(task) {
+    const { maxSteps = 10, temperature } = this.subAgentOptions;
+    const llmClient = new LLMClient(this.getSubAgentLLMProvider());
+    const subTools = this.getSubAgentTools();
+    const toolMap = new Map(subTools.map((t) => [t.getName(), t]));
+    const toolDefs = subTools.map((t) => t.toDefinition());
+    const systemPrompt = buildAgentSystemPrompt({
+      identityLine: this.getSubAgentSystemPrompt(),
+      tools: toolDefs,
+      allowedRunTargets: ["tool"],
+      supplementalRules: buildCoreStaticRules()
+    });
+    const messages = [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: task }
+    ];
+    for (let step = 0; step < maxSteps; step++) {
+      const response = await llmClient.chat({ messages, temperature });
+      messages.push({ role: "assistant", content: response.content });
+      const parsed = parseAgentResponse(response.content, {
+        // Allow "bash" so that exit 0 / exit 1 are intercepted as
+        // success / failure signals without being executed.
+        allowedRunTargets: ["tool", "bash"]
+      });
+      if (!parsed) {
+        return { success: false, error: "Sub-agent produced no structured response" };
+      }
+      if (parsed.outcome === "success") {
+        return { success: true, result: parsed.reasoning || "Done." };
+      }
+      if (parsed.outcome === "failure") {
+        return { success: false, error: parsed.reasoning || "Sub-agent reported failure" };
+      }
+      if (parsed.selectedToolCall) {
+        const raw = parsed.selectedToolCall;
+        const toolCall = coerceToolCallToDefinition(raw, toolDefs) ?? raw;
+        const tool = toolMap.get(toolCall.name);
+        if (!tool) {
+          const errResult = {
+            success: false,
+            error: `Unknown tool: ${toolCall.name}. Available: ${[...toolMap.keys()].join(", ")}`
+          };
+          messages.push({
+            role: "tool",
+            content: formatToolResultMessage(toolCall, errResult)
+          });
+          continue;
+        }
+        const result = await tool.execute(toolCall.parameters);
+        messages.push({
+          role: "tool",
+          content: formatToolResultMessage(toolCall, result)
+        });
+      }
+    }
+    return { success: false, error: `Sub-agent did not complete within ${maxSteps} steps` };
+  }
+};
+
 // src/registry.ts
 function isToolRegistryOptions(value) {
   if (!value || typeof value !== "object") {
@@ -7410,6 +7478,6 @@ async function executeToolLoopStep(options) {
   };
 }
 
-export { AGENT_MACHINE_STATES, AgentLoop, AgentMemoryLayer, ApiError, BackgroundBashRunCommand, BaseMemoryLayer, BaseValidationEnforcer, BashRunCommand, CODE_QUALITY_RULE_LINE, CharTokenEstimator, DEFAULT_AGENT_FALLBACK_SYSTEM_PROMPT, DEFAULT_ALLOWED_RUN_TARGETS, DEFAULT_RUN_COMMAND_REGISTRY, DEFAULT_THREAD_AUTO_SCROLL_BOTTOM_THRESHOLD, DEFAULT_TOOL_MEMORY_EXTRACTOR, ERROR_RECOVERY_RULE_LINE, ERROR_TRUNCATED_RESPONSE, INCREMENTAL_TESTING_RULE_LINE, JUST_BASH_SCRIPT_EXECUTION_RESTRICTION_LINES, JUST_BASH_SHELL_NATIVE_WORKFLOW_COMMAND_EXAMPLES, LLMClient, LLMResponseSchema, MAX_TOOL_RESULT_CHARS, PORT_CONFLICT_RULE_LINE, PendingAgentMessageBuffer, ProxyTool, ROOT_CAUSES_RULE_LINE, RunCommand, RunCommandRegistry, SHARED_TOOL_CALL_EXAMPLE_LINES, SHARED_TOOL_USAGE_RULE, SINGLE_TOOL_CALL_RUN_LINE_EXAMPLE, SKILL_INVOKE_READ_RULE_LINE, STANDARD_TOOL_CALL_FORMAT_RULES, SUPPORTED_RUN_TARGETS, StreamingToolParser, TODO_LIST_FIRST_RESPONSE_RULE_LINE, TOOL_CALL_SEPARATOR_RULE, Tool, ToolCallSchema, ToolLoopAgentRuntime, ToolRegistry, ToolRunCommand, VALIDATE_AFTER_CHANGES_RULE_LINE, WebToolLoopAgentRuntime, WebValidationEnforcer, agentMachine, applyIdleWebAgentState, applyInitialWebAgentRunState, buildAgentIdentityLine, buildAgentSystemPrompt, buildCompactionEntry, buildCoreStaticRules, buildNoStructuredResponseFoundError, buildParseFeedback, buildSkillAwareStaticContext, buildSkillsSection, buildStepUserMessage, buildToolLogRevealFrames, buildToolUsageExample, buildValidationErrorMessage, buildWebRuntimeRules, buildWorkspaceCodingStaticRules, canonicalizeCompactionText, coerceToolCallToDefinition, configure, containsStandaloneStructuredInvocationStart, createAgentMemoryLayer, createAppendToolsSectionCustomizer, createBackgroundBashDefinition, createConversationSink, createCustomRunCommandRegistry, createInitialWebAgentState, createRunCommandRuntimeBindings, createRuntimeStore, createToolAgentMessage, createToolRegistry, createToolsSectionOverrideCustomizer, createWebAgentMessageIdGenerator, createWebSearchToolActions, createWebToolLoopCallbacks, decodeEscapedShellText, defineRuntimeController, enrichToolResultWithUnixMetadata, executeBackgroundUnixCommandString, executeToolCallWithRunCommands, executeToolLoopStep, executeToolSafe, executeUnixCommandString, extractPrimaryCommandMetadata, extractTruncatedToolInfo, formatToolCallAsUnixCommand, formatToolDefinitions, formatToolResultMessage, formatToolsSection, formatUnixToolSurface, formatZodValidationError, getDiagnosticSummaryLine, getProviderConfig, getRunCommandPromptAvailability, getToolLogSummaryLine, isBackgroundBashToolCall, isBashToolCall, limitEntriesByRecency, machineStateToWebAgentPhase, mapConversationRoleToAgentRole, parseAgentResponse, parseResponseWithRecovery, parseStructuredAgentText, parseToolResultMessage, parseUnixToolCommand, readDiagnosticLevel, readDiagnosticSource, resolveToolDefinitionForInvocation, runStructuredLLMCompaction, selectLatestByKey, shouldAutoScrollThread, shouldSkipStepUserMessage, stripDiagnosticMessagePrefix, suppressWebValidationLog, tokenizeUnixCommand, truncateToolResult };
+export { AGENT_MACHINE_STATES, AgentLoop, AgentMemoryLayer, ApiError, BackgroundBashRunCommand, BaseMemoryLayer, BaseValidationEnforcer, BashRunCommand, CODE_QUALITY_RULE_LINE, CharTokenEstimator, DEFAULT_AGENT_FALLBACK_SYSTEM_PROMPT, DEFAULT_ALLOWED_RUN_TARGETS, DEFAULT_RUN_COMMAND_REGISTRY, DEFAULT_THREAD_AUTO_SCROLL_BOTTOM_THRESHOLD, DEFAULT_TOOL_MEMORY_EXTRACTOR, ERROR_RECOVERY_RULE_LINE, ERROR_TRUNCATED_RESPONSE, INCREMENTAL_TESTING_RULE_LINE, JUST_BASH_SCRIPT_EXECUTION_RESTRICTION_LINES, JUST_BASH_SHELL_NATIVE_WORKFLOW_COMMAND_EXAMPLES, LLMClient, LLMResponseSchema, MAX_TOOL_RESULT_CHARS, PORT_CONFLICT_RULE_LINE, PendingAgentMessageBuffer, ProxyTool, ROOT_CAUSES_RULE_LINE, RunCommand, RunCommandRegistry, SHARED_TOOL_CALL_EXAMPLE_LINES, SHARED_TOOL_USAGE_RULE, SINGLE_TOOL_CALL_RUN_LINE_EXAMPLE, SKILL_INVOKE_READ_RULE_LINE, STANDARD_TOOL_CALL_FORMAT_RULES, SUPPORTED_RUN_TARGETS, StreamingToolParser, SubAgentTool, TODO_LIST_FIRST_RESPONSE_RULE_LINE, TOOL_CALL_SEPARATOR_RULE, Tool, ToolCallSchema, ToolLoopAgentRuntime, ToolRegistry, ToolRunCommand, VALIDATE_AFTER_CHANGES_RULE_LINE, WebToolLoopAgentRuntime, WebValidationEnforcer, agentMachine, applyIdleWebAgentState, applyInitialWebAgentRunState, buildAgentIdentityLine, buildAgentSystemPrompt, buildCompactionEntry, buildCoreStaticRules, buildNoStructuredResponseFoundError, buildSkillAwareStaticContext, buildSkillsSection, buildStepUserMessage, buildToolLogRevealFrames, buildToolUsageExample, buildValidationErrorMessage, buildWebRuntimeRules, buildWorkspaceCodingStaticRules, canonicalizeCompactionText, coerceToolCallToDefinition, configure, containsStandaloneStructuredInvocationStart, createAgentMemoryLayer, createAppendToolsSectionCustomizer, createBackgroundBashDefinition, createConversationSink, createCustomRunCommandRegistry, createInitialWebAgentState, createRunCommandRuntimeBindings, createRuntimeStore, createToolAgentMessage, createToolRegistry, createToolsSectionOverrideCustomizer, createWebAgentMessageIdGenerator, createWebSearchToolActions, createWebToolLoopCallbacks, decodeEscapedShellText, defineRuntimeController, enrichToolResultWithUnixMetadata, executeBackgroundUnixCommandString, executeToolCallWithRunCommands, executeToolLoopStep, executeToolSafe, executeUnixCommandString, extractPrimaryCommandMetadata, extractTruncatedToolInfo, formatToolCallAsUnixCommand, formatToolDefinitions, formatToolResultMessage, formatToolsSection, formatUnixToolSurface, formatZodValidationError, getDiagnosticSummaryLine, getProviderConfig, getRunCommandPromptAvailability, getToolLogSummaryLine, isBackgroundBashToolCall, isBashToolCall, limitEntriesByRecency, machineStateToWebAgentPhase, mapConversationRoleToAgentRole, parseAgentResponse, parseResponseWithRecovery, parseStructuredAgentText, parseToolResultMessage, parseUnixToolCommand, readDiagnosticLevel, readDiagnosticSource, resolveToolDefinitionForInvocation, runStructuredLLMCompaction, selectLatestByKey, shouldAutoScrollThread, shouldSkipStepUserMessage, stripDiagnosticMessagePrefix, suppressWebValidationLog, tokenizeUnixCommand, truncateToolResult };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map