@dreki-gg/pi-subagent 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @dreki-gg/pi-subagent
 
+## 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
+
+- Tighten subagent prompts and the write-an-agent skill. The skill gains a "Prompt hygiene (anti-rot)" section (invariants over incidents, one owner per fact, every line must change behavior) plus matching review-checklist items, and the reviewer/worker/planner prompts state the consult handoff shape once instead of in three duplicated blocks. No behavior change.
+
 ## 0.9.1
 
 ### Patch Changes

package/README.md

@@ -26,6 +26,36 @@ 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`).
+
 ## 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/create-agent.ts

@@ -58,10 +58,7 @@ export function registerCreateAgentCommand(pi: ExtensionAPI) {
       const filePath = path.join(promptsDir, `${name}.md`);
 
       if (fs.existsSync(filePath)) {
-        ctx.ui.notify(
-          `Agent "${name}" already exists at ${filePath}`,
-          'warning',
-        );
+        ctx.ui.notify(`Agent "${name}" already exists at ${filePath}`, 'warning');
         return;
       }
 
@@ -69,16 +66,14 @@ export function registerCreateAgentCommand(pi: ExtensionAPI) {
       fs.mkdirSync(promptsDir, { recursive: true });
 
       // Write the template
-      const content = TEMPLATE
-        .replace(/\{\{name\}\}/g, name)
-        .replace(/\{\{description\}\}/g, description);
+      const content = TEMPLATE.replace(/\{\{name\}\}/g, name).replace(
+        /\{\{description\}\}/g,
+        description,
+      );
 
       fs.writeFileSync(filePath, content, 'utf-8');
 
-      ctx.ui.notify(
-        `Created agent "${name}" at ${path.relative(ctx.cwd, filePath)}`,
-        'info',
-      );
+      ctx.ui.notify(`Created agent "${name}" at ${path.relative(ctx.cwd, filePath)}`, 'info');
 
       // Send a follow-up so the LLM can help refine the prompt
       pi.sendUserMessage(

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/handoffs.ts

@@ -39,11 +39,19 @@ interface SectionEntry {
 }
 
 function normalizeWhitespace(value: string): string {
-  return value.replace(/\r/g, '').replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+  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, '');
+  return title
+    .trim()
+    .toLowerCase()
+    .replace(/[\s/]+/g, ' ')
+    .replace(/[():]/g, '');
 }
 
 function splitMarkdownSections(markdown: string): { preamble: string; sections: SectionEntry[] } {
@@ -141,7 +149,10 @@ function extractPaths(text: string): HandoffFileRef[] {
   const files: HandoffFileRef[] = [];
 
   const addPath = (rawPath: string, notes?: string) => {
-    const path = rawPath.trim().replace(/^`|`$/g, '').replace(/[),.:;]+$/g, '');
+    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;
@@ -203,7 +214,9 @@ export function buildHandoffFromResult(input: {
   const riskItems = uniq(extractListItems(getFirstSectionBody(sections, ['Risks'])));
   const openQuestions = uniq([
     ...extractListItems(getFirstSectionBody(sections, ['Open Questions'])),
-    ...toQuestions(extractListItems(getFirstSectionBody(sections, ['Notes', 'Constraints or Unknowns']))),
+    ...toQuestions(
+      extractListItems(getFirstSectionBody(sections, ['Notes', 'Constraints or Unknowns'])),
+    ),
   ]);
   const goal =
     extractParagraph(getFirstSectionBody(sections, ['Goal'])) ??

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);

package/extensions/subagent/list-agents.ts

@@ -37,11 +37,12 @@ export function registerListAgentsTool(
       const discovery = discoverAgents(ctx.cwd, agentScope, resolvedPaths);
 
       if (discovery.agents.length === 0) {
-        const dirs = agentScope === 'user'
-          ? '~/.pi/agent/prompts'
-          : agentScope === 'project'
-            ? '.pi/prompts'
-            : '~/.pi/agent/prompts and .pi/prompts';
+        const dirs =
+          agentScope === 'user'
+            ? '~/.pi/agent/prompts'
+            : agentScope === 'project'
+              ? '.pi/prompts'
+              : '~/.pi/agent/prompts and .pi/prompts';
         return {
           content: [
             {
@@ -53,10 +54,7 @@ export function registerListAgentsTool(
         };
       }
 
-      const lines: string[] = [
-        `Available agents (scope: ${agentScope}):`,
-        '',
-      ];
+      const lines: string[] = [`Available agents (scope: ${agentScope}):`, ''];
 
       for (const agent of discovery.agents) {
         lines.push(`### ${agent.name}`);

package/extensions/subagent/run-agent-args.ts

@@ -10,16 +10,18 @@ export interface RunAgentCommandOptions {
 }
 
 function tokenize(input: string): string[] {
-  return input.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, '')) ?? [];
+  return (
+    input.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, '')) ?? []
+  );
 }
 
 export function formatRunAgentUsage(): string {
   return 'Usage: /run-agent [--scope user|project|both] [--model <id>] [--thinking <level>] [--yes-project-agents] <agent> [task]';
 }
 
