@yanzc/claude-pro 0.0.0-stage → 0.4.1

package/src/runtime.js

@@ -0,0 +1,162 @@
+// Wires config, session mode, tools, MCP servers and the main agent together.
+
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { loadConfig, applyRememberedChoices } from './config.js';
+import { ModeManager } from './modes.js';
+import { CheckpointStore } from './checkpoints.js';
+import { loadAgents, loadSkills } from './agents.js';
+import { buildTools, toolsForSubagent } from './tools/index.js';
+import { findShell, pruneStaleShellFiles } from './utils/shell.js';
+import { mainSystemPrompt, subagentSystemPrompt } from './prompts.js';
+import { Agent } from './agent.js';
+import { isAbort } from './api.js';
+import { McpManager } from './mcp.js';
+import { HookRunner } from './hooks.js';
+import { BackgroundTasks, taskNotification } from './tasks.js';
+import { autoMemoryDir, pruneToolResults, pruneCheckpoints, projectDir } from './session.js';
+import { loadAutoMemoryIndex, takeEnvSnapshot, localDate } from './context.js';
+import { canRestart } from './restart.js';
+
+export async function createRuntime({ cwd, flags = {}, io }) {
+  const config = loadConfig({ cwd, flags });
+  applyRememberedChoices(config, flags); // what /model and /effort chose last time
+  if (flags.verify) config.verifyOverride = flags.verify;
+  pruneToolResults(cwd);
+  pruneCheckpoints(cwd);
+  pruneStaleShellFiles();
+  // Full access: nothing is ever asked. The only mode switch is the read-only plan mode (--plan).
+  const modes = new ModeManager(flags.plan ? 'plan' : 'full');
+  const checkpoints = new CheckpointStore(path.join(projectDir(cwd), 'checkpoints', `${Date.now()}-${crypto.randomBytes(3).toString('hex')}`));
+
+  const agents = loadAgents(cwd);
+  const mcp = new McpManager(config.settings.mcpServers, { cwd });
+  if (!flags.noMcp) await mcp.start((msg) => io.notice?.(msg, 'warn'));
+  const shell = findShell(config);
+
+  const hooks = new HookRunner(config);
+  const tasks = new BackgroundTasks();
+  const memoryDir = autoMemoryDir(cwd);
+  const runtime = { config, modes, checkpoints, agents, mcp, shell, io, cwd, hooks, tasks, memoryDir };
+  runtime.skills = loadSkills(cwd);
+  // The self-check builds the Restart tool too, so that a mistake in it is found before a restart relies on it.
+  const restartable = canRestart() || process.env.CLAUDE_PRO_SELF_CHECK === '1';
+  runtime.tools = buildTools(config, { agents, skills: runtime.skills, mcpTools: mcp.tools(), restart: restartable, peers: Boolean(io?.peers) || process.env.CLAUDE_PRO_SELF_CHECK === '1' });
+
+  // The system prompt is built once and kept for the conversation: a prompt that changes in the middle of it
+  // cannot be read from the prompt cache. So a change to what it is built from (memory, configuration) waits
+  // for the next place where the conversation starts over anyway, /clear or a compaction, which is how Claude
+  // Code treats edits to CLAUDE.md. The date and git state in it are a snapshot, shared with the sub-agents.
+  let promptCache = null;
+  let promptStale = false; // what the prompt is built from has changed since it was built
+  const snapshots = new Map(); // directory -> {date, git}
+  const snapshotFor = (dir) => {
+    const key = path.resolve(dir);
+    if (!snapshots.has(key)) snapshots.set(key, takeEnvSnapshot(key));
+    return snapshots.get(key);
+  };
+  runtime.systemPrompt = () => {
+    if (!promptCache) {
+      const autoMemory = config.autoMemoryEnabled ? { dir: memoryDir, index: loadAutoMemoryIndex(memoryDir) } : null;
+      promptCache = flags.systemPrompt || mainSystemPrompt({ cwd, model: config.mainModel, shellName: shell.name, extra: flags.appendSystemPrompt || '', autoMemory, selfRestart: restartable, snapshot: snapshotFor(cwd) });
+      promptStale = false;
+    }
+    return promptCache;
+  };
+  // Build the prompt again at the next request: for a new conversation (/clear), another model, a compaction.
+  runtime.invalidateSystemPrompt = () => { promptCache = null; promptStale = false; snapshots.clear(); notedDate = null; };
+  // Something it is built from changed in the middle of a conversation: note it, and leave the prompt as it is.
+  runtime.deferSystemPromptRefresh = () => { if (promptCache) promptStale = true; };
+  Object.defineProperty(runtime, 'systemPromptStale', { get: () => promptStale });
+  // A resumed conversation continues behind the system prompt it started with (as in Claude Code): its history
+  // was cached behind that one, and nothing is gained from building the prompt again. Not when the prompt was
+  // built for another model (it names the model, and each model's cache is its own anyway). The date in it is
+  // brought up to date by a note to the model, which comes after everything that is cached.
+  runtime.resumeSystemPrompt = (saved) => {
+    if (flags.systemPrompt || typeof saved !== 'string' || !saved.trim()) return false;
+    // --append-system-prompt is the last thing in the prompt: one built with other text is not what this run asked for
+    const extra = flags.appendSystemPrompt || '';
+    if (extra && !saved.endsWith(`\n\n${extra}`)) return false;
+    const modelIn = (text) => /^You are powered by the model (.+)\.$/m.exec(text)?.[1];
+    if (modelIn(saved) !== config.mainModel.id) return false;
+    promptCache = saved;
+    promptStale = false;
+    const then = /^Today's date: (\d{4}-\d{2}-\d{2})$/m.exec(saved)?.[1];
+    const today = localDate();
+    if (then && then !== today) {
+      runtime.agent.addReminder(`Today's date is ${today}. This conversation was resumed from an earlier session, so the date in the environment block of your instructions (${then}) is out of date.`);
+      notedDate = today;
+    }
+    return true;
+  };
+  // A conversation that goes on past midnight keeps the date its system prompt was built with (rebuilding the
+  // prompt would throw its cache away). The model is told the new date instead, once a day, in a note that goes
+  // with the next user message, after everything that is cached. Called before each of the main agent's turns.
+  let notedDate = null;
+  runtime.noteDateChange = (today = localDate()) => {
+    const then = promptCache && /^Today's date: (\d{4}-\d{2}-\d{2})$/m.exec(promptCache)?.[1];
+    if (!then || then === today || notedDate === today) return false;
+    notedDate = today;
+    runtime.agent.addReminder(`Today's date is ${today}. This conversation started on ${then}, so the date in the environment block of your instructions is out of date.`);
+    return true;
+  };
+
+  runtime.spawnSubagent = async ({ def, prompt, description, ctx }) => {
+    const model = def.model ? config.resolveModel(def.model) : config.subagentModel;
+    const subIo = io.subagentIo ? io.subagentIo({ def, description, parentCtx: ctx }) : {};
+    // The main agent is depth 0; an agent below the nesting limit may start sub-agents itself.
+    const depth = (ctx.depth ?? ctx.agent?.depth ?? 0) + 1;
+    const sub = new Agent({
+      config,
+      modes,
+      checkpoints,
+      depth,
+      spawnSubagent: runtime.spawnSubagent,
+      tools: toolsForSubagent(runtime.tools, def, { allowTask: depth < config.maxSubagentDepth }),
+      systemPrompt: subagentSystemPrompt({ cwd: ctx.cwd, model, shellName: shell.name, agentPrompt: def.prompt, snapshot: snapshotFor(ctx.cwd) }),
+      io: subIo,
+      model,
+      isSubagent: true,
+      cwd: ctx.cwd,
+      name: def.name,
+      hooks,
+    });
+    let result;
+    try {
+      result = await sub.run(prompt, { signal: ctx.signal });
+    } catch (err) {
+      // An API failure (rate limit, outage) must not throw away what the agent already found.
+      const partial = isAbort(err) || ctx.signal?.aborted ? '' : sub.assistantText();
+      if (partial) err.message += `\n\nThe agent failed before finishing (${sub.toolUseCount} tool uses). What it had written so far:\n${partial}`;
+      throw err;
+    } finally {
+      runtime.agent.addSubUsage(sub.usage); // whatever became of it, it was billed
+    }
+    if (result.interrupted) throw Object.assign(new Error('aborted'), { name: 'AbortError' });
+    return { text: result.text, toolUses: sub.toolUseCount, tokens: sub.usage.output + sub.lastContextTokens };
+  };
+
+  runtime.agent = new Agent({
+    config,
+    modes,
+    checkpoints,
+    tools: runtime.tools,
+    systemPrompt: runtime.systemPrompt,
+    io,
+    model: () => config.mainModel,
+    cwd,
+    spawnSubagent: runtime.spawnSubagent,
+    hooks,
+    tasks,
+    refreshSystemPrompt: () => runtime.invalidateSystemPrompt(), // a compaction starts the conversation over
+    beforeTurn: () => runtime.noteDateChange(),
+  });
+
+  // A finished background agent's report is queued for the main agent; the UI decides
+  // whether to start a new turn for it (when idle) or let the running turn pick it up.
+  tasks.onDone((task) => {
+    runtime.agent.notifications.push({ taskId: task.id, text: taskNotification(task) });
+    io.backgroundTaskDone?.(task);
+  });
+  return runtime;
+}

