@dreki-gg/pi-subagent 0.9.2 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @dreki-gg/pi-subagent
 
+## 0.11.0
+
+### Minor Changes
+
+- Model routing guidance and visible model attribution.
+
+  - `spawn-subagents` skill: new "Model routing" section — route each subagent task to the model whose strengths match the work (bulk token burn → cheap, user-facing → tasteful, reviews → strongest), honor a user model routing policy from AGENTS.md when one exists, and escalate without asking when a cheaper model's output misses the bar.
+  - Reasoning defaults: Opus-backed judgment/coding agents (advisor, planner, reviewer, validator, bug-prover, ux-designer) now run `thinking: high` instead of low/medium — reasoning effort applies per step, and high is the quality/cost sweet spot. Scouts stay low for cheap bulk recon.
+  - Result rendering: the model that ran each task is now shown next to the agent name in single, parallel, and chain headers (dim ` · model`), and in the working message while a run is active — so per-model quality is auditable at a glance. Parallel running placeholders resolve the model up front (task override → call default → agent default), so attribution shows while tasks are still running, not just after completion.
+  - `scout` and `docs-scout` default models move from `gpt-5.4-mini` to `gpt-5.6-luna` — near-Terra coding quality at the lowest benchmarked cost per task.
+
+## 0.10.0
+
+### Minor Changes
+
+- db4b119: Add a Cursor ACP backend: set a subagent's model to `cursor:<model>` (e.g. `cursor:composer-2.5`) to run the task on Cursor's agent via the Agent Client Protocol instead of spawning a `pi` process. Routing happens in one shared dispatcher, so it works across single / parallel / chain modes and the `/run-agent` command with an unchanged result shape. Permission requests are auto-approved; the `tools` allowlist and `thinking` level do not apply to `cursor:` models. Requires `cursor-agent` installed and authenticated (`agent login`).
+
 ## 0.9.2
 
 ### Patch Changes

package/README.md

@@ -26,6 +26,47 @@ Notes:
 - `/run-agent` provides autocomplete for `--model` and `--thinking`
 - the `subagent` tool supports the same fields in its schema, but this package does not currently add custom interactive autocomplete for tool-call JSON parameters
 
