@dreki-gg/pi-subagent 0.5.0 → 0.7.0

package/docs/plans/05_advisor-routing.plan.md

@@ -0,0 +1,244 @@
+---
+name: "Advisor / smart-friend routing"
+overview: "Add a bundled `advisor` role and lightweight escalation guidance so strong primary agents in `@dreki-gg/pi-subagent` can ask for focused second opinions on tricky cases without turning every task into a swarm. This slice is about capability routing, not replacing the main worker."
+todo:
+  - id: "advisor-routing-1"
+    task: "Add a bundled `advisor` agent with a focused consultative contract: diagnose, suggest next investigation, and surface risks without taking ownership of implementation"
+    status: done
+  - id: "advisor-routing-2"
+    task: "Teach bundled worker/planner/reviewer prompts when to call the advisor and what context to send"
+    status: done
+  - id: "advisor-routing-3"
+    task: "Add a reusable prompt entry point and docs examples for advisor-assisted workflows"
+    status: done
+---
+
+# Goal
+
+Introduce a lightweight advisor pattern so primary agents can consult a strong second opinion for hard cases while keeping a single primary owner of the work.
+
+# Context
+
+- Parent rationale: we want capability routing and targeted escalation, not a default “everyone talks to everyone” swarm.
+- Module root: `packages/subagent`
+- This slice should work with the current package architecture and should not depend on a new runtime mode.
+- Keep the advisor narrowly scoped: diagnose, redirect, highlight risk, or suggest the next question. The advisor should not silently become another worker.
+
+## What exists
+
+Current relevant file tree on disk:
+
+- `packages/subagent/agents/planner.md`
+- `packages/subagent/agents/reviewer.md`
+- `packages/subagent/agents/worker.md`
+- `packages/subagent/agents/docs-scout.md`
+- `packages/subagent/prompts/implement.md`
+- `packages/subagent/prompts/implement-and-review.md`
+- `packages/subagent/README.md`
+- `packages/subagent/extensions/subagent/index.ts`
+- `packages/subagent/extensions/subagent/agent-runner.ts`
+- `packages/subagent/skills/spawn-subagents/SKILL.md`
+- `packages/subagent/skills/write-an-agent/SKILL.md`
+
+Actual current state on disk:
+
+- There is no bundled `advisor` agent in `packages/subagent/agents/`.
+- There is no advisor-oriented prompt template in `packages/subagent/prompts/`.
+- The current bundled roles are:
+  - `planner` for planning (`packages/subagent/agents/planner.md`)
+  - `worker` for implementation (`packages/subagent/agents/worker.md`)
+  - `reviewer` for verification (`packages/subagent/agents/reviewer.md`)
+  - plus `scout`, `docs-scout`, and `ux-designer`
+- The package runner already supports spawned agents consulting tools as needed:
+  - in `packages/subagent/extensions/subagent/index.ts:325-328`, `runSingleAgent()` passes `--tools` only when frontmatter declares them
+  - in `packages/subagent/extensions/subagent/agent-runner.ts:73-76`, `runAgent()` behaves the same way
+  - therefore bundled agents with omitted `tools:` can keep access to the broader tool surface, including `subagent`
+- The current prompt contracts do **not** teach any role when to escalate:
+  - `planner.md` only says to produce a concrete plan
+  - `worker.md` only says to complete the task autonomously
+  - `reviewer.md` only says to review the diff / files
+- The `spawn-subagents` skill recommends specialists and review loops, but does not mention an advisor or “consult when tricky” routing rule.
+
+# API inventory
+
+## Existing agent prompt contracts that may invoke advisor
+
+From `packages/subagent/agents/planner.md`:
+
+```md
+You are a planning specialist.
+You must NOT make any changes. Only read, analyze, and plan.
+```
+
+From `packages/subagent/agents/worker.md`:
+
+```md
+You are a worker agent with full capabilities.
+Work autonomously to complete the assigned task. Use all available tools as needed.
+```
+
+From `packages/subagent/agents/reviewer.md`:
+
+```md
+You are a senior code reviewer.
+Analyze code for quality, security, and maintainability.
+```
+
+## Existing subagent entry shapes available to an advisor pattern
+
+From the `subagent` tool surface:
+
+```ts
+// single consult
+{ agent: 'advisor', task: '...' }
+
+// consult inside a chain
+{ chain: [{ agent: 'worker', task: '...' }, { agent: 'advisor', task: '... {previous} ...' }] }
+
+// focused parallel consults
+{ tasks: [{ agent: 'advisor', task: '...' }, { agent: 'docs-scout', task: '...' }] }
+```
+
+## Proposed advisor contract
+
+The advisor should return guidance the caller can act on immediately:
+
+```md
+## Assessment
+- what looks tricky / risky / ambiguous
+
+## What to inspect next
+- concrete files, commands, or questions
+
+## Recommendation
+- best next action for the caller
+
+## Risks
+- what could still go wrong
+```
+
+The advisor should not claim to have implemented or verified anything it did not actually inspect.
+
+# Tasks
+
+## 1. Add a bundled `advisor` agent with a focused consultative contract
+
+### Files
+- Create `packages/subagent/agents/advisor.md`
+
+### What to add
+Create a concise bundled agent whose sole job is to provide focused second-opinion guidance.
+
+### Required behavior
+- Work from the caller’s question plus any provided handoff.
+- Ask the caller to investigate specific files / commands when the answer depends on context the advisor has not yet inspected.
+- Surface hidden risks or better approaches.
+- Avoid taking over implementation.
+- Prefer decisive recommendations over brainstorming lists.
+
+### Frontmatter guidance
+- Use an existing strong model already in package conventions (default to `openai/gpt-5.4` unless there is a strong reason to diversify).
+- Keep the prompt under ~100 lines per `packages/subagent/skills/write-an-agent/SKILL.md`.
+- Omit `tools:` only if you want the advisor to have broad access; otherwise keep the tool list minimal and read-oriented.
+
+### Suggested prompt rules
+1. Diagnose the hard part, not the whole task from scratch.
+2. If more repo context is needed, say exactly what to inspect next.
+3. Return a recommendation the caller can act on immediately.
+4. Do not implement code or rewrite plans unless explicitly asked.
+
+## 2. Teach bundled prompts when to call the advisor and what context to send
+
+### Files
+- Modify `packages/subagent/agents/worker.md`
+- Modify `packages/subagent/agents/planner.md`
+- Modify `packages/subagent/agents/reviewer.md`
+
+### What to change
+Add small, explicit escalation rules to the existing bundled roles.
+
+### Recommended escalation triggers
+- `worker`
+  - ambiguous architecture tradeoff
+  - persistent failing tests or unexplained errors
+  - merge conflicts / tangled diffs
+  - security-sensitive or migration-heavy changes
+- `planner`
+  - multiple viable designs with materially different blast radius
+  - unclear ownership boundaries across packages
+  - need for sharper decomposition before implementation
+- `reviewer`
+  - uncertainty whether an issue is real vs. intended
+  - suspected deeper architectural problem beyond the current diff
+  - need for a second opinion on severity
+
+### Required context to send when consulting advisor
+Keep the consult lightweight:
+- current role (`worker` / `planner` / `reviewer`)
+- the exact question
+- touched files / symbols if known
+- the smallest relevant task summary
+- what has already been tried or observed
+
+### Notes
+- Do not tell every role to always call the advisor. This is an escalation path, not a mandatory step.
+- Keep the primary role in charge; the advisor should inform decisions, not replace ownership.
+
+## 3. Add a reusable prompt entry point and docs examples for advisor-assisted workflows
+
+### Files
+- Create `packages/subagent/prompts/consult-advisor.md`
+- Modify `packages/subagent/README.md`
+- Modify `packages/subagent/skills/spawn-subagents/SKILL.md`
+
+### What to add
+Create a simple prompt template that encourages focused advisor consultation without changing core workflow semantics.
+
+### Suggested prompt shape
+
+```md
+Use the subagent tool to consult the `advisor` agent about: $@
+
+The advisor should:
+1. identify the hard part
+2. suggest the next investigation or decision
+3. surface concrete risks
+4. return a recommendation, not a full implementation
+```
+
+### README / skill updates
+- Add `advisor` to the bundled agent list once shipped.
+- Add one example such as:
+  - “ask advisor whether this migration should be split before sending it to worker”
+  - “have worker consult advisor on the failing test loop”
+- In `spawn-subagents`, add guidance that advisor use is optional and should be reserved for tricky or high-risk cases.
+
+# Files to create
+
+- `packages/subagent/agents/advisor.md`
+- `packages/subagent/prompts/consult-advisor.md`
+
+# Files to modify
+
+- `packages/subagent/agents/worker.md` — add narrow escalation guidance
+- `packages/subagent/agents/planner.md` — add narrow escalation guidance
+- `packages/subagent/agents/reviewer.md` — add narrow escalation guidance
+- `packages/subagent/README.md` — document the new advisor role and one or two examples
+- `packages/subagent/skills/spawn-subagents/SKILL.md` — explain when to use advisor vs. planner/reviewer
+
+# Testing notes
+
+- If this remains markdown-only, there is no TypeScript validation requirement.
+- Manually test one focused consult, such as a planner or worker asking advisor a hard question, and verify:
+  - the advisor returns a recommendation rather than trying to own the full task
+  - the caller stays in charge of implementation or review
+  - the exchange is shorter and more targeted than a full additional workflow
+- If you introduce any helper TS module later to render consult packets, run `bun run --filter '@dreki-gg/pi-subagent' typecheck`.
+
+# Patterns to follow
+
+- `packages/subagent/skills/write-an-agent/SKILL.md:15-20` and `:46-67` — keep the new agent narrow, concise, and output-contract-driven
+- `packages/subagent/agents/planner.md:9-38` — example of a specialist planner role that the advisor should complement, not replace
+- `packages/subagent/agents/reviewer.md:10-37` — example of a verifier role that may occasionally need escalation
+- `packages/subagent/agents/worker.md:9-26` — example of a primary owner role that should remain in charge after consulting advisor
+- `packages/subagent/skills/spawn-subagents/SKILL.md:23-58` — existing specialist-selection guidance to extend with optional escalation