package/src/selfcheck.js

@@ -0,0 +1,71 @@
+// `claude-pro --self-check`: start the program the way a session does, but in a fake terminal, and see that
+// it comes up. A restart runs this first in a throwaway process, so that code which does not load or start
+// is found out while the session that can still fix it is running.
+
+import { PassThrough, Writable } from 'node:stream';
+
+const STARTUP_LIMIT_MS = 30_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function check() {
+  const problems = [];
+  const fail = (text) => problems.push(text);
+
+  let App;
+  try {
+    ({ App } = await import('./ui/repl.js'));
+    for (const file of ['./main.js', './print.js', './restart.js', './supervisor.js']) await import(file);
+  } catch (e) {
+    return [`A module does not load: ${e?.stack || e}`];
+  }
+
+  let screen = '';
+  const stdout = new Writable({ write(chunk, _enc, cb) { screen += chunk; cb(); } });
+  Object.assign(stdout, { isTTY: true, columns: 100, rows: 30, getColorDepth: () => 8 });
+  const stdin = new PassThrough();
+  Object.assign(stdin, { isTTY: true, setRawMode() {} });
+
+  const app = new App({ flags: { noMcp: true }, cwd: process.cwd(), stdin, stdout, noProcessExit: true });
+  let exited;
+  try {
+    exited = app.start('');
+    exited.catch((e) => fail(`Starting failed: ${e?.stack || e}`));
+    const began = Date.now();
+    while (!(screen.includes('Welcome to') && screen.includes('for shortcuts'))) {
+      if (problems.length) return problems;
+      if (Date.now() - began > STARTUP_LIMIT_MS) return [`The interface did not come up within ${STARTUP_LIMIT_MS / 1000} seconds.\n${screen.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '').slice(-800)}`];
+      await sleep(25);
+    }
+    if (/render error/.test(screen)) fail(`The interface failed to render: ${screen.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '').match(/render error[^\n]*/)?.[0]}`);
+
+    const names = new Set();
+    for (const tool of app.runtime.agent.toolSchemas()) {
+      if (!/^[a-zA-Z0-9_-]{1,128}$/.test(tool.name || '')) fail(`Tool name ${JSON.stringify(tool.name)} is not valid.`);
+      if (names.has(tool.name)) fail(`Tool ${tool.name} is defined twice.`);
+      names.add(tool.name);
+      if (typeof tool.description !== 'string' || !tool.description.trim()) fail(`Tool ${tool.name} has no description.`);
+      if (tool.input_schema?.type !== 'object') fail(`Tool ${tool.name} has no object input_schema.`);
+    }
+    const prompt = app.runtime.systemPrompt();
+    if (typeof prompt !== 'string' || prompt.length < 200) fail('The system prompt is empty.');
+  } catch (e) {
+    fail(`The check itself failed: ${e?.stack || e}`);
+  } finally {
+    try { app.exit(0); } catch { /* ignore */ }
+  }
+  return problems;
+}
+
+// Prints the result and ends the process (an interface that was started leaves timers and watchers around).
+export async function selfCheck() {
+  let problems;
+  try {
+    problems = await check();
+  } catch (e) {
+    problems = [`The check crashed: ${e?.stack || e}`];
+  }
+  const text = problems.length ? `Self-check failed:\n- ${problems.join('\n- ')}\n` : 'Self-check passed: every module loads and the interface starts.\n';
+  const code = problems.length ? 1 : 0;
+  process.stdout.write(text, () => process.exit(code));
+  return code;
+}

