🤖 refactor: strengthen exec sub-agent prompt guidance

[ThomasK33]

Summary

Strengthens the Exec sub-agent-only prompt to encourage Explore-first indexing/discovery (to preserve context window) and to more strongly remind sub-agents to call agent_report exactly once.

Implementation

• Updated subagent.append_prompt in src/node/builtinAgents/exec.md to explicitly frame Explore as the code indexer and to add a stronger agent_report reminder.
• Kept docs/agents/index.mdx in sync with the updated exec.md content.

Validation

• make static-check

---

📋 Implementation Plan

Plan: Strengthen Exec sub-agent prompt (Explore-first + agent_report)

Context / Why

The built-in Exec agent prompt should be updated only when Exec is launched as a sub-agent (child workspace) to:

1. Reinforce that it should use Explore sub-agents/tasks for code indexing, discovery, and planning (to preserve the Exec sub-agent’s context window for implementation).
2. More strongly remind Exec (in Exec mode) to call agent_report exactly once when the tool is available, to avoid the system fallback message:
   Your stream ended without calling agent_report. Call agent_report exactly once now with your final report.

Evidence

• src/node/builtinAgents/exec.md
  • Contains the Exec agent definition and already has a subagent.append_prompt block (only appended for sub-agent workspaces).
  • Current sub-agent guidance mentions using explore tasks and calling agent_report, but can be made more explicit about indexing/discovery/planning and preserving context window.
• src/node/services/aiService.ts
  • Sub-agent detection: const isSubagentWorkspace = Boolean(metadata.parentWorkspaceId);
  • Prompt assembly appends subagent.append_prompt only when isSubagentWorkspace is true.
• docs/agents/index.mdx
  • Includes an inline copy of exec.md content; should be kept consistent after edits.
• Tests: src/node/services/agentDefinitions/builtInAgentDefinitions.test.ts
  • Asserts the exec subagent append_prompt contains specific substrings; our change should preserve them.

Implementation details

1) Update Exec sub-agent-only prompt (recommended)

File: src/node/builtinAgents/exec.md

Edit the YAML frontmatter subagent.append_prompt (the | block) to add a short, explicit directive that:

• Treats explore tasks as the sub-agent’s code indexer (paths/symbols/callsites/tests/patterns).
• Encourages using explore tasks for discovery + mini-planning before editing.
• Mentions the why: to preserve the Exec sub-agent’s context window for implementation.
• Re-emphasizes that the run is not complete until agent_report is called.

Suggested shape (exact wording can be tweaked, but keep it short):

subagent:
  append_prompt: |
    You are running as a sub-agent in a child workspace.

    - Take a single narrowly scoped task and complete it end-to-end. Do not expand scope.
    - Preserve your context window: use `explore` tasks as your code indexer for code indexing + discovery.
      If you need repo context, spawn 1–N `explore` tasks (read-only) to locate paths/symbols/callsites/tests and confirm patterns, then sketch a short internal "mini-plan" before editing.
      If starting points + acceptance are already clear, skip the initial explore pass and only explore when blocked.
      Prefer 1–3 narrow explore tasks (possibly in parallel) and prefer outputs with paths + symbols + minimal excerpts.
    - **Before your stream ends, you MUST call `agent_report` exactly once.**
      (If you forget, the parent will inject a follow-up message and you’ll waste tokens.)
    - When you have a final answer, call agent_report exactly once with:
      ...

Notes:

• Keep the existing “If the task brief is missing critical information…” paragraph intact (tests expect that substring).
• This change satisfies the “only when launched as a sub-agent” requirement because subagent.append_prompt is appended only in child workspaces.
• Since this prompt is only appended for sub-agents, phrase it as a statement (not “If …”) so it reads unambiguously.
• agent_report is only available in sub-agent workspaces; keep the strengthened reminder inside subagent.append_prompt to avoid confusing top-level Exec runs.

2) Keep docs in sync

File: docs/agents/index.mdx

Update the inline exec.md snippet under the “### Exec” accordion to match the updated subagent.append_prompt text.

Verification

1. bun test src/node/services/agentDefinitions/builtInAgentDefinitions.test.ts
2. Manual sanity check: spawn an Exec sub-agent task and confirm the system prompt includes the new Explore-first + agent_report reminders.

Net LoC estimate (product code)

• src/node/builtinAgents/exec.md: ~+6–12 LoC (text only)
• docs/agents/index.mdx: ~+6–12 LoC (text only)

No TypeScript/runtime logic changes expected.

---

Generated with mux • Model: openai:gpt-5.2 • Thinking: xhigh • Cost: $1.53