@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.1

package/test/task-card.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from 'vitest';
+import { taskCardText } from '../src/task/card.ts';
+
+const result = (model: unknown, text: string) => ({ content: [{ type: 'text' as const, text }], details: { subagentType: 'poteto-agent', model } });
+
+test('the task card names the model that ran, with its thinking level (TASK-017)', () => {
+  expect(taskCardText(result({ provider: 'claude-subscription', id: 'claude-opus-5-5', thinking: 'high' }, 'done'), true).split('\n')[0]).toBe('poteto-agent · claude-subscription/claude-opus-5-5:high');
+});
+
+test('a card without a resolved model says Pi picked its default (TASK-017)', () => {
+  expect(taskCardText(result(null, 'done'), true).split('\n')[0]).toBe("poteto-agent · Pi's default model");
+});
+
+test('the card keeps the result text, shortened until expanded (TASK-017)', () => {
+  const long = Array.from({ length: 30 }, (_, index) => `line ${index}`).join('\n');
+  expect(taskCardText(result(null, long), true).split('\n')).toHaveLength(31);
+  const collapsed = taskCardText(result(null, long), false).split('\n');
+  expect(collapsed.slice(1, 3)).toEqual(['line 0', 'line 1']);
+  expect(collapsed.at(-1)).toBe('… 20 more lines');
+});
+
+test('a result without Task details renders its text alone (TASK-017)', () => {
+  expect(taskCardText({ content: [{ type: 'text', text: 'Invalid model' }], details: undefined }, false)).toBe('Invalid model');
+});
+
+test('a cloud agent card names its worktree branch (TASK-010)', () => {
+  const details = { subagentType: 'poteto-agent', model: null, worktree: { path: '/w', cwd: '/w', branch: 'pstack/x', base: 'HEAD', commit: 'c' } };
+  expect(taskCardText({ content: [{ type: 'text', text: 'done' }], details }, true).split('\n')[0]).toBe("poteto-agent · Pi's default model · branch pstack/x");
+});
+
+test('the card leads with the Task description, as Cursor names the subagent by it', () => {
+  const details = { subagentType: 'poteto-agent', model: null, description: 'Audit skill corpus' };
+  expect(taskCardText({ content: [{ type: 'text', text: 'done' }], details }, true).split('\n')[0]).toBe("Audit skill corpus · poteto-agent · Pi's default model");
+});

package/test/task-fork.test.ts