package/src/session.js

@@ -0,0 +1,139 @@
+// Transcript persistence: ~/.claude-pro/projects/<project>/<session-id>.jsonl
+// Each line is {type:'message', message} or {type:'reset', messages} (after /clear or compaction)
+// or {type:'meta', ...}.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { CONFIG_DIR } from './config.js';
+
+export function projectDir(cwd) {
+  const name = path.resolve(cwd).replace(/[^a-zA-Z0-9]/g, '-');
+  return path.join(CONFIG_DIR, 'projects', name);
+}
+
+// Where oversized tool output is saved (see persistLargeOutput in agent.js).
+export function toolResultsDir(cwd) {
+  return path.join(projectDir(cwd), 'tool-results');
+}
+
+// Delete saved tool output older than maxAgeMs (best effort, run at startup).
+export function pruneToolResults(cwd, maxAgeMs = 7 * 24 * 3600_000) {
+  const dir = toolResultsDir(cwd);
+  let entries = [];
+  try { entries = fs.readdirSync(dir); } catch { return; }
+  const cutoff = Date.now() - maxAgeMs;
+  for (const name of entries) {
+    const file = path.join(dir, name);
+    try { if (fs.statSync(file).mtimeMs < cutoff) fs.rmSync(file, { force: true }); } catch { /* ignore */ }
+  }
+}
+
+// Where /rewind keeps file snapshots: one sub-directory per run of the program.
+export function checkpointsDir(cwd) {
+  return path.join(projectDir(cwd), 'checkpoints');
+}
+
+// Delete snapshot directories of old runs (best effort, run at startup).
+export function pruneCheckpoints(cwd, maxAgeMs = 14 * 24 * 3600_000) {
+  const dir = checkpointsDir(cwd);
+  let entries = [];
+  try { entries = fs.readdirSync(dir); } catch { return; }
+  const cutoff = Date.now() - maxAgeMs;
+  for (const name of entries) {
+    const sub = path.join(dir, name);
+    try { if (fs.statSync(sub).mtimeMs < cutoff) fs.rmSync(sub, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}
+
+// Persistent, model-maintained memory for this project (MEMORY.md + topic files).
+export function autoMemoryDir(cwd) {
+  return path.join(projectDir(cwd), 'memory');
+}
+
+export class SessionStore {
+  constructor(cwd, id = crypto.randomUUID()) {
+    this.cwd = cwd;
+    this.id = id;
+    this.dir = projectDir(cwd);
+    this.file = path.join(this.dir, `${id}.jsonl`);
+    this.started = false;
+  }
+
+  append(entry) {
+    try {
+      if (!this.started) {
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.started = true;
+        if (!fs.existsSync(this.file)) fs.appendFileSync(this.file, JSON.stringify({ type: 'meta', cwd: this.cwd, created: new Date().toISOString() }) + '\n');
+      }
+      fs.appendFileSync(this.file, JSON.stringify(entry) + '\n');
+    } catch { /* persistence is best effort */ }
+  }
+
+  message(message) { this.append({ type: 'message', message, at: Date.now() }); }
+  // What the conversation is about now (the tab title); the newest one wins when the session is loaded.
+  setTopic(topic) { this.append({ type: 'meta', topic, at: Date.now() }); }
+  reset(messages) { this.append({ type: 'reset', messages, at: Date.now() }); }
+  // The system prompt this conversation runs behind, kept so that a resumed one continues behind the same prompt
+  // and so with the prompt cache it already has (see runtime.resumeSystemPrompt). Written when it first appears
+  // and whenever it changes (after a compaction); the newest one wins when the session is loaded.
+  setSystemPrompt(text) {
+    if (!text || text === this.systemPrompt) return;
+    this.systemPrompt = text;
+    this.append({ type: 'meta', systemPrompt: text, at: Date.now() });
+  }
+
+  static load(file) {
+    const messages = [];
+    const times = []; // when each message was stored (ms since epoch), parallel to `messages`; 0 = unknown
+    let meta = {};
+    let title = null;
+    let lastAt = 0; // when the conversation last changed: the latest message or reset (0: unknown)
+    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      let e;
+      try { e = JSON.parse(line); } catch { continue; }
+      if (e.type === 'message' || e.type === 'reset') lastAt = Math.max(lastAt, e.at || 0);
+      if (e.type === 'meta') meta = { ...meta, ...e };
+      else if (e.type === 'message') {
+        messages.push(e.message);
+        times.push(e.at || 0);
+        if (!title && e.message.role === 'user') title = firstUserText(e.message);
+      } else if (e.type === 'reset') {
+        // The messages of a reset (after /clear, compaction or a rewind) were not stored one by one,
+        // so their own times are unknown.
+        messages.splice(0, messages.length, ...e.messages);
+        times.splice(0, times.length, ...e.messages.map(() => 0));
+      }
+    }
+    return {
+      messages, times, lastAt, meta, title,
+      topic: typeof meta.topic === 'string' && meta.topic.trim() ? meta.topic : null,
+      systemPrompt: typeof meta.systemPrompt === 'string' && meta.systemPrompt.trim() ? meta.systemPrompt : null,
+    };
+  }
+
+  static list(cwd) {
+    const dir = projectDir(cwd);
+    let files = [];
+    try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')); } catch { return []; }
+    return files.map((f) => {
+      const file = path.join(dir, f);
+      const st = fs.statSync(file);
+      let title = null, count = 0;
+      try {
+        const loaded = SessionStore.load(file);
+        title = loaded.topic || loaded.title; // what it was about last, else its first message
+        count = loaded.messages.length;
+      } catch { /* ignore */ }
+      return { id: f.slice(0, -6), file, mtime: st.mtimeMs, title: title || '(no prompt)', count };
+    }).filter((s) => s.count > 0).sort((a, b) => b.mtime - a.mtime);
+  }
+}
+
+export function firstUserText(message) {
+  const blocks = typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : message.content;
+  const t = blocks.find((b) => b.type === 'text' && !b.text.startsWith('<system-reminder>') && !b.text.startsWith('['));
+  return t ? t.text.replace(/\s+/g, ' ').trim().slice(0, 100) : null;
+}

package/src/supervisor.js

@@ -0,0 +1,110 @@
+// A thin supervisor for interactive sessions, so that the program can restart itself and pick up changes
+// to its own source code without the user quitting and starting it again.
+//
+// bin/claude-pro.js runs an interactive session as a child process of the supervisor, on the same terminal.
+// A session that wants fresh code writes what has to survive into the file named by CLAUDE_PRO_RESTART_FILE
+// (see restart.js) and exits with RESTART_EXIT_CODE; the supervisor starts the program again, which reads
+// that file and carries on with the same conversation. Any other exit ends the session as it would have
+// without a supervisor.
+//
+// This file uses nothing but Node's built-in modules and stays loaded for the whole session, so a broken
+// source file can never take it down. (A change to this file or to bin/claude-pro.js is only picked up by
+// the next real start, because the running supervisor is the old code.)
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import tty from 'node:tty';
+
+export const RESTART_EXIT_CODE = 75; // EX_TEMPFAIL: the usual "start me again"
+export const ENV_SUPERVISED = 'CLAUDE_PRO_SUPERVISED'; // set in the child: it runs under a supervisor
+export const ENV_RESTART_FILE = 'CLAUDE_PRO_RESTART_FILE'; // where a restart request is left for the next child
+export const ENV_RESTARTED = 'CLAUDE_PRO_RESTARTED'; // set in a child that was started by a restart
+
+const NOT_INTERACTIVE = new Set(['-p', '--print', '-h', '--help', '-v', '--version', '--self-check']);
+const QUICK_CRASH_MS = 15_000;
+
+// How the session is started. VS Code (1.140 and later, terminal.integrated.tabs.allowAgentCliTitle) shows
+// the title a program sets (see Screen.setTitle) as the tab label only for the AI command lines it
+// recognises; any other program's tab just says "node". On Windows it recognises them by the command line
+// of node.exe, where a `\claude-code\` path segment means Claude Code. Starting the session through such a
+// path gets this program the same treatment. The directory does not have to exist: Node resolves `..` in
+// the path of the main script by itself, before looking at the file.
+export function sessionEntry(entry, platform = process.platform) {
+  if (platform !== 'win32') return entry;
+  const sep = path.win32.sep;
+  return `${path.win32.dirname(entry)}${sep}claude-code${sep}..${sep}${path.win32.basename(entry)}`;
+}
+
+// Whether this invocation is an interactive session that should run under the supervisor.
+export function shouldSupervise(argv, env = process.env, isTty = (fd) => tty.isatty(fd)) {
+  if (env[ENV_SUPERVISED] || /^(1|true|yes)$/i.test(env.CLAUDE_PRO_NO_SUPERVISOR || '')) return false;
+  if (!isTty(0) || !isTty(1)) return false;
+  if (argv[0] === 'config') return false;
+  return !argv.some((a) => NOT_INTERACTIVE.has(a));
+}
+
+function putTerminalRight() {
+  // The child may have died with the terminal in the mode it had set for itself.
+  try { process.stdout.write('\x1b[?2004l\x1b[?25h'); } catch { /* nothing to do */ }
+  try { if (tty.isatty(0)) process.stdin.setRawMode(false); } catch { /* nothing to do */ }
+}
+
+// Run `entry` (the program's own bin script) with `argv` until it ends without asking for a restart.
+// Resolves with the exit code to end the process with.
+export function supervise(argv, { entry, env = process.env, execPath = process.execPath, err = process.stderr } = {}) {
+  return new Promise((resolve) => {
+    const stateFile = path.join(os.tmpdir(), `claude-pro-restart-${process.pid}-${crypto.randomBytes(4).toString('hex')}.json`);
+    let child = null;
+    let stopping = false;
+    let restarted = false;
+    let finished = false;
+
+    const stop = (signal) => { stopping = true; try { child?.kill(signal); } catch { /* already gone */ } };
+    const handlers = {
+      SIGINT: () => { /* the terminal sends it to the child too, which decides what it means */ },
+      SIGTERM: () => stop('SIGTERM'),
+      SIGHUP: () => stop('SIGHUP'),
+    };
+    for (const [signal, fn] of Object.entries(handlers)) { try { process.on(signal, fn); } catch { /* not on this platform */ } }
+
+    const finish = (code, { abnormal = false } = {}) => {
+      if (finished) return;
+      finished = true;
+      for (const [signal, fn] of Object.entries(handlers)) { try { process.off(signal, fn); } catch { /* ignore */ } }
+      try { fs.rmSync(stateFile, { force: true }); } catch { /* ignore */ }
+      if (abnormal) putTerminalRight();
+      resolve(code);
+    };
+
+    const start = () => {
+      const childEnv = { ...env, [ENV_SUPERVISED]: '1', [ENV_RESTART_FILE]: stateFile };
+      if (restarted) childEnv[ENV_RESTARTED] = '1'; else delete childEnv[ENV_RESTARTED];
+      const startedAt = Date.now();
+      child = spawn(execPath, [sessionEntry(entry), ...argv], { stdio: 'inherit', env: childEnv });
+      child.on('error', (e) => {
+        child = null;
+        err.write(`claude-pro: could not start (${e.message})\n`);
+        finish(1, { abnormal: true });
+      });
+      child.on('exit', (code, signal) => {
+        child = null;
+        if (finished) return;
+        if (code === RESTART_EXIT_CODE && !stopping) {
+          restarted = true;
+          start();
+          return;
+        }
+        const exitCode = code ?? (signal ? 128 + (os.constants.signals[signal] || 0) : 1);
+        const quick = restarted && exitCode !== 0 && Date.now() - startedAt < QUICK_CRASH_MS;
+        if (quick) {
+          err.write(`\nclaude-pro stopped (exit code ${exitCode}) right after restarting. The code that was just loaded may be broken: fix it and start claude-pro again. The conversation is saved; \`claude-pro --continue\` resumes it.\n`);
+        }
+        finish(exitCode, { abnormal: exitCode !== 0 });
+      });
+    };
+    start();
+  });
+}

package/src/tasks.js

@@ -0,0 +1,76 @@
+// Background tasks: sub-agents started with `run_in_background`. Each runs with its own
+// abort signal (so finishing or interrupting the current turn does not stop it); when it
+// ends, listeners are told so the main agent can be notified.
+
+const MAX_RESULT_CHARS = 30_000;
+
+export class BackgroundTasks {
+  constructor() {
+    this.tasks = new Map();
+    this.counter = 0;
+    this.listeners = new Set();
+  }
+
+  onDone(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
+
+  // run(signal) -> Promise<{text, toolUses, tokens}>
+  start({ description, subagentType, run }) {
+    const id = `agent_${++this.counter}`;
+    const ctrl = new AbortController();
+    const task = { id, description, subagentType, status: 'running', started: Date.now(), ended: null, result: null, error: null, ctrl };
+    task.promise = Promise.resolve()
+      .then(() => run(ctrl.signal))
+      .then((result) => { task.status = 'completed'; task.result = result; })
+      .catch((err) => {
+        task.status = ctrl.signal.aborted ? 'killed' : 'failed';
+        task.error = ctrl.signal.aborted ? 'Stopped' : (err?.message || String(err));
+      })
+      .then(() => {
+        task.ended = Date.now();
+        for (const fn of this.listeners) { try { fn(task); } catch { /* listener errors must not break others */ } }
+        return task;
+      });
+    this.tasks.set(id, task);
+    return task;
+  }
+
+  get(id) { return this.tasks.get(id); }
+  list() { return [...this.tasks.values()]; }
+  running() { return this.list().filter((t) => t.status === 'running'); }
+
+  kill(id) {
+    const t = this.tasks.get(id);
+    if (!t || t.status !== 'running') return false;
+    t.ctrl.abort();
+    return true;
+  }
+
+  killAll() { for (const t of this.running()) t.ctrl.abort(); }
+
+  // Resolves with the next task to finish (or null if none is running).
+  waitAny() {
+    const running = this.running();
+    return running.length ? Promise.race(running.map((t) => t.promise)) : Promise.resolve(null);
+  }
+}
+
+export function taskResultText(task) {
+  if (task.status === 'completed') {
+    const text = task.result?.text || '(the agent returned no text)';
+    return text.length > MAX_RESULT_CHARS ? `${text.slice(0, MAX_RESULT_CHARS)}\n[result truncated]` : text;
+  }
+  return task.error || task.status;
+}
+
+// The message the main agent sees when a background task ends.
+export function taskNotification(task) {
+  const secs = Math.round(((task.ended || Date.now()) - task.started) / 1000);
+  return `<task-notification>
+<task-id>${task.id}</task-id>
+<status>${task.status}</status>
+<summary>Background agent "${task.description}" ${task.status} after ${secs}s</summary>
+<result>
+${taskResultText(task)}
+</result>
+</task-notification>`;
+}