@maplezzk/pi-interactive-subagents 3.11.1 → 3.12.0

package/README.md

@@ -92,7 +92,7 @@ Subagent panes are created without stealing keyboard focus (cmux, tmux). Launch
 
 ### Extensions
 
-**Subagents** — 4 main-session tools + 3 commands, plus 1 subagent-only tool:
+**Subagents** — 4 main-session tools + 2 commands, plus 1 subagent-only tool:
 
 | Tool                 | Description                                                                                 |
 | -------------------- | ------------------------------------------------------------------------------------------- |
@@ -104,7 +104,6 @@ Subagent panes are created without stealing keyboard focus (cmux, tmux). Launch
 | Command                    | Description                          |
 | -------------------------- | ------------------------------------ |
 | `/plan`                    | Start a full planning workflow       |
-| `/iterate`                 | Fork into a subagent for quick fixes |
 | `/subagent <agent> <task>` | Spawn a named agent directly         |
 
 ### Bundled Agents
@@ -155,26 +154,24 @@ The widget tracks each Pi-backed sub-agent from a child-written runtime snapshot
 
 These labels are no longer derived from session-file growth. Session JSONL is still used for transcript, resume, lineage, and result extraction, but Pi-backed liveness now comes from a small activity snapshot written by the child extension. A fixed internal watchdog marks a run as `stalled` when valid snapshots never appear, stop being readable, or stop matching the current child; valid long-running `active` or `waiting` states do not become `stalled` just because time passes. When a run enters `stalled` or recovers from it, the parent agent receives a steer message so it can react. All other status transitions stay in the widget only.
 
-**Interactive subagents stay silent.** Long-running user-driven subagents (e.g. `planner`, or any `/iterate` fork) do not wake the parent session on `stalled`/`recovered` transitions — the user is working directly in the subagent's pane, and a steer message there would just burn an orchestrator turn on a no-op "still waiting" ping. The widget still updates normally, and child snapshots are still recorded/classified regardless of the `interactive` setting. By default, agents with `auto-exit: true` are treated as autonomous and get stall pings; agents without it are treated as interactive and stay quiet. Override per-agent with `interactive: true|false` in frontmatter, or per-spawn with `interactive: true|false` on the tool call.
+**Interactive subagents stay silent.** Long-running user-driven subagents (e.g. `planner`) do not wake the parent session on `stalled`/`recovered` transitions — the user is working directly in the subagent's pane, and a steer message there would just burn an orchestrator turn on a no-op "still waiting" ping. The widget still updates normally, and child snapshots are still recorded/classified regardless of the `interactive` setting. By default, agents with `auto-exit: true` are treated as autonomous and get stall pings; agents without it are treated as interactive and stay quiet. Override per-agent with `interactive: true|false` in frontmatter, or per-spawn with `interactive: true|false` on the tool call.
 
 #### Configuration
 
-Subagent settings, including status display and the persisted Herdr mode, are controlled by `config.json` in the extension directory. Copy `config.json.example` to get started:
-
-```bash
-cp config.json.example config.json
-```
+The persisted Herdr mode, child-spawning policy, and explicit child-extension list are read from the user extension config at `~/.pi/agent/extensions/pi-interactive-subagents/config.json` (respecting `PI_CODING_AGENT_DIR`). The status panel's `status.enabled` is read from the installed package's `config.json`, falling back to `config.json.example`. The package's `config.json.example` documents the available fields; add `allowSubagentSpawning` and `subagentExtensions` to the user config without overwriting its existing mux settings:
 
 ```json
 {
   "herdrMode": "split",
+  "allowSubagentSpawning": false,
+  "subagentExtensions": [],
   "status": {
     "enabled": true
   }
 }
 ```
 
-`herdrMode` accepts `split` (default, backward-compatible pane layout) or `tab` (one background tab per subagent). The `/config:subagent herdr split|tab` command updates this field.
+`herdrMode` accepts `split` (default, backward-compatible pane layout) or `tab` (one background tab per subagent). The `/config:subagent herdr split|tab` command updates this field. `allowSubagentSpawning` is a global switch for whether child subagents may create or manage other subagents; it defaults to `false`. Set it to `true` to enable the lifecycle tools in child sessions when the corresponding extension is selected. `subagentExtensions` is an optional list of extension paths to load explicitly in child sessions; automatic project/global extension discovery is disabled. Paths may be absolute, start with `~/`, or be relative to `PI_CODING_AGENT_DIR`. `subagent-done.ts` is always loaded. Explicit `deny-tools` restrictions still apply.
 
 `config.json` is gitignored so local overrides don't get committed.
 
@@ -186,10 +183,7 @@ cp config.json.example config.json
 // Named agent with defaults from agent definition
 subagent({ name: "Scout", agent: "scout", task: "Analyze the codebase..." });
 
-// Force a full-context fork for this spawn
-subagent({ name: "Iterate", fork: true, task: "Fix the bug where..." });
-
-// Agent defaults can choose a different session-mode via frontmatter
+// Child sessions start fresh; use session-mode: lineage-only when lineage metadata is useful
 subagent({ name: "Planner", agent: "planner", task: "Work through the design with me" });
 
 // Custom working directory
