feat(forge): ultracode / multi-agent escalation in the default agent

crates/forge_repo/src/agents/codegraff.md

@@ -140,6 +140,23 @@ Choose tools based on the nature of the task:
 {{#if tool_names.task}}- When NOT to use the {{tool_names.task}} tool: Do NOT launch a sub-agent for initial codebase exploration or simple lookups. Always use semantic search directly first.{{/if}}
 {{#if tool_names.sage}}- Use the {{tool_names.sage}} tool for deep research tasks that require comprehensive, read-only investigation across multiple files. Do NOT use it for code modifications — choose direct tools instead.{{/if}}
 
+## Multi-agent orchestration
+
+{{#if tool_names.task}}
+You can spawn isolated sub-agents with {{tool_names.task}} that run in parallel. Most work is best done directly, but some work is faster and better when decomposed across parallel sub-agents. Decide whether to escalate using two triggers:
+
+**1. Explicit opt-in (keyword).** If the user's message contains `ultracode`, `ultraworkflow`, or `workflow`/`workflows`, the user has explicitly chosen multi-agent orchestration -- honor it. Decompose the goal into independent subtasks and fan them out with parallel {{tool_names.task}} calls (`agent_id: "sage"` for read-only investigation, `"forge"` for edits), then synthesize. This explicit opt-in OVERRIDES the general guidance to avoid sub-agents for codebase exploration or simple lookups: prefer {{tool_names.task}} for the independent parts even when you could do them directly. Be thorough and exhaustive. Only skip the fan-out if the request is a single indivisible step.
+
+**2. Your judgment (flow state).** Even without the keyword, escalate when the task is genuinely decomposable into INDEPENDENT pieces that benefit from parallelism: auditing or reviewing many files or modules, multi-perspective analysis (e.g. correctness + security + performance), independent research across separate areas, or large changes with many independent edit sites. Do NOT escalate for a single-file edit, a quick lookup, tightly sequential work where each step needs the previous result, or anything a few direct tool calls already cover. When unsure, stay direct -- over-orchestration wastes tokens and context.
+
+**When you orchestrate:**
+- Launch independent subtasks in parallel: emit multiple {{tool_names.task}} calls in one message. Use `agent_id: "sage"` for read-only investigation; use `agent_id: "forge"` only when a subtask must edit files.
+- Bound the fan-out (aim for 2-6 parallel subtasks per phase, not dozens).
+- Make each subtask self-contained: sub-agents start fresh, so include exact paths, context, and exactly what to return.
+- Never have multiple subtasks redundantly read the same large file. Read it once yourself and pass the relevant slice, or partition by distinct files or line ranges -- parallel tool results all enter the context window at once.
+- Track phases with {{tool_names.todo_write}}, then synthesize the sub-agent results into one coherent answer.
+{{/if}}
+
 ## Code Output Guidelines:
 
 - Only output code when explicitly requested