🤖 refactor: strengthen exec sub-agent prompt guidance (#2061)

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`

---

<details>
<summary>📋 Implementation Plan</summary>

# 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):

```md
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._

</details>

---

_Generated with `mux` • Model: openai:gpt-5.2 • Thinking: xhigh • Cost:
`$1.53`_

<!-- mux-attribution: model=openai:gpt-5.2 thinking=xhigh costs=1.53 -->

Author: ThomasK33

docs/agents/index.mdx

@@ -302,19 +302,21 @@ ui:
 subagent:
   runnable: true
   append_prompt: |
-    If you are running as a sub-agent in a child workspace:
+    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.
-    - If you need repo context, spawn 1–N `explore` tasks (read-only) to locate code/tests/patterns, then write a short internal "mini-plan" before editing.
+    - 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 code/tests/patterns, then write a short internal "mini-plan" before editing.
       If the task brief already includes clear starting points + acceptance criteria, skip the initial explore pass and only explore when blocked.
-      Prefer `explore` outputs that include paths + symbols + minimal excerpts.
+      Prefer 1–3 narrow `explore` tasks (possibly in parallel) and prefer outputs that include paths + symbols + minimal excerpts.
     - If the task brief is missing critical information (scope, acceptance, or starting points) and you cannot infer it safely after a quick `explore`, do not guess.
       Stop and call `agent_report` once with 1–3 concrete questions/unknowns for the parent agent, and do not create commits.
     - Run targeted verification and create one or more git commits.
-    - When you have a final answer, call agent_report exactly once with:
+    - **Before your stream ends, you MUST call `agent_report` exactly once with:**
       - What changed (paths / key details)
       - What you ran (tests, typecheck, lint)
       - Any follow-ups / risks
+      (If you forget, the parent will inject a follow-up message and you'll waste tokens.)
     - You may call task/task_await/task_list/task_terminate to delegate further when available.
       Delegation is limited by Max Task Nesting Depth (Settings → Agents → Task Settings).
     - Do not call propose_plan.

src/node/builtinAgents/exec.md

@@ -6,19 +6,21 @@ ui:
 subagent:
   runnable: true
   append_prompt: |
-    If you are running as a sub-agent in a child workspace:
+    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.
-    - If you need repo context, spawn 1–N `explore` tasks (read-only) to locate code/tests/patterns, then write a short internal "mini-plan" before editing.
+    - 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 code/tests/patterns, then write a short internal "mini-plan" before editing.
       If the task brief already includes clear starting points + acceptance criteria, skip the initial explore pass and only explore when blocked.
-      Prefer `explore` outputs that include paths + symbols + minimal excerpts.
+      Prefer 1–3 narrow `explore` tasks (possibly in parallel) and prefer outputs that include paths + symbols + minimal excerpts.
     - If the task brief is missing critical information (scope, acceptance, or starting points) and you cannot infer it safely after a quick `explore`, do not guess.
       Stop and call `agent_report` once with 1–3 concrete questions/unknowns for the parent agent, and do not create commits.
     - Run targeted verification and create one or more git commits.
-    - When you have a final answer, call agent_report exactly once with:
+    - **Before your stream ends, you MUST call `agent_report` exactly once with:**
       - What changed (paths / key details)
       - What you ran (tests, typecheck, lint)
       - Any follow-ups / risks
+      (If you forget, the parent will inject a follow-up message and you'll waste tokens.)
     - You may call task/task_await/task_list/task_terminate to delegate further when available.
       Delegation is limited by Max Task Nesting Depth (Settings → Agents → Task Settings).
     - Do not call propose_plan.