package/extensions/subagent/agent-result-utils.ts

@@ -0,0 +1,12 @@
+import type { AgentResult } from './agent-runner-types.js';
+
+export function getFinalText(result: AgentResult): string {
+  for (let i = result.messages.length - 1; i >= 0; i--) {
+    const msg = result.messages[i];
+    if (msg.role !== 'assistant') continue;
+    for (const part of msg.content) {
+      if (part.type === 'text') return part.text;
+    }
+  }
+  return '(no output)';
+}

package/extensions/subagent/agent-runner-types.ts

@@ -0,0 +1,23 @@
+import type { Message } from '@mariozechner/pi-ai';
+
+export interface UsageStats {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+
+export interface AgentResult {
+  agent: string;
+  task: string;
+  exitCode: number;
+  messages: Message[];
+  stderr: string;
+  usage: UsageStats;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}

package/extensions/subagent/{delegate-executor.ts → agent-runner.ts}

@@ -5,8 +5,8 @@ import * as path from 'node:path';
 import { withFileMutationQueue } from '@mariozechner/pi-coding-agent';
 import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
 import type { Message } from '@mariozechner/pi-ai';
-import { discoverAgentsWithPackages, type AgentScope } from './agents';
-import type { AgentResult, UsageStats } from './delegate-types';
+import { discoverAgentsWithPackages, type AgentScope } from './agents.js';
+import type { AgentResult, UsageStats } from './agent-runner-types.js';
 
 function emptyUsage(): UsageStats {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
@@ -43,6 +43,8 @@ export type OnPhaseUpdate = (phaseName: string, agentName: string, result: Agent
 export interface RunAgentOptions {
   agentScope?: AgentScope;
   cwd?: string;
+  model?: string;
+  thinking?: string;
   onUpdate?: OnPhaseUpdate;
   phaseName?: string;
   signal?: AbortSignal;
@@ -70,9 +72,12 @@ export async function runAgent(
     };
   }
 
+  const selectedModel = options.model ?? agent.model;
+  const selectedThinking = options.thinking ?? agent.thinking;
+
   const args: string[] = ['--mode', 'json', '-p', '--no-session'];
-  if (agent.model) args.push('--model', agent.model);
-  if (agent.thinking) args.push('--thinking', agent.thinking);
+  if (selectedModel) args.push('--model', selectedModel);
+  if (selectedThinking) args.push('--thinking', selectedThinking);
   if (agent.tools && agent.tools.length > 0) args.push('--tools', agent.tools.join(','));
 
   let tmpPromptDir: string | null = null;
@@ -85,7 +90,7 @@ export async function runAgent(
     messages: [],
     stderr: '',
     usage: emptyUsage(),
-    model: agent.model,
+    model: selectedModel,
   };
 
   try {
@@ -195,27 +200,3 @@ export async function runAgent(
       }
   }
 }
-
-export async function runParallel(
-  cwd: string,
-  agentNames: string[],
-  task: string,
-  options: RunAgentOptions = {},
-): Promise<AgentResult[]> {
-  const MAX_CONCURRENCY = 4;
-  const results: AgentResult[] = new Array(agentNames.length);
-  let nextIndex = 0;
-
-  const workers = new Array(Math.min(MAX_CONCURRENCY, agentNames.length))
-    .fill(null)
-    .map(async () => {
-      while (true) {
-        const current = nextIndex++;
-        if (current >= agentNames.length) return;
-        results[current] = await runAgent(cwd, agentNames[current], task, options);
-      }
-    });
-
-  await Promise.all(workers);
-  return results;
-}

package/extensions/subagent/agents.ts

@@ -16,6 +16,7 @@ import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
 
 export type AgentScope = 'user' | 'project' | 'both';
 export type AgentSource = 'bundled' | 'user' | 'project' | 'package';
+export type AgentSessionStrategy = 'inline' | 'fork-at';
 
 export interface AgentConfig {
   name: string;
@@ -23,6 +24,7 @@ export interface AgentConfig {
   tools?: string[];
   model?: string;
   thinking?: string;
+  sessionStrategy?: AgentSessionStrategy;
   systemPrompt: string;
   source: AgentSource;
   filePath: string;
@@ -36,6 +38,13 @@ export interface AgentDiscoveryResult {
 /** Bundled agents ship with the package (../../agents relative to extensions/subagent/) */
 const bundledAgentsDir = path.resolve(import.meta.dirname, '..', '..', 'agents');
 
+function parseSessionStrategy(value?: string): AgentSessionStrategy | undefined {
+  if (!value) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'inline' || normalized === 'fork-at') return normalized;
+  return undefined;
+}
+
 function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
   const agents: AgentConfig[] = [];
 
@@ -79,6 +88,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
       tools: tools && tools.length > 0 ? tools : undefined,
       model: frontmatter.model,
       thinking: frontmatter.thinking,
+      sessionStrategy: parseSessionStrategy(frontmatter.sessionStrategy),
       systemPrompt: body,
       source,
       filePath,
@@ -152,6 +162,7 @@ function loadAgentFromFile(filePath: string, source: AgentSource): AgentConfig |
     tools: tools && tools.length > 0 ? tools : undefined,
     model: frontmatter.model,
     thinking: frontmatter.thinking,
+    sessionStrategy: parseSessionStrategy(frontmatter.sessionStrategy),
     systemPrompt: body,
     source,
     filePath,

package/extensions/subagent/handoffs.ts

@@ -0,0 +1,273 @@
+export interface HandoffFileRef {
+  path: string;
+  notes?: string;
+}
+
+export interface HandoffEnvelope {
+  version: 'subagent-handoff/v1';
+  sourceAgent: string;
+  sourceStep?: number;
+  task: string;
+  summary: string;
+  goal?: string;
+  decisions: string[];
+  constraints: string[];
+  files: HandoffFileRef[];
+  symbols: string[];
+  openQuestions: string[];
+  rawOutput: string;
+}
+
+export interface RenderHandoffOptions {
+  includeRawOutput?: boolean;
+  maxRawChars?: number;
+}
+
+const DEFAULT_MAX_RAW_CHARS = 4000;
+const MAX_SUMMARY_ITEMS = 3;
+const SECTION_RE = /^##\s+(.+)$/gm;
+const CODE_SYMBOL_RE =
+  /^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)|^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*[:=]|^(?:export\s+)?(?:interface|type|class|enum)\s+([A-Za-z_$][\w$]*)/gm;
+const BULLET_SYMBOL_RE =
+  /^\s*(?:[-*]|\d+\.)\s+`?([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)`?(?=\s*(?:-|:|\())/gm;
+const PATH_RE = /\b(?:\.?\.?\/)?(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+(?:\.[A-Za-z0-9_.-]+)?\b/g;
+const CODE_PATH_RE = /`([^`\n]+(?:\/[A-Za-z0-9_.-]+)+[^`\n]*)`/g;
+
+interface SectionEntry {
+  title: string;
+  body: string;
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\r/g, '').replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+function normalizeSectionTitle(title: string): string {
+  return title.trim().toLowerCase().replace(/[\s/]+/g, ' ').replace(/[():]/g, '');
+}
+
+function splitMarkdownSections(markdown: string): { preamble: string; sections: SectionEntry[] } {
+  const matches = Array.from(markdown.matchAll(SECTION_RE));
+  if (matches.length === 0) {
+    return { preamble: normalizeWhitespace(markdown), sections: [] };
+  }
+
+  const sections: SectionEntry[] = [];
+  const preamble = normalizeWhitespace(markdown.slice(0, matches[0]?.index ?? 0));
+
+  for (let i = 0; i < matches.length; i++) {
+    const current = matches[i];
+    const next = matches[i + 1];
+    const title = current[1]?.trim() ?? '';
+    const start = (current.index ?? 0) + current[0].length;
+    const end = next?.index ?? markdown.length;
+    const body = normalizeWhitespace(markdown.slice(start, end));
+    sections.push({ title, body });
+  }
+
+  return { preamble, sections };
+}
+
+function getSectionBodies(sections: SectionEntry[], titles: string[]): string[] {
+  const wanted = new Set(titles.map(normalizeSectionTitle));
+  return sections
+    .filter((section) => wanted.has(normalizeSectionTitle(section.title)))
+    .map((section) => section.body)
+    .filter(Boolean);
+}
+
+function getFirstSectionBody(sections: SectionEntry[], titles: string[]): string | undefined {
+  return getSectionBodies(sections, titles)[0];
+}
+
+function extractListItems(section: string | undefined): string[] {
+  if (!section) return [];
+
+  const matches = Array.from(section.matchAll(/^\s*(?:[-*]|\d+\.)\s+(.+)$/gm));
+  if (matches.length === 0) return [];
+
+  return matches
+    .map((match) => normalizeWhitespace(match[1] ?? ''))
+    .map((item) => item.replace(/^[`*_]+|[`*_]+$/g, '').trim())
+    .filter(Boolean);
+}
+
+function extractParagraph(section: string | undefined): string | undefined {
+  if (!section) return undefined;
+  const paragraph = normalizeWhitespace(section.split(/\n\n+/)[0] ?? '');
+  const normalized = paragraph.replace(/^[-*]\s+/, '').trim();
+  return normalized && !isSentinelItem(normalized) ? paragraph : undefined;
+}
+
+function truncate(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, Math.max(0, maxChars - 14)).trimEnd()}\n… (truncated)`;
+}
+
+function isSentinelItem(value: string): boolean {
+  return /^(?:none|n\/a|not applicable)$/i.test(value.trim());
+}
+
+function uniq(values: string[]): string[] {
+  return Array.from(
+    new Set(values.map((value) => value.trim()).filter((value) => value && !isSentinelItem(value))),
+  );
+}
+
+function summarizeBullets(items: string[]): string | undefined {
+  const filtered = items.filter((item) => !isSentinelItem(item));
+  if (filtered.length === 0) return undefined;
+  return filtered.slice(0, MAX_SUMMARY_ITEMS).join('; ');
+}
+
+function summarizeSection(section: string | undefined): string | undefined {
+  if (!section) return undefined;
+  return summarizeBullets(extractListItems(section)) ?? extractParagraph(section);
+}
+
+function buildSummary(preamble: string, sections: SectionEntry[]): string {
+  const parts = [
+    summarizeSection(getFirstSectionBody(sections, ['Goal', 'Completed'])),
+    summarizeSection(getFirstSectionBody(sections, ['Plan', 'Architecture', 'Integration Notes'])),
+    summarizeSection(getFirstSectionBody(sections, ['Recommended Next Step', 'Notes', 'Risks'])),
+    extractParagraph(preamble),
+  ].filter((part): part is string => Boolean(part));
+
+  return parts.length > 0 ? parts.slice(0, MAX_SUMMARY_ITEMS).join(' ') : '(no summary available)';
+}
+
+function extractPaths(text: string): HandoffFileRef[] {
+  const seen = new Set<string>();
+  const files: HandoffFileRef[] = [];
+
+  const addPath = (rawPath: string, notes?: string) => {
+    const path = rawPath.trim().replace(/^`|`$/g, '').replace(/[),.:;]+$/g, '');
+    if (!path.includes('/')) return;
+    if (path.startsWith('http://') || path.startsWith('https://')) return;
+    if (seen.has(path)) return;
+    seen.add(path);
+    files.push({ path, notes });
+  };
+
+  for (const match of text.matchAll(CODE_PATH_RE)) {
+    addPath(match[1] ?? '');
+  }
+
+  for (const match of text.matchAll(PATH_RE)) {
+    addPath(match[0] ?? '');
+  }
+
+  return files;
+}
+
+function extractSymbols(text: string): string[] {
+  const symbols: string[] = [];
+
+  for (const match of text.matchAll(CODE_SYMBOL_RE)) {
+    const symbol = match[1] ?? match[2] ?? match[3];
+    if (symbol) symbols.push(symbol);
+  }
+
+  for (const match of text.matchAll(BULLET_SYMBOL_RE)) {
+    const symbol = match[1];
+    if (symbol && !symbol.includes('/')) symbols.push(symbol);
+  }
+
+  return uniq(symbols);
+}
+
+function toQuestions(items: string[]): string[] {
+  return items.filter(
+    (item) =>
+      /\?$/.test(item) || /\b(?:unknown|unclear|unresolved|question|follow up|todo)\b/i.test(item),
+  );
+}
+
+function renderList(title: string, items: string[]): string[] {
+  if (items.length === 0) return [];
+  return [`## ${title}`, ...items.map((item) => `- ${item}`), ''];
+}
+
+export function buildHandoffFromResult(input: {
+  agent: string;
+  step?: number;
+  task: string;
+  output: string;
+}): HandoffEnvelope {
+  const output = input.output.trim() || '(no output)';
+  const { preamble, sections } = splitMarkdownSections(output);
+  const decisions = uniq(extractListItems(getFirstSectionBody(sections, ['Decisions'])));
+  const explicitConstraints = uniq(
+    extractListItems(getFirstSectionBody(sections, ['Constraints', 'Constraints or Unknowns'])),
+  );
+  const riskItems = uniq(extractListItems(getFirstSectionBody(sections, ['Risks'])));
+  const openQuestions = uniq([
+    ...extractListItems(getFirstSectionBody(sections, ['Open Questions'])),
+    ...toQuestions(extractListItems(getFirstSectionBody(sections, ['Notes', 'Constraints or Unknowns']))),
+  ]);
+  const goal =
+    extractParagraph(getFirstSectionBody(sections, ['Goal'])) ??
+    extractParagraph(getFirstSectionBody(sections, ['Completed'])) ??
+    undefined;
+
+  return {
+    version: 'subagent-handoff/v1',
+    sourceAgent: input.agent,
+    sourceStep: input.step,
+    task: input.task,
+    summary: buildSummary(preamble, sections),
+    goal,
+    decisions,
+    constraints: uniq([...explicitConstraints, ...riskItems]),
+    files: extractPaths(output),
+    symbols: extractSymbols(output),
+    openQuestions,
+    rawOutput: output,
+  };
+}
+
+export function renderHandoffForPrompt(
+  handoff: HandoffEnvelope,
+  options: RenderHandoffOptions = {},
+): string {
+  const includeRawOutput = options.includeRawOutput ?? true;
+  const maxRawChars = options.maxRawChars ?? DEFAULT_MAX_RAW_CHARS;
+  const lines: string[] = [
+    '## Previous Agent Handoff',
+    `- Source Agent: ${handoff.sourceAgent}`,
+    ...(handoff.sourceStep ? [`- Step: ${handoff.sourceStep}`] : []),
+    `- Task: ${truncate(handoff.task, 240)}`,
+    `- Summary: ${handoff.summary}`,
+    '',
+  ];
+
+  if (handoff.goal) {
+    lines.push('## Goal', handoff.goal, '');
+  }
+
+  lines.push(...renderList('Decisions', handoff.decisions));
+  lines.push(...renderList('Constraints', handoff.constraints));
+
+  if (handoff.files.length > 0) {
+    lines.push('## Files');
+    for (const file of handoff.files) {
+      lines.push(file.notes ? `- \`${file.path}\` - ${file.notes}` : `- \`${file.path}\``);
+    }
+    lines.push('');
+  }
+
+  lines.push(...renderList('Symbols', handoff.symbols));
+  lines.push(...renderList('Open Questions', handoff.openQuestions));
+
+  if (includeRawOutput) {
+    lines.push(
+      '## Raw Output (truncated)',
+      '```markdown',
+      truncate(handoff.rawOutput, maxRawChars),
+      '```',
+      '',
+    );
+  }
+
+  return lines.join('\n').trim();
+}