@resolveworks/fork 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Johan Schuijt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# fork
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Spawn [pi](https://github.com/earendil-works/pi) subagents in tmux windows. Each child is a separate pi process you can watch and type into; it reports back over a Unix socket and stays alive for revision requests. Assumes fluency with pi, tmux, and git worktrees, and stays out of the way — including silently doing nothing outside tmux.
+
+## Requirements
+
+- pi 0.80.4 or newer (newest pi API used: `agent_settled`)
+- tmux, with pi running inside it
+- git, for `branch` worktree isolation
+- Linux; macOS untested (nothing Linux-specific), Windows unsupported
+
+## Install
+
+```bash
+pi install npm:@resolveworks/fork
+```
+
+Or from git:
+
+```bash
+pi install git:github.com/resolveworks/fork
+```
+
+Or once, without installing:
+
+```bash
+pi -e npm:@resolveworks/fork
+```
+
+Then restart pi, or `/reload`.
+
+## What you get
+
+The parent session gains three tools:
+
+- `spawn_agent({ task, branch? })` — writes the task to a file and opens a new tmux window running `pi @<taskfile>`. Returns immediately. The child sees the task plus normal project context, not the parent's conversation, so the task must be self-contained.
+- `message_agent({ id, text })` — steers a revision request into the child's current run, or starts a new turn when the child is idle.
+- `close_agent({ id })` — mechanical shutdown; no model turn spent.
+
+The child gains `report_result({ result })`. The report travels over a Unix socket and arrives in the parent as a steering notification: immediately if the parent is idle, or injected into the parent's current run after its pending tool calls. The child stays alive after reporting, awaiting the verdict: revisions via `message_agent`, or closure. Reports are outcomes, not progress updates. If delivery fails, the child is told unambiguously and retries with the same payload — a retry cannot double-deliver. Interrupting the parent would drop its queued notifications, so fork re-delivers them once the interrupted run settles — an escape can no longer lose a report.
+
+Don't poll. Navigate windows with your usual tmux keys.
+
+## Isolation
+
+Without `branch`, the child shares the parent's working tree — fine for read-only or sequential work, a bad idea for concurrent editors.
+
+With `branch: "kebab-name"`, fork runs `git worktree add ~/.pi/worktrees/<uuid> -b agent/<kebab-name> HEAD` and spawns the child there. The child commits its work; `close_agent` force-removes the worktree (uncommitted work dies with it) and retains the branch for normal review and merge.
+
+Fork deliberately does no environment setup and runs no checks. `git worktree add` fires the repo's `post-checkout` hook — put pnpm/uv/whatever setup there. Commit hooks validate.
+
+## Config
+
+`~/.pi/agent/fork.json`, overridden per-project by `.pi/fork.json` (read only in trusted projects). All fields optional; passed through to the child as CLI flags:
+
+```json
+{ "model": "glm-5.2", "provider": "zai", "thinking": "high" }
+```
+
+## Runtime state
+
+Under `~/.pi/agent/extensions/fork/` (sockets and task files are mode `0o600`):
+
+- `sockets/<parent-session-id>.sock` — result channel, child → parent
+- `agents/<uuid>.sock` — verdict channel, parent → child
+- `tasks/<uuid>.md` — the task handed to the child; a present task file marks an open agent and is authoritative across extension reloads
+
+## Development
+
+Requires Node.js 22.18 or newer and pnpm 11.3.0.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm format:check
+```
+
+Use `pnpm format` to apply formatting.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,899 @@
+/**
+ * fork — Spawn pi subagents in separate tmux windows.
+ *
+ * The parent registers `spawn_agent`, `message_agent`, and `close_agent`
+ * tools. Calling spawn_agent opens a new tmux window running pi with the
+ * given task and returns immediately. The child reports results through `report_result`;
+ * each report is delivered over a Unix socket as a notification that reaches
+ * the parent promptly: if the parent is idle the report starts a turn at
+ * once; if it is mid-run the report is steered into that run — delivered
+ * after its current tool calls, before the next LLM call. An interrupt
+ * clears the steering queue without delivering queued custom messages, so
+ * reports are tracked until delivery is confirmed and re-delivered when an
+ * interrupted run settles. The child stays alive after
+ * reporting: the parent reviews the report, sends revision requests with
+ * message_agent, and closes the child with close_agent.
+ *
+ * Configure the subagent model via ~/.pi/agent/fork.json (global) or
+ * .pi/fork.json (project, overrides global). Any field is optional:
+ *   { "model": "glm-5.2", "provider": "zai", "thinking": "high" }
+ * Fork passes these settings to the child pi process as CLI flags, so pi
+ * resolves them using its normal startup rules.
+ *
+ * Requires: run pi inside tmux.
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+  CONFIG_DIR_NAME,
+  type ExtensionAPI,
+  getAgentDir,
+  getMarkdownTheme,
+  keyHint,
+  type MessageRenderer,
+} from "@earendil-works/pi-coding-agent";
+import { Box, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+// ── tmux ────────────────────────────────────────────────────────────
+
+function inTmux(): boolean {
+  return !!process.env.TMUX;
+}
+
+/** Run tmux synchronously with argv passed directly (no shell), so paths and
+ * arguments with spaces/metacharacters are never shell-interpreted. */
+function tmuxSync(args: string[], timeout = 3000): string {
+  const result = spawnSync("tmux", args, { encoding: "utf-8", timeout });
+  if (result.error) throw result.error;
+  if (result.status !== 0 || result.signal) {
+    const detail = [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join(" / ");
+    const where =
+      result.signal !== null ? `signal ${result.signal}` : `exit ${result.status ?? "?"}`;
+    throw new Error(`fork: tmux ${args[0]} failed (${where})${detail ? `: ${detail}` : ""}`);
+  }
+  return result.stdout;
+}
+
+function tmuxSession(): string {
+  return tmuxSync(["display-message", "-p", "#S"]).trim();
+}
+
+// ── paths ───────────────────────────────────────────────────────────
+
+const PI_DIR = path.join(os.homedir(), ".pi");
+const ROOT = path.join(PI_DIR, "agent", "extensions", "fork");
+const SOCKETS_DIR = path.join(ROOT, "sockets");
+const AGENTS_DIR = path.join(ROOT, "agents");
+const TASKS_DIR = path.join(ROOT, "tasks");
+const WORKTREES_DIR = path.join(PI_DIR, "worktrees");
+const BRANCH_PREFIX = "agent/";
+const BRANCH_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const RESULT_TYPE = "fork-result";
+const MESSAGE_TYPE = "fork-message";
+
+/** Number of markdown lines shown when the message row is collapsed (ctrl+o to expand). */
+const PREVIEW_LINES = 10;
+
+/** Render fork messages like pi's default custom-message rendering, plus a
+ * collapsed preview with an expand hint for long subagent reports. */
+const renderForkMessage: MessageRenderer = (message, options, theme) => {
+  const text =
+    typeof message.content === "string"
+      ? message.content
+      : message.content
+          .filter((item) => item.type === "text")
+          .map((item) => item.text ?? "")
+          .join("\n");
+
+  let body = text;
+  let hint = "";
+  if (!options.expanded) {
+    const lines = text.split("\n");
+    if (lines.length > PREVIEW_LINES) {
+      const remaining = lines.length - PREVIEW_LINES;
+      hint =
+        theme.fg("muted", `... (${remaining} more lines,`) +
+        " " +
+        keyHint("app.tools.expand", "to expand") +
+        theme.fg("muted", ")");
+      body = lines.slice(0, PREVIEW_LINES).join("\n");
+    }
+  }
+
+  const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
+  box.addChild(
+    new Text(theme.fg("customMessageLabel", theme.bold(`[${message.customType}]`)), 0, 0),
+  );
+  box.addChild(new Spacer(1));
+  box.addChild(
+    new Markdown(body, 0, 0, getMarkdownTheme(), {
+      color: (t) => theme.fg("customMessageText", t),
+    }),
+  );
+  if (hint) {
+    box.addChild(new Spacer(1));
+    box.addChild(new Text(hint, 0, 0));
+  }
+  return box;
+};
+
+function socketPathFor(sessionId: string): string {
+  return path.join(SOCKETS_DIR, `${sessionId}.sock`);
+}
+
+function agentSocketPathFor(id: string): string {
+  return path.join(AGENTS_DIR, `${id}.sock`);
+}
+
+function taskPathFor(id: string): string {
+  return path.join(TASKS_DIR, `${id}.md`);
+}
+
+function worktreePathFor(id: string): string {
+  return path.join(WORKTREES_DIR, id);
+}
+
+/** Exact lowercase format emitted by randomUUID(); also blocks path traversal. */
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+// ── wire protocol (newline-delimited JSON) ──────────────────────────
+
+/** Child → parent, over the parent's session socket. */
+interface ResultPayload {
+  id: string;
+  summary: string;
+}
+
+/** Parent → child, over the child's agent socket. */
+type AgentMessage = { type: "message"; text: string };
+
+// ── config (~/.pi/agent/fork.json, .pi/fork.json) ───────────────────
+
+interface ForkConfig {
+  /** Model id or pattern (supports `provider/id` and `:thinking`). */
+  model?: string;
+  provider?: string;
+  /** Thinking level passed to the child via `--thinking`. */
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+}
+
+function readConfig(file: string): ForkConfig {
+  try {
+    if (!fs.existsSync(file)) return {};
+    return JSON.parse(fs.readFileSync(file, "utf-8")) as ForkConfig;
+  } catch (err) {
+    console.error(`fork: failed to load ${file}: ${err}`);
+    return {};
+  }
+}
+
+/** Merge global + project config. Project wins; only read if trusted. */
+function loadConfig(cwd: string, projectTrusted: boolean): ForkConfig {
+  const globalCfg = readConfig(path.join(getAgentDir(), "fork.json"));
+  const projectCfg = projectTrusted ? readConfig(path.join(cwd, CONFIG_DIR_NAME, "fork.json")) : {};
+  return { ...globalCfg, ...projectCfg };
+}
+
+// ── git worktrees ───────────────────────────────────────────────────
+
+interface WorktreeInfo {
+  path: string;
+  branch: string;
+  repoCwd: string;
+}
+
+/** Run git without a shell. The generous timeout allows repository-owned
+ * post-checkout hooks to perform normal worktree setup. */
+async function git(
+  pi: ExtensionAPI,
+  args: string[],
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const result = await pi.exec("git", args, {
+    cwd,
+    signal,
+    timeout: 10 * 60 * 1000,
+  });
+  if (result.code !== 0 || result.killed) {
+    const detail = [result.stderr.trim(), result.stdout.trim()]
+      .filter(Boolean)
+      .join(" / ")
+      .slice(-4000);
+    const where = result.killed ? "killed" : `exit ${result.code}`;
+    throw new Error(`fork: git ${args[0]} failed (${where})${detail ? `: ${detail}` : ""}`);
+  }
+  return result.stdout;
+}
+
+/** Remove a worktree created by a failed spawn, then delete its new branch.
+ * Cleanup is best-effort so the original spawn error remains authoritative. */
+async function rollbackWorktree(pi: ExtensionAPI, info: WorktreeInfo): Promise<void> {
+  try {
+    await git(pi, ["worktree", "remove", "--force", info.path], info.repoCwd);
+  } catch (err) {
+    console.error(`fork: could not roll back worktree ${info.path}: ${err}`);
+    return;
+  }
+
+  try {
+    await git(pi, ["branch", "-D", info.branch], info.repoCwd);
+  } catch (err) {
+    console.error(`fork: could not roll back branch ${info.branch}: ${err}`);
+  }
+}
+
+async function createWorktree(
+  pi: ExtensionAPI,
+  cwd: string,
+  id: string,
+  branchName: string,
+  signal?: AbortSignal,
+): Promise<WorktreeInfo> {
+  if (!BRANCH_NAME.test(branchName)) {
+    throw new Error("fork: branch names must use lowercase letters, numbers, and single dashes");
+  }
+  const branch = `${BRANCH_PREFIX}${branchName}`;
+
+  // An explicit branch outside Git fails rather than degrading to shared mode.
+  await git(pi, ["rev-parse", "--show-toplevel"], cwd, signal);
+  fs.mkdirSync(WORKTREES_DIR, { recursive: true });
+  const info = { path: worktreePathFor(id), branch, repoCwd: cwd };
+  try {
+    await git(pi, ["worktree", "add", "--quiet", "-b", branch, info.path, "HEAD"], cwd, signal);
+  } catch (err) {
+    // post-checkout can fail after creating both artifacts. Git rejects an
+    // existing branch before creating our path, so .git proves these are ours.
+    if (fs.existsSync(path.join(info.path, ".git"))) {
+      await rollbackWorktree(pi, info);
+    }
+    throw err;
+  }
+  return info;
+}
+
+// ── spawn (fire-and-forget) ─────────────────────────────────────────
+
+function spawn(
+  session: string,
+  sessionId: string,
+  id: string,
+  taskPath: string,
+  cwd: string,
+  config: ForkConfig,
+  branch?: string,
+): void {
+  // argv passed directly; tmux runs a multi-arg command without `sh -c`, so
+  // no shell quoting is needed. Let pi resolve model settings itself.
+  const cmdArgs = ["pi", "--subagent-socket", socketPathFor(sessionId), "--subagent-id", id];
+  if (config.provider) cmdArgs.push("--provider", config.provider);
+  if (config.model) cmdArgs.push("--model", config.model);
+  if (config.thinking) cmdArgs.push("--thinking", config.thinking);
+  if (branch) cmdArgs.push("--subagent-branch", branch);
+  cmdArgs.push(`@${taskPath}`);
+
+  tmuxSync(["new-window", "-d", "-t", `${session}:`, "-n", id, "-c", cwd, ...cmdArgs]);
+}
+
+// ── line servers and socket writes ──────────────────────────────────
+
+/** Remove a file, tolerating an already-missing path. Never throws —
+ * callers (spawn rollback, socket teardown) must keep working. */
+function safeUnlink(filePath: string, what: string): void {
+  try {
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+    console.error(`fork: could not remove ${what} ${filePath}: ${err}`);
+  }
+}
+
+/**
+ * Listen on sockPath and invoke onLine per newline-delimited payload. A
+ * stale socket file from a previous run is removed first. Server errors
+ * (e.g. unable to bind) are logged, not thrown: the session keeps running
+ * and the peer reports connection failures on its side. Mode 0o600 is
+ * enforced once listening starts.
+ */
+function serveLines(sockPath: string, what: string, onLine: (line: string) => void): net.Server {
+  safeUnlink(sockPath, `stale ${what}`);
+  const server = net.createServer((socket) => {
+    let buf = "";
+    socket.setEncoding("utf-8");
+    socket.on("error", (err) => {
+      console.error(`fork: ${what} connection error: ${err}`);
+    });
+    socket.on("data", (chunk: string) => {
+      buf += chunk;
+      for (let nl = buf.indexOf("\n"); nl >= 0; nl = buf.indexOf("\n")) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (line.length === 0) continue;
+        onLine(line);
+      }
+    });
+  });
+  server.on("error", (err) => {
+    console.error(`fork: ${what} error: ${err}`);
+  });
+  server.listen(sockPath, () => {
+    try {
+      fs.chmodSync(sockPath, 0o600);
+    } catch (err) {
+      console.error(`fork: could not chmod ${what} ${sockPath}: ${err}`);
+    }
+  });
+  return server;
+}
+
+function teardownServer(server: net.Server, sockPath: string, what: string) {
+  // close() with a callback absorbs ERR_SERVER_NOT_RUNNING instead of
+  // emitting an unhandled 'error'.
+  server.close((err) => {
+    if (err && (err as NodeJS.ErrnoException).code !== "ERR_SERVER_NOT_RUNNING") {
+      console.error(`fork: error closing ${what}: ${err}`);
+    }
+  });
+  safeUnlink(sockPath, what);
+}
+
+/** Deliver one message to a live agent. Throws when the agent is unreachable
+ * or the write does not flush; callers report failure and keep their state. */
+function sendToAgent(id: string, message: AgentMessage): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const socket = net.connect(agentSocketPathFor(id));
+    const finish = (err?: Error) => {
+      if (settled) return;
+      settled = true;
+      if (err) {
+        socket.destroy();
+        reject(err);
+      } else {
+        resolve();
+      }
+    };
+    socket.setTimeout(5000);
+    socket.once("error", (err) => finish(err));
+    socket.once("timeout", () => finish(new Error("timed out after 5 seconds")));
+    socket.end(`${JSON.stringify(message)}\n`, () => finish());
+  });
+}
+
+// ── result delivery ─────────────────────────────────────────────────
+
+/** Deliver one report as a fork-result message, tracked in `undelivered`.
+ *
+ * A report is steered into the parent's current run: it is delivered after
+ * the current tool calls, before the next LLM call, so the parent can fold
+ * it into the work at hand rather than waiting for the run to finish (the
+ * follow-up idiom pi's examples use fits events that must run as fresh
+ * turns; a report is news the parent can use now). A report that arrives
+ * while the parent is idle starts a turn at once. The steering queue is
+ * cleared without delivering when the parent is interrupted (escape) — pi
+ * only restores typed text to the editor — so every report is tracked until
+ * its message_end confirms delivery; agent_settled re-delivers the rest
+ * (see setupParent). The nonce rides in `details`, which never reaches the
+ * LLM. */
+function deliverResult(
+  pi: ExtensionAPI,
+  payload: ResultPayload,
+  undelivered: Map<string, ResultPayload>,
+): void {
+  const summary = payload.summary.trim() || "(no output)";
+  const nonce = randomUUID();
+  undelivered.set(nonce, payload);
+  pi.sendMessage(
+    {
+      customType: RESULT_TYPE,
+      content: `Subagent ${payload.id} reported:\n\n${summary}`,
+      display: true,
+      details: { nonce },
+    },
+    { triggerTurn: true, deliverAs: "steer" },
+  );
+}
+
+/**
+ * Parse and act on one newline-delimited result line. Malformed JSON or shape
+ * is logged and ignored without aborting the handler or dropping later lines.
+ * A result is delivered only while its agent is still open (task file present).
+ */
+function processResultLine(line: string, deliver: (payload: ResultPayload) => void): void {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch (err) {
+    console.error(`fork: ignoring malformed result line (invalid JSON): ${err}`);
+    return;
+  }
+
+  const candidate = parsed as Partial<ResultPayload>;
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    typeof candidate.id !== "string" ||
+    candidate.id.length === 0 ||
+    typeof candidate.summary !== "string"
+  ) {
+    console.error(`fork: ignoring malformed result payload: ${line}`);
+    return;
+  }
+
+  const { id, summary } = candidate as ResultPayload;
+  if (!UUID_V4.test(id)) {
+    console.error(`fork: ignoring result with invalid subagent id (not a UUID v4): ${id}`);
+    return;
+  }
+
+  if (!fs.existsSync(taskPathFor(id))) {
+    console.error(`fork: ignoring result for unknown or closed id ${id}`);
+    return;
+  }
+
+  deliver({ id, summary });
+}
+
+// ── parent setup ────────────────────────────────────────────────────
+
+/** Validate an agent id and that the agent is still open (task file present). */
+function assertOpenAgent(id: string): void {
+  if (!UUID_V4.test(id)) {
+    throw new Error(`Invalid subagent id (not a UUID v4): ${id}`);
+  }
+  if (!fs.existsSync(taskPathFor(id))) {
+    throw new Error(`Unknown or already closed subagent ${id}`);
+  }
+}
+
+function setupParent(
+  pi: ExtensionAPI,
+  ctx: { sessionManager: { getSessionId: () => string } },
+): void {
+  fs.mkdirSync(SOCKETS_DIR, { recursive: true });
+  fs.mkdirSync(TASKS_DIR, { recursive: true });
+
+  const session = tmuxSession();
+  const sessionId = ctx.sessionManager.getSessionId();
+  const sockPath = socketPathFor(sessionId);
+
+  // Reports are tracked from sendMessage until their message_end confirms
+  // they reached the transcript. pi drains its queues before a session
+  // settles, so anything still tracked on agent_settled was dropped by an
+  // interrupt. Re-delivering is safe then: the session is idle, so each
+  // report triggers a fresh turn exactly as it would have without the
+  // interrupt.
+  const undelivered = new Map<string, ResultPayload>();
+  const deliver = (payload: ResultPayload) => deliverResult(pi, payload, undelivered);
+
+  // Task files are authoritative, so running children survive extension reloads.
+  const server = serveLines(sockPath, "result socket", (line) => processResultLine(line, deliver));
+
+  pi.on("message_end", (event) => {
+    const message = event.message;
+    if (message.role !== "custom" || message.customType !== RESULT_TYPE) return;
+    const nonce = (message.details as { nonce?: string } | undefined)?.nonce;
+    if (nonce !== undefined) undelivered.delete(nonce);
+  });
+
+  pi.on("agent_settled", () => {
+    const dropped = [...undelivered.values()];
+    undelivered.clear();
+    for (const payload of dropped) {
+      console.error(`fork: re-delivering report of subagent ${payload.id} dropped by an interrupt`);
+      deliver(payload);
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    teardownServer(server, sockPath, "result socket");
+  });
+
+  pi.registerMessageRenderer(RESULT_TYPE, renderForkMessage);
+
+  pi.registerTool({
+    name: "spawn_agent",
+    label: "Spawn Agent",
+    description:
+      "Delegate a self-contained task to a subagent: a fresh pi session in a " +
+      "new tmux window. By default it shares your working tree; provide branch " +
+      "to create an isolated Git worktree on a new agent/<name> branch. Use " +
+      "for independent work that benefits from isolated context; do simple, " +
+      "sequential, or context-dependent work yourself. The subagent sees the " +
+      "task plus normal project context (AGENTS.md, files), but not this " +
+      "conversation, so include needed context in the task. Avoid concurrent " +
+      "editing agents in shared mode. Returns immediately with a spawn " +
+      "confirmation. The report arrives later as a message in this " +
+      "session — steered into current work or a new turn when idle; do not " +
+      "poll or sleep. Continue other work or end your turn. Then " +
+      "request revisions with message_agent or close it with close_agent.",
+    parameters: Type.Object({
+      task: Type.String({
+        description:
+          "Self-contained instructions passed verbatim as the subagent's initial " +
+          "prompt. Include the goal, needed conversation-specific context, " +
+          "constraints, relevant paths or symbols, prior findings or errors, and " +
+          "the expected output. Do not reference context it cannot see or repeat " +
+          "project instructions from AGENTS.md.",
+      }),
+      branch: Type.Optional(
+        Type.String({
+          pattern: BRANCH_NAME.source,
+          description:
+            "Lowercase kebab-case name for a new isolated-worktree branch, " +
+            "without the agent/ prefix (for example, issue-4-worktree-isolation). " +
+            "Fork creates the exact branch agent/<name> from HEAD; it must not " +
+            "already exist. Omit to share the current working tree.",
+        }),
+      ),
+    }),
+    execute: async (_id, params, signal, _onUpdate, toolCtx) => {
+      const { task, branch } = params as { task: string; branch?: string };
+      const id = randomUUID();
+      const taskPath = taskPathFor(id);
+      fs.writeFileSync(taskPath, task, { mode: 0o600 });
+
+      let worktree: WorktreeInfo | undefined;
+      try {
+        const config = loadConfig(toolCtx.cwd, toolCtx.isProjectTrusted());
+        if (branch !== undefined) {
+          worktree = await createWorktree(pi, toolCtx.cwd, id, branch, signal);
+        }
+        spawn(
+          session,
+          sessionId,
+          id,
+          taskPath,
+          worktree?.path ?? toolCtx.cwd,
+          config,
+          worktree?.branch,
+        );
+      } catch (err) {
+        if (worktree) await rollbackWorktree(pi, worktree);
+        // Roll back exactly this id's task file so pi reports the spawn error.
+        safeUnlink(taskPath, `task file for ${id}`);
+        throw err;
+      }
+
+      const location = worktree ? `${worktree.path} on branch ${worktree.branch}` : toolCtx.cwd;
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              `Spawned subagent ${id} in ${location}. ` +
+              "Do not poll or sleep; continue other work or end your turn. Its " +
+              "report will arrive as a message in this session, after which it " +
+              "stays alive awaiting your verdict.",
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "message_agent",
+    label: "Message Agent",
+    description:
+      "Send a revision request or follow-up instruction to a live subagent. " +
+      "It receives your text as a new turn, acts on it, and reports again. " +
+      "Use after reviewing its report when changes are needed; use " +
+      "close_agent when the work is accepted. The next report arrives as a " +
+      "message in this session; do not poll or sleep.",
+    parameters: Type.Object({
+      id: Type.String({
+        description: "The subagent's UUID, from its spawn result or report.",
+      }),
+      text: Type.String({
+        description:
+          "The feedback or instruction for the subagent. It sees this text " +
+          "plus its own session context, not your conversation — reference " +
+          "its work, not things you only said locally.",
+      }),
+    }),
+    execute: async (_toolId, params) => {
+      const { id, text } = params as { id: string; text: string };
+      assertOpenAgent(id);
+      try {
+        await sendToAgent(id, { type: "message", text });
+      } catch (err) {
+        throw new Error(
+          `Could not reach subagent ${id}: ${err}. It may still be starting ` +
+            "(retry shortly) or may have exited; if it stays unreachable, " +
+            "clean up its tmux window and task file manually.",
+        );
+      }
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              `Message delivered to subagent ${id}. Do not poll or sleep; its ` +
+              "report will arrive as a message in this session.",
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "close_agent",
+    label: "Close Agent",
+    description:
+      "Shut down a live subagent's session without spending a model turn. " +
+      "Use to accept its report or to stop one you no longer need. For an " +
+      "isolated agent, this removes its worktree but retains its agent/<name> " +
+      "branch for normal review, merge, or deletion. Subagents stay alive " +
+      "until closed; close every subagent when you are done with it.",
+    parameters: Type.Object({
+      id: Type.String({
+        description: "The subagent's UUID, from its spawn result or report.",
+      }),
+    }),
+    execute: async (_toolId, params) => {
+      const { id } = params as { id: string };
+      assertOpenAgent(id);
+      const worktreePath = worktreePathFor(id);
+      const hasWorktree = fs.existsSync(path.join(worktreePath, ".git"));
+
+      // Kill the window first: SIGHUP reaches the whole process group, so
+      // in-flight tool subprocesses die with the session, and pi's signal
+      // path runs session_shutdown teardown without waiting for a busy
+      // session to settle. A failure means the window is already gone;
+      // cleanup proceeds either way.
+      try {
+        tmuxSync(["kill-window", "-t", `${session}:=${id}`]);
+      } catch {
+        // Window already closed, renamed, or session gone — nothing to kill.
+      }
+
+      let cleanupWarning = "";
+      if (hasWorktree) {
+        try {
+          await git(pi, ["worktree", "remove", "--force", worktreePath], worktreePath);
+        } catch (err) {
+          cleanupWarning = ` Worktree cleanup failed: ${err}. Remove ${worktreePath} manually.`;
+          console.error(`fork:${cleanupWarning}`);
+        }
+      }
+
+      safeUnlink(taskPathFor(id), `task file for ${id}`);
+      const retained = hasWorktree ? " Its branch was retained." : "";
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Closed subagent ${id}; killed its tmux window.${retained}${cleanupWarning}`,
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+}
+
+// ── child setup ─────────────────────────────────────────────────────
+
+function subagentSystemPrompt(branch?: string): string {
+  const workspace = branch
+    ? `You work in an isolated Git worktree on branch ${branch}. Commit all ` +
+      "work before reporting so the parent can review and merge the branch; " +
+      "repository commit hooks provide its validation."
+    : "You share the parent's working tree, so your edits are immediately " +
+      "visible to the parent.";
+
+  return (
+    "# Role\n\n" +
+    "You are a subagent executing one task delegated by a parent pi session. " +
+    "You see the task and pi's normal project context, but not the parent's " +
+    "conversation. Focus only on the delegated task. " +
+    workspace +
+    "\n\n" +
+    "# Reporting to the parent\n\n" +
+    "report_result is the only channel that reaches the parent. It cannot " +
+    "see your text replies, your tool output, or anything else in this " +
+    "session — so a turn that ends in plain text leaves the parent waiting " +
+    "forever, with no way to know you responded.\n\n" +
+    "- Call report_result when the task is done, when you have acted on a " +
+    "revision request from the parent, and when you are blocked and need " +
+    "the parent's input.\n" +
+    "- Every message from the parent calls for a report_result response, " +
+    "even if the report is only a brief status update.\n" +
+    "- After reporting, end your turn and wait. The session stays alive: " +
+    "the parent reviews each report and either sends you a revision request " +
+    "as an ordinary message or closes the session."
+  );
+}
+
+/**
+ * Parse and act on one newline-delimited parent message. Malformed JSON or
+ * shape is logged and ignored without aborting the handler or dropping later
+ * lines.
+ */
+function processAgentLine(pi: ExtensionAPI, line: string): void {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch (err) {
+    console.error(`fork: ignoring malformed agent line (invalid JSON): ${err}`);
+    return;
+  }
+
+  if (typeof parsed !== "object" || parsed === null) {
+    console.error(`fork: ignoring malformed agent message: ${line}`);
+    return;
+  }
+  const candidate = parsed as { type?: unknown; text?: unknown };
+
+  if (candidate.type === "message" && typeof candidate.text === "string") {
+    // steer: a revision request is news the child can fold into its current
+    // run; it is delivered after the child's pending tool calls, before its
+    // next LLM call.
+    // The tags and the trailing instruction matter: without an explicit cue
+    // to report back, a child may answer in plain text and end its turn,
+    // which never reaches the parent.
+    pi.sendMessage(
+      {
+        customType: MESSAGE_TYPE,
+        content:
+          `<message-from-parent>\n${candidate.text}\n</message-from-parent>\n\n` +
+          "Act on this message, then report the outcome with report_result. " +
+          "The parent receives only report_result output — it cannot see " +
+          "your text replies.",
+        display: true,
+      },
+      { triggerTurn: true, deliverAs: "steer" },
+    );
+    return;
+  }
+
+  console.error(`fork: ignoring malformed agent message: ${line}`);
+}
+
+function setupChild(
+  pi: ExtensionAPI,
+  socketPath: string,
+  subagentId: string,
+  branch?: string,
+): void {
+  pi.on("before_agent_start", (event) => {
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${subagentSystemPrompt(branch)}`,
+    };
+  });
+
+  // ── result reporting (child → parent) ──────────────────────────────
+  //
+  // Delivery failures are reported to the model, which retries with the same
+  // result. Failures are unambiguous in practice: they mean the parent is
+  // gone or the write failed, so a retry cannot deliver a report twice.
+  let reportState: "open" | "sending" = "open";
+
+  pi.registerTool({
+    name: "report_result",
+    label: "Report Result",
+    description:
+      "Send a result report to the parent — the only channel that reaches " +
+      "it. The parent cannot see your text replies. Use when the task is " +
+      "done, when reporting a requested revision, or when you are " +
+      "blocked and need the parent's input. Report outcomes, not " +
+      "progress updates.",
+    parameters: Type.Object({
+      result: Type.String({
+        description:
+          "The complete result for the parent. Include the outcome and, when " +
+          "relevant, edits, verification, and blockers.",
+      }),
+    }),
+    execute: async (_id, params, _signal, _onUpdate, toolCtx) => {
+      if (reportState !== "open") {
+        throw new Error("report_result is already delivering a report");
+      }
+      reportState = "sending";
+
+      const { result } = params as { result: string };
+      const payload = `${JSON.stringify({ id: subagentId, summary: result })}\n`;
+
+      try {
+        await new Promise<void>((resolve, reject) => {
+          let settled = false;
+          const socket = net.connect(socketPath);
+          const finish = (err?: Error) => {
+            if (settled) return;
+            settled = true;
+            if (err) {
+              socket.destroy();
+              reject(err);
+            } else {
+              resolve();
+            }
+          };
+
+          socket.setTimeout(5000);
+          socket.once("error", (err) => finish(err));
+          socket.once("timeout", () => finish(new Error("timed out after 5 seconds")));
+          socket.end(payload, () => finish());
+        });
+      } catch (err) {
+        reportState = "open";
+        const message = `fork: could not deliver result to parent: ${err}`;
+        console.error(message);
+        toolCtx.ui.notify(
+          `${message}. The report was not sent; retry report_result with the same result.`,
+          "error",
+        );
+        throw new Error(
+          "Result delivery failed; the report was not sent. Retry " +
+            "report_result with the same result.",
+        );
+      }
+
+      reportState = "open";
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: "Report delivered. End your turn and await the parent's verdict.",
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+
+  // ── verdict channel (parent → child) ─────────────────────────────────
+
+  fs.mkdirSync(AGENTS_DIR, { recursive: true });
+  const agentSockPath = agentSocketPathFor(subagentId);
+  const server = serveLines(agentSockPath, "agent socket", (line) => processAgentLine(pi, line));
+
+  pi.on("session_shutdown", () => {
+    teardownServer(server, agentSockPath, "agent socket");
+  });
+
+  pi.registerMessageRenderer(MESSAGE_TYPE, renderForkMessage);
+}
+
+// ── extension entry ────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  if (!inTmux()) return;
+
+  pi.registerFlag("subagent-socket", {
+    description: "Parent socket path (internal)",
+    type: "string",
+  });
+
+  pi.registerFlag("subagent-id", {
+    description: "Subagent ID for result routing (internal)",
+    type: "string",
+  });
+
+  pi.registerFlag("subagent-branch", {
+    description: "Isolated worktree branch (internal)",
+    type: "string",
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    const socketPath = pi.getFlag("subagent-socket") as string | undefined;
+
+    if (socketPath === undefined) {
+      // Parent mode
+      setupParent(pi, ctx);
+      return;
+    }
+
+    // Child mode
+    const subagentId = pi.getFlag("subagent-id") as string;
+    const branch = pi.getFlag("subagent-branch") as string | undefined;
+    setupChild(pi, socketPath, subagentId, branch);
+  });
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@resolveworks/fork",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Subagents for Pi — spawn pi sessions in tmux windows with task delegation and revision loops",
+  "type": "module",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "index.ts"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/resolveworks/fork.git"
+  },
+  "homepage": "https://github.com/resolveworks/fork#readme",
+  "bugs": "https://github.com/resolveworks/fork/issues",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.4",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.8",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "@types/node": "^26.4.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.3.0",
+    "typescript": "^6.0.3"
+  },
+  "lint-staged": {
+    "*.ts": "biome check --write"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "format": "biome check --write .",
+    "format:check": "biome check ."
+  }
 }