@@ -0,0 +1,233 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { type ExtensionContext, SessionManager } from '@earendil-works/pi-coding-agent';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { subagentDir } from '../src/paths.ts';
+import { type AgentDefinition, GENERAL_PURPOSE } from '../src/task/agents.ts';
+import { type AgentRecord, acquireRunLock, forkTranscript, transcriptFor, writeRecord } from '../src/task/records.ts';
+import { planFork, prepareFork, taskPreflight } from '../src/task/tool.ts';
+import type { Worktree } from '../src/task/worktree.ts';
+
+const source = '11111111-2222-4333-8444-555555555555';
+const forkId = '99999999-2222-4333-8444-555555555555';
+const reviewer: AgentDefinition = { type: 'reviewer', description: 'r', readonly: true, background: false, prompt: '' };
+const agents = [GENERAL_PURPOSE, reviewer];
+const notRunning = () => false;
+
+let root = '';
+let workspace = '';
+let dir = '';
+let previousAgentDir: string | undefined;
+
+const ctx = () =>
+  ({ cwd: workspace, model: undefined, thinkingLevel: undefined, modelRegistry: { getAvailable: () => [] }, sessionManager: { getSessionId: () => 'parent-session' }, isProjectTrusted: () => true }) as unknown as ExtensionContext;
+const params = (extra: Record<string, unknown> = {}) => ({ description: 'fork it', prompt: 'next task', fork: source, ...extra });
+
+function writeTranscript(agentId: string, cwd: string): string {
+  const header = { type: 'session', version: 3, id: agentId, timestamp: '2026-10-28T10:00:00.000Z', cwd };
+  const user = { type: 'message', id: 'e1', parentId: null, timestamp: '2026-10-28T10:00:01.000Z', message: { role: 'user', content: 'first task', timestamp: 1 } };
+  const assistant = { type: 'message', id: 'e2', parentId: 'e1', timestamp: '2026-10-28T10:00:02.000Z', message: { role: 'assistant', content: [{ type: 'text', text: 'built it' }], timestamp: 2 } };
+  const path = join(dir, `2026-10-28T10-00-00-000Z_${agentId}.jsonl`);
+  writeFileSync(path, `${[header, user, assistant].map((entry) => JSON.stringify(entry)).join('\n')}\n`);
+  return path;
+}
+
+function writeSource(extra: Partial<AgentRecord> = {}, runCwd: string = workspace): string {
+  writeRecord(dir, { agentId: source, type: 'generalPurpose', readonly: false, cwd: workspace, createdAt: '2026-10-28T10:00:00.000Z', depth: 1, model: { provider: 'p', id: 'm', thinking: 'high' }, ...extra });
+  return writeTranscript(source, runCwd);
+}
+
+const lines = (path: string) =>
+  readFileSync(path, 'utf8')
+    .trim()
+    .split('\n')
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), 'fork-')));
+  workspace = join(root, 'workspace');
+  mkdirSync(workspace);
+  previousAgentDir = process.env['PI_CODING_AGENT_DIR'];
+  process.env['PI_CODING_AGENT_DIR'] = join(root, 'agent');
+  dir = subagentDir(workspace);
+  mkdirSync(dir, { recursive: true });
+});
+afterEach(() => {
+  if (previousAgentDir === undefined) delete process.env['PI_CODING_AGENT_DIR'];
+  else process.env['PI_CODING_AGENT_DIR'] = previousAgentDir;
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe('Task fork preflight', () => {
+  test('refuses fork with resume', () => {
+    expect(() => taskPreflight(params({ resume: source }), 0)).toThrow('fork and resume cannot be combined');
+  });
+
+  test.for([{ environment: 'cloud' as const }, { environment: 'local' as const }, { environment: 'cloud' as const, cloud_base_branch: 'main' }])('refuses fork with %j: the fork runs where the source ran', (extra) => {
+    expect(() => taskPreflight(params(extra), 0)).toThrow('fork runs where the source agent ran, so it takes no environment or cloud_base_branch.');
+  });
+
+  test('refuses fork_turns without fork (fork from a turn)', () => {
+    expect(() => taskPreflight({ description: 'd', prompt: 'p', fork_turns: 1 }, 0)).toThrow('fork_turns needs fork: it says how many user turns of the source agent to copy.');
+  });
+
+  test('refuses a fork from a grandchild, as resume does', () => {
+    expect(() => taskPreflight(params(), 2)).toThrow('cannot launch further subagents');
+  });
+});
+
+describe('planFork', () => {
+  test('a new agent ID that starts from the source record: type, model, readonly, directory, depth', () => {
+    writeSource();
+    const plan = planFork(params(), ctx(), agents, notRunning, 0, forkId);
+    expect(plan).toMatchObject({ kind: 'fork', agentId: forkId, forkedFrom: source, model: { provider: 'p', id: 'm', thinking: 'high' }, readonly: false, workspace, worktree: undefined, depth: 1 });
+    expect(plan.agent.type).toBe('generalPurpose');
+    expect(plan.notes).toEqual([`Forked from agent ${source}.`]);
+  });
+
+  test("runs in the source's worktree and records the same branch", () => {
+    const tree = join(root, 'worktrees', source);
+    mkdirSync(tree, { recursive: true });
+    const worktree: Worktree = { path: tree, cwd: tree, branch: `pstack/${source}`, base: 'HEAD', commit: 'abc' };
+    writeSource({ worktree }, tree);
+    const plan = planFork(params(), ctx(), agents, notRunning, 0, forkId);
+    expect(plan.worktree).toEqual(worktree);
+    expect(plan.workspace).toBe(workspace);
+  });
+
+  test('readonly can be added but never lifted', () => {
+    writeSource({ readonly: true });
+    expect(planFork(params({ readonly: false }), ctx(), agents, notRunning, 0, forkId).readonly).toBe(true);
+    writeSource({ readonly: false });
+    expect(planFork(params({ readonly: true }), ctx(), agents, notRunning, 0, forkId).readonly).toBe(true);
+    expect(planFork(params({ subagent_type: 'generalPurpose', readonly: false }), ctx(), agents, notRunning, 0, forkId).readonly).toBe(false);
+  });
+
+  test('a readonly source type keeps the fork readonly even under another type', () => {
+    writeSource({ type: 'reviewer', readonly: false });
+    expect(planFork(params({ subagent_type: 'generalPurpose' }), ctx(), agents, notRunning, 0, forkId).readonly).toBe(true);
+  });
+
+  test('keeps the deeper of the source depth and the caller depth', () => {
+    writeSource({ depth: 2 });
+    expect(planFork(params(), ctx(), agents, notRunning, 0, forkId).depth).toBe(2);
+  });
+
+  test('refuses while the source is running in this runtime', () => {
+    writeSource();
+    expect(() => planFork(params(), ctx(), agents, (id) => id === source, 0, forkId)).toThrow(`Agent ${source} is still running.`);
+  });
+
+  test('refuses an unknown source like resume does', () => {
+    expect(() => planFork(params(), ctx(), agents, notRunning, 0, forkId)).toThrow(`Unknown agent ID ${source}.`);
+  });
+
+  test('refuses a source without a transcript', () => {
+    writeRecord(dir, { agentId: source, type: 'generalPurpose', readonly: false, cwd: workspace, createdAt: '2026-10-28T10:00:00.000Z' });
+    expect(() => planFork(params(), ctx(), agents, notRunning, 0, forkId)).toThrow('has no transcript to fork');
+  });
+});
+
+describe('forkTranscript', () => {
+  test('copies the source session under the new ID, with the source as its parent and unchanged', () => {
+    const tree = join(root, 'tree');
+    const sourcePath = writeSource({}, tree);
+    const before = readFileSync(sourcePath, 'utf8');
+    const copy = forkTranscript(dir, source, forkId);
+    expect(copy).toBe(transcriptFor(dir, forkId));
+    expect(copy.endsWith(`_${forkId}.jsonl`)).toBe(true);
+    const [header, ...entries] = lines(copy);
+    expect(header).toMatchObject({ type: 'session', id: forkId, cwd: tree, parentSession: sourcePath });
+    expect(entries).toEqual(lines(sourcePath).slice(1));
+    expect(readFileSync(sourcePath, 'utf8')).toBe(before);
+    // What `pi --session-id <fork> --session-dir <dir>` run in the source's directory opens.
+    expect(SessionManager.findById(tree, forkId, dir)).toBe(copy);
+    expect(SessionManager.findById(tree, source, dir)).toBe(sourcePath);
+  });
+});
+
+describe('forkTranscript: fork_turns', () => {
+  function writeTurns(turns: number): string {
+    const header = { type: 'session', version: 3, id: source, timestamp: '2026-10-28T10:00:00.000Z', cwd: workspace };
+    const entries = Array.from({ length: turns }, (_, turn) => [
+      { type: 'message', id: `u${turn}`, parentId: turn === 0 ? null : `a${turn - 1}`, timestamp: '2026-10-28T10:00:01.000Z', message: { role: 'user', content: `task ${turn}`, timestamp: 1 } },
+      { type: 'message', id: `a${turn}`, parentId: `u${turn}`, timestamp: '2026-10-28T10:00:02.000Z', message: { role: 'assistant', content: [{ type: 'text', text: `done ${turn}` }], timestamp: 2 } },
+    ]).flat();
+    const path = join(dir, `2026-10-28T10-00-00-000Z_${source}.jsonl`);
+    writeFileSync(path, `${[header, ...entries].map((entry) => JSON.stringify(entry)).join('\n')}\n`);
+    return path;
+  }
+  const userTexts = (path: string) =>
+    SessionManager.open(path)
+      .buildSessionContext()
+      .messages.filter((message) => message.role === 'user')
+      .map((message) => message.content);
+
+  test('copies only the first N user turns, and the copy opens at the end of turn N', () => {
+    const sourcePath = writeTurns(3);
+    const copy = forkTranscript(dir, source, forkId, 2);
+    expect(
+      lines(copy)
+        .slice(1)
+        .map((entry) => entry['id']),
+    ).toEqual(['u0', 'a0', 'u1', 'a1']);
+    expect(userTexts(copy)).toEqual(['task 0', 'task 1']);
+    expect(userTexts(sourcePath)).toEqual(['task 0', 'task 1', 'task 2']);
+  });
+
+  test('a turn count past the end copies the whole transcript', () => {
+    writeTurns(2);
+    expect(userTexts(forkTranscript(dir, source, forkId, 5))).toEqual(['task 0', 'task 1']);
+  });
+
+  test('prepareFork applies fork_turns and names it in the notes', () => {
+    writeSource();
+    writeTurns(3);
+    const { plan, lock } = prepareFork(params({ fork_turns: 1 }), ctx(), { agents, depth: 0 }, notRunning);
+    expect(userTexts(transcriptFor(dir, plan.agentId) ?? '')).toEqual(['task 0']);
+    expect(plan.notes[0]).toBe(`Forked from agent ${source}, keeping its first 1 user turn.`);
+    lock.release();
+  });
+});
+
+describe('prepareFork: plan mode', () => {
+  test('forks in plan mode, marking the launch for plan mode while the record keeps the source readonly (C-H3, C-M1)', () => {
+    writeSource();
+    const { plan, lock } = prepareFork(params(), ctx(), { agents, depth: 0, planMode: () => true }, notRunning);
+    expect([plan.planMode, plan.readonly, plan.worktree]).toEqual([true, false, undefined]);
+    lock.release();
+  });
+
+  test("a plan-mode fork of an isolated worker runs readonly in that worker's worktree", () => {
+    const tree = join(root, 'worktrees', source);
+    mkdirSync(tree, { recursive: true });
+    const worktree: Worktree = { path: tree, cwd: tree, branch: `pstack/${source}`, base: 'HEAD', commit: 'abc' };
+    writeSource({ worktree }, tree);
+    const { plan, lock } = prepareFork(params(), ctx(), { agents, depth: 0, planMode: () => true }, notRunning);
+    expect([plan.planMode, plan.readonly, plan.worktree]).toEqual([true, false, worktree]);
+    lock.release();
+  });
+});
+
+describe('prepareFork: run locks', () => {
+  test('copies the transcript, holds the new agent lock, and leaves the source unlocked', () => {
+    writeSource();
+    const { plan, lock } = prepareFork(params(), ctx(), { agents, depth: 0 }, notRunning);
+    expect(plan.agentId).not.toBe(source);
+    expect(transcriptFor(dir, plan.agentId)).toBeDefined();
+    expect(existsSync(join(dir, `${plan.agentId}.lock`))).toBe(true);
+    expect(existsSync(join(dir, `${source}.lock`))).toBe(false);
+    lock.release();
+  });
+
+  test('refuses while another process holds the source run lock, copying nothing', () => {
+    writeSource();
+    const held = acquireRunLock(dir, source);
+    expect(() => prepareFork(params(), ctx(), { agents, depth: 0 }, notRunning)).toThrow(`Agent ${source} is still running. Wait for its completion before forking it.`);
+    held.release();
+    const leftovers = readdirSync(dir).filter((name) => name.endsWith('.jsonl') || name.endsWith('.lock'));
+    expect(leftovers).toEqual([`2026-10-28T10-00-00-000Z_${source}.jsonl`]);
+  });
+});

package/test/task-format.test.ts

@@ -0,0 +1,65 @@
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from '@earendil-works/pi-coding-agent';
+import { describe, expect, test } from 'vitest';
+import { backgroundText, bounded, foregroundText, notificationText, worktreeLine, worktreePreface } from '../src/task/format.ts';
+
+const id = '11111111-2222-4333-8444-555555555555';
+
+describe('Task texts (TASK-002, TASK-003, SEC-001)', () => {
+  test('foreground output keeps the Cursor structure', () => {
+    expect(foregroundText(id, 'DONE', '/s/x.jsonl', ['Note: n'])).toBe(
+      `This is the output of the subagent:\n\nresponse:\n<response>\nDONE\n</response>\n\nAgent ID: ${id} (pass it as \`resume\` to send a follow-up after it completes)\nTranscript: /s/x.jsonl\nNote: n`,
+    );
+  });
+
+  test('background launch names the agent and says not to poll', () => {
+    expect(backgroundText(id, undefined)).toBe(
+      `Subagent is running in the background. Its final response arrives automatically after your turn ends, so do not wait or poll for it. End your turn or work on something else.\n\nAgent ID: ${id} (pass it as \`resume\` to send a follow-up after it completes)`,
+    );
+  });
+
+  test('the notification carries every Cursor field', () => {
+    expect(notificationText({ status: 'error', agentId: id, title: 't', toolCallId: 'c1', detail: 'boom' }).split('\n').slice(2)).toEqual([
+      '<task>',
+      'kind: subagent',
+      'status: error',
+      `task_id: ${id}`,
+      'title: t',
+      'tool_call_id: c1',
+      'detail: boom',
+      '</task>',
+    ]);
+  });
+
+  test("bounds model-facing output with Pi's own limits and points to the transcript (review r2: architecture 6)", () => {
+    const lines = Array.from({ length: 3_000 }, (_, index) => `line ${index}`).join('\n');
+    const text = bounded(lines, '/s/x.jsonl');
+    expect(text.split('\n').slice(-2)).toEqual([`line ${DEFAULT_MAX_LINES - 1}`, '[truncated: showing 2000 of 3000 lines; the full response is in /s/x.jsonl]']);
+    expect(bounded('short', undefined)).toBe('short');
+  });
+
+  test('cuts a single oversized line at the byte limit instead of dropping it', () => {
+    const text = bounded('é'.repeat(40_000), '/s/x.jsonl');
+    expect([Buffer.byteLength(text.split('\n[truncated')[0] ?? '', 'utf8'), text.endsWith('[truncated: showing 50.0KB of 78.1KB; the full response is in /s/x.jsonl]')]).toEqual([DEFAULT_MAX_BYTES, true]);
+  });
+
+  test('cuts on a character boundary in linear time', () => {
+    const started = performance.now();
+    const text = bounded('😀'.repeat(2_000_000), undefined);
+    const kept = text.split('\n[truncated')[0] ?? '';
+    expect([Buffer.byteLength(kept, 'utf8'), kept.endsWith('😀'), performance.now() - started < 2_000]).toEqual([51_200, true, true]);
+  });
+});
+
+describe('cloud worktree texts (TASK-010)', () => {
+  const worktree = { path: '/w/wt', cwd: '/w/wt/pkg', branch: `pstack/${id}`, base: 'main', commit: 'abc123' };
+
+  test('the result line names the worktree and the branch to merge', () => {
+    expect(worktreeLine(worktree)).toBe(`Worktree: /w/wt on branch pstack/${id}, from main at abc123. Merge pstack/${id} to take the subagent's commits.`);
+  });
+
+  test("the child's prompt opens with where it runs and that it must commit", () => {
+    expect(worktreePreface(worktree, 'do it')).toBe(
+      `You are running in an isolated git worktree at /w/wt (working directory /w/wt/pkg) on branch pstack/${id}, created from main at abc123. Uncommitted changes in the parent's checkout are not here. Commit your changes to pstack/${id} before you finish, because the parent agent merges from that branch.\n\ndo it`,
+    );
+  });
+});

package/test/task-model.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from 'vitest';
+import { type AvailableModel, resolveSubagentModel } from '../src/task/models.ts';
+
+const FULL = ['low', 'medium', 'high', 'xhigh', 'max'];
+const available: AvailableModel[] = [
+  { provider: 'claude-subscription', id: 'claude-opus-5-5', reasoning: true, levels: FULL },
+  { provider: 'claude-subscription', id: 'claude-haiku-4-5', reasoning: true, levels: FULL },
+  { provider: 'grok-build', id: 'grok-4.7', reasoning: true, levels: ['low', 'medium', 'high', 'xhigh'] },
+  { provider: 'deepseek', id: 'deepseek-flash', reasoning: true, levels: ['off', 'low', 'high', 'max'] },
+  { provider: 'other', id: 'deepseek-flash', reasoning: false, levels: ['off'] },
+];
+const parent = { provider: 'claude-subscription', id: 'claude-haiku-4-5', thinking: 'low' as const };
+
+describe('resolveSubagentModel (TASK-007)', () => {
+  test.for([undefined, '', 'inherit', 'inherit-parent', 'auto', 'default'])('%s runs on the parent model and thinking level', (value) => {
+    expect(resolveSubagentModel(value, available, parent)).toEqual({ provider: 'claude-subscription', id: 'claude-haiku-4-5', thinking: 'low' });
+  });
+
+  test('inherit with no parent model leaves the choice to the child', () => {
+    expect([resolveSubagentModel('inherit', available, undefined), resolveSubagentModel('inherit', available, parent)]).toEqual([undefined, parent]);
+  });
+
+  test.for([
+    { value: 'claude-opus-5-5-xhigh', expected: { provider: 'claude-subscription', id: 'claude-opus-5-5', thinking: 'xhigh' } },
+    { value: 'claude-opus-5-5-max-fast', expected: { provider: 'claude-subscription', id: 'claude-opus-5-5', thinking: 'max' } },
+    { value: 'grok-4.7-xhigh-fast', expected: { provider: 'grok-build', id: 'grok-4.7', thinking: 'xhigh' } },
+    { value: 'claude-opus-5-5-thinking-high', expected: { provider: 'claude-subscription', id: 'claude-opus-5-5', thinking: 'high' } },
+    { value: 'claude-opus-5-5', expected: { provider: 'claude-subscription', id: 'claude-opus-5-5' } },
+  ])('maps the Cursor slug $value (TASK-007, RULE-003)', ({ value, expected }) => {
+    expect(resolveSubagentModel(value, available, parent)).toEqual(expected);
+  });
+
+  test('maps Cursor slugs with none, minimal, or a bare -fast suffix (Cursor CLI 2026.10.22 model list)', () => {
+    const local = [...available, { provider: 'openai', id: 'gpt-5.3-codex', reasoning: true, levels: ['minimal', 'low', 'high'] }];
+    expect([
+      resolveSubagentModel('grok-4.7-fast', local, parent),
+      resolveSubagentModel('deepseek/deepseek-flash-none', local, parent),
+      resolveSubagentModel('gpt-5.3-codex-minimal', local, parent),
+      resolveSubagentModel('gpt-5.3-codex-minimal-fast', local, parent),
+    ]).toEqual([
+      { provider: 'grok-build', id: 'grok-4.7' },
+      { provider: 'deepseek', id: 'deepseek-flash', thinking: 'off' },
+      { provider: 'openai', id: 'gpt-5.3-codex', thinking: 'minimal' },
+      { provider: 'openai', id: 'gpt-5.3-codex', thinking: 'minimal' },
+    ]);
+  });
+
+  test.for([
+    { value: 'deepseek/deepseek-flash', expected: { provider: 'deepseek', id: 'deepseek-flash' } },
+    { value: 'deepseek/deepseek-flash:high', expected: { provider: 'deepseek', id: 'deepseek-flash', thinking: 'high' } },
+    { value: 'claude-opus-5-5:medium', expected: { provider: 'claude-subscription', id: 'claude-opus-5-5', thinking: 'medium' } },
+  ])('maps the Pi spec $value', ({ value, expected }) => {
+    expect(resolveSubagentModel(value, available, parent)).toEqual(expected);
+  });
+
+  test('selects model ids that contain a colon, with or without a thinking level (review: security 5)', () => {
+    const local = [...available, { provider: 'ollama', id: 'llama3:8b', reasoning: true, levels: ['off', 'high'] }];
+    expect([resolveSubagentModel('ollama/llama3:8b', local, parent), resolveSubagentModel('llama3:8b', local, parent), resolveSubagentModel('llama3:8b:high', local, parent)]).toEqual([
+      { provider: 'ollama', id: 'llama3:8b' },
+      { provider: 'ollama', id: 'llama3:8b' },
+      { provider: 'ollama', id: 'llama3:8b', thinking: 'high' },
+    ]);
+  });
+
+  test('prefers a model whose own id ends in -fast for a -fast slug (review: parity)', () => {
+    const fast = [...available, { provider: 'grok-build', id: 'grok-4.7-fast', reasoning: true, levels: ['low', 'xhigh'] }];
+    expect(resolveSubagentModel('grok-4.7-xhigh-fast', fast, parent)).toEqual({ provider: 'grok-build', id: 'grok-4.7-fast', thinking: 'xhigh' });
+  });
+
+  test.for([
+    { value: 'claude-opus-5-5[effort=high]', expected: { provider: 'claude-subscription', id: 'claude-opus-5-5', thinking: 'high' } },
+    { value: 'claude-opus-5-5[]', expected: { provider: 'claude-subscription', id: 'claude-opus-5-5' } },
+    { value: 'claude-opus-5-5[effort=high,context=300k]', expected: { provider: 'claude-subscription', id: 'claude-opus-5-5', thinking: 'high' } },
+    { value: 'grok-4.7[fast=false]', expected: { provider: 'grok-build', id: 'grok-4.7' } },
+    { value: 'grok-4.7[fast=true, effort=low]', expected: { provider: 'grok-build', id: 'grok-4.7', thinking: 'low' } },
+    { value: 'deepseek/deepseek-flash[effort=max]', expected: { provider: 'deepseek', id: 'deepseek-flash', thinking: 'max' } },
+  ])('maps the Cursor model parameters in $value', ({ value, expected }) => {
+    expect(resolveSubagentModel(value, available, parent)).toEqual(expected);
+  });
+
+  test('fast=true picks a model whose own id ends in -fast, and fast=false keeps the standard one', () => {
+    const fast = [...available, { provider: 'grok-build', id: 'grok-4.7-fast', reasoning: true, levels: ['low', 'xhigh'] }];
+    expect([resolveSubagentModel('grok-4.7[fast=true,effort=xhigh]', fast, parent), resolveSubagentModel('grok-4.7[fast=false]', fast, parent)]).toEqual([
+      { provider: 'grok-build', id: 'grok-4.7-fast', thinking: 'xhigh' },
+      { provider: 'grok-build', id: 'grok-4.7' },
+    ]);
+  });
+
+  test.for(['claude-opus-5-5[speed=1]', 'claude-opus-5-5[effort=turbo]', 'claude-opus-5-5[fast=maybe]', 'claude-opus-5-5[effort]', 'claude-opus-5-5-high[effort=low]'])('rejects the model parameters in %s with the allowed list', (value) => {
+    expect(() => resolveSubagentModel(value, available, parent)).toThrow(`Invalid model selection "${value}".`);
+  });
+
+  test('rejects an effort parameter the model does not support', () => {
+    expect(() => resolveSubagentModel('grok-4.7[effort=max]', available, parent)).toThrow('grok-build/grok-4.7 does not support thinking level max; it supports low, medium, high, xhigh.');
+  });
+
+  test("an id that two providers share resolves to the parent chat's provider in every form (C-M5)", () => {
+    const deepseekParent = { provider: 'deepseek', id: 'deepseek-flash', thinking: 'high' as const };
+    expect(['deepseek-flash', 'deepseek-flash:max', 'deepseek-flash[effort=low]', 'deepseek-flash-max'].map((value) => resolveSubagentModel(value, available, deepseekParent))).toEqual([
+      { provider: 'deepseek', id: 'deepseek-flash' },
+      { provider: 'deepseek', id: 'deepseek-flash', thinking: 'max' },
+      { provider: 'deepseek', id: 'deepseek-flash', thinking: 'low' },
+      { provider: 'deepseek', id: 'deepseek-flash', thinking: 'max' },
+    ]);
+    expect(resolveSubagentModel('deepseek-flash', available, { provider: 'other', id: 'x' })).toEqual({ provider: 'other', id: 'deepseek-flash' });
+  });
+
+  test('rejects an id that two providers share, naming both', () => {
+    expect(() => resolveSubagentModel('deepseek-flash', available, parent)).toThrow('Model "deepseek-flash" matches more than one provider: deepseek/deepseek-flash, other/deepseek-flash. Use <provider>/<model-id>.');
+  });
+
+  test('rejects an unknown model with the allowed list in Cursor format', () => {
+    expect(() => resolveSubagentModel('no-such-model-xyz', available, parent)).toThrow(
+      [
+        'Invalid model selection "no-such-model-xyz". Model could not be resolved to a valid subagent model.',
+        'Allowed model slugs:',
+        '- inherit',
+        '- claude-subscription/claude-opus-5-5 (thinking: low, medium, high, xhigh, max)',
+        '- claude-subscription/claude-haiku-4-5 (thinking: low, medium, high, xhigh, max)',
+        '- grok-build/grok-4.7 (thinking: low, medium, high, xhigh)',
+        '- deepseek/deepseek-flash (thinking: off, low, high, max)',
+        '- other/deepseek-flash',
+        '',
+        'Add a thinking level as <model>:<level>, for example claude-opus-5-5:xhigh, or as <model>[effort=<level>].',
+        'The `model` parameter is optional. If omitted, the subagent uses the same model as the parent agent.',
+      ].join('\n'),
+    );
+  });
+
+  test.for([
+    { value: 'grok-4.7-max-fast', reason: 'grok-build/grok-4.7 does not support thinking level max; it supports low, medium, high, xhigh.' },
+    { value: 'deepseek/deepseek-flash:xhigh', reason: 'deepseek/deepseek-flash does not support thinking level xhigh; it supports off, low, high, max.' },
+    { value: 'other/deepseek-flash:high', reason: 'other/deepseek-flash does not support thinking level high; it supports off.' },
+  ])('rejects $value, a thinking level the model does not support, as Cursor rejects an unlisted slug (review r2: parity 3)', ({ value, reason }) => {
+    expect(() => resolveSubagentModel(value, available, parent)).toThrow(`Invalid model selection "${value}". ${reason}\nAllowed model slugs:`);
+  });
+
+  test('rejects an unknown effort suffix rather than guessing', () => {
+    expect(() => resolveSubagentModel('claude-opus-5-5-turbo', available, parent)).toThrow('Invalid model selection "claude-opus-5-5-turbo".');
+  });
+});