@gotgenes/pi-subagents 12.0.0 → 13.0.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [13.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v12.1.0...pi-subagents-v13.0.0) (2026-05-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* the `skills:` custom-agent frontmatter key and skill preloading are removed; children always load the parent's skills.
+* the `extensions:` custom-agent frontmatter key is removed; children always load the parent's extensions.
+* `SpawnOptions.isolated` and the `isolated:` custom-agent frontmatter key are removed. Children always load the parent's extensions.
+
+### Features
+
+* always inherit extensions; make the recursion guard unconditional ([#264](https://github.com/gotgenes/pi-packages/issues/264)) ([3cc682e](https://github.com/gotgenes/pi-packages/commit/3cc682ec401167f922a1f892f6260a10f9fa99f2))
+* always inherit skills; remove noSkills and the skill-preload path ([#264](https://github.com/gotgenes/pi-packages/issues/264)) ([93266ff](https://github.com/gotgenes/pi-packages/commit/93266ff4a204d154b357efac57912330fad240be))
+* remove isolated from the subagent spawn API and lifecycle ([#264](https://github.com/gotgenes/pi-packages/issues/264)) ([d08f340](https://github.com/gotgenes/pi-packages/commit/d08f34066ea472d850423e67349b7a623ca72f42))
+
+## [12.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v12.0.0...pi-subagents-v12.1.0) (2026-05-29)
+
+
+### Features
+
+* export WorkspaceProvider collaborator types by name ([#272](https://github.com/gotgenes/pi-packages/issues/272)) ([1ff4697](https://github.com/gotgenes/pi-packages/commit/1ff4697a3033be445340d18af005a5d34fb5934d))
+
 ## [12.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.6.0...pi-subagents-v12.0.0) (2026-05-29)
 
 

package/dist/public.d.ts

@@ -25,7 +25,6 @@ interface AgentInvocation {
     modelName?: string;
     thinking?: ThinkingLevel;
     maxTurns?: number;
-    isolated?: boolean;
     inheritContext?: boolean;
     runInBackground?: boolean;
 }
@@ -125,7 +124,6 @@ interface SpawnOptions {
     model?: string;
     maxTurns?: number;
     thinkingLevel?: string;
-    isolated?: boolean;
     inheritContext?: boolean;
     foreground?: boolean;
     bypassQueue?: boolean;
@@ -167,4 +165,4 @@ declare function getSubagentsService(): SubagentsService | undefined;
 declare function unpublishSubagentsService(): void;
 
 export { SUBAGENT_EVENTS, getSubagentsService, publishSubagentsService, unpublishSubagentsService };
-export type { LifetimeUsage, SpawnOptions, SubagentRecord, SubagentStatus, SubagentsService, WorkspaceProvider };
+export type { LifetimeUsage, SpawnOptions, SubagentRecord, SubagentStatus, SubagentsService, Workspace, WorkspaceDisposeOutcome, WorkspaceDisposeResult, WorkspacePrepareContext, WorkspaceProvider };

package/docs/architecture/architecture.md

@@ -45,8 +45,6 @@ flowchart TB
         SessionConfig["assembleSessionConfig<br/>(pure assembler)"]
         Prompts["prompts<br/>(system prompt)"]
         Context["context<br/>(parent history)"]
-        SafeFs["safe-fs<br/>(symlink/name guards)"]
-        SkillLoader["skill-loader<br/>(preload skills)"]
         Env["env<br/>(git/platform)"]
         ModelResolver["model-resolver<br/>(fuzzy match)"]
     end
@@ -90,8 +88,7 @@ flowchart TB
     AgentManager --> AgentRunner
     AgentRunner --> SessionConfig
     SessionConfig --> AgentTypeRegistry
-    SessionConfig --> Prompts & SkillLoader & Env
-    SkillLoader --> SafeFs
+    SessionConfig --> Prompts & Env
     AgentTypeRegistry --> DefaultAgents & CustomAgents
     RecordObserver -.->|subscribes| AgentRunner
     UIObserver -.->|subscribes| AgentRunner
@@ -260,8 +257,6 @@ src/
 │   ├── prompts.ts                  system prompt building
 │   ├── content-items.ts            shared message content parsing (tool-call names, assistant content)
 │   ├── context.ts                  parent conversation extraction
-│   ├── safe-fs.ts                  symlink rejection and safe file reads
-│   ├── skill-loader.ts             skill preloading
 │   ├── env.ts                      git/platform detection
 │   ├── model-resolver.ts           fuzzy model name resolution
 │   └── session-dir.ts              session directory derivation
@@ -415,7 +410,7 @@ Key types:
 
 - `SubagentsService` — `spawn`, `getRecord`, `listAgents`, `abort`, `steer`, `waitForAll`, `hasRunning`.
 - `SubagentRecord` — serializable agent snapshot (no live session objects).
-- `SpawnOptions` — `description`, `model`, `maxTurns`, `thinkingLevel`, `isolated`, `inheritContext`, `foreground`, `bypassQueue`.
+- `SpawnOptions` — `description`, `model`, `maxTurns`, `thinkingLevel`, `inheritContext`, `foreground`, `bypassQueue`.
 - `SUBAGENT_EVENTS` — channel constants for `pi.events` subscriptions.
 
 ### Accessor pattern
@@ -482,11 +477,11 @@ Latent extensibility is the deliverable; a vacant hook is not.
 ### Core responsibilities (keep)
 
 - **Agent definitions** — name, model, thinking, system prompt, tools list.
-- **Prompt composition** — system prompt assembly, skill preloading into prompt.
+- **Prompt composition** — system prompt assembly.
 - **Session lifecycle** — create child sessions, bind extensions, run conversation loop, track results.
 - **Concurrency management** — queue, abort, resume, max concurrency.
 - **Recursion guard** — remove pi-subagents' own three tools from child sessions (prevent infinite nesting).
-  With `isolated` removed, children always load the parent's resources, so the guard becomes unconditional rather than gated on `cfg.extensions`.
+  With `isolated` removed (#264), children always load the parent's resources, so the guard is unconditional rather than gated on `cfg.extensions`.
   This is the core defending its own invariant, keyed off its own tool names — not policy.
 - **Lifecycle events** — emit awaited, ordered events when child sessions spawn, are created, complete, and are disposed.
 - **Workspace provider seam** — accept a registered `WorkspaceProvider` and consult it for the child's cwd; default to the parent's cwd when none is registered.
@@ -499,7 +494,8 @@ Latent extensibility is the deliverable; a vacant hook is not.
 - **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) — environment policy, not core.
   Git worktrees are one *strategy* for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
   Evicted to `@gotgenes/pi-subagents-worktrees` (#263), the first consumer of the workspace provider seam.
-- **Extension lifecycle control** (`extensions: false`, `isolated`, `noSkills`) — deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
+- **Extension lifecycle control** (`extensions: false`, `isolated`, `noSkills`) — removed in #264.
+  Deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
   Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
 
 ### Composition model
@@ -536,20 +532,20 @@ This is achieved across phases: Phase 14 (strip policy), Phase 16 (invert depend
 These interfaces carry hidden dependencies that obscure true coupling.
 Bags with 10+ fields are the highest priority for decomposition.
 
-| Interface                   | Fields                                                 | Consumers                                         | Severity  |
-| --------------------------- | ------------------------------------------------------ | ------------------------------------------------- | --------- |
-| `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done    |
-| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done    |
-| `RunOptions`                | 9 (`RunContext` nested)                                | agent-runner                                      | ✓ done    |
-| `SessionConfig`             | 8 (flat fields, ToolFilterConfig removed)              | agent-runner (output of assembler)                | ✓ done    |
-| `NotificationDetails`       | 10                                                     | notification                                      | Low (DTO) |
-| `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Low (SDK) |
-| `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done    |
-| `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Low (SDK) |
-| `AgentToolDeps`             | 8                                                      | agent-tool                                        | ✓ done    |
-| `AgentMenuDeps`             | 8                                                      | agent-menu                                        | ✓ done    |
-| `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low       |
-| `AgentInit`                 | 8                                                      | agent                                             | Low       |
+| Interface                   | Fields                                                      | Consumers                                         | Severity  |
+| --------------------------- | ----------------------------------------------------------- | ------------------------------------------------- | --------- |
+| `ResolvedSpawnConfig`       | 3 nested                                                    | foreground-runner, background-spawner, agent-tool | ✓ done    |
+| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                          | agent-manager (internal)                          | ✓ done    |
+| `RunOptions`                | 9 (`RunContext` nested)                                     | agent-runner                                      | ✓ done    |
+| `SessionConfig`             | 6 (flat fields; extensions/noSkills/extras removed in #264) | agent-runner (output of assembler)                | ✓ done    |
+| `NotificationDetails`       | 10                                                          | notification                                      | Low (DTO) |
+| `ResourceLoaderOptions`     | 10                                                          | agent-runner (SDK bridge)                         | Low (SDK) |
+| `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1)      | agent-runner                                      | ✓ done    |
+| `CreateSessionOptions`      | 9                                                           | agent-runner (SDK bridge)                         | Low (SDK) |
+| `AgentToolDeps`             | 8                                                           | agent-tool                                        | ✓ done    |
+| `AgentMenuDeps`             | 8                                                           | agent-menu                                        | ✓ done    |
+| `ConversationViewerOptions` | 8                                                           | conversation-viewer                               | Low       |
+| `AgentInit`                 | 8                                                           | agent                                             | Low       |
 
 ### Complexity hotspots
 
@@ -604,7 +600,6 @@ interface SpawnExecution {
   thinking: ThinkingLevel | undefined;
   inheritContext: boolean;
   runInBackground: boolean;
-  isolated: boolean;
   agentInvocation: AgentInvocation;
 }
 
@@ -648,7 +643,7 @@ export interface RunContext {
 }
 ```
 
-The remaining `RunOptions` fields (`model`, `maxTurns`, `signal`, `isolated`, `thinkingLevel`, `defaultMaxTurns`, `graceTurns`, `onSessionCreated`) are genuine execution parameters.
+The remaining `RunOptions` fields (`model`, `maxTurns`, `signal`, `thinkingLevel`, `defaultMaxTurns`, `graceTurns`, `onSessionCreated`) are genuine execution parameters.
 `RunOptions` now has 9 fields: 1 nested `context: RunContext` (2 per-call fields) plus 8 flat execution fields.
 
 #### SessionConfig (11 fields → extract ToolFilterConfig) — done ([#168][168])
@@ -761,7 +756,7 @@ Migrate `@gotgenes/pi-permission-system` to subscribe to `session-created`/`disp
 #### Step 2: Define the `WorkspaceProvider` seam — [#262] ✅ Delivered
 
 Added the `WorkspaceProvider` / `Workspace` interfaces (`src/lifecycle/workspace.ts`) and `SubagentsService.registerWorkspaceProvider` (single provider, throws on duplicate, returns an unregister disposer).
-Only `WorkspaceProvider` is named-re-exported from `service.ts`; `Workspace` and the context types resolve via inference when a consumer assigns to `WorkspaceProvider` (named re-exports of the collaborator types are tracked in #272).
+All five workspace types are named-re-exported from `service.ts`: `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult` (added in #272).
 At run-start `Agent.run()` consults the registered provider for the child's cwd and a disposal handle; with no provider the child runs in the parent's cwd (the legacy worktree-collaborator fallback was removed when worktrees left the core in #263).
 On completion the core calls `Workspace.dispose({ status, description })` and appends the returned `resultAddendum` verbatim — the provider owns the wording.
 
@@ -778,16 +773,17 @@ Removed `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `i
 
 - Supersedes #256.
   New package registered in `release-please-config.json` and `.pi/settings.json` (after pi-subagents); consumes the published `@gotgenes/pi-subagents` from the registry (`linkWorkspacePackages: false`), since `exports.types` resolves to the shipped declaration bundle.
-  Only `WorkspaceProvider` is importable by name from 11.6.0; the collaborator types are recovered via inference until #272 adds named re-exports.
+  From the release carrying #272, all five workspace types are importable by name: `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult`.
 - Outcome: git leaves the core; worktree users install one package, everyone else pays nothing.
 
-#### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264]
+#### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264] ✅ Delivered
 
-Children always load the parent's extensions and skills; the recursion guard becomes unconditional.
+Children always load the parent's extensions and skills; the recursion guard is now unconditional.
 Deny-at-use (the in-child permission layer) covers tool restriction; prevent-load is left as a latent provider seam (not shipped).
+The `skills` curation axis collapsed symmetrically with `extensions`: `AgentConfig.skills`, the skill-preload path (`skill-loader.ts`, `safe-fs.ts`, `preloadSkills`, `PromptExtras`), `SessionConfig.{extensions,noSkills,extras}`, and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are all gone.
 
-- Depends on: Step 1 (deny-at-use over events).
-- Outcome: the `isolated`/`extensions`/`noSkills` axis is gone; one fewer conditional in the guard.
+- Depended on: Step 1 (deny-at-use over events).
+- Outcome: the `isolated`/`extensions`/`noSkills`/`skills` axis is gone; the guard is unconditional.
 
 #### Step 5: Born-complete child execution; dissolve the runner — [#265]
 

package/docs/plans/0264-remove-extension-lifecycle-control.md

@@ -0,0 +1,275 @@
+---
+issue: 264
+issue_title: "Remove isolated / extensions:false / noSkills from core"
+---
+
+# Remove the extension-lifecycle-control axis from the core
+
+## Problem Statement
+
+The core still carries an extension-lifecycle-control axis — `isolated`, `extensions: false`, and `noSkills` — that lets a spawn blanket-disable a child's extensions and skills.
+Per ADR 0002, this is policy that does not belong in a minimal orchestrator.
+Deny-at-use (the in-child permission layer, shipped in Step 1 / #261) already covers what `isolated` pretended to do for tools.
+Prevent-load (refusing to bind an extension for true sandboxing) is genuinely generative and is deliberately left as a *latent, un-built* provider seam — we do not ship a vacant hook.
+
+This is Phase 16, Step 4.
+With the axis gone, children always load the parent's extensions and skills, and the recursion guard — which currently gates on `cfg.extensions` — becomes unconditional.
+
+## Goals
+
+- Remove `isolated` from the spawn API, `SubagentsService`, the lifecycle plumbing, and the config assembler.
+- Remove the `extensions` boolean from `AgentConfig` and the assembler (children always inherit extensions).
+- Remove `noSkills` from the assembler and the resource-loader options.
+- Collapse the skill-curation axis symmetrically: remove `AgentConfig.skills` and the skill-**preload** path (`skill-loader.ts`, `safe-fs.ts`, `preloadSkills`, `PromptExtras`, `extras.skillBlocks`).
+  Children always load Pi's full skill system, exactly as `skills: true` does today.
+- Make the recursion guard unconditional — it always strips `subagent` / `get_subagent_result` / `steer_subagent` from children, keyed off the core's own tool names.
+- This is a **breaking** change: the public `SpawnOptions.isolated` field and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are removed.
+  Suggested commits use `feat!:`.
+
+## Non-Goals
+
+- Born-complete child execution / dissolving the runner — that is Step 5 (#265) and depends on this step.
+  `RunOptions`, `runAgent`, `ConcreteAgentRunner`, and `Agent.run()` survive this issue (with `isolated` removed from them).
+- Shipping a prevent-load provider seam — ADR 0002 leaves it latent until a real consumer needs it.
+- Changing `builtinToolNames` (the `tools:` frontmatter allowlist) — that is a separate, surviving concern.
+- Changing deny-at-use behavior in `@gotgenes/pi-permission-system` — already in place from #261.
+
+## Background
+
+Relevant modules and how they relate:
+
+- `src/types.ts` — declares `AgentConfig` (`extensions`, `skills`, `isolated`) and `AgentInvocation` (`isolated`).
+- `src/config/default-agents.ts` — the three embedded agents set `extensions: true`, `skills: true`.
+- `src/config/custom-agents.ts` — parses `extensions` / `skills` / `isolated` from `.md` frontmatter via `resolveBoolExtensions` and `inheritField`.
+- `src/config/invocation-config.ts` — merges `isolated` from agent config + tool params.
+- `src/config/agent-types.ts` — an absolute-fallback `AgentConfig` literal sets `extensions: true`, `skills: true`.
+- `src/session/session-config.ts` — `assembleSessionConfig` derives `extensions`/`skills` from `options.isolated`, calls `io.preloadSkills` when `skills` is `string[]`, and computes `noSkills`.
+  Returns `SessionConfig.{ extensions, noSkills, extras }`.
+- `src/session/prompts.ts` — `buildAgentPrompt` injects `extras.skillBlocks` as `# Preloaded Skill:` sections; `PromptExtras` carries only `skillBlocks` (memory was removed in #185).
+- `src/session/skill-loader.ts` — `preloadSkills` reads named skill files from disk; consumes `safe-fs.ts`.
+- `src/session/safe-fs.ts` — symlink/path-traversal guards; **only consumer is `skill-loader.ts`**.
+- `src/lifecycle/agent-runner.ts` — `RunOptions.isolated` flows into the assembler; `createResourceLoader` is called with `noExtensions: !cfg.extensions` and `noSkills: cfg.noSkills`; the recursion guard runs only `if (cfg.extensions)`.
+  `ResourceLoaderOptions` (a local narrow interface, not the SDK type) declares `noExtensions?` / `noSkills?`.
+- `src/lifecycle/agent.ts` — `AgentInit.isolated`, the `_isolated` field, and `isolated:` in the `runner.run(...)` call.
+- `src/lifecycle/agent-manager.ts` — `AgentSpawnConfig.isolated` and its pass-through to `new Agent(...)`.
+- `src/tools/{agent-tool,spawn-config,foreground-runner,background-spawner}.ts` — tool schema `isolated`, `SpawnExecution.isolated`, and pass-through.
+- `src/service/{service,service-adapter}.ts` — public `SpawnOptions.isolated` and its pass-through to the manager.
+- `src/ui/{display,agent-config-editor,agent-creation-wizard}.ts` — `isolated` tag, eject-content emission, and generation-prompt template text.
+- `src/index.ts` — wires `preloadSkills` and `buildAgentPrompt` into `assemblerIO`.
+
+AGENTS.md constraints that apply:
+
+- Conventional Commits; breaking changes use `feat!:`.
+- Do not edit `CHANGELOG.md` (release-please owns it).
+- When removing an export, grep all `src/` and `test/` for the symbol before finalizing (done below).
+- When adding/removing a module, check `docs/architecture/` for layout listings and complexity tables that reference it (done below — Mermaid + tree + field tables).
+- One-sentence-per-line markdown; sequential numbering restarting per heading.
+
+## Design Overview
+
+This is a **symmetric collapse**, not a refactor.
+Two parallel axes leave the core together:
+
+| Axis       | Today                                                          | After                                         |
+| ---------- | -------------------------------------------------------------- | --------------------------------------------- |
+| Extensions | `extensions: true \| false`; `isolated` forces `false`         | always inherit (field gone)                   |
+| Skills     | `skills: true \| string[] \| false`; `isolated` forces `false` | always inherit full skill system (field gone) |
+
+The `skills` field collapses for the same reason `extensions` does: `noSkills` is the single mechanism behind **both** restriction modes (`skills: false` → no skills; `skills: string[]` → only those, preloaded into the prompt with the SDK loader suppressed).
+Removing `noSkills` without removing `AgentConfig.skills` would leave a field that silently stops restricting — a `string[]` agent would get its baked-in skills *plus* the full system.
+ADR 0002 says children always load the parent's skills, which is exactly the `skills: true` path; the other two values are skill curation/policy and leave the core.
+
+### Assembler after collapse
+
+`assembleSessionConfig` loses the `isolated` branch, the `preloadSkills` block, and the `noSkills`/`extensions`/`extras` outputs:
+
+```typescript
+export interface AssemblerOptions {
+  cwd?: string;
+  model?: unknown;
+  thinkingLevel?: ThinkingLevel;
+  // isolated removed
+}
+
+export interface SessionConfig {
+  effectiveCwd: string;
+  systemPrompt: string;
+  toolNames: string[];
+  model: unknown;
+  thinkingLevel: ThinkingLevel | undefined;
+  agentMaxTurns: number | undefined;
+  // extensions, noSkills, extras removed
+}
+```
+
+`AssemblerIO` drops `preloadSkills`, keeping only `buildAgentPrompt` (now called without `extras`).
+
+### Runner after collapse
+
+The resource-loader call drops the two suppression flags, and the guard runs unconditionally:
+
+```typescript
+const loader = deps.io.createResourceLoader({
+  cwd: cfg.effectiveCwd,
+  agentDir,
+  noPromptTemplates: true,
+  noThemes: true,
+  noContextFiles: true,
+  systemPromptOverride: () => cfg.systemPrompt,
+  appendSystemPromptOverride: () => [],
+  // noExtensions, noSkills removed
+});
+// ...
+await session.bindExtensions({});
+// Recursion guard — now unconditional (children always load extensions).
+const filtered = filterActiveTools(session.getActiveToolNames());
+session.setActiveToolsByName(filtered);
+```
+
+`ResourceLoaderOptions` drops `noExtensions?` / `noSkills?` (a local narrow interface — removing the latent fields keeps us honest per ADR 0002's "no vacant hooks").
+
+### Call-site sketch — recursion guard (Tell-Don't-Ask check)
+
+The guard already asks the session for its active tools and tells it the filtered set — unchanged except for removing the `if`.
+No new collaborator, no reach-through; the only structural change is that `cfg.extensions` is no longer consulted, so `SessionConfig` no longer needs to expose it.
+This is a narrowing of the assembler's output contract, which is the desired direction.
+
+### Edge cases
+
+- Append-mode agents: `parentSystemPrompt` still embeds parent context via `systemPromptOverride`; nothing about that path depends on skills/extensions flags.
+- Custom agents with legacy `extensions:` / `skills:` / `isolated:` frontmatter: the keys are silently ignored after this change (no parse, no warning).
+  `resolveBoolExtensions` already warned on the deprecated allowlist syntax; that warning path is removed with the parser.
+- The absolute-fallback `AgentConfig` in `agent-types.ts` drops `extensions`/`skills` like every other construction site.
+
+## Module-Level Changes
+
+### Source — `isolated` axis
+
+- `src/types.ts` — remove `AgentConfig.isolated`, `AgentInvocation.isolated`.
+- `src/config/invocation-config.ts` — remove `isolated` from `AgentInvocationParams` and the return object.
+- `src/config/custom-agents.ts` — remove the `isolated:` frontmatter parse.
+- `src/session/session-config.ts` — remove `AssemblerOptions.isolated` and the `options.isolated ? false : ...` derivation (read `agentConfig.extensions`/`agentConfig.skills` directly, for now).
+- `src/lifecycle/agent-runner.ts` — remove `RunOptions.isolated` and the `isolated:` argument passed to `assembleSessionConfig`.
+- `src/lifecycle/agent.ts` — remove `AgentInit.isolated`, the `_isolated` field + constructor assignment, and `isolated:` in the `runner.run(...)` call.
+- `src/lifecycle/agent-manager.ts` — remove `AgentSpawnConfig.isolated` and its pass-through to `new Agent(...)`.
+- `src/tools/agent-tool.ts` — remove the `isolated` schema property.
+- `src/tools/spawn-config.ts` — remove `SpawnExecution.isolated`, the `const isolated = resolvedConfig.isolated`, `isolated` in `agentInvocation`, and `isolated` in the `execution` return.
+- `src/tools/foreground-runner.ts` / `src/tools/background-spawner.ts` — remove `isolated: execution.isolated`.
+- `src/service/service.ts` — remove `SpawnOptions.isolated`.
+- `src/service/service-adapter.ts` — remove `isolated: options?.isolated` from the `manager.spawn(...)` call.
+- `src/ui/display.ts` — remove `if (invocation.isolated) tags.push("isolated")` and the `isolated` mention in the JSDoc example.
+- `src/ui/agent-config-editor.ts` — remove the `isolated: true` line from `buildEjectContent`.
+- `src/ui/agent-creation-wizard.ts` — remove the `isolated:` template line and the "Set isolated: true …" guideline.
+
+### Source — `extensions` axis + unconditional guard
+
+- `src/types.ts` — remove `AgentConfig.extensions`.
+- `src/config/default-agents.ts` — remove `extensions: true` from all three agents.
+- `src/config/agent-types.ts` — remove `extensions: true` from the absolute-fallback literal.
+- `src/config/custom-agents.ts` — remove the `extensions:` frontmatter parse and delete `resolveBoolExtensions`.
+- `src/session/session-config.ts` — remove `SessionConfig.extensions` and stop assigning it.
+- `src/lifecycle/agent-runner.ts` — remove `ResourceLoaderOptions.noExtensions`, drop `noExtensions` from the `createResourceLoader` call, and make the recursion guard unconditional (delete `if (cfg.extensions)`); update the explanatory comment.
+- `src/ui/agent-config-editor.ts` — remove the `extensions: false` line from `buildEjectContent`.
+- `src/ui/agent-creation-wizard.ts` — remove the `extensions:` template line.
+
+### Source — `skills` axis + preload path
+
+- `src/types.ts` — remove `AgentConfig.skills`.
+- `src/config/default-agents.ts` — remove `skills: true` from all three agents.
+- `src/config/agent-types.ts` — remove `skills: true` from the absolute-fallback literal.
+- `src/config/custom-agents.ts` — remove the `skills:` frontmatter parse and delete `inheritField` (its only remaining callers are `skills`/`extensions`; `csvList`, `parseCsvField`, `str`, `nonNegativeInt` stay — `csvList` still serves `tools:`).
+- `src/session/session-config.ts` — remove `AssemblerIO.preloadSkills`, `SessionConfig.noSkills`, `SessionConfig.extras`, the `extras`/`preloadSkills` block, and the `extras` argument to `buildAgentPrompt`.
+- `src/session/prompts.ts` — remove `PromptExtras`, the `extras` parameter, and the `extrasSuffix` logic.
+- `src/session/skill-loader.ts` — **delete** (export `preloadSkills`, `PreloadedSkill`).
+- `src/session/safe-fs.ts` — **delete** (sole consumer was `skill-loader.ts`).
+- `src/lifecycle/agent-runner.ts` — remove `ResourceLoaderOptions.noSkills` and drop `noSkills` from the `createResourceLoader` call.
+- `src/index.ts` — remove the `preloadSkills` import and its `assemblerIO.preloadSkills` wiring.
+- `src/ui/agent-config-editor.ts` — remove the `skills: false` / `skills: <list>` lines from `buildEjectContent`.
+- `src/ui/agent-creation-wizard.ts` — remove the `skills:` template line.
+
+### Tests
+
+- `test/session/skill-loader.test.ts` — **delete**.
+- `test/session/safe-fs.test.ts` — **delete**.
+- `test/session/session-config.test.ts` — remove the `isolated`-mode `describe`, the `noSkills` assertions, and the preload tests; keep model-resolution and prompt-assembly assertions.
+- `test/session/prompts.test.ts` — remove `isolated`/`extensions`/`skills` from `AgentConfig` fixtures and any `skillBlocks`/`extras` cases.
+- `test/config/invocation-config.test.ts` — remove `isolated` cases and fixture fields.
+- `test/config/custom-agents.test.ts` — remove `extensions` / `skills` / `isolated` frontmatter-parsing tests.
+- `test/config/agent-types.test.ts` — remove `extensions` / `skills` / `isolated` from fixtures.
+- `test/lifecycle/agent-runner-extension-tools.test.ts` — remove `extensions`/`skills`/`isolated` from the mock config; delete the "extensions: false skips the filter entirely" test; keep/adjust the post-bind guard tests to assert the guard runs unconditionally.
+- `test/tools/spawn-config.test.ts` — remove the "sets isolated from params" test and `isolated` fixture fields.
+- `test/tools/background-spawner.test.ts` / `test/tools/foreground-runner.test.ts` — remove `isolated` from fixtures and `agentInvocation` assertions.
+- `test/tools/result-renderer.test.ts` — remove the `"isolated"` tag case.
+- `test/ui/agent-config-editor.test.ts` — remove the `isolated` / `extensions: false` eject-emission tests.
+- `test/display.test.ts` — remove `extensions`/`skills` from `AgentConfig` fixtures.
+- `test/helpers/runner-io.ts` — remove `extensions`/`skills`/`isolated` from `DEFAULT_AGENT_CONFIG`.
+- `test/helpers/runner-io.test.ts` — remove the `config.extensions`/`config.skills` assertions and the `extensions: true` override case.
+- `test/helpers/ui-stubs.ts` — remove `extensions: true` / `skills: true` from the stub `AgentConfig`.
+
+### Docs
+
+- `docs/architecture/architecture.md` —
+  remove the `SafeFs` and `SkillLoader` nodes from the session-domain Mermaid subgraph;
+  remove `safe-fs.ts` and `skill-loader.ts` from the directory-tree listing;
+  drop `isolated` from the `SpawnOptions` field list (≈ line 418) and the `RunOptions` field list (≈ line 651);
+  mark Phase 16 Step 4 (#264) done in the roadmap and update the "Children always load the parent's extensions and skills" note;
+  reflect the smaller session domain (8 → 6 modules).
+- `.pi/skills/package-pi-subagents/SKILL.md` — update the Session domain row (module count 8 → 6, drop `safe-fs.ts` / `skill-loader.ts` from the file list).
+
+## Test Impact Analysis
+
+1. New coverage enabled — minimal (this is a removal).
+   The one behavioral assertion worth strengthening: the post-bind recursion guard now runs **unconditionally**.
+   Update `agent-runner-extension-tools.test.ts` so a case that previously relied on `extensions: true` instead asserts the guard always calls `setActiveToolsByName` and always excludes `EXCLUDED_TOOL_NAMES`, with no config dependence.
+2. Tests that become redundant and are removed —
+   `skill-loader.test.ts` and `safe-fs.test.ts` (modules deleted);
+   the `isolated`-mode `describe` in `session-config.test.ts`;
+   the "extensions: false skips the filter entirely" case;
+   `isolated` parameter tests in `spawn-config.test.ts` / `invocation-config.test.ts`;
+   `extensions` / `skills` frontmatter-parsing tests in `custom-agents.test.ts`.
+3. Tests that must stay (genuinely exercise surviving layers) —
+   prompt assembly (`prompts.test.ts`, minus `extras`);
+   model resolution in `session-config.test.ts`;
+   the post-bind guard ordering tests (adjusted, not removed);
+   custom-agent `tools:` parsing (`csvList` survives).
+
+## TDD Order
+
+Each cycle ends green (`pnpm run check` + `pnpm -r run test`).
+Because removing a field from `AgentConfig` / `AgentInvocation` breaks every reader and every object-literal construction site at once (TS excess-property + property-access), each cycle folds its test updates into the same commit (per the testing skill's removal rule).
+The three axes are split so each commit stays reviewable and leaves the repo compiling.
+
+1. Remove the `isolated` axis end-to-end.
+   Surface: `types.ts` (`AgentConfig.isolated`, `AgentInvocation.isolated`), `invocation-config.ts`, `custom-agents.ts` (parse only), `session-config.ts` (`AssemblerOptions.isolated` + derivation), `agent-runner.ts` (`RunOptions.isolated`), `agent.ts`, `agent-manager.ts`, `tools/*`, `service*.ts`, `ui/*` (isolated bits), plus all listed tests.
+   After: `extensions`/`skills`/`noSkills` still function; the assembler reads `agentConfig.extensions`/`agentConfig.skills` directly.
+   Commit: `feat!: remove isolated from the subagent spawn API and lifecycle (#264)`.
+2. Remove the `extensions` axis; make the recursion guard unconditional.
+   Surface: `types.ts` (`AgentConfig.extensions`), `default-agents.ts`, `agent-types.ts` (fallback), `custom-agents.ts` (parse + delete `resolveBoolExtensions`), `session-config.ts` (`SessionConfig.extensions`), `agent-runner.ts` (`ResourceLoaderOptions.noExtensions`, drop `noExtensions` arg, unconditional guard), `ui/agent-config-editor.ts` + `ui/agent-creation-wizard.ts` (extensions bits), plus tests (including the guard-always-runs update and deleting the "skips filter" case).
+   Commit: `feat!: always inherit extensions; make the recursion guard unconditional (#264)`.
+3. Remove the `skills` axis, `noSkills`, and the skill-preload path.
+   Surface: `types.ts` (`AgentConfig.skills`), `default-agents.ts`, `agent-types.ts` (fallback), `custom-agents.ts` (parse + delete `inheritField`), `session-config.ts` (`AssemblerIO.preloadSkills`, `SessionConfig.noSkills`/`extras`, preload block, `buildAgentPrompt` call), `prompts.ts` (`PromptExtras`/`extras`/`extrasSuffix`), delete `skill-loader.ts` + `safe-fs.ts`, `agent-runner.ts` (`ResourceLoaderOptions.noSkills`, drop arg), `index.ts` (wiring), `ui/*` (skills bits), plus tests (delete `skill-loader.test.ts` + `safe-fs.test.ts`).
+   Commit: `feat!: always inherit skills; remove noSkills and the skill-preload path (#264)`.
+4. Update the architecture doc and package skill.
+   Surface: `docs/architecture/architecture.md` (Mermaid session subgraph, directory tree, `SpawnOptions`/`RunOptions` field lists, roadmap status), `.pi/skills/package-pi-subagents/SKILL.md` (session domain row).
+   Commit: `docs: record removal of the extension-lifecycle-control axis (#264)`.
+
+## Risks and Mitigations
+
+- Risk: `resolveBoolExtensions` / `inheritField` deletion removes a helper still used elsewhere.
+  Mitigation: greps confirm `resolveBoolExtensions` is used only by the removed `extensions` parse, and `inheritField` only by `extensions`/`skills`; `csvList`/`parseCsvField` (used by `tools:`) stay.
+- Risk: deleting `safe-fs.ts` orphans an import.
+  Mitigation: grep confirms `skill-loader.ts` is its sole consumer; `safe-fs.test.ts` is deleted in the same cycle.
+- Risk: removing `SpawnOptions.isolated` breaks a published consumer of the service.
+  Mitigation: this is an intentional breaking change (ADR 0002); `feat!:` triggers a major bump via release-please.
+  The public type surface is verified by `pnpm run verify:public-types` after Step 3.
+- Risk: skill behavior silently changes for agents that relied on `skills: string[]` curation.
+  Mitigation: documented in Goals as breaking; children now inherit the full skill system, which is strictly more capable, and deny-at-use governs what they may act on.
+- Risk: a test file is touched in multiple cycles (e.g. `runner-io.ts`).
+  Mitigation: each cycle removes only the field it owns; ordering is fixed (isolated → extensions → skills) so no cycle leaves a dangling reference.
+
+## Open Questions
+
+- Should custom-agent `.md` files with now-defunct `extensions:` / `skills:` / `isolated:` frontmatter emit a one-time deprecation warning, or be silently ignored?
+  Deferred: silent-ignore matches the Phase 14 precedent for the removed `disallowed_tools` field; revisit only if users report confusion.
+- Does `verify:public-types` need a new negative assertion that `isolated` is absent from `SpawnOptions`?
+  Deferred to Step 3 implementation — the existing consumer type-check will fail if a stale field lingers.

package/docs/plans/0272-export-workspace-collaborator-types.md

@@ -0,0 +1,147 @@
+---
+issue: 272
+issue_title: "Export WorkspaceProvider collaborator types by name from the public surface"
+---
+
+# Export `WorkspaceProvider` collaborator types by name from the public surface
+
+## Problem Statement
+
+`@gotgenes/pi-subagents` re-exports the `WorkspaceProvider` seam by name from its public surface, but not the four collaborator types that seam references: `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult`.
+Those types are inlined into the bundled declaration (rolled in because `WorkspaceProvider` references them) but never exported by name.
+A consumer implementing the seam — `@gotgenes/pi-subagents-worktrees` (#263) — cannot `import type { Workspace, WorkspacePrepareContext } from "@gotgenes/pi-subagents"`.
+Instead it recovers the names through indexed-access gymnastics (`Parameters<WorkspaceProvider["prepare"]>[0]`, `NonNullable<Awaited<ReturnType<...>>>`).
+That compiles and is type-safe, but every seam consumer has to repeat the same incantation rather than importing the names directly.
+
+## Goals
+
+- Re-export `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult` by name from `src/service/service.ts`, alongside `WorkspaceProvider`.
+- Confirm the four names land in the bundled `dist/public.d.ts` and are importable by an external consumer.
+- Extend the verification harness (`scripts/verify-public-types.sh`) so its symbol guard and probe consumer assert the four names are present and importable.
+- `feat:` — adds names to the publishable public API surface (purely additive, non-breaking).
+
+## Non-Goals
+
+- No change to `src/lifecycle/workspace.ts` — the four interfaces already exist there with the right shapes; this issue only re-exports them.
+- No change to the runtime accessor functions, `SubagentsService`, `SpawnOptions`, `SubagentRecord`, or `SUBAGENT_EVENTS`.
+- No edits to `@gotgenes/pi-subagents-worktrees`.
+  Replacing its indexed-access aliases with named imports and bumping its `@gotgenes/pi-subagents` dependency is deferred to that package — it can only consume these names after `pi-subagents` cuts a new release carrying them (the registry-consumption model settled in #270).
+- No source restructuring of the entry's type closure (out of scope per #270's design; the rollup bundle already inlines the closure).
+- No new vitest unit test — the re-exports are type-only and erase at runtime, so they are verified by the type-level `verify:public-types` harness, not by the runtime suite.
+
+## Background
+
+Relevant modules:
+
+- `packages/pi-subagents/src/service/service.ts` — the public entry.
+  It currently imports `type { WorkspaceProvider } from "#src/lifecycle/workspace"` and `type { LifetimeUsage } from "#src/lifecycle/usage"`, and ends with `export type { LifetimeUsage, ..., WorkspaceProvider }`.
+  A standing comment already anticipates this issue: "Named re-exports of those collaborator types are tracked in #272."
+- `packages/pi-subagents/src/lifecycle/workspace.ts` — defines all four collaborator interfaces plus `WorkspaceProvider`.
+  `WorkspacePrepareContext` carries `agentId`, `agentType`, `baseCwd`, and optional `invocation`; `WorkspaceDisposeOutcome` carries `status` and `description`; `WorkspaceDisposeResult` carries optional `resultAddendum`; `Workspace` carries `readonly cwd` and `dispose(outcome)`.
+- `packages/pi-subagents/rollup.dts.config.mjs` — rolls `src/service/service.ts` into a self-contained `dist/public.d.ts`, inlining `#src/*` types and keeping `@earendil-works/*` external.
+  No config change is needed: once the names are exported from the entry, `rollup-plugin-dts` carries the (already-inlined) declarations through as named exports.
+- `packages/pi-subagents/scripts/verify-public-types.sh` — the CI-backed verification harness.
+  It packs the tarball, runs a self-containment guard (`grep '#src'`), loops a symbol-presence guard (`for sym in getSubagentsService WorkspaceProvider SubagentsService LifetimeUsage`), then type-checks a throwaway `probe.ts` consumer against the packaged tarball.
+
+Constraints from `AGENTS.md` and the package skill:
+
+- Ship-source model with one build step: `build:types` (rollup) regenerates `dist/public.d.ts` at `prepack`; `dist/` is gitignored and must never be committed.
+- Run `pnpm run verify:public-types` after any change to the public surface — it is also a CI step.
+- Open-for-extension/closed-for-modification: pi-subagents is a minimal core; re-exporting collaborator types of an existing seam is consistent with that boundary (no new behavior, no consumer knowledge).
+
+## Design Overview
+
+The change is additive and type-only.
+`service.ts` already imports the seam's entry type; extend that import to bring in the four collaborator types, then list them in the existing `export type { … }`.
+
+Import and re-export shape after the change:
+
+```typescript
+import type { LifetimeUsage } from "#src/lifecycle/usage";
+import type {
+  Workspace,
+  WorkspaceDisposeOutcome,
+  WorkspaceDisposeResult,
+  WorkspacePrepareContext,
+  WorkspaceProvider,
+} from "#src/lifecycle/workspace";
+
+export type {
+  LifetimeUsage,
+  SpawnOptions,
+  SubagentRecord,
+  SubagentStatus,
+  SubagentsService,
+  Workspace,
+  WorkspaceDisposeOutcome,
+  WorkspaceDisposeResult,
+  WorkspacePrepareContext,
+  WorkspaceProvider,
+};
+```
+
+Consumer call site this enables (the pattern that motivates the issue):
+
+```typescript
+import type {
+  Workspace,
+  WorkspaceDisposeOutcome,
+  WorkspaceDisposeResult,
+  WorkspacePrepareContext,
+  WorkspaceProvider,
+} from "@gotgenes/pi-subagents";
+
+const provider: WorkspaceProvider = {
+  async prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined> {
+    return { cwd: ctx.baseCwd, dispose: (_outcome: WorkspaceDisposeOutcome) => undefined };
+  },
+};
+```
+
+Edge cases:
+
+- The standing comment in `service.ts` ("Named re-exports of those collaborator types are tracked in #272") becomes stale once the re-exports land — update it to describe the current state rather than a tracked future.
+- `WorkspaceProvider` already pulls the four collaborator declarations into the rollup bundle by reference, so adding the named exports does not change the bundle's self-containment (the `grep '#src'` guard stays green).
+
+## Module-Level Changes
+
+- `packages/pi-subagents/src/service/service.ts` — widen the `#src/lifecycle/workspace` type import to include `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult`; add the same four names to the `export type { … }` block; replace the "tracked in #272" comment with a present-tense description of the seam's named re-exports.
+- `packages/pi-subagents/scripts/verify-public-types.sh` — add the four names to the `for sym in …` symbol-presence guard, and extend the inline `probe.ts` to import and exercise the four types by name (e.g. annotate a `prepare` implementation with `WorkspacePrepareContext`/`Workspace` and reference `WorkspaceDisposeOutcome`/`WorkspaceDisposeResult`).
+
+No architecture-doc updates are required: `docs/architecture/architecture.md` lists `workspace.ts` under the Lifecycle domain but does not enumerate the public surface's named exports, and no complexity/health table references this change.
+
+## Test Impact Analysis
+
+This is a type-only re-export change, not an extraction or refactor.
+
+1. New tests enabled: none at the vitest level — type-only re-exports erase at runtime and cannot be observed by the runtime suite.
+   The meaningful new assertion is at the type level: the extended `verify:public-types` probe proves the four names are importable from the packaged tarball, and the symbol guard proves they appear in `dist/public.d.ts`.
+2. Redundant existing tests: none.
+   `test/service/service.test.ts` exercises the runtime accessors and `SUBAGENT_EVENTS`; it is unaffected and stays as-is.
+3. Tests that must stay as-is: the full vitest suite (the regression canary) and `test/lifecycle/agent.test.ts` (which imports `Workspace`/`WorkspaceProvider` from `#src/lifecycle/workspace` internally — unrelated to the public re-export).
+
+## TDD Order
+
+The "test surface" here is the type-level verification harness, which is the red→green loop for a type-only public-surface change.
+
+1. Extend the verification harness (red → green in one step).
+   Add the four names to the `for sym in …` guard in `scripts/verify-public-types.sh` and extend the inline `probe.ts` to import them by name.
+   Run `pnpm run verify:public-types` to confirm it fails (red) because the names are absent from `dist/public.d.ts` and the probe import is unresolved.
+   Then add the import and `export type` entries in `src/service/service.ts` and update the standing comment, and re-run `pnpm run verify:public-types` to confirm it passes (green).
+   Harness change and source change land together because the type checker proves them as a unit — a packaged-tarball probe cannot import names the entry does not yet export.
+   Commit: `feat: export WorkspaceProvider collaborator types by name (#272)`.
+
+The harness step and the source step are bundled into a single commit deliberately: splitting them would leave the repo in a state where `verify:public-types` (a CI step) fails between commits.
+
+## Risks and Mitigations
+
+- Risk: the rollup bundle does not surface the new names as named exports.
+  Mitigation: `rollup-plugin-dts` carries through whatever the entry exports; the symbol guard + probe in `verify:public-types` prove the names land in `dist/public.d.ts` and are importable.
+- Risk: committing the generated `dist/public.d.ts`.
+  Mitigation: `dist/` is gitignored and regenerated at `prepack`; the plan commits only `service.ts` and the harness script.
+- Risk: stale comment misleads future readers.
+  Mitigation: the comment update is part of the same step.
+
+## Open Questions
+
+- The downstream simplification in `@gotgenes/pi-subagents-worktrees` (swap indexed-access aliases for named imports, bump the `@gotgenes/pi-subagents` dependency) is intentionally deferred until a `pi-subagents` release carries these exports — it is tracked with #263's follow-up, not this plan.