+## Cursor Composer (ACP backend)
+
+Set a subagent's model to `cursor:<model>` to run the task on Cursor's agent via the
+[Agent Client Protocol](https://agentclientprotocol.com/) instead of spawning a `pi`
+process. A bare `cursor:` (or `cursor`) defaults to `composer-2.5`.
+
+```jsonc
+// single run on Composer 2.5
+{ "agent": "worker", "task": "…", "model": "cursor:composer-2.5" }
+```
+
+Works across every mode (single / parallel / chain) and the `/run-agent` command —
+routing happens in one shared dispatcher, so the result shape and rendering are
+identical to pi-backed subagents.
+
+**Prerequisites**
+
+- `cursor-agent` installed (default `~/.local/bin/cursor-agent`). Override the binary
+  with the `CURSOR_AGENT_BIN` env var.
+- Authenticated once: `agent login` (or set `CURSOR_API_KEY`).
+
+**Behavior notes**
+
+- Cursor runs **its own tools** in ACP headless mode and auto-executes them; the
+  subagent `tools` allowlist and `thinking` level do **not** apply to `cursor:` models.
+- Permission prompts (`session/request_permission`) are auto-approved (most permissive
+  allow option) so runs never block. Cursor typically does not prompt for normal ops.
+- The model is passed as `cursor-agent --model <model> acp`; see `cursor-agent --list-models`
+  for available ids (e.g. `cursor:gpt-5.2`).
+
+## Model Routing
+
+The `spawn-subagents` skill teaches the orchestrating agent to route each task to the model whose strengths match the work instead of one default model for everything:
+
+- **Bulk token burn goes cheap** — log digging, large specs, migrations, clear-spec implementation.
+- **User-facing output goes tasteful** — public APIs, SDKs, UI copy go to (or are reviewed by) the highest-taste model.
+- **Reviews get the strong model** — cheap models only as an extra perspective, never the sole reviewer.
+- **Defaults, not limits** — redo cheap-model output on a stronger model without asking; judge the output, not the price tag.
+
+If your context files (e.g. a global `AGENTS.md`) define a model routing policy — a table scoring your models on intelligence / taste / cost — the skill treats it as authoritative when picking per-task `model` overrides. Result headers and working messages show which model ran each task (` · model`), so quality is auditable per model.
+
 ## Opinionated Defaults
 
 This package is intentionally opinionated about orchestration:

package/extensions/subagent/agent-runner.ts

@@ -1,7 +1,8 @@
 import type { ResolvedPaths } from '@earendil-works/pi-coding-agent';
 import { discoverAgents, type AgentScope } from './agents.js';
 import type { AgentResult } from './agent-runner-types.js';
-import { emptyUsage, spawnPiAgent, type ToolExecutionStartEvent } from './spawn-utils.js';
+import { emptyUsage, type ToolExecutionStartEvent } from './spawn-utils.js';
+import { dispatchSubagent } from './cursor/dispatch.js';
 
 export type OnPhaseUpdate = (phaseName: string, agentName: string, result: AgentResult) => void;
 
@@ -51,7 +52,7 @@ export async function runAgent(
     model: selectedModel,
   };
 
-  const spawnResult = await spawnPiAgent({
+  const spawnResult = await dispatchSubagent({
     cwd: options.cwd ?? cwd,
     agentName: agent.name,
     task,

package/extensions/subagent/cursor/acp-runner.ts

@@ -0,0 +1,143 @@
+/**
+ * Run a subagent task on Cursor's Composer family via `cursor-agent acp`,
+ * driven by the official @agentclientprotocol/sdk library (the current home of
+ * the Agent Client Protocol TypeScript SDK, formerly @zed-industries/agent-client-protocol).
+ *
+ * Returns the same SpawnPiAgentResult shape as spawnPiAgent so it is a drop-in
+ * backend behind dispatchSubagent — rendering, synthesis, and handoffs are
+ * unchanged.
+ */
+
+import { spawn } from 'node:child_process';
+import { Readable, Writable } from 'node:stream';
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  type Client,
+  type RequestPermissionRequest,
+  type SessionNotification,
+} from '@agentclientprotocol/sdk';
+import type { SpawnPiAgentOptions, SpawnPiAgentResult } from '../spawn-utils.js';
+import { emptyUsage } from '../spawn-utils.js';
+import { parseCursorModel } from './model.js';
+import {
+  buildCancelledResponse,
+  buildPermissionResponse,
+  selectPermissionOption,
+} from './permissions.js';
+import { CursorUpdateReducer } from './update-mapping.js';
+
+const CURSOR_BIN = process.env.CURSOR_AGENT_BIN || 'cursor-agent';
+
+export async function runCursorAcpAgent(options: SpawnPiAgentOptions): Promise<SpawnPiAgentResult> {
+  const { model } = parseCursorModel(options.model);
+  const displayModel = `cursor:${model}`;
+
+  const result: SpawnPiAgentResult = {
+    exitCode: 0,
+    messages: [],
+    stderr: '',
+    wasAborted: false,
+    usage: emptyUsage(),
+    model: displayModel,
+  };
+
+  const reducer = new CursorUpdateReducer(displayModel);
+  const seenToolCalls = new Set<string>();
+
+  const proc = spawn(CURSOR_BIN, ['--model', model, 'acp'], {
+    cwd: options.cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  proc.stderr.on('data', (d: Buffer) => {
+    result.stderr += d.toString();
+  });
+
+  // Bridge Node child stdio to Web streams for ndJsonStream.
+  const stream = ndJsonStream(
+    Writable.toWeb(proc.stdin) as WritableStream<Uint8Array>,
+    Readable.toWeb(proc.stdout) as unknown as ReadableStream<Uint8Array>,
+  );
+
+  const client: Client = {
+    async requestPermission(params: RequestPermissionRequest) {
+      const optionId = selectPermissionOption(params.options);
+      return optionId ? buildPermissionResponse(optionId) : buildCancelledResponse();
+    },
+    async sessionUpdate(note: SessionNotification) {
+      const update = note.update;
+      reducer.apply(update);
+
+      if (update.sessionUpdate === 'tool_call' && !seenToolCalls.has(update.toolCallId)) {
+        seenToolCalls.add(update.toolCallId);
+        options.onToolExecutionStart?.({
+          toolCallId: update.toolCallId,
+          toolName: update.title || update.kind || 'tool',
+          args: (update.rawInput as Record<string, unknown>) ?? {},
+        });
+      }
+
+      // Live snapshot for streaming TUI updates.
+      result.messages = [reducer.current()];
+      options.onMessage?.(reducer.current());
+    },
+  };
+
+  const conn = new ClientSideConnection(() => client, stream);
+
+  let sessionId: string | undefined;
+  const onAbort = () => {
+    result.wasAborted = true;
+    if (sessionId) conn.cancel({ sessionId }).catch(() => {});
+    proc.kill('SIGTERM');
+    setTimeout(() => {
+      if (!proc.killed) proc.kill('SIGKILL');
+    }, 5000);
+  };
+  if (options.signal) {
+    if (options.signal.aborted) onAbort();
+    else options.signal.addEventListener('abort', onAbort, { once: true });
+  }
+
+  try {
+    await conn.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+    });
+
+    const session = await conn.newSession({ cwd: options.cwd, mcpServers: [] });
+    sessionId = session.sessionId;
+
+    const promptText = options.systemPrompt?.trim()
+      ? `${options.systemPrompt}\n\nTask: ${options.task}`
+      : `Task: ${options.task}`;
+
+    const promptResult = await conn.prompt({
+      sessionId,
+      prompt: [{ type: 'text', text: promptText }],
+    });
+
+    const finalized = reducer.finalize(promptResult.stopReason);
+    result.messages = finalized.messages;
+    result.usage = finalized.usage;
+    result.stopReason = finalized.stopReason;
+    result.exitCode = result.wasAborted ? 1 : 0;
+  } catch (err) {
+    result.exitCode = 1;
+    result.errorMessage = err instanceof Error ? err.message : String(err);
+    const finalized = reducer.finalize(result.wasAborted ? 'cancelled' : 'error');
+    result.messages = finalized.messages;
+    result.usage = finalized.usage;
+    result.stopReason = finalized.stopReason;
+  } finally {
+    try {
+      proc.stdin.end();
+    } catch {
+      /* ignore */
+    }
+    if (!proc.killed) proc.kill();
+  }
+
+  return result;
+}

package/extensions/subagent/cursor/dispatch.ts

@@ -0,0 +1,18 @@
+/**
+ * Single routing seam for subagent backends.
+ *
+ * Models prefixed with `cursor:` run through Cursor's ACP server (Composer
+ * family); everything else spawns a pi process as before. Both backends return
+ * the identical SpawnPiAgentResult shape, so callers are backend-agnostic.
+ */
+
+import { spawnPiAgent, type SpawnPiAgentOptions, type SpawnPiAgentResult } from '../spawn-utils.js';
+import { parseCursorModel } from './model.js';
+import { runCursorAcpAgent } from './acp-runner.js';
+
+export function dispatchSubagent(options: SpawnPiAgentOptions): Promise<SpawnPiAgentResult> {
+  if (parseCursorModel(options.model).isCursor) {
+    return runCursorAcpAgent(options);
+  }
+  return spawnPiAgent(options);
+}

package/extensions/subagent/cursor/model.ts

@@ -0,0 +1,34 @@
+/**
+ * Cursor model-prefix parsing.
+ *
+ * A subagent model of the form `cursor:<model>` routes the run through
+ * `cursor-agent acp` (Cursor's Composer family) instead of spawning a pi
+ * process. A bare `cursor:` or `cursor` defaults to `composer-2.5`.
+ */
+
+const CURSOR_PREFIX = 'cursor:';
+const DEFAULT_CURSOR_MODEL = 'composer-2.5';
+
+export interface ParsedCursorModel {
+  /** True when the model selects the Cursor ACP backend. */
+  isCursor: boolean;
+  /** The resolved model id: bare Cursor model name when isCursor, else passthrough. */
+  model: string;
+}
+
+export function parseCursorModel(model?: string): ParsedCursorModel {
+  if (!model) return { isCursor: false, model: '' };
+
+  const trimmed = model.trim();
+
+  if (trimmed === 'cursor') {
+    return { isCursor: true, model: DEFAULT_CURSOR_MODEL };
+  }
+
+  if (trimmed.toLowerCase().startsWith(CURSOR_PREFIX)) {
+    const rest = trimmed.slice(CURSOR_PREFIX.length).trim();
+    return { isCursor: true, model: rest || DEFAULT_CURSOR_MODEL };
+  }
+
+  return { isCursor: false, model: trimmed };
+}

package/extensions/subagent/cursor/permissions.ts

@@ -0,0 +1,26 @@
+/**
+ * Auto-approval policy for Cursor ACP permission requests.
+ *
+ * In ACP headless mode Cursor usually executes tool calls without prompting,
+ * but when it does send `session/request_permission` the client must answer or
+ * the turn blocks. We auto-select the most permissive "allow" option.
+ */
+
+import type { PermissionOption, RequestPermissionResponse } from '@agentclientprotocol/sdk';
+
+/**
+ * Choose which option to grant. Prefers `allow_always`, then `allow_once`,
+ * then the first option. Returns undefined when no options are offered.
+ */
+export function selectPermissionOption(options: PermissionOption[]): string | undefined {
+  const byKind = (kind: PermissionOption['kind']) => options.find((o) => o.kind === kind)?.optionId;
+  return byKind('allow_always') ?? byKind('allow_once') ?? options[0]?.optionId;
+}
+
+export function buildPermissionResponse(optionId: string): RequestPermissionResponse {
+  return { outcome: { outcome: 'selected', optionId } };
+}
+
+export function buildCancelledResponse(): RequestPermissionResponse {
+  return { outcome: { outcome: 'cancelled' } };
+}

package/extensions/subagent/cursor/update-mapping.ts

@@ -0,0 +1,141 @@
+/**
+ * Map Cursor ACP `session/update` notifications into the pi Message[] +
+ * UsageStats shape the rest of the subagent code consumes.
+ *
+ * A single ACP prompt turn is accumulated into one pi AssistantMessage whose
+ * content interleaves text parts and toolCall parts in arrival order, so the
+ * existing renderers (getFinalOutput / getDisplayItems) work unchanged.
+ */
+
+import type {
+  AssistantMessage,
+  Message,
+  StopReason,
+  TextContent,
+  ThinkingContent,
+  ToolCall,
+} from '@earendil-works/pi-ai';
+import type { SessionNotification } from '@agentclientprotocol/sdk';
+import type { UsageStats } from '../agent-runner-types.js';
+import { emptyUsage } from '../spawn-utils.js';
+
+type SessionUpdate = SessionNotification['update'];
+
+function blockText(content: { type: string; text?: string }): string {
+  return content?.type === 'text' ? (content.text ?? '') : '';
+}
+
+export function mapStopReason(raw?: string): StopReason {
+  switch (raw) {
+    case 'end_turn':
+    case 'completed':
+      return 'stop';
+    case 'max_tokens':
+    case 'max_turn_requests':
+      return 'length';
+    case 'cancelled':
+      return 'aborted';
+    case 'refusal':
+    case 'error':
+      return 'error';
+    default:
+      return 'stop';
+  }
+}
+
+/**
+ * Accumulates ACP session updates into a single pi assistant message.
+ * Stateful but free of I/O — unit-testable by feeding `apply()` a sequence.
+ */
+export class CursorUpdateReducer {
+  private readonly assistant: AssistantMessage;
+  private hasContent = false;
+  readonly usage: UsageStats = emptyUsage();
+
+  constructor(model: string) {
+    this.assistant = {
+      role: 'assistant',
+      content: [],
+      api: 'cursor-acp',
+      provider: 'cursor',
+      model,
+      usage: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      },
+      stopReason: 'stop',
+      timestamp: Date.now(),
+    };
+  }
+
+  /** Apply one `update` payload from a SessionNotification. */
+  apply(update: SessionUpdate): void {
+    switch (update.sessionUpdate) {
+      case 'agent_message_chunk': {
+        const text = blockText(update.content);
+        if (text) {
+          this.markTurn();
+          this.appendText(text);
+        }
+        break;
+      }
+      case 'agent_thought_chunk': {
+        const text = blockText(update.content);
+        if (text) {
+          this.markTurn();
+          const part: ThinkingContent = { type: 'thinking', thinking: text };
+          this.assistant.content.push(part);
+        }
+        break;
+      }
+      case 'tool_call': {
+        this.markTurn();
+        const part: ToolCall = {
+          type: 'toolCall',
+          id: update.toolCallId,
+          name: update.title || update.kind || 'tool',
+          arguments: (update.rawInput as Record<string, unknown>) ?? {},
+        };
+        this.assistant.content.push(part);
+        break;
+      }
+      // tool_call_update / plan / available_commands_update / current_mode_update:
+      // no projection needed for subagent output.
+      default:
+        break;
+    }
+  }
+
+  private markTurn(): void {
+    if (!this.hasContent) {
+      this.hasContent = true;
+      this.usage.turns = Math.max(this.usage.turns, 1);
+    }
+  }
+
+  private appendText(text: string): void {
+    const last = this.assistant.content.at(-1);
+    if (last && last.type === 'text') {
+      (last as TextContent).text += text;
+    } else {
+      const part: TextContent = { type: 'text', text };
+      this.assistant.content.push(part);
+    }
+  }
+
+  /** Current assistant message (live snapshot for streaming callbacks). */
+  current(): AssistantMessage {
+    return this.assistant;
+  }
+
+  /** Finalize and return the collected messages + usage. */
+  finalize(rawStopReason?: string): { messages: Message[]; usage: UsageStats; stopReason: string } {
+    this.assistant.stopReason = mapStopReason(rawStopReason);
+    const messages: Message[] = this.hasContent ? [this.assistant] : [];
+    return { messages, usage: this.usage, stopReason: rawStopReason ?? 'end_turn' };
+  }
+}

package/extensions/subagent/index.ts

@@ -44,6 +44,7 @@ import type { AgentResult } from './agent-runner-types.js';
 import { getFinalText } from './agent-result-utils.js';
 import { buildHandoffFromResult, renderHandoffForPrompt } from './handoffs.js';
 import { emptyUsage, spawnPiAgent, type ToolExecutionStartEvent } from './spawn-utils.js';
+import { dispatchSubagent } from './cursor/dispatch.js';
 import { registerListAgentsTool } from './list-agents.js';
 import { registerCreateAgentCommand } from './create-agent.js';
 
@@ -356,7 +357,7 @@ async function runSingleAgent(
   };
 
   let spawnResult: Awaited<ReturnType<typeof spawnPiAgent>> | undefined;
-  spawnResult = await spawnPiAgent({
+  spawnResult = await dispatchSubagent({
     cwd: cwd ?? defaultCwd,
     agentName: agent.name,
     task,
@@ -526,6 +527,13 @@ export default function (pi: ExtensionAPI) {
   ): Promise<Array<{ value: string; label?: string; description?: string }>> {
     const items = new Map<string, { value: string; label?: string; description?: string }>();
 
+    // Cursor ACP backend: cursor:<model> routes through `cursor-agent acp`.
+    items.set('cursor:composer-2.5', {
+      value: 'cursor:composer-2.5',
+      label: 'cursor:composer-2.5',
+      description: 'Cursor Composer 2.5 via ACP (requires cursor-agent + agent login)',
+    });
+
     try {
       const authStorage = AuthStorage.create();
       const modelRegistry = ModelRegistry.create(authStorage);
@@ -662,7 +670,11 @@ export default function (pi: ExtensionAPI) {
             : undefined;
 
           if (ctx.hasUI) {
-            ctx.ui.setWorkingMessage(`Chain step ${i + 1}/${params.chain.length}: ${step.agent}`);
+            const stepModel =
+              step.model ?? params.model ?? agents.find((a) => a.name === step.agent)?.model;
+            ctx.ui.setWorkingMessage(
+              `Chain step ${i + 1}/${params.chain.length}: ${step.agent}${stepModel ? ` · ${stepModel}` : ''}`,
+            );
           }
 
           const result = await runSingleAgent(
@@ -742,10 +754,12 @@ export default function (pi: ExtensionAPI) {
 
         // Initialize placeholder results
         for (let i = 0; i < params.tasks.length; i++) {
+          const t = params.tasks[i];
           allResults[i] = {
-            agent: params.tasks[i].agent,
+            agent: t.agent,
             agentSource: 'unknown',
-            task: params.tasks[i].task,
+            task: t.task,
+            model: t.model ?? params.model ?? agents.find((a) => a.name === t.agent)?.model,
             exitCode: -1, // -1 = still running
             messages: [],
             stderr: '',
@@ -832,7 +846,10 @@ export default function (pi: ExtensionAPI) {
 
       if (params.agent && params.task) {
         if (ctx.hasUI) {
-          ctx.ui.setWorkingMessage(`Running agent: ${params.agent}`);
+          const singleModel = params.model ?? agents.find((a) => a.name === params.agent)?.model;
+          ctx.ui.setWorkingMessage(
+            `Running agent: ${params.agent}${singleModel ? ` · ${singleModel}` : ''}`,
+          );
         }
 
         const result = await runSingleAgent(
@@ -965,7 +982,7 @@ export default function (pi: ExtensionAPI) {
 
         if (expanded) {
           const container = new Container();
-          let header = `${icon} ${theme.fg('toolTitle', theme.bold(r.agent))}${theme.fg('muted', ` (${r.agentSource})`)}`;
+          let header = `${icon} ${theme.fg('toolTitle', theme.bold(r.agent))}${r.model ? theme.fg('dim', ` · ${r.model}`) : ''}${theme.fg('muted', ` (${r.agentSource})`)}`;
           if (isError && r.stopReason) header += ` ${theme.fg('error', `[${r.stopReason}]`)}`;
           container.addChild(new Text(header, 0, 0));
           if (isError && r.errorMessage)
@@ -1002,7 +1019,7 @@ export default function (pi: ExtensionAPI) {
           return container;
         }
 
-        let text = `${icon} ${theme.fg('toolTitle', theme.bold(r.agent))}${theme.fg('muted', ` (${r.agentSource})`)}`;
+        let text = `${icon} ${theme.fg('toolTitle', theme.bold(r.agent))}${r.model ? theme.fg('dim', ` · ${r.model}`) : ''}${theme.fg('muted', ` (${r.agentSource})`)}`;
         if (isError && r.stopReason) text += ` ${theme.fg('error', `[${r.stopReason}]`)}`;
         if (isError && r.errorMessage) text += `\n${theme.fg('error', `Error: ${r.errorMessage}`)}`;
         else if (displayItems.length === 0) text += `\n${theme.fg('muted', '(no output)')}`;
@@ -1057,7 +1074,7 @@ export default function (pi: ExtensionAPI) {
             container.addChild(new Spacer(1));
             container.addChild(
               new Text(
-                `${theme.fg('muted', `─── Step ${r.step}: `) + theme.fg('accent', r.agent)} ${rIcon}`,
+                `${theme.fg('muted', `─── Step ${r.step}: `) + theme.fg('accent', r.agent)}${r.model ? theme.fg('dim', ` · ${r.model}`) : ''} ${rIcon}`,
                 0,
                 0,
               ),
@@ -1107,7 +1124,7 @@ export default function (pi: ExtensionAPI) {
         for (const r of details.results) {
           const rIcon = r.exitCode === 0 ? theme.fg('success', '✓') : theme.fg('error', '✗');
           const displayItems = getDisplayItems(r.messages);
-          text += `\n\n${theme.fg('muted', `─── Step ${r.step}: `)}${theme.fg('accent', r.agent)} ${rIcon}`;
+          text += `\n\n${theme.fg('muted', `─── Step ${r.step}: `)}${theme.fg('accent', r.agent)}${r.model ? theme.fg('dim', ` · ${r.model}`) : ''} ${rIcon}`;
           if (displayItems.length === 0) text += `\n${theme.fg('muted', '(no output)')}`;
           else text += `\n${renderDisplayItems(displayItems, 5)}`;
         }
@@ -1148,7 +1165,11 @@ export default function (pi: ExtensionAPI) {
 
             container.addChild(new Spacer(1));
             container.addChild(
-              new Text(`${theme.fg('muted', '─── ') + theme.fg('accent', r.agent)} ${rIcon}`, 0, 0),
+              new Text(
+                `${theme.fg('muted', '─── ') + theme.fg('accent', r.agent)}${r.model ? theme.fg('dim', ` · ${r.model}`) : ''} ${rIcon}`,
+                0,
+                0,
+              ),
             );
             container.addChild(
               new Text(theme.fg('muted', 'Task: ') + theme.fg('dim', r.task), 0, 0),
@@ -1196,7 +1217,7 @@ export default function (pi: ExtensionAPI) {
                 ? theme.fg('success', '✓')
                 : theme.fg('error', '✗');
           const displayItems = getDisplayItems(r.messages);
-          text += `\n\n${theme.fg('muted', '─── ')}${theme.fg('accent', r.agent)} ${rIcon}`;
+          text += `\n\n${theme.fg('muted', '─── ')}${theme.fg('accent', r.agent)}${r.model ? theme.fg('dim', ` · ${r.model}`) : ''} ${rIcon}`;
           if (displayItems.length === 0)
             text += `\n${theme.fg('muted', r.exitCode === -1 ? '(running...)' : '(no output)')}`;
           else text += `\n${renderDisplayItems(displayItems, 5)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled prompts",
   "keywords": [
     "pi-package"
@@ -30,6 +30,9 @@
       "./prompts"
     ]
   },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.0.0"
+  },
   "devDependencies": {
     "@types/node": "24",
     "oxfmt": "^0.43.0",

package/prompts/advisor.md

@@ -3,7 +3,7 @@ name: advisor
 description: Focused second-opinion consult for tricky planning, implementation, or review decisions
 tools: read, grep, find, ls
 model: anthropic/claude-opus-4-6
-thinking: low
+thinking: high
 ---
 
 You are an advisor.

package/prompts/bug-prover.md

@@ -3,7 +3,7 @@ name: bug-prover
 description: Create the smallest failing repro for a suspected bug. Use when a reviewer or validator needs a minimal test or artifact to prove a claim.
 tools: read, grep, find, ls, bash, edit, write
 model: anthropic/claude-opus-4-6
-thinking: low
+thinking: high
 sessionStrategy: fork-at
 ---
 

package/prompts/docs-scout.md

@@ -2,7 +2,7 @@
 name: docs-scout
 description: Documentation scout that uses Context7 first, then summarizes the relevant implementation details
 tools: context7_resolve_library_id, context7_get_library_docs, context7_get_cached_doc_raw, read, grep, find, ls
-model: openai/gpt-5.4-mini
+model: openai/gpt-5.6-luna
 thinking: low
 ---
 

package/prompts/planner.md

@@ -3,7 +3,7 @@ name: planner
 description: Creates implementation plans from context and requirements
 tools: read, grep, find, ls, subagent
 model: anthropic/claude-opus-4-6
-thinking: medium
+thinking: high
 ---
 
 You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.

package/prompts/reviewer.md

@@ -3,7 +3,7 @@ name: reviewer
 description: Code review specialist for quality and security analysis
 tools: read, grep, find, ls, bash, subagent
 model: anthropic/claude-opus-4-6
-thinking: low
+thinking: high
 sessionStrategy: fork-at
 ---
 

package/prompts/scout.md

@@ -2,7 +2,7 @@
 name: scout
 description: Fast codebase recon that returns compressed context for handoff to other agents
 tools: read, grep, find, ls, bash
-model: openai/gpt-5.4-mini
+model: openai/gpt-5.6-luna
 thinking: low
 ---
 

package/prompts/ux-designer.md

@@ -3,7 +3,7 @@ name: ux-designer
 description: Frontend UI designer that produces clean, human-designed interfaces — anti-Codex aesthetic
 tools: read, grep, find, ls
 model: anthropic/claude-opus-4-6
-thinking: low
+thinking: high
 ---
 
 You are a frontend UX designer agent. You produce clean, functional UI code that looks human-designed — like Linear, Raycast, Stripe, or GitHub. You exist to counter the default AI aesthetic.

package/prompts/validator.md

@@ -3,7 +3,7 @@ name: validator
 description: Validate or falsify a specific bug, regression, or behavior claim from code, tests, and commands. Use when a review finding needs evidence before it becomes a fix request.
 tools: read, grep, find, ls, bash
 model: anthropic/claude-opus-4-6
-thinking: low
+thinking: high
 ---
 
 You are a validator.

package/prompts/worker.md

@@ -1,8 +1,7 @@
 ---
 name: worker
 description: General-purpose subagent with full capabilities, isolated context
-model: openai/gpt-5.5
-thinking: low
+model: cursor:composer-2.5
 sessionStrategy: fork-at
 ---
 

package/skills/spawn-subagents/SKILL.md

@@ -26,6 +26,8 @@ Strong triggers:
 - "ask advisor for a second opinion on this"
 - "validate whether this review finding is real"
 - "prove this bug with a minimal failing test"
+- "route this to the cheap model"
+- "use the right model for each piece"
 
 Patterns:
 
@@ -114,13 +116,33 @@ Avoid:
 - calling `advisor` when `planner` or `reviewer` already has enough signal to proceed alone
 - sending speculative review findings back for fixes before they are validated when evidence is needed
 
-## 8. Agent discovery and creation
+## 8. Model routing
+Route each subagent task to the model whose strengths match the work, not to one default model for everything.
+
+Policy source:
+- If the user's context files (AGENTS.md or equivalent) define a model routing policy — a table scoring models on axes like intelligence, taste, and cost — that policy is authoritative. Apply it when picking `model` overrides for `single` / `parallel` / `chain` tasks.
+- Without a user policy, use the agent prompt's default model and these structural rules.
+
+Structural rules (harness-independent):
+- **Bulk token burn goes cheap.** Log digging, reading large files/specs/PDFs, data analysis, mechanical migrations, and clear-spec implementation belong on the cheapest capable model.
+- **User-facing output goes tasteful.** Public APIs, SDKs, UI copy, and design decisions go to the highest-taste model, or are reviewed by it before shipping.
+- **Reviews get the strong model.** Plan and implementation reviews run on the strongest model; a cheap model may be added as an extra independent perspective, never as the only reviewer.
+- **Defaults, not limits.** If a cheaper model's output does not meet the bar, rerun the task on a stronger model without asking. Judge the output, not the price tag — escalating costs less than shipping mediocre work.
+- **Cost is a tiebreaker only.** Use cheap models to gather information before engaging an expensive one, never to avoid it.
+- **Name the model.** When reporting delegated work back, say which model ran each task so quality can be judged per model.
+
+Mechanics:
+- Pass `model` per task/step (e.g. `{ agent: "worker", task: "…", model: "cursor:composer-2.5" }`) or once per call as a default for all tasks.
+- `cursor:<model>` routes through Cursor's agent via ACP — useful as a distinct cheap/fast implementation backend.
+
+## 9. Agent discovery and creation
 Use `list_agents` before spawning when you're unsure which agents exist.
 Use `/create-agent <name> [description]` to scaffold a new project-local agent in `.pi/prompts/` when the user needs a custom agent that doesn't exist yet.
 - After creating, read and refine the prompt file to fit the use case.
 - Remember to use `agentScope: "both"` or `"project"` to include project-local agents.
 
 Execution rules:
+- Route each task to the model whose strengths match the work; honor the user's model routing policy when one exists (section 8).
 - Use `manager` when the task is too large for one prompt but still needs coherent decisions.
 - Use `advisor` for targeted second opinions on tricky or high-risk cases.
 - Use `validator` to confirm a claim before escalating it as a fix.

package/test/cursor-acp-runner.e2e.test.ts

@@ -0,0 +1,42 @@
+/**
+ * End-to-end check against a real `cursor-agent acp` server.
+ * Gated behind CURSOR_ACP_E2E=1 (requires cursor-agent installed + `agent login`).
+ *
+ *   CURSOR_ACP_E2E=1 bun test test/cursor-acp-runner.e2e.test.ts
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCursorAcpAgent } from '../extensions/subagent/cursor/acp-runner.js';
+
+const E2E = !!process.env.CURSOR_ACP_E2E;
+const maybe = E2E ? it : it.skip;
+
+describe('runCursorAcpAgent (e2e)', () => {
+  maybe(
+    'completes a real Composer 2.5 turn',
+    async () => {
+      const cwd = await mkdtemp(join(tmpdir(), 'cursor-acp-e2e-'));
+      const result = await runCursorAcpAgent({
+        cwd,
+        agentName: 'e2e',
+        task: 'Reply with exactly the word: ok',
+        model: 'cursor:composer-2.5',
+      });
+
+      const text = result.messages
+        .filter((m) => m.role === 'assistant')
+        .flatMap((m) => (m as any).content)
+        .filter((p: any) => p.type === 'text')
+        .map((p: any) => p.text)
+        .join('');
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stopReason).toBeDefined();
+      expect(text.trim().length).toBeGreaterThan(0);
+    },
+    120_000,
+  );
+});

package/test/cursor-model.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'bun:test';
+import { parseCursorModel } from '../extensions/subagent/cursor/model.js';
+
+describe('parseCursorModel', () => {
+  it('treats undefined/empty as non-cursor', () => {
+    expect(parseCursorModel(undefined)).toEqual({ isCursor: false, model: '' });
+    expect(parseCursorModel('')).toEqual({ isCursor: false, model: '' });
+  });
+
+  it('passes through normal models', () => {
+    expect(parseCursorModel('anthropic/claude-sonnet')).toEqual({
+      isCursor: false,
+      model: 'anthropic/claude-sonnet',
+    });
+  });
+
+  it('routes cursor:<model> to the cursor backend', () => {
+    expect(parseCursorModel('cursor:composer-2.5')).toEqual({
+      isCursor: true,
+      model: 'composer-2.5',
+    });
+    expect(parseCursorModel('cursor:gpt-5.2')).toEqual({ isCursor: true, model: 'gpt-5.2' });
+  });
+
+  it('defaults bare cursor / empty suffix to composer-2.5', () => {
+    expect(parseCursorModel('cursor')).toEqual({ isCursor: true, model: 'composer-2.5' });
+    expect(parseCursorModel('cursor:')).toEqual({ isCursor: true, model: 'composer-2.5' });
+  });
+
+  it('is case-insensitive on the prefix and trims', () => {
+    expect(parseCursorModel('  Cursor:composer-2.5  ')).toEqual({
+      isCursor: true,
+      model: 'composer-2.5',
+    });
+  });
+});

package/test/cursor-permissions.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'bun:test';
+import type { PermissionOption } from '@agentclientprotocol/sdk';
+import {
+  buildCancelledResponse,
+  buildPermissionResponse,
+  selectPermissionOption,
+} from '../extensions/subagent/cursor/permissions.js';
+
+const opt = (kind: PermissionOption['kind'], optionId: string): PermissionOption => ({
+  kind,
+  optionId,
+  name: optionId,
+});
+
+describe('selectPermissionOption', () => {
+  it('prefers allow_always', () => {
+    const options = [
+      opt('reject_once', 'r'),
+      opt('allow_once', 'ao'),
+      opt('allow_always', 'aa'),
+    ];
+    expect(selectPermissionOption(options)).toBe('aa');
+  });
+
+  it('falls back to allow_once when no allow_always', () => {
+    expect(selectPermissionOption([opt('reject_once', 'r'), opt('allow_once', 'ao')])).toBe('ao');
+  });
+
+  it('falls back to the first option when no allow kinds', () => {
+    expect(selectPermissionOption([opt('reject_once', 'r'), opt('reject_always', 'ra')])).toBe('r');
+  });
+
+  it('returns undefined for empty options', () => {
+    expect(selectPermissionOption([])).toBeUndefined();
+  });
+});
+
+describe('response builders', () => {
+  it('builds a selected outcome', () => {
+    expect(buildPermissionResponse('aa')).toEqual({
+      outcome: { outcome: 'selected', optionId: 'aa' },
+    });
+  });
+
+  it('builds a cancelled outcome', () => {
+    expect(buildCancelledResponse()).toEqual({ outcome: { outcome: 'cancelled' } });
+  });
+});

package/test/cursor-update-mapping.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'bun:test';
+import type { SessionNotification } from '@agentclientprotocol/sdk';
+import { CursorUpdateReducer, mapStopReason } from '../extensions/subagent/cursor/update-mapping.js';
+
+type Update = SessionNotification['update'];
+
+const textChunk = (text: string): Update => ({
+  sessionUpdate: 'agent_message_chunk',
+  content: { type: 'text', text },
+});
+
+const toolCall = (toolCallId: string, title: string, rawInput: Record<string, unknown>): Update =>
+  ({
+    sessionUpdate: 'tool_call',
+    toolCallId,
+    title,
+    rawInput,
+  }) as Update;
+
+describe('CursorUpdateReducer', () => {
+  it('coalesces message chunks into one assistant text part', () => {
+    const r = new CursorUpdateReducer('composer-2.5');
+    r.apply(textChunk('Hello'));
+    r.apply(textChunk(' world'));
+    const { messages, usage } = r.finalize('end_turn');
+    expect(messages).toHaveLength(1);
+    expect(messages[0].role).toBe('assistant');
+    const textPart = (messages[0] as any).content.find((p: any) => p.type === 'text');
+    expect(textPart.text).toBe('Hello world');
+    expect(usage.turns).toBe(1);
+  });
+
+  it('records tool calls as toolCall parts', () => {
+    const r = new CursorUpdateReducer('composer-2.5');
+    r.apply(textChunk('working'));
+    r.apply(toolCall('t1', 'Edit file', { path: 'a.ts' }));
+    const { messages } = r.finalize('end_turn');
+    const parts = (messages[0] as any).content;
+    const tool = parts.find((p: any) => p.type === 'toolCall');
+    expect(tool.name).toBe('Edit file');
+    expect(tool.arguments).toEqual({ path: 'a.ts' });
+  });
+
+  it('produces no messages when nothing was emitted', () => {
+    const r = new CursorUpdateReducer('composer-2.5');
+    const { messages, usage } = r.finalize();
+    expect(messages).toHaveLength(0);
+    expect(usage.turns).toBe(0);
+  });
+
+  it('maps stop reasons to pi StopReason', () => {
+    expect(mapStopReason('end_turn')).toBe('stop');
+    expect(mapStopReason('max_tokens')).toBe('length');
+    expect(mapStopReason('cancelled')).toBe('aborted');
+    expect(mapStopReason('refusal')).toBe('error');
+    expect(mapStopReason(undefined)).toBe('stop');
+  });
+});