@d3ara1n/pi-subagent 3.0.0 → 3.2.0

package/README.md

@@ -8,22 +8,30 @@ Provides a `subagent_delegate` tool that lets the main model offload tasks to sp
 
 **The main model is the decision maker; subagents are executors.**
 
-Your primary AI has the most complete context — it knows the full conversation history, project structure, and task at hand. Subagents are spawned with **clean, isolated contexts** to handle specific, well-defined tasks without polluting the main model's context window.
+Your primary AI has the most complete context — it knows the full conversation history, project structure, and task at hand. Subagents are isolated by default to handle specific, well-defined tasks without polluting the main model's context window. A caller can explicitly opt into a filtered, text-only snapshot of the active parent branch when a task genuinely depends on prior dialogue.
 
 This means:
 - **Subagents don't plan** — the main model decides what needs to be done and provides a clear task description
 - **Subagents don't orchestrate the overall plan** — the main model decides what to do and examines each result to pick the next move; nested delegation (worker → explorer) only offloads self-contained exploration/research inside one task
-- **Subagents don't inherit history** — they don't need the full conversation; just a precise task description
+- **Subagents are isolated by default** — give them a precise, self-contained task; use `inheritConversation` only when prior dialogue is necessary
 - **Multiple subagents can run in parallel** — emit multiple `subagent_delegate` calls in one turn; pi executes them concurrently
 - **Subagents can nest subagents** — a `worker` can delegate exploration to `explorer` without returning to the main model
 
 > This design currently focuses on single-task delegation rather than chain pipelines or context-forking — those patterns fit better when subagents act as advisors (planner, oracle) rather than executors.
 
+## Model Compatibility
+
+Observations on how main models behave with this plugin, one family per subsection. Subagent role models are configured separately via [pi-model-roles](../pi-model-roles); the notes below concern the **main model** — the orchestrator that decides when to delegate.
+
+### GPT family
+
+**Not recommended.** As of GPT 5.6, GPT models delegate pathologically: they abandon built-in tools (`read`, `edit`, `write`) and MCP entirely and route everything through subagents — `explorer` to read files, `worker` to modify them, `reviewer` to verify each change, then worker → reviewer → worker correction loops over and over. Every task a direct handful of tool calls would finish turns into a long delegate chain, wasting large amounts of time and tokens. Use a main model that treats direct tool calls as the default and delegation as the exception.
+
 ## How it works
 
 1. Main model calls the `subagent_delegate` tool with a role and task description
 2. The extension resolves the role to a model via pi-model-roles
-3. Spawns an isolated pi child process in RPC mode (`--mode rpc`) with the configured model, tools, and system prompt — agent events stream back over stdout while stdin carries the initial prompt and mid-run steering commands. Children are headless: interactive extension dialogs (`ctx.ui.select/confirm/input`) are answered automatically with `cancelled` (standard "user declined" semantics), so an extension that asks never hangs the run
+3. Spawns a pi child process in RPC mode (`--mode rpc`, always without a reused parent session) with the configured model, tools, and system prompt. It is isolated by default; `inheritConversation: true` adds a filtered parent-branch snapshot to its initial stdin prompt. Agent events stream back over stdout while stdin carries the initial prompt and mid-run steering commands. Children are headless: interactive extension dialogs (`ctx.ui.select/confirm/input`) are answered automatically with `cancelled` (standard "user declined" semantics), so an extension that asks never hangs the run
 4. **Real-time TUI progress** shows tool calls, turns, and elapsed time as the subagent runs
 5. After completion, an **AI-generated one-line summary** is produced for compact display
 6. Returns the result to the main model with usage statistics (turns, tokens, cost)
@@ -33,19 +41,19 @@ This means:
 | Role | Model Role | Timeout | Tools | Can Delegate To | Description |
 |------|-----------|---------|-------|-----------------|-------------|
 | `explorer` | fast | 900s | read, find, grep, bash | — | Fast code exploration incl. git history inspection (read-only) |
-| `reviewer` | heavy | 3600s | read, bash, grep, find | — | Deep code review, runs git/tests for evidence (read-only) |
+| `reviewer` | heavy | 3600s | read, bash, grep, find, subagent_delegate | explorer, researcher | Deep code review, runs git/tests for evidence (read-only); delegates exploration & web verification |
 | `worker` | default | 2400s | all (no whitelist) | explorer, researcher | Implementation — the only role that can modify files; full tool access (web, MCP, everything) |