@@ -203,7 +197,6 @@ subagent({ name: "Designer", agent: "game-designer", cwd: "agents/game-designer"
 | `name`                 | string  | required       | Display name (shown in widget and pane title)                                                     |
 | `task`                 | string  | required       | Task prompt for the sub-agent                                                                     |
 | `agent`                | string  | —              | Load defaults from agent definition                                                               |
-| `fork`                 | boolean | `false`        | Force the full-context fork mode for this spawn, overriding any agent `session-mode` frontmatter  |
 | `interactive`          | boolean | derived        | Mark this spawn as interactive (don't wake the parent on stall/recovery). Defaults to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit`. |
 | `model`                | string  | —              | Override agent's default model                                                                    |
 | `systemPrompt`         | string  | —              | Append to system prompt                                                                           |
@@ -290,18 +283,6 @@ Tab/window titles update to show current phase:
 
 ---
 
-## The `/iterate` Workflow
-
-For quick, focused work without polluting the main session's context.
-
-```
-/iterate Fix the off-by-one error in the pagination logic
-```
-
-This always forks the current session into a subagent with full conversation context. It does not inherit an agent default `session-mode`. Make the fix, verify it, and exit to return. The main session gets a summary of what was done.
-
----
-
 ## Custom Agents
 
 Place a `.md` file in `.pi/agents/` (project) or `~/.pi/agent/agents/` (global):
@@ -314,7 +295,6 @@ model: anthropic/claude-sonnet-4-6
 thinking: minimal
 tools: read, bash, edit, write
 session-mode: lineage-only
-spawning: false
 ---
 
 # My Agent
@@ -332,8 +312,8 @@ You are a specialized agent that does X...
 | `thinking`    | string  | Thinking level: `minimal`, `medium`, `high`                                                                                                                                                                                                                                 |
 | `tools`       | string  | Comma-separated **native pi tools only**: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`                                                                                                                                                                             |
 | `skills`      | string  | Comma-separated skill names to auto-load                                                                                                                                                                                                                                    |
-| `session-mode` | string | Default child-session mode: `standalone`, `lineage-only`, or `fork` |
-| `spawning`    | boolean | Set `false` to deny all subagent-spawning tools                                                                                                                                                                                                                             |
+| `session-mode` | string | Default child-session mode: `standalone` or `lineage-only` |
+| `spawning`    | boolean | Legacy field retained for compatibility. Use the global `allowSubagentSpawning` setting to control child-session subagent lifecycle tools. |
 | `deny-tools`  | string  | Comma-separated extension tool names to deny                                                                                                                                                                                                                                |
 | `auto-exit`   | boolean | Auto-shutdown when the agent finishes its turn — no `subagent_done` call needed. If the user sends any input, auto-exit is permanently disabled and the user takes over the session. Recommended for autonomous agents (scout, worker); not for interactive ones (planner). Also determines the default value of `interactive` (see below). |
 | `interactive` | boolean | derived        | Override whether stall/recovery transitions wake the parent session. Defaults to the inverse of `auto-exit`: autonomous agents (`auto-exit: true`) are non-interactive and get stall pings; agents without `auto-exit` are interactive and stay quiet. Explicit values take precedence. |
@@ -346,15 +326,12 @@ Discovery still resolves precedence before visibility filtering. If a project-lo
 
 ### `session-mode`
 
-Choose how a subagent session starts:
+Choose how a child session starts:
 
 - `standalone` — default fresh session with no lineage link to the caller
 - `lineage-only` — fresh blank child session with `parentSession` linkage, but no copied turns from the caller
-- `fork` — linked child session seeded with the caller's prior conversation context
 
-`lineage-only` is useful when you want session discovery and fork lineage UX to show the relationship later, but you do **not** want the child to inherit the parent's turns.
-
-`fork: true` on the tool call always forces the `fork` mode for that specific spawn. `/iterate` uses this explicit override on purpose.
+All child tasks are delivered through an artifact-backed initial message. There is no full-context fork mode.
 
 ```yaml
 ---
@@ -376,7 +353,7 @@ When set to `true`, the agent session shuts down automatically as soon as the ag
 **When to use:**
 
 - ✅ Autonomous agents (scout, worker, reviewer) that run to completion
-- ❌ Interactive agents (planner, iterate) where the user drives the session
+- ❌ Interactive agents (planner) where the user drives the session
 
 ```yaml
 ---
@@ -389,7 +366,7 @@ auto-exit: true
 
 Controls whether status transitions (`stalled`, `recovered`) wake the parent session with a steer message.
 
-**Default:** the inverse of `auto-exit`. Autonomous agents (`auto-exit: true`) are non-interactive and ping the parent on stall/recovery; agents without `auto-exit` are interactive and stay quiet. Bare spawns with no agent defs (e.g. `/iterate` with `fork: true`) are treated as interactive.
+**Default:** the inverse of `auto-exit`. Autonomous agents (`auto-exit: true`) are non-interactive and ping the parent on stall/recovery; agents without `auto-exit` are interactive and stay quiet. Bare spawns with no agent defs are treated as interactive.
 
 **Why it exists:** Interactive agents can run for minutes or hours while the user thinks, types, and reads in the subagent's pane. Child snapshots still update the widget, but stalled/recovered supervision messages rarely need to wake the parent for user-driven sessions. Skipping the steer keeps the parent quiet until the child actually finishes.
 
@@ -415,18 +392,11 @@ subagent({ name: "Scout", agent: "scout", interactive: true, task: "..." });
 
 ## Tool Access Control
 
-By default, every sub-agent can spawn further sub-agents. Control this with frontmatter:
-
-### `spawning: false`
+Child subagent sessions cannot create or manage other subagents unless the global `allowSubagentSpawning` setting is `true`. When it is `false` (the default), the lifecycle tools `subagent`, `subagent_interrupt`, `subagents_list`, and `subagent_resume` are not registered in child sessions. The child-only `subagent_done` tool remains available; `caller_ping` remains available for requesting help from the parent.
 
-Denies all subagent lifecycle tools (`subagent`, `subagent_interrupt`, `subagents_list`, `subagent_resume`):
+### `spawning` (legacy)
 
-```yaml
----
-name: worker
-spawning: false
----
-```
+The global `allowSubagentSpawning` setting is authoritative for child sessions. Existing `spawning: false` fields remain accepted for compatibility but do not override the global setting.
 
 ### `deny-tools`
 
@@ -439,15 +409,9 @@ deny-tools: subagent
 ---
 ```
 
-### Recommended Configuration
+### Global setting
 
-| Agent      | `spawning`  | Rationale                                    |
-| ---------- | ----------- | -------------------------------------------- |
-| planner    | _(default)_ | Legitimately spawns scouts for investigation |
-| worker     | `false`     | Should implement tasks, not delegate         |
-| researcher | `false`     | Should research, not spawn                   |
-| reviewer   | `false`     | Should review, not spawn                     |
-| scout      | `false`     | Should gather context, not spawn             |
+The global switch applies uniformly to planner, worker, reviewer, scout, and custom child sessions. Leave `allowSubagentSpawning` as `false` unless a child agent is explicitly expected to create or manage another subagent.
 
 ---
 
@@ -478,7 +442,6 @@ Set a default `cwd` in agent frontmatter:
 ---
 name: game-designer
 cwd: ./agents/game-designer
-spawning: false
 ---
 ```
 

package/README.zh-CN.md

@@ -39,10 +39,9 @@ zellij --session pi   # 然后运行 pi
 
 ## 主要能力
 
-- **4 个主会话工具 + 3 个命令**：`subagent`、`subagent_interrupt`、`subagents_list`、`subagent_resume`；命令 `/plan`、`/iterate`、`/subagent`
+- **4 个主会话工具 + 2 个命令**：`subagent`、`subagent_interrupt`、`subagents_list`、`subagent_resume`；命令 `/plan`、`/subagent`
 - **内置 agent**：planner、scout、worker、reviewer、visual-tester
 - **`/plan` 工作流**：调研 → 规划 → 确认 → 执行 → 审查 的完整流水线
-- **`/iterate` 工作流**：fork 当前会话到子 agent 做快速修改，不污染主上下文
 - **caller_ping**：子 agent 向父 agent 求助的机制
 - **自定义 agent**：在 `.pi/agents/` 或 `~/.pi/agent/agents/` 放置 `.md` 定义文件
 
@@ -50,22 +49,20 @@ zellij --session pi   # 然后运行 pi
 
 ## 配置
 
-状态显示与持久化 Herdr 模式由扩展目录下的 `config.json` 控制。复制 `config.json.example` 开始：
-
-```bash
-cp config.json.example config.json
-```
+持久化的 Herdr 模式、子 agent 创建策略和子 agent 扩展列表读取自用户扩展配置 `~/.pi/agent/extensions/pi-interactive-subagents/config.json`（遵循 `PI_CODING_AGENT_DIR`）。状态面板的 `status.enabled` 读取已安装包目录的 `config.json`，不存在时回退到 `config.json.example`。`config.json.example` 仅用于说明字段；向用户配置添加 `allowSubagentSpawning` 和 `subagentExtensions` 时不要覆盖已有的 mux 设置：
 
 ```json
 {
   "herdrMode": "split",
+  "allowSubagentSpawning": false,
+  "subagentExtensions": [],
   "status": {
     "enabled": true
   }
 }
 ```
 
-`herdrMode` 支持 `split`（默认，兼容原有 pane 布局）和 `tab`（每个 subagent 独立后台 Tab）。`/config:subagent herdr split|tab` 会更新该字段。
+`herdrMode` 支持 `split`（默认，兼容原有 pane 布局）和 `tab`（每个 subagent 独立后台 Tab）。`allowSubagentSpawning` 是全局开关，控制子 agent 是否可以创建或管理其他 subagent，默认值为 `false`；设置为 `true` 后，子 agent 才会获得这些生命周期工具。`subagentExtensions` 是可选扩展路径列表；子 agent 不再自动发现项目级和全局扩展，只加载列表中的扩展，`subagent-done.ts` 始终加载。路径可以是绝对路径、`~/` 路径，或相对于 `PI_CODING_AGENT_DIR` 的路径。`/config:subagent herdr split|tab` 会更新 Herdr 字段。
 
 ## 致谢
 

package/SKILL.md

@@ -7,7 +7,7 @@ description: "配置与排查 interactive subagents 的终端复用器、Herdr s
 
 ## 诊断
 
-读取实际 Pi agent 目录下的 `extensions/pi-interactive-subagents/config.json`：`mux` 保存后端偏好，`herdrMode` 保存 `split|tab`。状态面板的 `status.enabled` 由安装包根目录的 `config.json` 读取；不存在时读取同目录 `config.json.example`。状态行数当前固定为 4，不是配置项。
+读取实际 Pi agent 目录下的 `extensions/pi-interactive-subagents/config.json`：`mux` 保存后端偏好，`herdrMode` 保存 `split|tab`，`allowSubagentSpawning` 控制子 agent 是否可以创建/管理其他 subagent，`subagentExtensions` 指定子 agent 显式加载的扩展路径列表，默认不自动发现其他扩展。默认 `allowSubagentSpawning` 为 `false`，`subagent-done.ts` 始终加载。状态面板的 `status.enabled` 由安装包根目录的 `config.json` 读取；不存在时读取同目录 `config.json.example`。状态行数当前固定为 4，不是配置项。
 
 环境变量优先级：`PI_TERMINAL_MUX` > `PI_SUBAGENT_MUX` > 持久化 `mux` > `auto`；`PI_SUBAGENT_HERDR_MODE` > 持久化 `herdrMode` > `split`。
 

package/config.json.example

@@ -1,5 +1,7 @@
 {
   "herdrMode": "split",
+  "allowSubagentSpawning": false,
+  "subagentExtensions": [],
   "status": {
     "enabled": true
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplezzk/pi-interactive-subagents",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "description": "Interactive async subagents for pi — spawn, orchestrate, and manage sub-agent sessions in multiplexer panes. Fork of HazAT/pi-interactive-subagents.",
   "type": "module",
   "main": "./index.ts",

package/pi-extension/subagents/index.ts

@@ -2,7 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "@sinclair/typebox";
 import { Box, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createTranslator, loadCatalog } from "pi-extensions-i18n";
 import {
@@ -48,6 +48,8 @@ import {
   HERDR_SURFACE_MODES,
   loadHerdrModeConfig,
   loadMuxConfig,
+  loadSubagentExtensionsConfig,
+  loadSubagentSpawningConfig,
   saveHerdrMode,
   saveMuxPreference,
   SUBAGENT_MUX_BACKENDS,
@@ -56,6 +58,8 @@ import {
 } from "./mux-config.ts";
 
 import {
+  SUBAGENT_SESSION_MODE_LINEAGE_ONLY,
+  SUBAGENT_SESSION_MODE_STANDALONE,
   findLastAssistantMessage,
   getNewEntries,
   seedSubagentSessionFile,
@@ -168,12 +172,6 @@ const SubagentParams = Type.Object({
         "Working directory for the sub-agent. The agent starts in this folder and picks up its local .pi/ config, CLAUDE.md, skills, and extensions. Use for role-specific subfolders.",
     }),
   ),
-  fork: Type.Optional(
-    Type.Boolean({
-      description:
-        "Force the full-context fork mode for this spawn. The sub-agent inherits the current session conversation, overriding any agent frontmatter session-mode.",
-    }),
-  ),
   interactive: Type.Optional(
     Type.Boolean({
       description:
@@ -201,7 +199,10 @@ const SubagentParams = Type.Object({
   ),
 });
 
-type SubagentSessionMode = "standalone" | "lineage-only" | "fork";
+type SubagentSessionMode =
+  | typeof SUBAGENT_SESSION_MODE_STANDALONE
+  | typeof SUBAGENT_SESSION_MODE_LINEAGE_ONLY;
+const DEFAULT_SUBAGENT_SESSION_MODE: SubagentSessionMode = SUBAGENT_SESSION_MODE_STANDALONE;
 
 interface AgentDefaults {
   model?: string;
@@ -232,7 +233,7 @@ interface ListedAgentDefinition extends AgentDefinition {
   source: AgentSource;
 }
 
-/** Tools that are gated by `spawning: false` */
+/** Tools that are unavailable inside child subagent sessions. */
 const SPAWNING_TOOLS = new Set([
   "subagent",
   "subagent_interrupt",
@@ -241,21 +242,19 @@ const SPAWNING_TOOLS = new Set([
 ]);
 
 /**
- * Resolve the effective set of denied tool names from agent defaults.
- * `spawning: false` expands to all SPAWNING_TOOLS.
- * `deny-tools` adds individual tool names on top.
+ * Resolve the effective set of denied tool names for a child subagent.
+ * The global switch controls whether every child session may create or manage
+ * other subagents; the legacy `spawning` field does not override it.
+ * `deny-tools` can add individual restrictions on top.
  */
-function resolveDenyTools(agentDefs: AgentDefaults | null): Set<string> {
-  const denied = new Set<string>();
-  if (!agentDefs) return denied;
-
-  // spawning: false → deny all spawning tools
-  if (agentDefs.spawning === false) {
-    for (const t of SPAWNING_TOOLS) denied.add(t);
-  }
+function resolveDenyTools(
+  agentDefs: AgentDefaults | null,
+  allowSubagentSpawning = false,
+): Set<string> {
+  const denied = allowSubagentSpawning ? new Set<string>() : new Set(SPAWNING_TOOLS);
 
   // deny-tools: explicit list
-  if (agentDefs.denyTools) {
+  if (agentDefs?.denyTools) {
     for (const t of agentDefs.denyTools
       .split(",")
       .map((s) => s.trim())
@@ -276,6 +275,30 @@ function getBundledAgentsDir(): string {
   return join(SUBAGENTS_DIR, "../../agents");
 }
 
+const HOME_PREFIX = "~/";
+
+/** Resolve an extension path from the user config against the Pi agent directory. */
+function resolveSubagentExtensionPath(extensionPath: string): string {
+  if (extensionPath === "~") return homedir();
+  if (extensionPath.startsWith(HOME_PREFIX)) return join(homedir(), extensionPath.slice(HOME_PREFIX.length));
+  return isAbsolute(extensionPath) ? extensionPath : join(getAgentConfigDir(), extensionPath);
+}
+
+/** Load and resolve explicitly configured child-session extension paths. */
+function getConfiguredSubagentExtensions(): string[] {
+  return loadSubagentExtensionsConfig().extensions.map(resolveSubagentExtensionPath);
+}
+
+/** Build the no-discovery flag and explicit extensions for a child Pi command. */
+function buildChildExtensionArgs(extensionPaths = getConfiguredSubagentExtensions()): string[] {
+  return [
+    NO_EXTENSIONS_FLAG,
+    EXTENSION_FLAG,
+    shellEscape(join(SUBAGENTS_DIR, SUBAGENT_DONE_EXTENSION_FILE)),
+    ...extensionPaths.flatMap((extensionPath) => [EXTENSION_FLAG, shellEscape(extensionPath)]),
+  ];
+}
+
 function getFrontmatterValue(frontmatter: string, key: string): string | undefined {
   const match = frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
   return match ? match[1].trim() : undefined;
@@ -285,8 +308,9 @@ function parseOptionalBoolean(value: string | undefined): boolean | undefined {
   return value != null ? value === "true" : undefined;
 }
 
+/** Parse a supported session mode; invalid values return undefined. */
 function parseSessionMode(value: string | undefined): SubagentSessionMode | undefined {
-  if (value === "standalone" || value === "lineage-only" || value === "fork") {
+  if (value === SUBAGENT_SESSION_MODE_STANDALONE || value === SUBAGENT_SESSION_MODE_LINEAGE_ONLY) {
     return value;
   }
   return undefined;
@@ -376,30 +400,20 @@ function getDefaultSessionDirFor(cwd: string, _agentDir: string): string {
   return sessionDir;
 }
 
-function resolveEffectiveSessionMode(
-  params: Static<typeof SubagentParams>,
-  agentDefs: AgentDefaults | null,
-): SubagentSessionMode {
-  if (params.fork) return "fork";
-  return agentDefs?.sessionMode ?? "standalone";
+/** Resolve the agent-configured session mode, defaulting to standalone. */
+function resolveEffectiveSessionMode(agentDefs: AgentDefaults | null): SubagentSessionMode {
+  return agentDefs?.sessionMode ?? DEFAULT_SUBAGENT_SESSION_MODE;
 }
 
-function resolveLaunchBehavior(
-  params: Static<typeof SubagentParams>,
-  agentDefs: AgentDefaults | null,
-): {
+/** Resolve launch behavior for standalone and lineage-only child sessions. */
+function resolveLaunchBehavior(agentDefs: AgentDefaults | null): {
   sessionMode: SubagentSessionMode;
-  seededSessionMode: "lineage-only" | "fork" | null;
-  inheritsConversationContext: boolean;
-  taskDelivery: "direct" | "artifact";
+  seededSessionMode: typeof SUBAGENT_SESSION_MODE_LINEAGE_ONLY | null;
 } {
-  const sessionMode = resolveEffectiveSessionMode(params, agentDefs);
-  const inheritsConversationContext = sessionMode === "fork";
+  const sessionMode = resolveEffectiveSessionMode(agentDefs);
   return {
     sessionMode,
-    seededSessionMode: sessionMode === "standalone" ? null : sessionMode,
-    inheritsConversationContext,
-    taskDelivery: inheritsConversationContext ? "direct" : "artifact",
+    seededSessionMode: sessionMode === DEFAULT_SUBAGENT_SESSION_MODE ? null : SUBAGENT_SESSION_MODE_LINEAGE_ONLY,
   };
 }
 
@@ -412,12 +426,11 @@ function resolveLaunchBehavior(
  *   3. Default: the inverse of `auto-exit`. Agents that auto-exit are
  *      autonomous (scout, worker, reviewer) and the parent session should be
  *      woken on stall/recovery transitions. Agents that don't auto-exit are
- *      driven by the user in their own pane (planner, iterate/fork) and
- *      stall pings are noise.
+ *      driven by the user in their own pane (planner) and stall pings are
+ *      noise.
  *
- * When no agent defs exist at all (bare `subagent({ name, task })` call,
- * typical for `/iterate` with `fork: true`), `autoExit` is undefined and the
- * subagent is treated as interactive — matching the intent of iterate.
+ * When no agent defs exist at all (bare `subagent({ name, task })` call),
+ * `autoExit` is undefined and the subagent is treated as interactive.
  */
 function resolveEffectiveInteractive(
   params: Static<typeof SubagentParams>,
@@ -706,6 +719,10 @@ function updateWidget() {
  * as standalone prompts in the child session.
  */
 const SUBAGENT_CONTROL_TOOLS = ["caller_ping", "subagent_done"] as const;
+const FILE_TIMESTAMP_LENGTH = 19;
+const NO_EXTENSIONS_FLAG = "--no-extensions";
+const EXTENSION_FLAG = "--extension";
+const SUBAGENT_DONE_EXTENSION_FILE = "subagent-done.ts";
 
 /**
  * Build the child --tools allowlist.
@@ -731,21 +748,19 @@ function buildSubagentToolAllowlist(effectiveTools?: string): string | null {
   return [...allow].join(",");
 }
 
-function buildPiPromptArgs(params: {
-  effectiveSkills?: string;
-  taskDelivery: "direct" | "artifact";
-  taskArg: string;
-}): string[] {
+/**
+ * Build positional prompt args for a child launch.
+ * Skills must be separate prompts so Pi expands each `/skill:` directive.
+ */
+function buildPiPromptArgs(params: { effectiveSkills?: string; taskArg: string }): string[] {
   const skillPrompts = (params.effectiveSkills ?? "")
     .split(",")
     .map((s) => s.trim())
     .filter(Boolean)
     .map((skill) => `/skill:${skill}`);
 
-  const needsSeparator = params.taskDelivery === "artifact" && skillPrompts.length > 0;
-
   return [
-    ...(needsSeparator ? [""] : []),
+    ...(skillPrompts.length > 0 ? [""] : []),
     ...skillPrompts,
     params.taskArg,
   ];
@@ -1115,6 +1130,7 @@ export const __test__ = {
   resolveLaunchBehavior,
   resolveEffectiveInteractive,
   buildSubagentToolAllowlist,
+  buildChildExtensionArgs,
   buildPiPromptArgs,
   formatWidgetRightLabel,
   observeRunningSubagent,
@@ -1188,11 +1204,10 @@ async function launchSubagent(
     await new Promise<void>((resolve) => setTimeout(resolve, getShellReadyDelayMs()));
   }
 
-  const launchBehavior = resolveLaunchBehavior(params, agentDefs);
+  const launchBehavior = resolveLaunchBehavior(agentDefs);
 
   if (launchBehavior.seededSessionMode) {
     seedSubagentSessionFile({
-      mode: launchBehavior.seededSessionMode,
       parentSessionFile: sessionFile,
       childSessionFile: subagentSessionFile,
       childCwd: targetCwdForSession,
@@ -1201,25 +1216,21 @@ async function launchSubagent(
 
   const activityFile = getSubagentActivityFile(artifactDir, id);
   mkdirSync(dirname(activityFile), { recursive: true });
-  const { inheritsConversationContext } = launchBehavior;
 
-  // Build the task message
-  // Only full-context fork mode inherits prior conversation state.
-  // Blank-session modes need the wrapper instructions and artifact-backed handoff.
+  // Build the task message. All child sessions use artifact-backed delivery.
   const modeHint = agentDefs?.autoExit
     ? "Complete your task autonomously."
     : "Complete your task. When finished, call the subagent_done tool. The user can interact with you at any time.";
   const summaryInstruction = agentDefs?.autoExit
     ? "Your FINAL assistant message should summarize what you accomplished."
     : "Your FINAL assistant message (before calling subagent_done or before the user exits) should summarize what you accomplished.";
-  const denySet = resolveDenyTools(agentDefs);
+  const { allowSubagentSpawning } = loadSubagentSpawningConfig();
+  const denySet = resolveDenyTools(agentDefs, allowSubagentSpawning);
   const identity = agentDefs?.body ?? params.systemPrompt ?? null;
   const systemPromptMode = agentDefs?.systemPromptMode;
   const identityInSystemPrompt = systemPromptMode && identity;
   const roleBlock = identity && !identityInSystemPrompt ? `\n\n${identity}` : "";
-  const fullTask = inheritsConversationContext
-    ? params.task
-    : `${roleBlock}\n\n${modeHint}\n\n${params.task}\n\n${summaryInstruction}`;
+  const fullTask = `${roleBlock}\n\n${modeHint}\n\n${params.task}\n\n${summaryInstruction}`;
   // ── Claude Code CLI path ──
   if (agentDefs?.cli === "claude") {
     const sentinelFile = `/tmp/pi-claude-${id}-done`;
@@ -1297,12 +1308,9 @@ async function launchSubagent(
   // ── Pi CLI path ──
 
   // Build pi command
-  const parts: string[] = ["pi"];
+  const parts: string[] = ["pi", ...buildChildExtensionArgs()];
   parts.push("--session", shellEscape(subagentSessionFile));
 
-  const subagentDonePath = join(SUBAGENTS_DIR, "subagent-done.ts");
-  parts.push("-e", shellEscape(subagentDonePath));
-
   if (effectiveModel) {
     const model = effectiveThinking ? `${effectiveModel}:${effectiveThinking}` : effectiveModel;
     parts.push("--model", shellEscape(model));
@@ -1313,7 +1321,7 @@ async function launchSubagent(
   // auto-detect file paths and read their contents.
   if (identityInSystemPrompt && identity) {
     const flag = systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt";
-    const spTimestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const spTimestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, FILE_TIMESTAMP_LENGTH);
     const spSafeName = params.name
       .toLowerCase()
       .replace(/[^a-z0-9\s-]/g, "")
@@ -1363,33 +1371,22 @@ async function launchSubagent(
   }
   const envPrefix = envParts.join(" ") + " ";
 
-  // Pass task and skill prompts to the sub-agent.
-  // Only full-context fork mode gets a direct task argument because it already
-  // inherits the parent conversation. Blank-session modes use artifact-backed
-  // handoff so the wrapper instructions arrive as the initial user message.
-  let taskArg: string;
-  if (launchBehavior.taskDelivery === "direct") {
-    taskArg = fullTask;
-  } else {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-    const safeName = params.name
-      .toLowerCase()
-      .replace(/[^a-z0-9\s-]/g, "") // strip everything except alphanumeric, spaces, hyphens
-      .replace(/\s+/g, "-") // spaces to hyphens
-      .replace(/-+/g, "-") // collapse multiple hyphens
-      .replace(/^-|-$/g, ""); // trim leading/trailing hyphens
-    const artifactName = `context/${safeName || "subagent"}-${timestamp}.md`;
-    const artifactPath = join(artifactDir, artifactName);
-    mkdirSync(dirname(artifactPath), { recursive: true });
-    writeFileSync(artifactPath, fullTask, "utf8");
-    taskArg = `@${artifactPath}`;
-  }
-
-  for (const promptArg of buildPiPromptArgs({
-    effectiveSkills,
-    taskDelivery: launchBehavior.taskDelivery,
-    taskArg,
-  })) {
+  // Pass task and skill prompts to the child. The task is written to an
+  // artifact so wrapper instructions arrive as the initial user message.
+  const artifactTimestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, FILE_TIMESTAMP_LENGTH);
+  const safeName = params.name
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "") // strip everything except alphanumeric, spaces, hyphens
+    .replace(/\s+/g, "-") // spaces to hyphens
+    .replace(/-+/g, "-") // collapse multiple hyphens
+    .replace(/^-|-$/g, ""); // trim leading/trailing hyphens
+  const artifactName = `context/${safeName || "subagent"}-${artifactTimestamp}.md`;
+  const artifactPath = join(artifactDir, artifactName);
+  mkdirSync(dirname(artifactPath), { recursive: true });
+  writeFileSync(artifactPath, fullTask, "utf8");
+  const taskArg = `@${artifactPath}`;
+
+  for (const promptArg of buildPiPromptArgs({ effectiveSkills, taskArg })) {
     parts.push(shellEscape(promptArg));
   }
 
@@ -2042,11 +2039,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
         await new Promise<void>((resolve) => setTimeout(resolve, getShellReadyDelayMs()));
 
         // Build pi resume command
-        const parts = ["pi", "--session", shellEscape(params.sessionPath)];
-
-        // Load subagent-done extension so the agent can self-terminate if needed
-        const subagentDonePath = join(SUBAGENTS_DIR, "subagent-done.ts");
-        parts.push("-e", shellEscape(subagentDonePath));
+        const parts = ["pi", ...buildChildExtensionArgs(), "--session", shellEscape(params.sessionPath)];
 
         const sessionId = ctx.sessionManager.getSessionId();
         const artifactDir = getArtifactDir(ctx.sessionManager.getSessionDir(), sessionId);
@@ -2055,7 +2048,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
         let resumeMsgFile: string | undefined;
         if (params.message) {
-          const msgTimestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+          const msgTimestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, FILE_TIMESTAMP_LENGTH);
           resumeMsgFile = join(
             artifactDir,
             "subagent-resume",
@@ -2073,6 +2066,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
         // Build env prefix — propagate PI_CODING_AGENT_DIR for config isolation
         const resumeEnvParts: string[] = [];
+        const { allowSubagentSpawning } = loadSubagentSpawningConfig();
         if (process.env.PI_CODING_AGENT_DIR) {
           resumeEnvParts.push(`PI_CODING_AGENT_DIR=${shellEscape(process.env.PI_CODING_AGENT_DIR)}`);
         }
@@ -2080,6 +2074,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
         resumeEnvParts.push(`PI_SUBAGENT_SESSION=${shellEscape(params.sessionPath)}`);
         resumeEnvParts.push(`PI_SUBAGENT_ID=${shellEscape(id)}`);
         resumeEnvParts.push(`PI_SUBAGENT_ACTIVITY_FILE=${shellEscape(activityFile)}`);
+        resumeEnvParts.push(
+          `PI_DENY_TOOLS=${shellEscape([...resolveDenyTools(null, allowSubagentSpawning)].join(","))}`,
+        );
         if (autoExit) {
           resumeEnvParts.push(`PI_SUBAGENT_AUTO_EXIT=1`);
         }
@@ -2205,18 +2202,6 @@ export default function subagentsExtension(pi: ExtensionAPI) {
       },
     });
 
-  // /iterate command — fork the session into a subagent
-  pi.registerCommand("iterate", {
-    description: "Fork session into a subagent for focused work (bugfixes, iteration)",
-    handler: async (args, _ctx) => {
-      const task = args.trim() || "";
-      const toolCall = task
-        ? `Use subagent to fork a session. fork: true, name: "Iterate", task: ${JSON.stringify(task)}`
-        : `Use subagent to fork a session. fork: true, name: "Iterate", task: "The user wants to do some hands-on work. Help them with whatever they need."`;
-      pi.sendUserMessage(toolCall);
-    },
-  });
-
   // /subagent command — spawn a subagent by name
   pi.registerCommand("subagent", {
     description: "Spawn a subagent: /subagent <agent> <task>",

package/pi-extension/subagents/mux-config.ts

@@ -20,10 +20,22 @@ export interface SubagentHerdrModeConfig {
   source: SubagentMuxConfigSource;
 }
 
+export interface SubagentSpawningConfig {
+  allowSubagentSpawning: boolean;
+  source: SubagentMuxConfigSource;
+}
+
+export interface SubagentExtensionsConfig {
+  extensions: string[];
+  source: SubagentMuxConfigSource;
+}
+
 const BACKENDS: readonly MuxBackend[] = ["muxy", "cmux", "tmux", "zellij", "wezterm", "herdr", "otty", "orca"];
 const CONFIG_FILE = "config.json";
 const HERDR_MODE_ENV = "PI_SUBAGENT_HERDR_MODE";
 const DEFAULT_HERDR_MODE: HerdrSurfaceMode = HERDR_SURFACE_MODE_SPLIT;
+const DEFAULT_ALLOW_SUBAGENT_SPAWNING = false;
+const DEFAULT_SUBAGENT_EXTENSIONS: readonly string[] = [];
 
 function isMuxBackend(value: unknown): value is MuxBackend {
   return typeof value === "string" && (BACKENDS as readonly string[]).includes(value);
@@ -111,6 +123,29 @@ export function loadHerdrModeConfig(path = muxConfigPath()): SubagentHerdrModeCo
   return { herdrMode: DEFAULT_HERDR_MODE, source: "default" };
 }
 
+/** Read the global child-subagent spawning switch; disabled by default. */
+export function loadSubagentSpawningConfig(path = muxConfigPath()): SubagentSpawningConfig {
+  const stored = readConfigObject(path).allowSubagentSpawning;
+  if (typeof stored === "boolean") {
+    return { allowSubagentSpawning: stored, source: "file" };
+  }
+
+  return { allowSubagentSpawning: DEFAULT_ALLOW_SUBAGENT_SPAWNING, source: "default" };
+}
+
+/** Read the explicit extension list for child sessions; empty by default. */
+export function loadSubagentExtensionsConfig(path = muxConfigPath()): SubagentExtensionsConfig {
+  const stored = readConfigObject(path).subagentExtensions;
+  if (Array.isArray(stored) && stored.every((value) => typeof value === "string" && value.trim())) {
+    return {
+      extensions: stored.map((value) => value.trim()),
+      source: "file",
+    };
+  }
+
+  return { extensions: [...DEFAULT_SUBAGENT_EXTENSIONS], source: "default" };
+}
+
 /** Apply persisted mux and Herdr mode settings when no explicit environment override exists. */
 export function applyPersistedMuxPreference(path = muxConfigPath()): void {
   if (!environmentPreference()) {

package/pi-extension/subagents/session.ts

@@ -17,36 +17,10 @@ export interface MessageEntry extends SessionEntry {
   };
 }
 
-export type SeededSubagentSessionMode = "lineage-only" | "fork";
-
-function getForkContentLines(parentSessionFile: string): string[] {
-  const raw = readFileSync(parentSessionFile, "utf8");
-  const lines = raw.split("\n").filter((line) => line.trim());
-
-  let truncateAt = lines.length;
-  for (let i = lines.length - 1; i >= 0; i--) {
-    try {
-      const entry = JSON.parse(lines[i]);
-      if (entry.type === "message" && entry.message?.role === "user") {
-        truncateAt = i;
-        break;
-      }
-    } catch {
-      // ignore malformed lines
-    }
-  }
-
-  return lines.slice(0, truncateAt).filter((line) => {
-    try {
-      return JSON.parse(line).type !== "session";
-    } catch {
-      return true;
-    }
-  });
-}
+export const SUBAGENT_SESSION_MODE_STANDALONE = "standalone" as const;
+export const SUBAGENT_SESSION_MODE_LINEAGE_ONLY = "lineage-only" as const;
 
 export function seedSubagentSessionFile(params: {
-  mode: SeededSubagentSessionMode;
   parentSessionFile: string;
   childSessionFile: string;
   childCwd: string;
@@ -59,9 +33,7 @@ export function seedSubagentSessionFile(params: {
     cwd: params.childCwd,
     parentSession: params.parentSessionFile,
   };
-  const contentLines =
-    params.mode === "fork" ? getForkContentLines(params.parentSessionFile) : [];
-  const lines = [JSON.stringify(header), ...contentLines];
+  const lines = [JSON.stringify(header)];
 
   mkdirSync(dirname(params.childSessionFile), { recursive: true });
   writeFileSync(params.childSessionFile, lines.join("\n") + "\n", "utf8");