pi-fork-join 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-fork-join contributors
+
+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

@@ -0,0 +1,191 @@
+# pi-fork-join
+
+In-process **shared-prefix concurrent fork/join** for the Pi coding agent.
+
+Keep your main agent's context window clean while running several independent
+investigations in parallel. Each fork is a child `AgentSession` **in the same
+process** that inherits the current active branch as its shared prefix, runs a
+bounded task, and returns only a dense structured report. The parent's context
+window never receives the forks' intermediate tool logs or thinking.
+
+`pi-fork-join` is the in-process realization of the "shared-prefix concurrent
+fork" idea: the execution engine is brand new (no child `pi` process, no JSONL
+snapshot round-trip), while the configuration surface is adapted from the
+`pi-fork` extension (MIT).
+
+## Install
+
+```bash
+pi install git:github.com/InertialG/pi-fork-join
+```
+
+Or run from source:
+
+```bash
+pi -e ./src/index.ts
+```
+
+## Usage
+
+The extension registers one tool, `fork_join`:
+
+```json
+{
+  "tasks": [
+    { "id": "data", "task": "Inspect the data layer; return evidence and risk." },
+    { "id": "concurrency", "task": "Audit the concurrency/state model; return risks." },
+    { "id": "impl", "task": "Implement step 3 and land the patch.", "write": true }
+  ],
+  "maxConcurrency": 4
+}
+```
+
+Each fork inherits the parent conversation **up to, but excluding, the assistant
+message that contains the current `fork_join` call** — the call itself, its
+sibling task descriptions, and any parallel-status text are not visible inside a
+branch. `fork_join` blocks until all forks finish and returns their reports in
+input order. The parent is responsible for synthesis and any final serial edits.
+
+## Context semantics
+
+`fork_join` locates the current call in the active branch and uses the entry
+*before* it as the shared fork base:
+
+```text
+C0: existing conversation and tool results
+C1: current assistant message
+    ├─ optional text
+    └─ fork_join toolCall
+
+child_i = C0 + private_task_i
+```
+
+This means:
+
+- Every child sees the same history that existed before the current call.
+- No child sees the `fork_join` call, sibling tasks, or parallel-status text.
+- Prior tool results and earlier fork reports that already entered the parent
+  history are treated exactly like any serial result — nothing is deleted or
+  semantically pruned.
+- Locating the call is a hard requirement: if it cannot be found, or is
+  ambiguous, the whole `fork_join` fails rather than silently falling back to
+  the current leaf (which would leak the running call into children).
+
+A single task failing does not discard the batch; the parent still receives the
+status of every task.
+
+## Isolation model
+
+Isolation is enforced by **tool policy**, not by filesystem copying — and it is
+**best-effort, not a sandbox**. A read-only fork excludes the `edit`/`write`
+tools, which is what prevents the classic parallel-edit clobber race. But both
+read-only and write forks still have `bash`, which can create, modify, and
+delete files. Treat `read-only` as "no edit/write tools" — not as "cannot touch
+the filesystem". The parent agent retains final authority and should not
+delegate destructive or security-sensitive work to any fork without awareness.
+
+| Fork kind | Tools | Working directory | When |
+|---|---|---|---|
+| **Read-only (default)** | `read`, `bash`, `grep`, `find`, `ls` — **no `edit`/`write`** | shared parent `cwd` | investigation, review, evidence collection |
+| **Write (`write: true`)** | above **plus** `edit`, `write` | its **own git worktree** | a fork that must call `edit`/`write` |
+
+Design rationale:
+
+- **Read-only is the default and needs no worktree.** Because no fork has
+  `edit`/`write`, concurrent forks cannot clobber each other through those tools
+  regardless of scheduling order. Read-only forks also see the parent's
+  **current dirty working tree** (uncommitted changes), which is exactly what an
+  investigating agent needs. They still have `bash`, so they *can* write files
+  if they try — that is an accepted limitation, surfaced honestly here and in
+  the tool description, not silently hidden.
+- **Worktree only for write forks.** A write fork is isolated in its own git
+  worktree so its `edit`/`write` cannot race the parent or other forks. A
+  worktree forks from the **last commit**: the parent's uncommitted changes are
+  deliberately **not** visible inside it. Worktree isolation is also best-effort
+  against a cooperative model; a fork that deliberately writes to an absolute
+  parent path can escape it. Write forks require a git repository; if none
+  exists, that fork fails with a clear error.
+- **Non-git directories** are fine for read-only forks (they use the shared
+  `cwd`). Only `write: true` needs git.
+
+## Concurrency
+
+- Forks run on the **single event loop** of the parent process. LLM calls, tool
+  subprocesses, and file I/O are all async I/O, so several forks genuinely
+  overlap (wall-clock ≈ slowest fork, not the sum). There is no CPU parallelism;
+  that is a deliberate and correct trade for this I/O-bound workload.
+- Concurrency is bounded by `maxConcurrency` (default `4`, max `8`) via a
+  worker pool. This keeps provider calls and worktrees within a sane budget.
+- **Cancellation:** when the parent tool call is aborted, every running fork's
+  session is aborted. Fork results report `cancelled`.
+- **Failure isolation:** each fork runs in its own `AgentSession`; one fork
+  failing does not cancel the others. Failures are collected per-fork.
+
+## Context isolation
+
+- Only the final assistant report of each fork is returned to the parent.
+- Fork transcripts, tool calls, and thinking never enter the parent context.
+- The shared prefix is rebuilt from the current **active branch only**
+  (`sessionManager.getBranch()`); sibling/abandoned branches are excluded.
+- Messages are deep-cloned before seeding, so a fork can never mutate the
+  parent's history.
+
+## Settings
+
+Configure under the `pi-fork-join` key in `~/.pi/agent/settings.json`
+(global) or `.pi/settings.json` (project). Project overrides global.
+
+```json
+{
+  "pi-fork-join": {
+    "defaultMaxConcurrency": 4,
+    "costFooter": true,
+    "leanChildren": true
+  }
+}
+```
+
+- `defaultMaxConcurrency` — used when a `fork_join` call omits `maxConcurrency`.
+- `costFooter` — show fork cost as a dim footer status line.
+- `leanChildren` — children load only the base system prompt + project
+  `AGENTS.md`, skipping extensions/skills/prompts/themes. Default `true`
+  (prevents child extension bloat and accidental recursive `fork_join`).
+
+## Development
+
+```bash
+npm install            # peer deps for typechecking
+npm test               # node --test unit tests (pure modules + real git worktrees)
+npm run typecheck      # tsc --noEmit against the installed pi packages
+```
+
+The unit tests exercise the pure modules (scheduler, tool policy, report
+assembly/extraction, config, and git worktree create/remove round-trips).
+`src/fork-runner.ts` and `src/index.ts` are type-checked against the installed
+pi SDK; integration against a live model/provider requires running inside pi
+(`pi -e ./src/index.ts` and calling `fork_join`).
+
+## Important caveats
+
+- **Single-threaded:** forked CPU-bound work still serializes on the event
+  loop. This extension is tuned for I/O-bound agent investigation.
+- **Read-only is not a sandbox:** a read-only fork still has `bash`, which can
+  create/delete files. It only lacks `edit`/`write` tools. The parent agent
+  must not rely on a read-only fork being unable to touch the filesystem.
+- **Context pollution on repeated calls:** each fork inherits the shared prefix.
+  If you call `fork_join` repeatedly in one session, later forks inherit the
+  earlier fork reports and may drift into meta-commentary. Prefer a single
+  `fork_join` call for all parallel tasks, and run clean experiments in a fresh
+  session.
+- **Worktree sees only committed state:** a `write: true` fork cannot see your
+  uncommitted parent changes. Use read-only forks (shared `cwd`) when a fork
+  must inspect the dirty working tree.
+- **Report-only contract:** only the final report returns to the parent; fork
+  tool logs and thinking never enter the parent context.
+
+## License
+
+MIT. The configuration surface and early design were adapted from
+[`pi-fork`](https://github.com/elpapi42/pi-fork) (MIT); the in-process
+execution engine and shared-prefix context implementation are original to this
+package.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-fork-join",
+  "version": "0.1.0",
+  "description": "In-process shared-prefix concurrent fork/join for the Pi coding agent. Read-only forks by default; write forks are isolated in their own git worktrees. The parent keeps its context window; children return dense structured reports.",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "pi",
+    "fork",
+    "join",
+    "subagent",
+    "concurrency",
+    "parallel",
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InertialG/pi-fork-join.git"
+  },
+  "homepage": "https://github.com/InertialG/pi-fork-join#readme",
+  "bugs": {
+    "url": "https://github.com/InertialG/pi-fork-join/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.75.0",
+    "@earendil-works/pi-ai": ">=0.75.0",
+    "@earendil-works/pi-coding-agent": ">=0.75.0",
+    "@earendil-works/pi-tui": ">=0.75.0",
+    "@sinclair/typebox": ">=0.34.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.75.0",
+    "@earendil-works/pi-ai": ">=0.75.0",
+    "@earendil-works/pi-coding-agent": ">=0.75.0",
+    "@earendil-works/pi-tui": ">=0.75.0",
+    "@sinclair/typebox": ">=0.34.0",
+    "typescript": "^5.5.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const SETTINGS_KEY = "pi-fork-join";
+
+export interface ForkJoinConfig {
+  /** Default maxConcurrency when a call omits it. */
+  defaultMaxConcurrency: number;
+  /** Show fork cost as an extra dimmed footer status line. */
+  costFooter: boolean;
+  /** When true, children never load extensions/skills/prompts/themes. */
+  leanChildren: boolean;
+}
+
+export const DEFAULT_CONFIG: ForkJoinConfig = {
+  defaultMaxConcurrency: 4,
+  costFooter: true,
+  leanChildren: true,
+};
+
+function readNamespacedConfig(settingsPath: string): Partial<ForkJoinConfig> {
+  if (!existsSync(settingsPath)) return {};
+  try {
+    const raw = JSON.parse(readFileSync(settingsPath, "utf-8")) as Record<string, unknown>;
+    const nested = raw[SETTINGS_KEY];
+    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return {};
+    const cfg = nested as Record<string, unknown>;
+    const parsed: Partial<ForkJoinConfig> = {};
+    if (typeof cfg.defaultMaxConcurrency === "number" && Number.isInteger(cfg.defaultMaxConcurrency)) {
+      parsed.defaultMaxConcurrency = cfg.defaultMaxConcurrency;
+    }
+    if (typeof cfg.costFooter === "boolean") parsed.costFooter = cfg.costFooter;
+    if (typeof cfg.leanChildren === "boolean") parsed.leanChildren = cfg.leanChildren;
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+/** Load the `pi-fork-join` settings namespace, merging global + project (project wins). */
+export function loadConfig(cwd: string): ForkJoinConfig {
+  const agentDir = getAgentDir();
+  const global = readNamespacedConfig(agentDir + "/settings.json");
+  const project = readNamespacedConfig(cwd + "/.pi/settings.json");
+  return { ...DEFAULT_CONFIG, ...global, ...project };
+}

package/src/context.ts

@@ -0,0 +1,110 @@
+import { buildSessionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+/**
+ * Minimal structural view of a session manager needed to resolve the fork base.
+ *
+ * `ctx.sessionManager` exposes more, but typing against a small structural
+ * interface keeps this module decoupled and unit-testable.
+ */
+export interface ForkBaseSession {
+  getBranch(): readonly SessionEntry[];
+  getEntries(): SessionEntry[];
+}
+
+/**
+ * True when a session entry is an assistant message containing a tool call
+ * whose id matches `toolCallId`. Used to locate the current `fork_join` call.
+ */
+export function containsToolCall(entry: SessionEntry, toolCallId: string): boolean {
+  if (entry.type !== "message") return false;
+  const msg = entry.message;
+  if (msg.role !== "assistant") return false;
+  const content = (msg as { content?: unknown }).content;
+  if (!Array.isArray(content)) return false;
+  return content.some((block) => {
+    if (!block || typeof block !== "object") return false;
+    const b = block as { type?: unknown; id?: unknown };
+    return b.type === "toolCall" && b.id === toolCallId;
+  });
+}
+
+/**
+ * Locate the assistant message entry containing the current `fork_join` tool
+ * call and return its `parentId` — the shared fork base for every branch.
+ *
+ * Walking the active branch from the end means the returned base is the entry
+ * immediately *before* the `fork_join` call, so the call itself, its sibling
+ * tasks, and any parallel-status text never enter a child context.
+ *
+ * Returns `null` when the call is the very first message (empty history), which
+ * callers must interpret as "no prior context". Throws instead of silently
+ * falling back to the current leaf when the call cannot be located or when the
+ * id is ambiguous.
+ */
+export function findForkBaseEntryId(
+  sessionManager: ForkBaseSession,
+  toolCallId: string,
+): string | null {
+  const branch = sessionManager.getBranch();
+  let parentId: string | null | undefined;
+  let matches = 0;
+
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i];
+    if (!containsToolCall(entry, toolCallId)) continue;
+    matches += 1;
+    parentId = entry.parentId;
+  }
+
+  if (matches === 0) {
+    throw new Error(`Cannot locate fork_join call entry: ${toolCallId}`);
+  }
+  if (matches > 1) {
+    throw new Error(`Multiple fork_join call entries found for id: ${toolCallId}`);
+  }
+  return parentId ?? null;
+}
+
+/**
+ * Resolve the shared-prefix context for all forks: every session entry from the
+ * root up to (and including) the fork base, i.e. everything before the current
+ * `fork_join` call.
+ *
+ * Uses Pi's own `buildSessionContext` so compaction, branch summaries, custom
+ * messages, and entry-to-message conversion follow Pi's original rules — this
+ * module never decides what history is "trustworthy" or drops prior fork
+ * results. It only converts entries on the base path into LLM `AgentMessage`s.
+ *
+ * The base is validated to be on the active branch because `buildSessionContext`
+ * silently falls back to the current leaf for an unknown id; that fallback would
+ * re-leak the running `fork_join` call into children and is explicitly rejected.
+ */
+export function resolveForkBaseContext(
+  sessionManager: ForkBaseSession,
+  forkBaseId: string | null,
+): AgentMessage[] {
+  if (forkBaseId !== null) {
+    const onBranch = sessionManager.getBranch().some((e) => e.id === forkBaseId);
+    if (!onBranch) {
+      throw new Error(`Fork base entry not on the active branch: ${forkBaseId}`);
+    }
+  }
+  const context = buildSessionContext(sessionManager.getEntries(), forkBaseId);
+  return context.messages;
+}
+
+/**
+ * Deep-clone a message so a child session can never mutate the parent's
+ * history (or a sibling's seeded copy).
+ */
+export function cloneMessage<T>(value: T): T {
+  if (typeof structuredClone === "function") {
+    try {
+      return structuredClone(value);
+    } catch {
+      /* fall through to JSON clone */
+    }
+  }
+  return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/fork-runner.ts

@@ -0,0 +1,132 @@
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  SessionManager,
+  SettingsManager,
+  type AgentSession,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { cloneMessage } from "./context.js";
+import { buildForkTaskPrompt, extractFinalReport } from "./report.js";
+import { resolveTools } from "./tool-policy.js";
+import { MAX_REPORT_CHARS, type ForkResult } from "./types.js";
+
+export interface RunForkOptions {
+  id: string;
+  task: string;
+  write: boolean;
+  /** Effective working directory: shared parent cwd, or a worktree path. */
+  cwd: string;
+  /**
+   * Shared-prefix context (root → fork base) already resolved from the parent
+   * session. Every branch starts from the same array; each fork gets its own
+   * deep-cloned copy so children can never mutate each other or the parent.
+   */
+  baseMessages: readonly AgentMessage[];
+  model?: unknown;
+  thinkingLevel?: unknown;
+  modelRuntime: unknown;
+  /** Lean children: load only the base system prompt + project AGENTS.md. */
+  leanChildren: boolean;
+  signal?: AbortSignal;
+}
+
+/**
+ * Run one fork as an in-process AgentSession.
+ *
+ * The child is a fresh, in-memory session. We seed `agent.state.messages` with
+ * the parent's shared prefix (zero-copy context, no JSONL round-trip, no
+ * process spawn), then run `prompt()` with the task. Only the final assistant
+ * report is returned to the caller.
+ *
+ * Concurrency note: LLM/tool work here is all async I/O, so several such child
+ * sessions genuinely overlap on the single event loop. The parent's context
+ * window only ever receives each child's final report.
+ */
+export async function runFork(opts: RunForkOptions): Promise<ForkResult> {
+  const started = Date.now();
+  let session: AgentSession | undefined;
+  let unsubscribe: (() => void) | undefined;
+
+  try {
+    const loader = new DefaultResourceLoader({
+      cwd: opts.cwd,
+      agentDir: getAgentDir(),
+      noExtensions: opts.leanChildren,
+      noSkills: opts.leanChildren,
+      noPromptTemplates: opts.leanChildren,
+      noThemes: opts.leanChildren,
+    });
+    await loader.reload();
+
+    const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false } });
+
+    const created = await createAgentSession({
+      cwd: opts.cwd,
+      model: opts.model as never,
+      thinkingLevel: opts.thinkingLevel as never,
+      tools: resolveTools(opts.write),
+      modelRuntime: opts.modelRuntime as never,
+      resourceLoader: loader,
+      settingsManager,
+      sessionManager: SessionManager.inMemory(opts.cwd),
+    });
+    session = created.session;
+
+    // Seed the shared prefix. Clone per fork so concurrent children and the
+    // parent each own independent message objects.
+    session.agent.state.messages = opts.baseMessages.map(cloneMessage);
+
+    // Propagate cancellation to the child.
+    const signal = opts.signal;
+    const onAbort = (): void => {
+      void session?.abort();
+    };
+    if (signal) {
+      if (signal.aborted) void session.abort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    let toolCalls = 0;
+    let turns = 0;
+    unsubscribe = session.subscribe((ev) => {
+      if (ev.type === "tool_execution_start") toolCalls += 1;
+      else if (ev.type === "turn_end") turns += 1;
+    });
+
+    await session.prompt(buildForkTaskPrompt(opts.task));
+
+    if (signal) signal.removeEventListener("abort", onAbort);
+
+    const report = extractFinalReport(session.messages as AgentMessage[], MAX_REPORT_CHARS);
+    const status = signal?.aborted ? "cancelled" : "completed";
+
+    return {
+      id: opts.id,
+      task: opts.task,
+      write: opts.write,
+      status,
+      report,
+      toolCalls,
+      turns,
+      durationMs: Date.now() - started,
+      worktreeUsed: opts.write,
+    };
+  } catch (err) {
+    return {
+      id: opts.id,
+      task: opts.task,
+      write: opts.write,
+      status: "failed",
+      toolCalls: 0,
+      turns: 0,
+      durationMs: Date.now() - started,
+      error: err instanceof Error ? err.message : String(err),
+      worktreeUsed: opts.write,
+    };
+  } finally {
+    unsubscribe?.();
+    session?.dispose();
+  }
+}

package/src/index.ts

@@ -0,0 +1,183 @@
+import { Type } from "@sinclair/typebox";
+import { ModelRuntime, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "./config.js";
+import { findForkBaseEntryId, resolveForkBaseContext } from "./context.js";
+import { runFork } from "./fork-runner.js";
+import { renderForkJoinCall, renderForkJoinResult } from "./render.js";
+import { mapLimit } from "./scheduler.js";
+import {
+  DEFAULT_MAX_CONCURRENCY,
+  MAX_MAX_CONCURRENCY,
+  MAX_TASKS,
+  type ForkJoinToolDetails,
+  type ForkResult,
+  type ForkTaskSpec,
+} from "./types.js";
+import { createWorktree, detectRepoRoot, removeWorktree, type Worktree } from "./worktree.js";
+
+const TaskParams = Type.Object({
+  id: Type.String({
+    description:
+      "Unique id for this task, used to correlate results. Keep it short and meaningful (e.g. 'data', 'concurrency').",
+  }),
+  task: Type.String({
+    description:
+      "The bounded task for the fork. Make the local goal self-contained but do NOT re-explain the shared context the fork already inherits. Say where the fork's decision authority ends; ambiguities should be surfaced back rather than resolved unilaterally.",
+  }),
+  write: Type.Optional(
+    Type.Boolean({
+      description:
+        "If true the fork may call edit/write and runs isolated in its own git worktree. If false (default) the fork has no edit/write tools and runs in the shared working directory. NOTE: read-only still includes bash, which can create/delete files; read-only prevents edit/write-tool races between parallel forks, it is NOT a filesystem sandbox. The parent retains final authority and must not rely on a read-only fork being unable to touch files.",
+    }),
+  ),
+});
+
+const ForkJoinParams = Type.Object({
+  tasks: Type.Array(TaskParams, {
+    minItems: 1,
+    maxItems: MAX_TASKS,
+    description: "Independent tasks to run in parallel forks. Tasks MUST be mutually independent; do not batch sequentially dependent steps.",
+  }),
+  maxConcurrency: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: MAX_MAX_CONCURRENCY,
+      description: `Concurrent fork limit (default ${DEFAULT_MAX_CONCURRENCY}, max ${MAX_MAX_CONCURRENCY}).`,
+    }),
+  ),
+  write: Type.Optional(
+    Type.Boolean({
+      description:
+        "Default write flag inherited by tasks that do not set one explicitly. Default false.",
+    }),
+  ),
+});
+
+function formatJoinText(details: ForkJoinToolDetails): string {
+  const lines: string[] = [`fork_join: ${details.results.length} task(s), ${details.durationMs}ms`];
+  for (const r of details.results) {
+    if (r.status === "completed" && r.report) {
+      lines.push(`\n=== [${r.id}]${r.write ? " (worktree)" : ""} ===\n${r.report}`);
+    } else {
+      lines.push(`\n=== [${r.id}] ${r.status}${r.error ? `: ${r.error}` : ""} ===`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "fork_join",
+    label: "Fork/Join",
+    description:
+      "Run several independent stages concurrently from the parent context before the current call. Spawn forks that share the conversation up to, but excluding, the assistant message containing the current fork_join call; the current call and sibling task descriptions are not visible inside a branch. Each fork runs its task and returns only its final dense report; the parent remains responsible for synthesis and final edits. Use it to offload context-heavy independent investigations (explore separate subsystems, compare competing explanations, run independent reviews, collect evidence in parallel). IMPORTANT: forks still run bash (read-only forks only drop edit/write), so a fork can create/delete files; this is not a sandbox. Do not delegate destructive or security-sensitive work to a fork without awareness.",
+    promptSnippet: "Run independent stages concurrently from the parent context before the current call",
+    promptGuidelines: [
+      "Use fork_join when two or more stages can be completed independently.",
+      "Put all independent stages in one fork_join call.",
+      "Each fork_join task must state its own local objective.",
+      "Do not tell one fork_join task that another task is currently running.",
+      "Do not use fork_join when one task requires another task's result.",
+      "Each task inherits the parent conversation up to, but excluding, the assistant message containing the current fork_join call; the current call and sibling task descriptions are not visible inside a branch.",
+    ],
+    parameters: ForkJoinParams,
+    renderCall: renderForkJoinCall,
+    renderResult: renderForkJoinResult,
+    executionMode: "sequential",
+
+    async execute(toolCallId, params, signal, _onUpdate, ctx) {
+      const started = Date.now();
+      const config = loadConfig(ctx.cwd);
+
+      // Locate the current fork_join call and resolve the shared prefix once.
+      // Every branch starts from the entry before this call; the call itself,
+      // sibling tasks, and any parallel-status text never enter a child.
+      // Location failure is a hard error, never a silent fallback to the leaf.
+      const forkBaseId = findForkBaseEntryId(ctx.sessionManager, toolCallId);
+      const baseMessages = resolveForkBaseContext(ctx.sessionManager, forkBaseId);
+      const maxConcurrency = Math.min(
+        params.maxConcurrency ?? config.defaultMaxConcurrency,
+        MAX_MAX_CONCURRENCY,
+      );
+      const defaultWrite = params.write ?? false;
+
+      const tasks: ForkTaskSpec[] = params.tasks.map((t) => ({
+        id: t.id,
+        task: t.task,
+        write: t.write ?? defaultWrite,
+      }));
+
+      const modelRuntime = await ModelRuntime.create({ signal });
+      const worktrees: Worktree[] = [];
+
+      const results = await mapLimit(tasks, maxConcurrency, async (task): Promise<ForkResult> => {
+        let cwd = ctx.cwd;
+        let worktree: Worktree | undefined;
+
+        if (task.write) {
+          const root = await detectRepoRoot(ctx.cwd);
+          if (!root) {
+            return {
+              id: task.id,
+              task: task.task,
+              write: true,
+              status: "failed",
+              toolCalls: 0,
+              turns: 0,
+              durationMs: 0,
+              error:
+                "write fork requires a git repository for worktree isolation; none found at the current directory.",
+              worktreeUsed: false,
+            };
+          }
+          try {
+            worktree = await createWorktree(root);
+          } catch (err) {
+            return {
+              id: task.id,
+              task: task.task,
+              write: true,
+              status: "failed",
+              toolCalls: 0,
+              turns: 0,
+              durationMs: 0,
+              error: `worktree isolation failed: ${err instanceof Error ? err.message : String(err)}`,
+              worktreeUsed: false,
+            };
+          }
+          worktrees.push(worktree);
+          cwd = worktree.path;
+        }
+
+        try {
+          return await runFork({
+            id: task.id,
+            task: task.task,
+            write: task.write,
+            cwd,
+            baseMessages,
+            model: ctx.model,
+            thinkingLevel: ctx.thinkingLevel,
+            modelRuntime,
+            leanChildren: config.leanChildren,
+            signal,
+          });
+        } finally {
+          if (worktree) await removeWorktree(worktree);
+        }
+      });
+
+      const details: ForkJoinToolDetails = {
+        status: "completed",
+        results,
+        durationMs: Date.now() - started,
+        maxConcurrency,
+      };
+
+      return {
+        content: [{ type: "text", text: formatJoinText(details) }],
+        details,
+      };
+    },
+  });
+}

package/src/render.ts

@@ -0,0 +1,57 @@
+import { Text } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ForkJoinToolDetails, ForkResult } from "./types.js";
+
+/** Compact one-line header for the fork_join tool call. */
+export function renderForkJoinCall(
+  args: { tasks?: { id?: string; write?: boolean }[] },
+  theme: Theme,
+  _context: unknown,
+): Text {
+  const n = args.tasks?.length ?? 0;
+  const writes = (args.tasks ?? []).filter((t) => t.write).length;
+  const text = new Text("", 0, 0);
+  let content = theme.fg("toolTitle", theme.bold("fork_join "));
+  content += theme.fg("accent", `${n}`);
+  content += " forks";
+  if (writes > 0) content += theme.fg("dim", ` (${writes} write/worktree)`);
+  text.setText(content);
+  return text;
+}
+
+/** Renders fork results with per-fork status lines; expanded shows reports. */
+export function renderForkJoinResult(
+  result: { details?: ForkJoinToolDetails; isError?: boolean },
+  options: { expanded: boolean },
+  theme: Theme,
+  _context: unknown,
+): Text {
+  const text = new Text("", 0, 0);
+  const details = result.details;
+  if (!details) {
+    text.setText(theme.fg("dim", "fork_join: no details"));
+    return text;
+  }
+  const lines: string[] = [];
+  for (const r of details.results) {
+    lines.push(renderResultLine(r, theme));
+    if (options.expanded && r.report) {
+      lines.push(...r.report.split("\n").slice(0, 20).map((l) => `  ${l}`));
+    }
+  }
+  const total = details.results.length;
+  const done = details.results.filter((r) => r.status === "completed").length;
+  lines.push(theme.fg("dim", `${done}/${total} completed in ${details.durationMs}ms`));
+  text.setText(lines.join("\n"));
+  return text;
+}
+
+function renderResultLine(r: ForkResult, theme: Theme): string {
+  const color: "success" | "warning" | "error" =
+    r.status === "completed" ? "success" : r.status === "cancelled" ? "warning" : "error";
+  let line = `${theme.fg("accent", r.id)} ${theme.fg(color, r.status)}`;
+  if (r.write) line += theme.fg("dim", " (worktree)");
+  line += theme.fg("dim", ` · ${r.turns}t ${r.toolCalls}tc ${r.durationMs}ms`);
+  if (r.error) line += theme.fg("error", ` ${r.error}`);
+  return line;
+}