-| `researcher` | fast | 2400s | web_search, fetch_content, source_check, get_search_content, read, bash, edit, write, delegate | explorer | Web research + GitHub repo analysis; writes artifacts only inside its temp dir |
+| `researcher` | fast | 2400s | web_search, fetch_content, source_check, get_search_content, read, bash, edit, write, subagent_delegate | explorer | Web research + GitHub repo analysis; writes artifacts only inside its temp dir |
 
 **Web tool naming**: `researcher`'s web tools use the community-standard names (`web_search`, `fetch_content`, `source_check`, `get_search_content`) shared by the most popular Pi web extensions — [pi-web-access](https://github.com/nicobailon/pi-web-access), `pi-web-tools`, `pi-browse`, and others. Install any of those and the researcher gets web access out of the box. If your web extension uses different tool names (e.g. `websearch`/`webfetch`) or you renamed the tools via a `toolNames` config, override `researcher.tools` in `agentOverrides` to match.
 
-**Nested delegation**: `worker` and `researcher` can spawn their own subagents. This keeps the main model's context clean — a worker can explore unfamiliar code via an `explorer` subagent without returning intermediate results to the main model.
+**Nested delegation**: `worker`, `reviewer`, and `researcher` can spawn their own subagents. This keeps the caller's context clean — a worker can explore unfamiliar code via an `explorer` subagent without returning intermediate results, and a reviewer can verify third-party library behavior via a `researcher` subagent without leaving the diff.
 
 **Parallel execution**: To run multiple subagents concurrently, emit multiple `subagent_delegate` calls in a single turn. Pi's framework executes them in parallel automatically, with each subagent getting its own TUI progress display.
 
 ## TUI Display
 
-- **During execution**: the task's first line with a ⏳ (or ⏸ queued) indicator, a live stream of thinking blocks and tool calls (latest 5 collapsed, everything expanded), and a usage line (elapsed/budget time, turns, tokens, peak context, cost, model)
+- **During execution**: the task's first line with a ⏳ (or ⏸ queued) indicator, a live stream of thinking blocks and tool calls (latest 5 collapsed, everything expanded), and a usage line (elapsed/budget time, turns, tokens, peak context, cost, model). Delegates using inherited conversation are marked in the tool-call title.
 - **Collapsed result**: the task's first line, then `✓` + the AI-generated summary (or the first line of the output), then the usage line — no activity replay
 - **Expanded result** (Ctrl+O): reference files, context size, the full task, the complete activity stream, the final output as rendered Markdown, and usage details
 - **Fallback trace**: when a provider error (429, quota, timeout, ...) kills a run and it is retried on the role's `fallbackRole`, a `⚠ fallback: first attempt <model> failed (<reason>)` line appears in both views — also while the retry is running (see [Fallback observability](#fallback-observability))
@@ -65,7 +73,7 @@ A centered overlay covering most of the screen. A tab row across the top lists e
 
 The **activity page** (default) is the run's live feed: a continuous, append-only list where each entry is static text with a state icon, and the only animated thing is the ellipsis on a running entry (`.` → `..` → `...`). Finishing freezes an entry in place — its position never changes, only the icon flips. Streamed assistant text grows in place as the run's last line and settles into plain terminal-colored text at the turn boundary. The feed is scrollable (`↑↓`, `PgUp/PgDn`, `Home`/`End`): the view pins to the end and auto-follows new entries; scrolling up unpins (a `⋮ N earlier` marker appears), and reaching the bottom again re-pins. Both foreground and background runs appear here; a foreground run stays listed while its delegate call blocks the main agent. A run leaves the view once its result is in the conversation — when the last one goes, the overlay shows a centered empty notice (with `Esc close` hinted) rather than shrinking away.
 
-The **brief page** shows the run's inputs and vitals at full width: the task and context verbatim (wrapped; head+tail elided beyond 20k chars), the reference file list annotated with `✓`/`·` for whether the child's tool calls actually touched each file, usage and time stats, the fallback trace, and a stderr tail on failures.
+The **brief page** shows the run's inputs and vitals at full width: the task and context verbatim (wrapped; head+tail elided beyond 20k chars), inherited-conversation size and truncation status when enabled (never its text), the reference file list annotated with `✓`/`·` for whether the child's tool calls actually touched each file, usage and time stats, the fallback trace, and a stderr tail on failures.
 
 Steer input is modal so keys never conflict with typing: in browse mode `s` opens the editor, `Enter` queues the message into the focused run (only while it is running) and returns to browse, `Esc` cancels and clears. The message appears immediately in the feed as an `↩ steer:` entry and is delivered to the child after its current tool batch, before its next LLM call — the run keeps its progress. `Esc` in browse mode closes the overlay.
 
