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

package/src/task/runner.ts

@@ -0,0 +1,459 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+
+import type { ImageContent, Usage as ProviderUsage } from '@earendil-works/pi-ai';
+import { detectSupportedImageMimeTypeFromFile } from '@earendil-works/pi-coding-agent';
+import { PACKAGE_ROOT } from '../paths.ts';
+import type { ModelSpec } from './models.ts';
+
+// TodoWrite only changes the child's own todo list, so a readonly reviewer can still keep one. The child replaces
+// bash with a sandboxed read-only shell (readonly-shell.ts).
+const READONLY_TOOLS = 'read,grep,find,ls,bash,TodoWrite';
+const AGENT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,126}[A-Za-z0-9]$/;
+export const KILL_GRACE_MS = 3_000;
+// Dialogs block a run until answered. A subagent has nobody to ask, so its owner dismisses them.
+const DIALOG_METHODS = new Set(['select', 'confirm', 'input', 'editor']);
+
+/** Provider usage, plus whether `cost.total` was reported by the provider rather than priced locally. */
+export interface Usage extends ProviderUsage {
+  cost: ProviderUsage['cost'] & { totalFromProvider?: boolean | undefined };
+}
+
+export interface ChildArgsOptions {
+  sessionDir: string;
+  agentId: string;
+  model?: ModelSpec;
+  readonly?: boolean;
+  /** Tools to add back to the loadout Pi restores from the transcript (records.ts `readonlyLaunchRestores`). */
+  restoreTools?: readonly string[];
+  /** The parent's project trust, so the child loads the same project resources (`ctx.isProjectTrusted()`). */
+  trusted?: boolean;
+}
+
+/** Argv for one `pi --mode rpc` subagent process. Its prompts travel as RPC commands on stdin, never in argv. */
+export function childArgs(options: ChildArgsOptions): string[] {
+  const model = options.model === undefined ? [] : ['--model', `${options.model.provider}/${options.model.id}`, ...(options.model.thinking === undefined ? [] : ['--thinking', options.model.thinking])];
+  return [
+    '--mode',
+    'rpc',
+    '--session-dir',
+    options.sessionDir,
+    '--session-id',
+    options.agentId,
+    '-e',
+    PACKAGE_ROOT,
+    ...(options.trusted === undefined ? [] : [options.trusted ? '--approve' : '--no-approve']),
+    ...model,
+    ...(options.readonly === true ? ['--tools', READONLY_TOOLS, '--no-mcp'] : []),
+    ...(options.readonly !== true && (options.restoreTools ?? []).length > 0 ? ['--tools', (options.restoreTools ?? []).map((name) => `+${name}`).join(',')] : []),
+  ];
+}
+
+export function validateAgentId(id: string): string {
+  if (!AGENT_ID.test(id)) throw new Error(`"${id.slice(0, 80)}" is not a valid agent ID.`);
+  return id;
+}
+
+/** Absolute paths of files to attach: `~` expands as in Pi's read paths, and each must be an existing file. */
+export function resolveAttachments(paths: readonly string[], cwd: string, home: string = homedir()): string[] {
+  return paths.map((path) => {
+    const expanded = path === '~' || path.startsWith('~/') ? join(home, path.slice(1)) : path;
+    const absolute = isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+    if (!existsSync(absolute)) throw new Error(`file_attachments: ${absolute} does not exist`);
+    if (!statSync(absolute).isFile()) throw new Error(`file_attachments: ${absolute} is not a file`);
+    return absolute;
+  });
+}
+
+export interface ChildInput {
+  text: string;
+  images: ImageContent[];
+}
+
+const VIDEO = /\.(?:mp4|m4v|mov|webm|avi|mkv)$/i;
+
+/**
+ * The first message Pi builds from piped input and `@file` arguments, which RPC mode does not accept: the trimmed
+ * prompt, then each non-empty text file in a <file> block, and each image as an attachment with an empty <file> block.
+ */
+export async function withAttachments(prompt: string, attachments: readonly string[]): Promise<ChildInput> {
+  let text = prompt.trim();
+  const images: ImageContent[] = [];
+  for (const path of attachments) {
+    const bytes = readFileSync(path);
+    if (bytes.length === 0) continue;
+    // Pi model inputs have no video type. Name the file instead of feeding binary bytes to the text parser.
+    if (VIDEO.test(path)) {
+      text += `<file name="${path}">[video attachment; this host cannot send video to the model, open the path with a media tool]</file>\n`;
+      continue;
+    }
+    const mimeType = await detectSupportedImageMimeTypeFromFile(path);
+    if (mimeType === null) {
+      text += `<file name="${path}">\n${bytes.toString('utf8').replace(/^\uFEFF/, '')}\n</file>\n`;
+      continue;
+    }
+    images.push({ type: 'image', mimeType, data: bytes.toString('base64') });
+    text += `<file name="${path}"></file>\n`;
+  }
+  return { text, images };
+}
+
+export interface ChildOptions {
+  command: readonly string[];
+  args: readonly string[];
+  prompt: string;
+  images?: readonly ImageContent[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  onEvent?: (event: { type: string } & Record<string, unknown>) => void;
+}
+
+export interface ChildOutcome {
+  finalText: string;
+  usage: Usage;
+  failure?: string;
+  stderr: string;
+}
+
+export interface ChildHandle {
+  done: Promise<ChildOutcome>;
+  /** Ends the child and its process group now: session shutdown or an aborted foreground call. */
+  kill: () => void;
+  /** stop_agent: aborts the run over RPC so the transcript records it, then kills the group if it outlives the grace period. */
+  stop: () => void;
+  /** Queues a message into the running turn (a new turn if the run just ended); rejects once the child is closing. */
+  steer: (text: string, images: readonly ImageContent[]) => Promise<void>;
+  pid: number | undefined;
+}
+
+export const zeroUsage = (): Usage => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, totalFromProvider: true } });
+
+export function addUsage(left: Usage, right: Usage): Usage {
+  return {
+    input: left.input + right.input,
+    output: left.output + right.output,
+    cacheRead: left.cacheRead + right.cacheRead,
+    cacheWrite: left.cacheWrite + right.cacheWrite,
+    totalTokens: left.totalTokens + right.totalTokens,
+    cost: {
+      input: left.cost.input + right.cost.input,
+      output: left.cost.output + right.cost.output,
+      cacheRead: left.cost.cacheRead + right.cost.cacheRead,
+      cacheWrite: left.cost.cacheWrite + right.cost.cacheWrite,
+      total: left.cost.total + right.cost.total,
+      totalFromProvider: left.cost.totalFromProvider === true && right.cost.totalFromProvider === true,
+    },
+  };
+}
+
+interface AssistantRecord {
+  text: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+/**
+ * Usage a JSON-mode event adds to the child's session totals, counted the way Pi's own session stats count it:
+ * assistant replies, tool results that carry nested usage (such as a grandchild subagent), and compactions.
+ */
+function usageOf(event: Record<string, unknown>): Usage | undefined {
+  if (event['type'] === 'compaction_end') return (event['result'] as { usage?: Usage } | undefined)?.usage;
+  const message = event['message'] as { role?: string; usage?: Usage } | undefined;
+  if (event['type'] !== 'message_end' || (message?.role !== 'assistant' && message?.role !== 'toolResult')) return undefined;
+  return message.usage;
+}
+
+function readAssistant(event: Record<string, unknown>): AssistantRecord | undefined {
+  const message = event['message'] as { role?: string; content?: { type: string; text?: string }[]; stopReason?: string; errorMessage?: string } | undefined;
+  if (event['type'] !== 'message_end' || message?.role !== 'assistant') return undefined;
+  const text = (message.content ?? [])
+    .filter((part) => part.type === 'text')
+    .map((part) => part.text ?? '')
+    .join('');
+  return {
+    text,
+    ...(message.stopReason === undefined ? {} : { stopReason: message.stopReason }),
+    ...(message.errorMessage === undefined ? {} : { errorMessage: message.errorMessage }),
+  };
+}
+
+function readUser(event: Record<string, unknown>): { text: string; images: ImageContent[] } | undefined {
+  if (event['type'] !== 'message_end') return undefined;
+  const message = event['message'] as { role?: string; content?: unknown } | undefined;
+  if (message?.role !== 'user') return undefined;
+  if (typeof message.content === 'string') return { text: message.content, images: [] };
+  if (!Array.isArray(message.content)) return undefined;
+  const text: string[] = [];
+  const images: ImageContent[] = [];
+  for (const part of message.content as { type?: string; text?: string; data?: string; mimeType?: string }[]) {
+    if (part.type === 'text') text.push(part.text ?? '');
+    if (part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string') images.push({ type: 'image', data: part.data, mimeType: part.mimeType });
+  }
+  return { text: text.join(''), images };
+}
+
+const sameImages = (left: readonly ImageContent[], right: readonly ImageContent[]): boolean => left.length === right.length && left.every((image, index) => image.data === right[index]?.data && image.mimeType === right[index]?.mimeType);
+/** A steering input this runner accepted, kept until Pi stores it as a user message. */
+export interface AcceptedSteer {
+  text: string;
+  images: readonly ImageContent[];
+}
+
+/**
+ * Rebuilds messages from a queue drain. Only steering entries were sent by this runner, so only they may reclaim a
+ * recorded image. Each recorded steer is used once, which keeps two identical texts with different images in order.
+ */
+export function recoverDrained(drained: readonly { queue: 'steering' | 'followUp'; text: string }[], accepted: readonly AcceptedSteer[]): AcceptedSteer[] {
+  const unused = [...accepted];
+  return drained.map(({ queue, text }) => {
+    if (queue === 'followUp') return { text, images: [] };
+    const exact = unused.findIndex((entry) => entry.text === text);
+    const [entry] = unused.splice(exact === -1 ? 0 : exact, 1);
+    return { text, images: entry?.images ?? [] };
+  });
+}
+
+function lineReader(onLine: (line: string) => void): (chunk: Buffer) => void {
+  const decoder = new StringDecoder('utf8');
+  let buffer = '';
+  return (chunk) => {
+    buffer += decoder.write(chunk);
+    for (let index = buffer.indexOf('\n'); index !== -1; index = buffer.indexOf('\n')) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (line !== '') onLine(line);
+    }
+  };
+}
+
+/** RPC mode reserves stdout for protocol records, but a child extension can still print there; such a line must not crash the parent. */
+function parseEvent(line: string): ({ type: string } & Record<string, unknown>) | undefined {
+  try {
+    const value: unknown = JSON.parse(line);
+    return typeof value === 'object' && value !== null && typeof (value as { type?: unknown }).type === 'string' ? (value as { type: string } & Record<string, unknown>) : undefined;
+  } catch (error) {
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+}
+
+/** Signals the child's whole process group. A group that is already gone (ESRCH) or not ours (EPERM) is left alone. */
+export function signalGroup(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(-pid, signal);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== 'ESRCH' && code !== 'EPERM') throw error;
+  }
+}
+
+function killGroup(pid: number | undefined): void {
+  if (pid === undefined) return;
+  signalGroup(pid, 'SIGTERM');
+  setTimeout(() => signalGroup(pid, 'SIGKILL'), KILL_GRACE_MS).unref();
+}
+
+interface ChildState {
+  usage: Usage;
+  stderr: string;
+  aborted: boolean;
+  stopped: boolean;
+  /** Why Pi refused the first prompt. */
+  refused?: string;
+  /** The recovery after a steer stranded at settlement could not continue the run. */
+  recoveryFailed?: string;
+}
+
+function outcomeOf(last: AssistantRecord | undefined, state: ChildState, code: number | null): ChildOutcome {
+  const base = { finalText: last?.text ?? '', usage: state.usage, stderr: state.stderr };
+  if (state.aborted) return { ...base, failure: 'Subagent was aborted' };
+  if (state.stopped) return { ...base, failure: 'Subagent was stopped with stop_agent' };
+  if (state.refused !== undefined) return { ...base, failure: state.refused };
+  if (state.recoveryFailed !== undefined) return { ...base, failure: state.recoveryFailed };
+  if (last?.stopReason === 'error' || last?.stopReason === 'aborted') return { ...base, failure: last.errorMessage ?? `subagent stopped: ${last.stopReason}` };
+  if (code !== 0) return { ...base, failure: `pi exited with code ${code}: ${state.stderr.trim().split('\n').at(-1) ?? ''}`.trim() };
+  return base;
+}
+
+interface RpcResponse {
+  id?: string;
+  success: boolean;
+  error?: string;
+  data?: { disposition?: string; steering?: string[]; followUp?: string[] };
+}
+
+/**
+ * Runs one `pi --mode rpc` child in its own process group, so abort and shutdown can stop it and everything it started.
+ * The child stays open while its run is active or a command awaits its response, so a steer always lands in a run;
+ * once the run settles with nothing outstanding, closing stdin makes Pi save the session and exit.
+ * Pi's `RpcClient` cannot start or end this child (no detached spawn, stdin close, `extension_ui_response`, or exit
+ * code); docs/native-gaps.md records each missing mechanism.
+ */
+export function startChild(options: ChildOptions): ChildHandle {
+  const [command, ...prefix] = options.command;
+  if (command === undefined) throw new Error('startChild needs a command');
+  const child = spawn(command, [...prefix, ...options.args], { cwd: options.cwd, env: options.env, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+  const state: ChildState = { usage: zeroUsage(), stderr: '', aborted: false, stopped: false };
+  let last: AssistantRecord | undefined;
+  let open = true;
+  let idle = true;
+  let steering: AcceptedSteer[] = [];
+  let recoveryRounds = 0;
+  let nextId = 0;
+  let grace: ReturnType<typeof setTimeout> | undefined;
+  const waiting = new Map<string, (response: RpcResponse) => void>();
+
+  const write = (record: Record<string, unknown>) => {
+    if (open) child.stdin.write(`${JSON.stringify(record)}\n`);
+  };
+  const close = () => {
+    if (!open) return;
+    open = false;
+    child.stdin.end();
+  };
+  const request = (record: Record<string, unknown>, onResponse: (response: RpcResponse) => void) => {
+    const id = `pstack-${nextId++}`;
+    waiting.set(id, onResponse);
+    write({ ...record, id });
+  };
+  const prompt = (text: string, images: readonly ImageContent[], onResponse: (response: RpcResponse) => void, streamingBehavior?: 'steer') =>
+    request({ type: 'prompt', message: text, ...(images.length === 0 ? {} : { images }), ...(streamingBehavior === undefined ? {} : { streamingBehavior }) }, (response) => {
+      if (response.data?.disposition === 'started') idle = false;
+      onResponse(response);
+    });
+  // A steer can reach Pi just as its run ends and stay queued with no run to take it. Draining that queue is the
+  // only native way to continue it, and the drain returns text only, so each drained message gets its recorded
+  // attachments back and keeps its own message boundary.
+  const closeWhenSettled = () => {
+    if (!open || !idle || waiting.size > 0) return;
+    if (state.stopped || steering.length === 0) return close();
+    if (recoveryRounds >= 3) {
+      state.recoveryFailed = `A steering message stayed queued after ${recoveryRounds} resume attempts: ${steering.map((entry) => entry.text).join(' | ')}`;
+      steering = [];
+      return close();
+    }
+    recoveryRounds += 1;
+    const accepted = steering;
+    steering = [];
+    request({ type: 'clear_queue' }, (response) => {
+      const drained = [...(response.data?.steering ?? []).map((text) => ({ queue: 'steering' as const, text })), ...(response.data?.followUp ?? []).map((text) => ({ queue: 'followUp' as const, text }))];
+      if (drained.length === 0) return closeWhenSettled();
+      const recovered = recoverDrained(drained, accepted);
+      steering = recovered;
+      for (const [index, entry] of recovered.entries()) prompt(entry.text, entry.images, () => undefined, index === 0 ? undefined : 'steer');
+    });
+  };
+
+  const kill = () => {
+    state.aborted = true;
+    killGroup(child.pid);
+  };
+  const stop = () => {
+    if (state.stopped || state.aborted) return;
+    state.stopped = true;
+    request({ type: 'clear_queue' }, () => undefined);
+    request({ type: 'abort' }, () => undefined);
+    grace = setTimeout(() => killGroup(child.pid), KILL_GRACE_MS);
+    grace.unref();
+  };
+  const steer = (text: string, images: readonly ImageContent[]) =>
+    new Promise<void>((resolve, reject) => {
+      if (!open || state.stopped || state.aborted) return reject(new Error('The subagent has finished its run.'));
+      const entry = { text, images };
+      steering.push(entry);
+      prompt(
+        text,
+        images,
+        (response) => {
+          if (!response.success) {
+            steering = steering.filter((candidate) => candidate !== entry);
+            return reject(new Error(response.error ?? 'Pi refused the message.'));
+          }
+          if (response.data?.disposition === 'handled') steering = steering.filter((candidate) => candidate !== entry);
+          resolve();
+        },
+        'steer',
+      );
+    });
+
+  const onRecord = (record: { type: string } & Record<string, unknown>) => {
+    if (record.type === 'response') {
+      const response = record as unknown as RpcResponse;
+      const onResponse = response.id === undefined ? undefined : waiting.get(response.id);
+      if (onResponse === undefined) return;
+      waiting.delete(response.id as string);
+      onResponse(response);
+      return closeWhenSettled();
+    }
+    if (record.type === 'extension_ui_request') {
+      if (DIALOG_METHODS.has(String(record['method']))) write({ type: 'extension_ui_response', id: record['id'], cancelled: true });
+      return;
+    }
+    options.onEvent?.(record);
+    const user = readUser(record);
+    if (user !== undefined) {
+      const matchers = [
+        (entry: { text: string; images: readonly ImageContent[] }) => entry.text === user.text && sameImages(entry.images, user.images),
+        (entry: { text: string }) => entry.text === user.text,
+        (entry: { images: readonly ImageContent[] }) => entry.images.length > 0 && sameImages(entry.images, user.images),
+      ];
+      let index = -1;
+      for (const matches of matchers) {
+        index = steering.findIndex(matches);
+        if (index !== -1) break;
+      }
+      if (index !== -1) {
+        steering.splice(index, 1);
+        recoveryRounds = 0;
+      }
+    }
+    if (record.type === 'agent_start') idle = false;
+    const usage = usageOf(record);
+    if (usage !== undefined) state.usage = addUsage(state.usage, usage);
+    last = readAssistant(record) ?? last;
+    if (record.type === 'agent_settled') {
+      idle = true;
+      closeWhenSettled();
+    }
+  };
+
+  child.stdout.on(
+    'data',
+    lineReader((line) => {
+      const record = parseEvent(line);
+      if (record === undefined) state.stderr = `${state.stderr}${line}\n`.slice(-8_192);
+      else onRecord(record);
+    }),
+  );
+  child.stderr.on('data', (chunk: Buffer) => {
+    state.stderr = `${state.stderr}${chunk.toString('utf8')}`.slice(-8_192);
+  });
+  // A child that exits or is killed before it reads a large prompt closes the pipe. Unhandled, that EPIPE would be an
+  // uncaught exception in the parent, and interactive Pi exits on one; the child's exit already reports the failure.
+  child.stdin.on('error', (error: NodeJS.ErrnoException) => {
+    if (error.code !== 'EPIPE' && error.code !== 'ECONNRESET') state.stderr = `${state.stderr}stdin: ${error.message}\n`.slice(-8_192);
+  });
+  if (options.signal?.aborted) kill();
+  else options.signal?.addEventListener('abort', kill, { once: true });
+  if (state.aborted || (options.prompt.trim() === '' && (options.images ?? []).length === 0)) close();
+  else
+    prompt(options.prompt, options.images ?? [], (response) => {
+      if (!response.success) state.refused = response.error ?? 'Pi refused the prompt.';
+    });
+  const done = new Promise<ChildOutcome>((resolveDone) => {
+    child.on('error', (error) => resolveDone({ finalText: '', usage: state.usage, stderr: state.stderr, failure: `could not start pi: ${error.message}` }));
+    child.on('close', (code) => {
+      open = false;
+      clearTimeout(grace);
+      options.signal?.removeEventListener('abort', kill);
+      resolveDone(outcomeOf(last, state, code));
+      for (const onResponse of waiting.values()) onResponse({ success: false, error: 'The subagent exited.' });
+      waiting.clear();
+    });
+  });
+  return { done, kill, stop, steer, pid: child.pid };
+}

package/src/task/status.ts

@@ -0,0 +1,170 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { subagentDir } from '../paths.ts';
+import type { ModelSpec } from './models.ts';
+import { readRecord, recordIds, runningPid, transcriptFor } from './records.ts';
+import { validateAgentId } from './runner.ts';
+
+const LIST_LIMIT = 20;
+const TEXT_LIMIT = 500;
+const FIRST_READ_BYTES = 64 * 1024;
+// A transcript can grow to hundreds of megabytes; status reads only its tail.
+const TAIL_LIMIT_BYTES = 4 * 1024 * 1024;
+
+export interface AgentStatus {
+  agentId: string;
+  state: 'running' | 'idle' | 'missing';
+  pid?: number;
+  type?: string;
+  model?: string;
+  readonly?: boolean;
+  directory?: string;
+  branch?: string;
+  forkedFrom?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  transcript?: string;
+  lastText?: string;
+}
+
+const modelName = (model: ModelSpec | undefined) => (model === undefined ? "Pi's default model" : `${model.provider}/${model.id}${model.thinking === undefined ? '' : `:${model.thinking}`}`);
+
+function truncate(text: string): string {
+  const flat = text.trim();
+  return flat.length > TEXT_LIMIT ? `${flat.slice(0, TEXT_LIMIT)}…` : flat;
+}
+
+function readTail(path: string, size: number, bytes: number): string {
+  const length = Math.min(size, bytes);
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(path, 'r');
+  try {
+    readSync(fd, buffer, 0, length, size - length);
+  } finally {
+    closeSync(fd);
+  }
+  return buffer.toString('utf8');
+}
+
+function assistantTextOf(line: string): string | undefined {
+  let entry: { type?: unknown; message?: { role?: unknown; content?: unknown } };
+  try {
+    entry = JSON.parse(line) as typeof entry;
+  } catch (error) {
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+  if (entry.type !== 'message' || entry.message?.role !== 'assistant' || !Array.isArray(entry.message.content)) return undefined;
+  const text = (entry.message.content as { type?: unknown; text?: unknown }[])
+    .filter((part) => part.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text as string)
+    .join('');
+  return text.trim() === '' ? undefined : truncate(text);
+}
+
+/** The text of the last assistant message in a Pi session file, scanning back from the end through at most its last 4 MiB. */
+export function lastAssistantText(transcript: string): string | undefined {
+  const { size } = statSync(transcript);
+  for (let bytes = FIRST_READ_BYTES; ; bytes *= 4) {
+    const lines = readTail(transcript, size, bytes).split('\n');
+    // The first line of a partial read is cut off.
+    if (bytes < size) lines.shift();
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      const text = assistantTextOf(lines[index]?.trim() ?? '');
+      if (text !== undefined) return text;
+    }
+    if (bytes >= size || bytes >= TAIL_LIMIT_BYTES) return undefined;
+  }
+}
+
+/** One agent's state from its record, run lock, and transcript. Reads files only; never starts anything. */
+export function agentStatus(dir: string, agentId: string): AgentStatus {
+  const record = readRecord(dir, agentId);
+  const transcript = transcriptFor(dir, agentId);
+  if (record === undefined && transcript === undefined) return { agentId, state: 'missing' };
+  const pid = runningPid(dir, agentId);
+  const updated = transcript ?? join(dir, `${agentId}.json`);
+  const lastText = transcript === undefined ? undefined : lastAssistantText(transcript);
+  return {
+    agentId,
+    state: pid === undefined ? 'idle' : 'running',
+    ...(pid === undefined ? {} : { pid }),
+    ...(record === undefined
+      ? {}
+      : {
+          type: record.type,
+          model: modelName(record.model),
+          readonly: record.readonly,
+          directory: record.worktree?.cwd ?? record.cwd,
+          createdAt: record.createdAt,
+          ...(record.worktree === undefined ? {} : { branch: record.worktree.branch }),
+          ...(record.forkedFrom === undefined ? {} : { forkedFrom: record.forkedFrom }),
+        }),
+    ...(existsSync(updated) ? { updatedAt: statSync(updated).mtime.toISOString() } : {}),
+    ...(transcript === undefined ? {} : { transcript }),
+    ...(lastText === undefined ? {} : { lastText }),
+  };
+}
+
+/** Agents with a record in `dir`, newest first, at most `limit`, and how many there are in all. */
+export function listAgentStatuses(dir: string, limit: number = LIST_LIMIT): { agents: AgentStatus[]; total: number } {
+  const records = recordIds(dir).flatMap((agentId) => {
+    try {
+      const record = readRecord(dir, agentId);
+      return record === undefined ? [] : [record];
+    } catch {
+      return [];
+    }
+  });
+  const newest = records.toSorted((left, right) => right.createdAt.localeCompare(left.createdAt)).slice(0, limit);
+  return { agents: newest.map((record) => agentStatus(dir, record.agentId)), total: records.length };
+}
+
+export function statusText(status: AgentStatus): string {
+  if (status.state === 'missing') return `Agent ${status.agentId}: missing (no record or transcript in this workspace)`;
+  const fields: [string, string | undefined][] = [
+    ['state', status.state === 'running' ? `running (pid ${status.pid})` : 'idle'],
+    ['type', status.type === undefined ? undefined : `${status.type}${status.readonly === true ? ' (readonly)' : ''}`],
+    ['model', status.model],
+    ['directory', status.directory],
+    ['branch', status.branch],
+    ['forked from', status.forkedFrom],
+    ['created', status.createdAt],
+    ['updated', status.updatedAt],
+    ['transcript', status.transcript],
+  ];
+  const lines = fields.flatMap(([name, value]) => (value === undefined ? [] : [`  ${name}: ${value}`]));
+  const last = status.lastText === undefined ? [] : ['  last response:', ...status.lastText.split('\n').map((line) => `    ${line}`)];
+  return [`Agent ${status.agentId}`, ...lines, ...last].join('\n');
+}
+
+export const AgentStatusParams = Type.Object({
+  agent_id: Type.Optional(Type.String({ description: 'Agent ID from an earlier Task call in this workspace. Omit it to list the most recent agents, newest first.' })),
+});
+
+const DESCRIPTION =
+  'Read-only status of subagents in this workspace: running or idle, type, model, directory, worktree branch, created and updated times, and the last response. This is the way to check on a worker; it never starts, messages, or resumes anything. Task resume would message a running agent or restart an idle one instead.';
+
+export function registerAgentStatus(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: 'agent_status',
+    label: 'Agent status',
+    description: DESCRIPTION,
+    promptSnippet: 'Check subagents read-only (running or idle, last response) without restarting them',
+    parameters: AgentStatusParams,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const dir = subagentDir(ctx.cwd);
+      if (params.agent_id !== undefined) {
+        const status = agentStatus(dir, validateAgentId(params.agent_id));
+        return { content: [{ type: 'text', text: statusText(status) }], details: { agents: [status], total: status.state === 'missing' ? 0 : 1 } };
+      }
+      const { agents, total } = listAgentStatuses(dir);
+      const header = total === 0 ? 'No subagents in this workspace yet.' : `${total} subagent${total === 1 ? '' : 's'} in this workspace${total > agents.length ? `; the ${agents.length} newest` : ''}:`;
+      return { content: [{ type: 'text', text: [header, ...agents.map(statusText)].join('\n\n') }], details: { agents, total } };
+    },
+  });
+}