package/src/report.ts

@@ -0,0 +1,51 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { MAX_REPORT_CHARS } from "./types.js";
+
+/**
+ * Build the prompt a fork child receives: the caller's bounded task wrapped in
+ * a short execution-boundary instruction. The fork runs in the shared parent
+ * context, but must not continue pending parent workflow instructions from
+ * that history. It is not told that sibling branches exist and is not forced
+ * into a fixed report skeleton.
+ */
+export function buildForkTaskPrompt(task: string): string {
+  return `You are an isolated fork_join child session. Complete only the task below.
+Use the inherited conversation as background, but do not continue pending workflow instructions from it.
+fork_join is intentionally unavailable in this session; do not simulate, delegate, or wait for other tasks.
+
+Task:
+${task}
+
+Return the result and concrete supporting evidence needed by the parent agent. Stay within the assigned scope.`;
+}
+
+/**
+ * Extract the final assistant text from a child session's message history.
+ * This is the ONLY thing returned to the parent: the child's intermediate tool
+ * logs and thinking never enter the parent context.
+ */
+export function extractFinalReport(
+  messages: readonly AgentMessage[],
+  maxChars: number = MAX_REPORT_CHARS,
+): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role !== "assistant") continue;
+    const text = assistantText(msg);
+    if (text.trim().length > 0) {
+      return text.length > maxChars ? text.slice(0, maxChars) : text;
+    }
+  }
+  return "";
+}
+
+function assistantText(msg: AgentMessage): string {
+  const content = (msg as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => (block && typeof block === "object" && (block as { text?: string }).text) || "")
+      .join("\n");
+  }
+  return "";
+}