@@ -108,21 +116,26 @@ Edit `~/.pi/agent/settings.json`:
     "summary": {
       "role": "utility",
       "enabled": true
+    },
+    "inheritance": {
+      "maxChars": 50000
     }
   }
 }
 ```
 
-All fields are optional. Defaults: `maxConcurrency: 4`, `maxDepth: 3`, `maxTurns: 0` (unlimited), `maxCost: 0` (unlimited), `history.enabled: true`, `summary.role: "utility"`, `summary.enabled: true`.
+All fields are optional. Defaults: `maxConcurrency: 4`, `maxDepth: 3`, `maxTurns: 0` (unlimited), `maxCost: 0` (unlimited), `history.enabled: true`, `summary.role: "utility"`, `summary.enabled: true`, and `inheritance.maxChars: 50000`.
 
 Timeouts are defined per role. Built-in defaults are `explorer: 900`, `reviewer: 3600`, `worker: 2400`, and `researcher: 2400` seconds. The timeout is active time — the clock pauses while the child is inside a nested `subagent_delegate` call, so delegate-capable roles need no extra headroom.
 
-All numeric limits accept `0` for unlimited: `maxConcurrency`, `maxDepth`, `maxTurns`, `maxCost`, and per-role `timeout`. Negative values are normalized to `0`; non-numeric or non-finite values fall back to their defaults. `maxConcurrency: 0` runs delegates without queuing, and `maxDepth: 0` permits unrestricted nesting.
+`maxConcurrency`, `maxDepth`, `maxTurns`, `maxCost`, and per-role `timeout` accept `0` for unlimited. Negative values are normalized to `0`; non-numeric or non-finite values fall back to their defaults. `inheritance.maxChars` is different: it must be a positive finite integer, and zero, negative, invalid, or non-finite values use the default. `maxConcurrency: 0` runs delegates without queuing, and `maxDepth: 0` permits unrestricted nesting.
 
 ### Agent Overrides
 
 Override, disable, or add subagent roles via `agentOverrides`. Built-in and custom roles are treated equally — all descriptions, examples, and decision triggers feed into the LLM's prompt dynamically.
 
+The built-in roles are defined in [`src/roles.ts`](src/roles.ts) — read them as reference templates when overriding. Each entry shows the exact shape and wording of every field (`role`, `description`, `examples`, `decisionTrigger`, `tools`/`subagentRoles`, `systemPrompt`, `timeout`, `fallbackRole`), so you can copy the built-in closest to what you want, paste it under `agentOverrides`, and adjust from a known-good starting point rather than writing a role from scratch.
+
 ```json
 {
   "subagent": {
@@ -161,7 +174,7 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
 
 Configuring both on the same role is an error — the role is skipped with an error notification at session start.
 
-**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role the whole run is retried on after a provider error; unset means no retry — see [Fallback observability](#fallback-observability)).
+**Optional fields:** `subagentRoles` (roles this role can spawn via delegate; absent means any available role, mirroring the `tools` default — declare it explicitly when a restricted role grants `subagent_delegate`), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role the whole run is retried on after a provider error; unset means no retry — see [Fallback observability](#fallback-observability)).
 
 Invalid custom roles (missing required fields) are skipped with an error notification at session start.
 
@@ -194,6 +207,26 @@ Delegate tasks that would generate many tool calls or verbose output to keep you
 ]
 ```
 
+### Inheriting parent conversation
+
+`inheritConversation` is opt-in and defaults to `false`. Use it when a delta task relies on the active parent dialogue and repeating that material would be impractical:
+
+```json
+{
+  "role": "worker",
+  "task": "Implement the approved approach and satisfy the acceptance checklist above.",
+  "inheritConversation": true
+}
+```
+
+At delegate execution, pi-subagent snapshots `buildContextEntries()` for the active branch. It serializes only compaction summaries, branch summaries, and text blocks from user and assistant messages. Thinking, images, tool calls and arguments, tool results, custom UI/state messages, bash messages, and model metadata are excluded. Newer compaction entries with a `retainedTail` are supported; older `firstKeptEntryId` compactions use the separately returned kept entries.
+
+The inherited body is mechanically limited by `inheritance.maxChars` (default 50,000). When it is too long, pi-subagent retains summary context and the newest dialogue, inserting an omission marker. No model call summarizes this input. The child receives it in an independent `<inherited_conversation>` block after `files` and before explicit `context` and `task`; the task remains authoritative. Inherited conversation can be incomplete, so the child must report missing material rather than guess.
+
+The tool-call title marks inherited runs. Expanded delegate input and `/subagent:view`'s brief page show the delivered character count plus `truncated` when applicable, next to the other input metadata; an enabled snapshot with no eligible text is shown as empty. The inherited body is never rendered or written to subagent history. History records only the safe inheritance flag, character count, and truncation status.
+
+Keep the default isolated mode for focused work. Without inheritance, `task`, `context`, and `files` must be self-contained.
+
 ## Background Delegation
 
 Three execution properties, kept separate:
@@ -254,7 +287,7 @@ Queued steers are visible in neither wait nor check results — they shape the r
 
 Each tool row renders one aspect of the same decomposition the foreground row shows all at once (input · process · result · usage):
 
-- **Background subagent_delegate row = input only.** Collapsed: `▶ sub-1 <task first line>`. Expanded: plus `@file` references, context size, and the full task text. Static — the run progresses invisibly until a subagent_wait/subagent_check row picks it up.
+- **Background subagent_delegate row = input only.** Collapsed: `▶ sub-1 <task first line>`. Expanded: plus `@file` references, context size, inherited-conversation size/truncation metadata when enabled, and the full task text. Static — the run progresses invisibly until a subagent_wait/subagent_check row picks it up.
 - **subagent_wait row = process + usage.** The input line shows the id list (or `(all)`) plus the timeout ceiling (`≤30s`) when one was given. One block per watched run: status line (`⏸ queued / ⏳ running` + id + task preview; bare, icon-free once terminal), a live activity stream (collapsed keeps the latest 5 items with a leading ellipsis; expanded shows everything) and a ticking usage bar. Once a run finishes, its process stream is replaced by a **status-only** result line (`✓ finished` / `⏲ budget-exceeded with the reason` / `⏱ timed out` / `⏹ cancelled with the reason` / `✗ <reason>`) — the output itself never appears in a subagent_wait row; expanded keeps the full process stream instead. A timed-out wait freezes the view.
 - **subagent_check row = the result view.** Same block shape as subagent_wait's single-run view (no id — there is only one), but the result line shows `✓ <AI summary>` (or the budget/failure reason when the run stopped early) and the expanded view renders the **full output** — subagent_check is where the conclusion lives.
 - **subagent_cancel row = confirmation only.** Collapsed: `⏹ sub-1 (worker): cancelled after 1 turn (~29s)` (or `• sub-1 (worker) already finished — nothing to cancel` for a no-op). Expanded adds the reason and the pointer to `subagent_check` — the partial output **never renders here**; it stays in the registry until a check row fetches it (layer contract: delegate = input, wait = process, cancel = intervention, check = result).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/config.test.ts

@@ -43,6 +43,19 @@ afterEach(() => {
 });
 
 describe("loadSubagentConfig", () => {
+  test("uses the inheritance default and accepts only positive finite integer maxChars", () => {
+    const { agentDir } = makeRoot();
+    writeSettings(agentDir, { subagent: { inheritance: { maxChars: 12 } } });
+    assert.equal(loadSubagentConfig().inheritance.maxChars, 12);
+
+    for (const maxChars of [0, -1, 0.5, 12.9, "500", false, null]) {
+      writeSettings(agentDir, { subagent: { inheritance: { maxChars } } });
+      assert.equal(loadSubagentConfig().inheritance.maxChars, DEFAULT_CONFIG.inheritance.maxChars);
+    }
+    writeSettingsText(agentDir, '{"subagent":{"inheritance":{"maxChars":1e999}}}');
+    assert.equal(loadSubagentConfig().inheritance.maxChars, DEFAULT_CONFIG.inheritance.maxChars);
+  });
+
   test("preserves zero limits and clamps negative numeric limits to unlimited", () => {
     const { agentDir } = makeRoot();
     writeSettings(agentDir, {
@@ -99,6 +112,7 @@ describe("loadSubagentConfig", () => {
         maxCost: 5,
         history: { enabled: false },
         summary: { enabled: false, role: "global-summary" },
+        inheritance: { maxChars: 1234 },
         agentOverrides: { global: { disabled: true } },
       },
     });
@@ -112,7 +126,11 @@ describe("loadSubagentConfig", () => {
     assert.equal(config.maxTurns, DEFAULT_CONFIG.maxTurns);
     assert.equal(config.maxCost, DEFAULT_CONFIG.maxCost);
     assert.deepEqual(config.history, DEFAULT_CONFIG.history);
-    assert.deepEqual(config.summary, { enabled: DEFAULT_CONFIG.summary.enabled, role: "project-summary" });
+    assert.deepEqual(config.summary, {
+      enabled: DEFAULT_CONFIG.summary.enabled,
+      role: "project-summary",
+    });
+    assert.deepEqual(config.inheritance, DEFAULT_CONFIG.inheritance);
     assert.deepEqual(config.agentOverrides, {});
   });
 });

package/src/config.ts

@@ -12,6 +12,12 @@ import type { SubagentConfig } from "./types.ts";
 import { DEFAULT_CONFIG } from "./types.ts";
 import { normalizeNonNegativeInteger, normalizeNonNegativeNumber } from "./utils.ts";
 
+function normalizePositiveInteger(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
 function readSettingsFile(filePath: string): any {
   try {
     const content = fs.readFileSync(filePath, "utf-8");
@@ -39,6 +45,7 @@ export function loadSubagentConfig(cwd?: string): SubagentConfig {
 
   const rawSummary = raw?.summary;
   const rawHistory = raw?.history;
+  const rawInheritance = raw?.inheritance;
   return {
     maxConcurrency: normalizeNonNegativeInteger(raw.maxConcurrency, DEFAULT_CONFIG.maxConcurrency),
     maxDepth: normalizeNonNegativeInteger(raw.maxDepth, DEFAULT_CONFIG.maxDepth),
@@ -51,6 +58,12 @@ export function loadSubagentConfig(cwd?: string): SubagentConfig {
       role: rawSummary?.role ?? DEFAULT_CONFIG.summary.role,
       enabled: rawSummary?.enabled ?? DEFAULT_CONFIG.summary.enabled,
     },
+    inheritance: {
+      maxChars: normalizePositiveInteger(
+        rawInheritance?.maxChars,
+        DEFAULT_CONFIG.inheritance.maxChars,
+      ),
+    },
     agentOverrides: raw.agentOverrides ?? {},
   };
 }

package/src/history.ts

@@ -38,6 +38,9 @@ export function persistSubagentHistory(
       role,
       task,
       timestamp: Date.now(),
+      inheritConversation: r.inheritConversation === true,
+      inheritedConversationChars: r.inheritedConversationChars,
+      inheritedConversationTruncated: r.inheritedConversationTruncated,
       exitCode: r.exitCode,
       stopReason: r.stopReason,
       model: r.model,

package/src/index.ts

@@ -16,11 +16,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
-import type {
-  SubagentConfig,
-  SubagentResult,
-  SubagentRole,
-} from "./types.ts";
+import type { SubagentConfig, SubagentResult, SubagentRole } from "./types.ts";
 import { DEFAULT_CONFIG } from "./types.ts";
 import { loadSubagentConfig } from "./config.ts";
 import { BUILTIN_ROLES } from "./roles.ts";
@@ -44,6 +40,7 @@ import {
 } from "./utils.ts";
 import { startSubagentRun, type RunHandle } from "./run.ts";
 import { buildInboxReminder, injectReminder } from "./reminder.ts";
+import { serializeInheritedConversation } from "./inheritance.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render.ts";
 import { createViewPanel } from "./view.ts";
 import {
@@ -149,11 +146,13 @@ export default function subagentExtension(pi: ExtensionAPI) {
       "- Delegate ONLY when a task involves significant work (heavy analysis, multi-step investigation, large-scope changes) AND you only care about the conclusion, not intermediate steps. A good test: the task would clutter your context with 3+ turns of raw tool output.",
       "- DO NOT delegate simple tasks — a single read, a one-line edit, a basic grep, or straightforward changes touching 1-2 files. Just do them yourself; spawning a child process costs more than the task.",
       "",
-      "SELF-CONTAINED DELEGATION (subagents have NO memory of this conversation):",
+      "DELEGATION CONTEXT MODES:",
       "",
-      "- The child sees exactly three things: task, context, files — nothing else of this chat exists for it. Any requirement, decision, or constraint it must know has to be restated in those channels.",
-      "- Never write phantom references (\"as discussed above\", \"per the requirements\") — the child has never seen that material. Inline the actual content instead.",
-      "- The isolation is deliberate: don't dump your whole conversation either. Pass what the task needs and nothing more, so the child's judgment isn't steered by irrelevant history.",
+      "- Self-contained (default): when task, context, and files contain everything the child needs, omit inheritConversation. The child receives no parent dialogue.",
+      '- Conversation-relative: when the task is intentionally written as a delta against this chat — e.g. "implement the approved approach", "review the requirements above", or "continue from our discussion" — set inheritConversation: true.',
+      "- Never send a conversation-relative task without inheritConversation: true. Either enable inheritance or rewrite the task to be self-contained.",
+      "- With inheritance enabled, keep task focused on the work to perform; do not duplicate the conversation into context. Use context for additional non-conversation background and files for source material.",
+      "- Inherited history may be compacted or truncated. If an older detail is essential and may fall outside the retained history, include it explicitly in task or context.",
       "",
       "AVAILABLE ROLES:",
       ...entries.map(([name, role]) => `  - ${name}: ${role.description}`),
@@ -304,7 +303,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_delegate",
     label: "Delegate to subagent",
     description:
-      "Delegate a task to a specialized subagent. By default the call blocks until the run finishes and returns the final output — intermediate tool output stays out of your context. With background: true it returns an id immediately and you collect the result later with subagent_wait/subagent_check. Subagents have no access to this conversation — everything they need must arrive through the parameters.",
+      "Delegate a task to a specialized subagent. By default the call blocks until the run finishes and returns the final output — intermediate tool output stays out of your context. With background: true it returns an id immediately and you collect the result later with subagent_wait/subagent_check. Subagents are isolated by default; inheritConversation optionally injects a filtered snapshot of the active parent branch.",
     promptSnippet: "Delegate tasks to specialized subagents",
     promptGuidelines: guidelines,
 
@@ -312,7 +311,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       role: Type.String({ description: "Subagent role to use" }),
       task: Type.String({
         description:
-          "The work to do — self-contained: the subagent cannot see this conversation, so restate any requirement or constraint it needs here or in `context`. Instructions only — background material belongs in `context`, reference file paths in `files`.",
+          "The work to do. Without conversation inheritance it must be self-contained, with every requirement or constraint restated here or in `context`; with inheritance it may be a delta against that history. Instructions only — background material belongs in `context`, reference file paths in `files`.",
       }),
       context: Type.Optional(
         Type.String({
@@ -326,6 +325,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
             'Reference file paths for the subagent to read directly (e.g. ["src/auth.ts", "docs/api.md"]). Injected as @file attachments — content stays out of your context window. Prefer this over pasting file contents into context.',
         }),
       ),
+      inheritConversation: Type.Optional(
+        Type.Boolean({
+          description:
+            "Opt in to a text-only, compaction-aware snapshot of the active parent conversation. Omit or false for isolation; true lets task be a delta against inherited history, which may be filtered or truncated.",
+        }),
+      ),
       background: Type.Optional(
         Type.Boolean({
           description:
@@ -370,6 +375,13 @@ export default function subagentExtension(pi: ExtensionAPI) {
         );
       }
 
+      const inheritedConversation = params.inheritConversation
+        ? serializeInheritedConversation(
+            ctx.sessionManager.buildContextEntries(),
+            config.inheritance.maxChars,
+          )
+        : undefined;
+
       const run = startSubagentRun({
         id: `sub-${++runCounter}`,
         toolCallId: _toolCallId,
@@ -378,6 +390,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
         task: params.task,
         context: params.context,
         files: params.files,
+        inheritConversation: params.inheritConversation === true,
+        inheritedConversation: inheritedConversation?.text,
+        inheritedConversationTruncated: inheritedConversation?.truncated,
         cwd: params.cwd ?? ctx.cwd,
         depth: CURRENT_DEPTH + 1,
         // Foreground runs die with the tool call; background runs outlive the turn.
@@ -430,6 +445,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
             task: params.task,
             context: params.context,
             files: params.files,
+            inheritConversation: params.inheritConversation === true,
+            inheritedConversationChars: inheritedConversation?.text.length,
+            inheritedConversationTruncated: inheritedConversation?.truncated,
           },
         };
       }
@@ -765,7 +783,8 @@ export default function subagentExtension(pi: ExtensionAPI) {
 
       // Terminal runs cannot be cancelled — point at check instead.
       if (run.state === "finished" || run.state === "failed") {
-        const what = run.state === "finished" ? "its result" : "the failure reason and partial output";
+        const what =
+          run.state === "finished" ? "its result" : "the failure reason and partial output";
         const text =
           `${params.id} (${run.role}) already ${run.state} — nothing to cancel. ` +
           `subagent_check(${params.id}) returns ${what}.`;
@@ -996,7 +1015,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
       // reported as already-terminal instead of cancelled.
       const targets =
         target === "all"
-          ? [...backgroundRuns.values()].filter((r) => r.state === "queued" || r.state === "running")
+          ? [...backgroundRuns.values()].filter(
+              (r) => r.state === "queued" || r.state === "running",
+            )
           : [backgroundRuns.get(target)!];
       if (targets.length === 0) {
         ctx.ui.notify("No live background runs to cancel.", "info");

package/src/inheritance.test.ts

@@ -0,0 +1,217 @@
+/** Tests for deterministic parent-conversation serialization. */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SessionManager, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { serializeInheritedConversation as createSnapshot } from "./inheritance.ts";
+
+function serializeInheritedConversation(entries: SessionEntry[], maxChars: number): string {
+  return createSnapshot(entries, maxChars).text;
+}
+
+function entries(items: unknown[]): SessionEntry[] {
+  return items as SessionEntry[];
+}
+
+const base = (type: string, id: string, extra: Record<string, unknown> = {}) => ({
+  type,
+  id,
+  parentId: null,
+  timestamp: "2026-01-01T00:00:00.000Z",
+  ...extra,
+});
+
+test("serializes only user/assistant text while filtering tool and UI state", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("message", "u", { message: { role: "user", content: "Need a change" } }),
+      base("message", "a", {
+        message: {
+          role: "assistant",
+          content: [
+            { type: "thinking", thinking: "private" },
+            { type: "text", text: "I will delegate this." },
+            {
+              type: "toolCall",
+              id: "call",
+              name: "subagent_delegate",
+              arguments: { secret: "no" },
+            },
+          ],
+        },
+      }),
+      base("message", "tool", {
+        message: {
+          role: "toolResult",
+          toolName: "bash",
+          content: [{ type: "text", text: "secret output" }],
+        },
+      }),
+      base("custom_message", "ui", { content: "UI state" }),
+      base("custom", "state", { data: { token: "no" } }),
+      base("message", "bash", { message: { role: "bashExecution", output: "shell output" } }),
+    ]),
+    10_000,
+  );
+
+  assert.equal(output, "[user]\nNeed a change\n\n[assistant]\nI will delegate this.");
+  assert.ok(!output.includes("private"));
+  assert.ok(!output.includes("secret"));
+  assert.ok(!output.includes("UI state"));
+  assert.ok(!output.includes("shell output"));
+});
+
+test("preserves active entry order, compaction summaries, and retained tails", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("compaction", "c", {
+        summary: "Earlier work",
+        retainedTail: [
+          { role: "compactionSummary", summary: "Retained compacted context" },
+          { role: "user", content: "Kept request" },
+          { role: "assistant", content: [{ type: "text", text: "Kept reply" }] },
+          { role: "branchSummary", summary: "Retained branch context" },
+        ],
+      }),
+      base("branch_summary", "b", { summary: "Abandoned branch" }),
+      base("message", "u", { message: { role: "user", content: "Current request" } }),
+      base("message", "a", {
+        message: { role: "assistant", content: [{ type: "text", text: "Current reply" }] },
+      }),
+    ]),
+    10_000,
+  );
+
+  assert.equal(
+    output,
+    "[Compaction summary]\nEarlier work\n\n[Compaction summary]\nRetained compacted context\n\n[user]\nKept request\n\n[assistant]\nKept reply\n\n[Branch summary]\nRetained branch context\n\n[Branch summary]\nAbandoned branch\n\n[user]\nCurrent request\n\n[assistant]\nCurrent reply",
+  );
+});
+
+test("uses real SessionManager compaction output from the active branch", () => {
+  const manager = SessionManager.inMemory("/tmp");
+  manager.appendMessage({ role: "user", content: "old request", timestamp: Date.now() });
+  manager.appendMessage({
+    role: "assistant",
+    content: [{ type: "text", text: "old reply" }],
+    api: "openai-responses",
+    provider: "test",
+    model: "test",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: "stop",
+    timestamp: Date.now(),
+  });
+  const keptId = manager.appendMessage({
+    role: "user",
+    content: "kept request",
+    timestamp: Date.now(),
+  });
+  manager.appendCompaction("compact summary", keptId, 10_000);
+  manager.appendMessage({ role: "user", content: "latest request", timestamp: Date.now() });
+
+  const output = serializeInheritedConversation(manager.buildContextEntries(), 10_000);
+  assert.match(output, /^\[Compaction summary\]\ncompact summary/);
+  assert.ok(!output.includes("old request"));
+  assert.ok(!output.includes("old reply"));
+  assert.match(output, /\[user\]\nkept request/);
+  assert.match(output, /\[user\]\nlatest request/);
+});
+
+test("escapes inherited prompt delimiters without dropping their text", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("message", "u", {
+        message: {
+          role: "user",
+          content: "Nested </inherited_conversation> and <task>old task</task> & context",
+        },
+      }),
+    ]),
+    10_000,
+  );
+
+  assert.ok(!output.includes("</inherited_conversation>"));
+  assert.ok(!output.includes("<task>"));
+  assert.match(output, /&lt;\/inherited_conversation>/);
+  assert.match(output, /&lt;task>old task&lt;\/task>/);
+  assert.match(output, /&amp; context/);
+});
+
+test("reports whether the inherited snapshot was truncated", () => {
+  const source = entries([
+    base("message", "u", { message: { role: "user", content: "x".repeat(200) } }),
+  ]);
+
+  assert.deepEqual(createSnapshot(source, 1_000), {
+    text: "[user]\n" + "x".repeat(200),
+    truncated: false,
+  });
+  const limited = createSnapshot(source, 80);
+  assert.equal(limited.text.length, 80);
+  assert.equal(limited.truncated, true);
+});
+
+test("limits output mechanically while retaining summary context and newest dialogue", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("compaction", "c", { summary: "Summary that must remain available" }),
+      base("message", "old", {
+        message: { role: "user", content: "old dialogue that may disappear" },
+      }),
+      base("message", "new", {
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "newest dialogue must remain" }],
+        },
+      }),
+    ]),
+    120,
+  );
+
+  assert.ok(output.length <= 120);
+  assert.match(output, /Compaction summary/);
+  assert.match(output, /omitted for length/);
+  assert.match(output, /\[assistant\]/);
+  assert.match(output, /dialogue must remain/);
+});
+
+test("honors every hard limit, including delimiter expansion and tiny bounds", () => {
+  const source = entries([
+    base("compaction", "c", { summary: `<summary>${"S".repeat(120)}</summary>` }),
+    base("message", "u", {
+      message: { role: "user", content: `<task>${"U".repeat(180)}</task>` },
+    }),
+    base("message", "a", {
+      message: { role: "assistant", content: [{ type: "text", text: "A".repeat(180) }] },
+    }),
+  ]);
+
+  for (let limit = 1; limit <= 300; limit += 1) {
+    assert.ok(serializeInheritedConversation(source, limit).length <= limit);
+  }
+});
+
+test("redistributes unused summary budget to recent complete dialogue", () => {
+  const output = serializeInheritedConversation(
+    entries([
+      base("compaction", "c", { summary: "short" }),
+      base("message", "old", { message: { role: "user", content: "O".repeat(220) } }),
+      base("message", "new", {
+        message: { role: "assistant", content: `latest-${"N".repeat(80)}` },
+      }),
+    ]),
+    240,
+  );
+
+  assert.equal(output.length, 240);
+  assert.match(output, /^\[Compaction summary\]\nshort/);
+  assert.match(output, /\[assistant\]\nlatest-/);
+  assert.match(output, /Earlier text in this message omitted/);
+});