-export function parseRunAgentArgs(rawArgs?: string):
-  | { ok: true; options: RunAgentCommandOptions }
-  | { ok: false; error: string } {
+export function parseRunAgentArgs(
+  rawArgs?: string,
+): { ok: true; options: RunAgentCommandOptions } | { ok: false; error: string } {
   const tokens = tokenize(rawArgs?.trim() ?? '');
   const taskTokens: string[] = [];
 

package/extensions/subagent/spawn-utils.ts

@@ -49,12 +49,19 @@ async function writePromptToTempFile(
   return { dir: tmpDir, filePath };
 }
 
-function cleanupTempFiles(
-  tmpPromptPath: string | null,
-  tmpPromptDir: string | null,
-): void {
-  if (tmpPromptPath) try { fs.unlinkSync(tmpPromptPath); } catch { /* ignore */ }
-  if (tmpPromptDir) try { fs.rmdirSync(tmpPromptDir); } catch { /* ignore */ }
+function cleanupTempFiles(tmpPromptPath: string | null, tmpPromptDir: string | null): void {
+  if (tmpPromptPath)
+    try {
+      fs.unlinkSync(tmpPromptPath);
+    } catch {
+      /* ignore */
+    }
+  if (tmpPromptDir)
+    try {
+      fs.rmdirSync(tmpPromptDir);
+    } catch {
+      /* ignore */
+    }
 }
 
 export interface ToolExecutionStartEvent {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.9.1",
+  "version": "0.10.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/planner.md

@@ -12,14 +12,10 @@ You must NOT make any changes. Only read, analyze, and plan.
 
 If the task has multiple viable designs, unclear ownership boundaries, or needs sharper decomposition before implementation, you may consult the `advisor` agent with the `subagent` tool.
 
-When consulting `advisor`, send only:
-- current role: `planner`
-- the exact design or decomposition question
-- implicated files or packages
-- the smallest relevant task summary
-- what constraints or trade-offs you already see
-
-Treat `advisor` as a focused second opinion. You still own the plan.
+When consulting `advisor`, send only: your role (`planner`), the exact
+design or decomposition question, the implicated files/packages, the
+smallest relevant task summary, and the constraints or trade-offs you
+already see. Treat it as a focused second opinion — you still own the plan.
 
 Input format you'll receive:
 - Context/findings from a scout agent

package/prompts/reviewer.md

@@ -30,25 +30,10 @@ Rules:
 8. Use `advisor` only when severity, intended behavior, or trade-offs remain unclear after inspection and validation.
 9. You still own the final review judgment. Support agents inform your conclusion; they do not replace it.
 
-When consulting `validator`, send only:
-- current role: `reviewer`
-- the exact bug or behavior claim to validate
-- changed files or symbols involved
-- the smallest relevant goal summary
-- what you already verified from diff/code
-
-When consulting `bug-prover`, send only:
-- current role: `reviewer`
-- the exact claim that now needs a minimal repro
-- files, symbols, tests, or commands already inspected
-- why read-only validation was insufficient
-
-When consulting `advisor`, send only:
-- current role: `reviewer`
-- the exact uncertainty or severity question
-- changed files or symbols involved
-- the smallest relevant goal summary
-- what you verified or could not verify from diff/code
+When consulting any support agent, send only: your role (`reviewer`), the
+exact claim or question, the files/symbols involved, the smallest relevant
+goal summary, and what you already verified from diff/code. For
+`bug-prover`, add why read-only validation was insufficient.
 
 Strategy:
 1. Inspect the diff and understand the reason for the change

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
 ---
 
@@ -12,14 +11,10 @@ Work autonomously to complete the assigned task. Use all available tools as need
 
 If a focused second opinion would reduce risk, you may consult the `advisor` agent with the `subagent` tool. Reserve that for ambiguous architecture tradeoffs, persistent failing tests or unexplained errors, merge conflicts or tangled diffs, and security-sensitive or migration-heavy changes.
 
-When consulting `advisor`, send only:
-- current role: `worker`
-- the exact question
-- touched files or symbols
-- the smallest relevant task summary
-- what you already tried or observed
-
-Treat `advisor` as a second opinion, not a replacement owner. You stay responsible for implementation and the final result.
+When consulting `advisor`, send only: your role (`worker`), the exact
+question, the touched files/symbols, the smallest relevant task summary,
+and what you already tried or observed. Treat it as a second opinion, not a
+replacement owner — you stay responsible for the final result.
 
 Keep the final response compact. It should function as a review packet for downstream agents, not a long implementation diary.
 

package/skills/write-an-agent/SKILL.md

@@ -59,9 +59,33 @@ Output:
 - Prefer local pi docs before external docs when writing `docs-scout`.
 - Mention validation commands in planner/worker/reviewer when package behavior changes.
 
+## Prompt hygiene (anti-rot)
+
+Prompts are code: unmaintained instructions become technical debt. Apply the
+same doctrine a project applies to its AGENTS.md — durable facts and
+invariants, not narration.
+
+- **Invariants, not incidents.** A rule earned from a field bug must state
+  the durable invariant, never the story ("fixes relocate gaps more often
+  than they close them" — not "remember that PR"). References to tools,
+  tickets, or model quirks of the moment rot first.
+- **One owner per fact.** Anything that drifts (model ids, tool lists,
+  paths) lives in frontmatter or arrives in the caller's task — never
+  restated in the body. A block repeated across prompts is the same fact
+  with N owners: compress it to one convention line per prompt.
+- **Every line changes behavior.** If deleting a line would not change what
+  the agent does, delete it.
+- **Output contracts are APIs.** Downstream agents parse the sections;
+  renaming or reshaping them is a breaking change — evolve additively.
+- **Update on every miss.** When an agent fails in the field, amend the rule
+  that should have caught it — as an invariant, in the same change as the
+  fix. A prompt that never absorbs its misses is rotting silently.
+
 ## Review checklist
 - Is the role narrower than a general engineer?
 - Would another agent know exactly when to use it?
 - Are the tools minimal?
 - Is the handoff structured?
 - Is the file under 100 lines?
+- Does any line narrate an incident instead of stating its invariant?
+- Is any fact stated here also owned somewhere else?

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');
+  });
+});