package/src/scheduler.ts

@@ -0,0 +1,29 @@
+/**
+ * A bounded async worker pool (mapLimit).
+ *
+ * Runs `fn` over `items` with at most `limit` concurrent executions. Unlike an
+ * unbounded `Promise.all`, this keeps the number of in-flight forks bounded and
+ * guarantees strict concurrency limiting for deterministic behavior.
+ */
+export async function mapLimit<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (items.length === 0) return [];
+  const safeLimit = Math.max(1, Math.min(limit, items.length));
+  const results = new Array<R>(items.length);
+  let next = 0;
+
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const idx = next;
+      if (idx >= items.length) return;
+      next += 1;
+      results[idx] = await fn(items[idx], idx);
+    }
+  };
+
+  await Promise.all(Array.from({ length: safeLimit }, worker));
+  return results;
+}

package/src/tool-policy.ts

@@ -0,0 +1,13 @@
+import { FULL_TOOLS, READ_ONLY_TOOLS } from "./types.js";
+
+/**
+ * Resolve the tool allowlist for a fork.
+ *
+ * Read-only forks (the default) deliberately exclude `edit`/`write`. Since no
+ * fork can mutate the shared working tree, concurrent forks cannot clobber each
+ * other regardless of scheduling. Write forks gain `edit`/`write`, but only run
+ * against their own isolated git worktree.
+ */
+export function resolveTools(write: boolean): string[] {
+  return write ? [...FULL_TOOLS] : [...READ_ONLY_TOOLS];
+}

package/src/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared types for the pi-fork-join extension.
+ */
+
+export type ForkStatus = "completed" | "failed" | "cancelled";
+
+/** A single task to run in an isolated fork. */
+export interface ForkTaskSpec {
+  id: string;
+  task: string;
+  /** If true, the fork may edit/write files and is isolated in a git worktree. */
+  write: boolean;
+}
+
+/** Per-fork runtime state while it runs. */
+export interface ForkTaskRuntime extends ForkTaskSpec {
+  /** Effective working directory (shared parent cwd, or a git worktree path for write forks). */
+  cwd: string;
+  worktreePath?: string;
+}
+
+/** Result collected from a completed/failed fork. */
+export interface ForkResult {
+  id: string;
+  task: string;
+  write: boolean;
+  status: ForkStatus;
+  /** Final assistant report text (truncated). Absent on failure. */
+  report?: string;
+  toolCalls: number;
+  turns: number;
+  durationMs: number;
+  error?: string;
+  /** True when the fork ran inside its own git worktree. */
+  worktreeUsed: boolean;
+  /** Non-fatal note, e.g. worktree fallback happened. */
+  isolationWarning?: string;
+}
+
+export interface ForkJoinToolDetails {
+  status: "completed";
+  results: ForkResult[];
+  durationMs: number;
+  maxConcurrency: number;
+}
+
+export const DEFAULT_MAX_CONCURRENCY = 4;
+export const MAX_MAX_CONCURRENCY = 8;
+export const MAX_TASKS = 8;
+export const MAX_REPORT_CHARS = 16_000;
+
+/** Tools available to a read-only fork. No edit/write, so no concurrent-clobber race. */
+export const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"] as const;
+/** Tools additionally enabled for a write fork (isolated in a git worktree). */
+export const WRITE_TOOLS = ["edit", "write"] as const;
+export const FULL_TOOLS = [...READ_ONLY_TOOLS, ...WRITE_TOOLS];

package/src/worktree.ts

@@ -0,0 +1,75 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const execFileAsync = promisify(execFile);
+
+export interface Worktree {
+  /** Repository top-level directory (from `git rev-parse --show-toplevel`). */
+  root: string;
+  /** The worktree's working directory. */
+  path: string;
+}
+
+/**
+ * Detect the git repository top-level for `cwd`. Returns null when not inside
+ * a git repository (or git is unavailable). Used to decide whether write-fork
+ * worktree isolation is possible.
+ */
+export async function detectRepoRoot(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-C", cwd, "rev-parse", "--show-toplevel"],
+      { timeout: 5000 },
+    );
+    const trimmed = stdout.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a detached git worktree at HEAD in a fresh temp directory.
+ *
+ * A worktree shares the repository's git objects but has its own working tree,
+ * so a write fork can edit files without racing the parent (or other forks).
+ * It intentionally forks from the last commit: uncommitted parent changes are
+ * NOT carried in. This is the documented isolation contract for write forks.
+ *
+ * The worktree is created on a detached HEAD (no new branch ref is needed
+ * because forks report changes back rather than pushing a branch).
+ */
+export async function createWorktree(root: string): Promise<Worktree> {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-fork-join-"));
+  await execFileAsync(
+    "git",
+    ["-C", root, "worktree", "add", "--detach", dir],
+    { timeout: 15_000 },
+  );
+  return { root, path: dir };
+}
+
+/**
+ * Remove a worktree, then best-effort delete the temp dir.
+ * Swallows cleanup errors so a failed join does not mask real fork failures.
+ */
+export async function removeWorktree(wt: Worktree): Promise<void> {
+  try {
+    await execFileAsync(
+      "git",
+      ["-C", wt.root, "worktree", "remove", "--force", wt.path],
+      { timeout: 15_000 },
+    );
+  } catch {
+    /* ignore */
+  }
+  try {
+    await fs.promises.rm(wt.path, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+}