@gotgenes/pi-subagents 10.0.1 → 10.2.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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).
 
+## [10.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.1.0...pi-subagents-v10.2.0) (2026-05-27)
+
+
+### Features
+
+* **pi-subagents:** add run lifecycle methods to Agent ([2a378f1](https://github.com/gotgenes/pi-packages/commit/2a378f1c82e977bdfee25931ab449757e364d589))
+
+
+### Documentation
+
+* **pi-subagents:** update architecture for async startAgent ([941eb10](https://github.com/gotgenes/pi-packages/commit/941eb109e71e4c51d5bb37a2a46ffc12f618d949))
+* plan async startAgent and RunHandle dissolution ([#228](https://github.com/gotgenes/pi-packages/issues/228)) ([647adf8](https://github.com/gotgenes/pi-packages/commit/647adf853fec63ea53afd63bc8204c89a6194bbe))
+* **retro:** add planning stage notes for issue [#228](https://github.com/gotgenes/pi-packages/issues/228) ([8dd9f8a](https://github.com/gotgenes/pi-packages/commit/8dd9f8ab7082c08e424b1b4a9557253af2ce584b))
+* **retro:** add retro notes for issue [#227](https://github.com/gotgenes/pi-packages/issues/227) ([78a4d64](https://github.com/gotgenes/pi-packages/commit/78a4d645f524465c64bf0b6ba1bcca37858e8721))
+* **retro:** add TDD stage notes for issue [#228](https://github.com/gotgenes/pi-packages/issues/228) ([ab497c5](https://github.com/gotgenes/pi-packages/commit/ab497c57723666d0635a0a08f9eecc06576da549))
+
+## [10.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.0.1...pi-subagents-v10.1.0) (2026-05-27)
+
+
+### Features
+
+* **pi-subagents:** add abort() to AgentRecord ([bbc9dc7](https://github.com/gotgenes/pi-packages/commit/bbc9dc779d2ff845680f6de34d0ef33c10cdf124))
+* **pi-subagents:** add setupWorktree() to AgentRecord ([1786fdb](https://github.com/gotgenes/pi-packages/commit/1786fdb939d3e858d6453b71a43b9fb3c3346a88))
+* **pi-subagents:** add steer buffering to AgentRecord ([a22d8c7](https://github.com/gotgenes/pi-packages/commit/a22d8c77e8074e1fe9f396305267380d9f3558b3))
+
+
+### Bug Fixes
+
+* **pi-subagents:** remove unused AgentInit/AgentStatus re-exports from types.ts ([6789cb7](https://github.com/gotgenes/pi-packages/commit/6789cb72e26eefd54da4ff6ee5dd847c4fa78385))
+
+
+### Documentation
+
+* **pi-subagents:** archive Phase 14, advance to Phase 15 ([a8147fb](https://github.com/gotgenes/pi-packages/commit/a8147fb3f6be9af6d73089bbb42b40080e8e04a7))
+* **pi-subagents:** update architecture for Agent rename ([#227](https://github.com/gotgenes/pi-packages/issues/227)) ([f9afc88](https://github.com/gotgenes/pi-packages/commit/f9afc88dcc21213abe453baa032563ff37499ca9))
+* plan evolve AgentRecord into Agent with behavior ([#227](https://github.com/gotgenes/pi-packages/issues/227)) ([d56ff97](https://github.com/gotgenes/pi-packages/commit/d56ff97408063de6467149dc332e35d4078dd137))
+* replace \n with <br/> in Mermaid node labels ([3312a45](https://github.com/gotgenes/pi-packages/commit/3312a4559100cf9ae923f67819653b5a99fceb12))
+* **retro:** add planning stage notes for issue [#227](https://github.com/gotgenes/pi-packages/issues/227) ([ccd9788](https://github.com/gotgenes/pi-packages/commit/ccd9788ac619ae9f0380cb4b0c0b632efb0faf68))
+* **retro:** add retro notes for issue [#239](https://github.com/gotgenes/pi-packages/issues/239) ([58a19a1](https://github.com/gotgenes/pi-packages/commit/58a19a1e65d93c753ef7ba9c24e34d4ebb6f172d))
+* **retro:** add TDD stage notes for issue [#227](https://github.com/gotgenes/pi-packages/issues/227) ([66cf314](https://github.com/gotgenes/pi-packages/commit/66cf314aa4bef736a689d547e75e8bede1757f85))
+
 ## [10.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.0.0...pi-subagents-v10.0.1) (2026-05-27)
 
 

package/docs/architecture/architecture.md

@@ -34,44 +34,44 @@ The extension is organized around six domains, each responsible for one aspect o
 flowchart TB
     subgraph config["Config domain"]
         direction TB
-        AgentTypeRegistry["AgentTypeRegistry\n(registry of agent types)"]
-        DefaultAgents["default-agents\n(built-in types)"]
-        CustomAgents["custom-agents\n(user .md files)"]
-        InvocationConfig["invocation-config\n(per-call merge)"]
+        AgentTypeRegistry["AgentTypeRegistry<br/>(registry of agent types)"]
+        DefaultAgents["default-agents<br/>(built-in types)"]
+        CustomAgents["custom-agents<br/>(user .md files)"]
+        InvocationConfig["invocation-config<br/>(per-call merge)"]
     end
 
     subgraph session["Session domain"]
         direction TB
-        SessionConfig["assembleSessionConfig\n(pure assembler)"]
-        Prompts["prompts\n(system prompt)"]
-        Context["context\n(parent history)"]
-        SafeFs["safe-fs\n(symlink/name guards)"]
-        SkillLoader["skill-loader\n(preload skills)"]
-        Env["env\n(git/platform)"]
-        ModelResolver["model-resolver\n(fuzzy match)"]
+        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
 
     subgraph lifecycle["Lifecycle domain"]
         direction TB
-        AgentManager["AgentManager\n(spawn, queue, abort)"]
-        AgentRunner["agent-runner\n(session, turns, results)"]
-        AgentRecord["AgentRecord\n(status state machine)"]
-        ParentSnapshot["ParentSnapshot\n(frozen parent state)"]
-        Worktree["worktree\n(git isolation)"]
+        AgentManager["AgentManager<br/>(spawn, queue, abort)"]
+        AgentRunner["agent-runner<br/>(session, turns, results)"]
+        Agent["Agent<br/>(status, behavior: abort/steer/worktree/run lifecycle)"]
+        ParentSnapshot["ParentSnapshot<br/>(frozen parent state)"]
+        Worktree["worktree<br/>(git isolation)"]
     end
 
     subgraph observation["Observation domain"]
         direction TB
-        RecordObserver["record-observer\n(stats via events)"]
-        Notification["notification\n(completion nudges)"]
-        UIObserver["ui-observer\n(streaming state)"]
+        RecordObserver["record-observer<br/>(stats via events)"]
+        Notification["notification<br/>(completion nudges)"]
+        UIObserver["ui-observer<br/>(streaming state)"]
     end
 
     subgraph tools["Tools domain"]
         direction TB
-        AgentTool["subagent tool\n(dispatch)"]
-        ResultRenderer["result-renderer\n(pure rendering)"]
-        SpawnConfig["spawn-config\n(resolve params)"]
+        AgentTool["subagent tool<br/>(dispatch)"]
+        ResultRenderer["result-renderer<br/>(pure rendering)"]
+        SpawnConfig["spawn-config<br/>(resolve params)"]
         FgRunner["foreground-runner"]
         BgSpawner["background-spawner"]
         GetResult["get_subagent_result"]
@@ -80,9 +80,9 @@ flowchart TB
 
     subgraph ui["UI domain"]
         direction TB
-        Widget["agent-widget\n(live status)"]
-        ConvViewer["conversation-viewer\n(session overlay)"]
-        Menu["agent-menu\n(slash command)"]
+        Widget["agent-widget<br/>(live status)"]
+        ConvViewer["conversation-viewer<br/>(session overlay)"]
+        Menu["agent-menu<br/>(slash command)"]
     end
 
     AgentTool --> AgentManager
@@ -101,11 +101,11 @@ flowchart TB
 
 ```mermaid
 classDiagram
-    class AgentRecord {
+    class Agent {
         +id: string
         +type: SubagentType
         +description: string
-        +status: AgentRecordStatus
+        +status: AgentStatus
         +result?: string
         +error?: string
         +toolUses: number
@@ -120,16 +120,25 @@ classDiagram
         +markError()
         +markStopped()
         +resetForResume()
+        +abort(): boolean
+        +queueSteer(message)
+        +flushPendingSteers(session)
+        +setupWorktree(worktrees, isolation)
+        +completeRun(result, worktrees)
+        +failRun(err, worktrees)
+        +wireSignal(signal, onAbort)
+        +attachObserver(unsub)
+        +releaseListeners()
+        +setOnRunFinished(fn)
     }
 
     class AgentManager {
         +spawn(snapshot, type, prompt, config)
         +spawnAndWait(snapshot, type, prompt, config)
         +resume(id, snapshot, exec)
-        +getRecord(id): AgentRecord
-        +listAgents(): AgentRecord[]
+        +getRecord(id): Agent
+        +listAgents(): Agent[]
         +abort(id)
-        +queueSteer(id, message)
     }
 
     class AgentTypeRegistry {
@@ -157,7 +166,7 @@ classDiagram
         +hasRunning(): boolean
     }
 
-    AgentManager --> AgentRecord : creates/manages
+    AgentManager --> Agent : creates/manages
     AgentManager --> ParentSnapshot : receives at spawn
     SubagentsService --> AgentManager : wraps via adapter
     AgentManager --> AgentTypeRegistry : resolves types
@@ -216,10 +225,10 @@ sequenceDiagram
     Asm-->>Runner: SessionConfig
     Runner->>Child: create session + run turn loop
     Child-->>Runner: result text
-    Runner-->>Mgr: update AgentRecord
-    Note over Mgr: record-observer subscribes to session events for stats
+    Runner-->>Mgr: update Agent
+    Note over Mgr: agent-observer subscribes to session events for stats
     Note over Mgr: ui-observer subscribes for streaming state
-    Mgr-->>Tool: AgentRecord
+    Mgr-->>Tool: Agent
     Tool-->>LLM: formatted result
 ```
 
@@ -259,11 +268,10 @@ src/
 ├── lifecycle/                      agent execution and state tracking
 │   ├── agent-manager.ts            spawn, queue, abort, resume, concurrency
 │   ├── agent-runner.ts             session creation, turn loop, tool filtering
-│   ├── agent-record.ts             status state machine
+│   ├── agent.ts                    status state machine, per-agent behavior (abort, steer, worktree)
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── execution-state.ts          session/output phase state
 │   ├── permission-bridge.ts        optional bridge to pi-permission-system registry
-│   ├── run-handle.ts               per-run cleanup lifecycle
 │   ├── worktree.ts                 git worktree isolation
 │   ├── worktree-state.ts           worktree phase state
 │   └── usage.ts                    token usage tracking
@@ -504,7 +512,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `AgentToolDeps`             | 8                                                      | agent-tool                                        | ✓ done    |
 | `AgentMenuDeps`             | 8                                                      | agent-menu                                        | ✓ done    |
 | `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low       |
-| `AgentRecordInit`           | 8                                                      | agent-record                                      | Low       |
+| `AgentInit`                 | 8                                                      | agent                                             | Low       |
 
 ### Complexity hotspots
 
@@ -665,103 +673,11 @@ Phase 13 addressed remaining closure factories, the last fallow refactoring targ
 All six steps are closed: [#214], [#215], [#216], [#217], [#218], [#219].
 See [phase-13-remaining-smells.md](history/phase-13-remaining-smells.md) for details.
 
-## Improvement roadmap (Phase 14 — strip policy from core)
+## Phase 14 (complete)
 
-Phase 14 removes tool and extension policy enforcement from pi-subagents.
-This code duplicates what pi-permission-system already provides with richer semantics (allow/ask/deny vs. binary hide).
-Removing it simplifies `runAgent`, shrinks `AgentConfig` and `SessionConfig`, and makes the Phase 15 domain-model work operate on a cleaner codebase.
-
-### Findings summary
-
-| Finding                                                                                   | Category      | Impact | Risk | Priority |
-| ----------------------------------------------------------------------------------------- | ------------- | ------ | ---- | -------- |
-| `disallowed_tools` duplicates pi-permission-system's `permission:` frontmatter            | A: Overlap    | 4      | 2    | 12       |
-| `extensions: string[]` allowlist is tool filtering disguised as lifecycle control         | A: Overlap    | 3      | 2    | 9        |
-| `filterActiveTools` ran twice (pre-bind + post-bind) to catch extension-registered tools  | B: Complexity | 3      | 1    | ✓ done   |
-| `ToolFilterConfig` existed solely to carry filtering state through the runner             | C: Accidental | 2      | 1    | ✓ done   |
-| `Agent` tool name is PascalCase — misaligns with Pi's lowercase built-in convention       | D: Convention | 2      | 1    | 3        |
-
-### Step 1: Remove `disallowed_tools` — [#237] ✅ Complete
-
-Remove the `disallowedTools` field from `AgentConfig` and all code that processes it.
-
-1. Remove `disallowedTools` from the `AgentConfig` interface in `types.ts`.
-2. Remove `disallowed_tools` parsing from custom agent frontmatter in `custom-agents.ts`.
-3. Remove `disallowedSet` from `ToolFilterConfig` in `session-config.ts`.
-4. Remove the `disallowedSet` construction in `assembleSessionConfig`.
-5. Remove the `disallowedSet` branch from `filterActiveTools` in `agent-runner.ts`.
-6. Remove `disallowed_tools` from the agent config editor UI.
-7. Remove `disallowed_tools` from the agent creation wizard.
-8. Update tests.
-
-- Target: `types.ts`, `custom-agents.ts`, `session-config.ts`, `agent-runner.ts`, `ui/agent-config-editor.ts`, `ui/agent-creation-wizard.ts`
-- Smell: A (responsibility overlap with pi-permission-system)
-- Outcome: users migrate to `permission:` frontmatter for tool restrictions; single source of truth for access control
-
-### Step 2: Remove `extensions` filtering — [#238] ✅ Complete
-
-Remove the `extensions: string[]` allowlist and simplify the field to a boolean.
-The `extensions: false` case (used by `isolated`) is retained in this step and removed in Phase 16.
-
-1. Change `extensions` type from `true | string[] | false` to `boolean` in `AgentConfig`.
-2. Remove the `extensions` array branch from `filterActiveTools` in `agent-runner.ts`.
-3. Remove `extensions` from the agent config editor and creation wizard.
-4. Update custom agent frontmatter parsing to treat array values as `true` (with a warning).
-5. Update tests.
-
-- Target: `types.ts`, `agent-runner.ts`, `session-config.ts`, `ui/agent-config-editor.ts`, `ui/agent-creation-wizard.ts`
-- Smell: A (tool filtering disguised as extension lifecycle control)
-- Outcome: `filterActiveTools` reduces to two concerns: recursion guard and `extensions: false` passthrough
-
-### Step 3: Collapse `filterActiveTools` to recursion guard — [#239] ✅ Complete
-
-With Steps 1–2 complete, `filterActiveTools` had only two remaining branches: the `EXCLUDED_TOOL_NAMES` recursion guard and the `extensions === false` passthrough.
-Inlined the `extensions === false` passthrough into the callsite and reduced the function to its essential purpose.
-
-1. Simplified `filterActiveTools` to filter only `EXCLUDED_TOOL_NAMES`.
-2. Removed `ToolFilterConfig` — the function no longer needs a config bag.
-3. Removed the pre-bind filter call — extension tools aren't in the active set pre-bind, so the guard is a no-op there.
-4. Kept a single post-bind filter call for the recursion guard.
-5. Flattened `SessionConfig` — removed `toolFilter: ToolFilterConfig`; `toolNames` and `extensions` are top-level fields.
-6. Updated tests.
-
-- Target: `agent-runner.ts`, `session-config.ts`
-- Smell: B (accidental complexity), C (two-pass filter dance)
-- Outcome: `filterActiveTools` is a one-liner; `SessionConfig` loses one nested type; the pre-bind/post-bind dance is gone
-
-### Step 4: Rename `Agent` tool to `subagent` — [#242] ✅ Complete
-
-Rename the `Agent` tool to `subagent` to align with Pi's built-in tool naming convention (all lowercase: `read`, `bash`, `write`, `edit`, `find`, `grep`, `ls`).
-The PascalCase name was inherited from tintinweb/pi-subagents (mimicking Claude Code's convention), but Pi uses lowercase for all built-in tools.
-The companion tools are already lowercase snake_case (`get_subagent_result`, `steer_subagent`), and nicobailon/pi-subagents already uses `subagent`.
-
-1. Rename tool name from `"Agent"` to `"subagent"` in `agent-tool.ts`.
-2. Update `label` and `promptSnippet` in the tool definition.
-3. Update `EXCLUDED_TOOL_NAMES` in `agent-runner.ts`.
-4. Update the fallback display name in `agent-tool.ts`.
-5. Update architecture docs (tool references, domain diagrams, cross-extension section).
-6. Update pi-permission-system docs that reference the `Agent` tool name.
-7. Update tests.
-
-- Target: `tools/agent-tool.ts`, `lifecycle/agent-runner.ts`, `docs/`, `../pi-permission-system/docs/`
-- Smell: D (convention mismatch — PascalCase in a lowercase ecosystem)
-- Outcome: all three tools use consistent lowercase naming; aligns with Pi's built-in convention
-
-### Step dependency diagram
-
-```mermaid
-flowchart LR
-    S1["Step 1\nRemove disallowed_tools"]
-    S2["Step 2\nRemove extensions filtering"]
-    S3["Step 3\nCollapse filterActiveTools"]
-    S4["Step 4\nRename Agent to subagent"]
-
-    S1 --> S3
-    S2 --> S3
-```
-
-Steps 1, 2, and 4 are independent and can proceed in parallel.
-Step 3 depends on Steps 1 and 2.
+Phase 14 removed tool and extension policy enforcement from pi-subagents, eliminating overlap with pi-permission-system.
+All four steps are closed: [#237], [#238], [#239], [#242].
+See [phase-14-strip-policy.md](history/phase-14-strip-policy.md) for details.
 
 [#237]: https://github.com/gotgenes/pi-packages/issues/237
 [#238]: https://github.com/gotgenes/pi-packages/issues/238
@@ -773,23 +689,24 @@ Step 3 depends on Steps 1 and 2.
 Phase 15 addresses the anemic domain model in the lifecycle layer.
 `AgentRecord` is a data bag — identity, status transitions, and stats — but no behavior.
 `AgentManager` reaches into records 37 times, doing work that belongs on the agent.
-Per-agent state (pending steers, abort logic, run lifecycle) is scattered across the manager, `RunHandle`, and a manager-level Map.
+Per-agent state (pending steers, abort logic, run lifecycle) was scattered across the manager, `RunHandle`, and a manager-level Map.
+`RunHandle` has been dissolved into `Agent` methods — see Step 2.
 
 The scheduling concern (queue, concurrency counter, drain) is tangled into `AgentManager` alongside collection management and run orchestration.
 `notifyConcurrencyChanged()` is a scheduling method exposed as a public API so settings can poke the queue — a cross-concern leak.
 
 ### Findings summary
 
-| Finding                                                       | Category     | Impact | Risk | Priority |
-| ------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
-| `AgentRecord` is anemic — no behavior, manager reaches in 37× | B: Oversized | 5      | 3    | 15       |
-| Scheduling tangled into `AgentManager` (3 fields, 3 methods)  | A: Coupling  | 4      | 2    | 12       |
-| `startAgent` uses `.then()`/`.catch()` instead of async/await | C: Callbacks | 3      | 2    | 10       |
-| `onSessionCreated` callback flows through 3 layers            | C: Callbacks | 3      | 2    | 10       |
-| `resume()` duplicates observer subscribe/unsubscribe pattern  | A: Redundant | 2      | 1    | 8        |
-| `exec`/`registry` relay-only deps on `AgentManager`           | C: Coupling  | 2      | 1    | 6        |
+| Finding                                                           | Category     | Impact | Risk | Priority |
+| ----------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
+| `AgentRecord` is anemic — no behavior, manager reaches in 37×     | B: Oversized | 5      | 3    | 15       |
+| Scheduling tangled into `AgentManager` (3 fields, 3 methods)      | A: Coupling  | 4      | 2    | 12       |
+| ~~`startAgent` uses `.then()`/`.catch()` instead of async/await~~ | C: Callbacks | 3      | 2    | ✅       |
+| `onSessionCreated` callback flows through 3 layers                | C: Callbacks | 3      | 2    | 10       |
+| `resume()` duplicates observer subscribe/unsubscribe pattern      | A: Redundant | 2      | 1    | 8        |
+| `exec`/`registry` relay-only deps on `AgentManager`               | C: Coupling  | 2      | 1    | 6        |
 
-### Step 1: Evolve AgentRecord into Agent with behavior — [#227]
+### Step 1: Evolve AgentRecord into Agent with behavior — [#227] ✅ Complete
 
 Rename `AgentRecord` → `Agent` (or wrap it).
 Move per-agent behavior from `AgentManager` into the agent:
@@ -802,15 +719,17 @@ Move per-agent behavior from `AgentManager` into the agent:
 - Smell: B (anemic domain model) + C (manager reaching into records)
 - Outcome: `AgentManager` delegates via Tell-Don't-Ask; per-agent state lives on the agent
 
-### Step 2: Convert startAgent to async/await — [#228]
+### Step 2: Convert startAgent to async/await — [#228] ✅ Complete
 
-Convert `startAgent` from synchronous (returns void, assigns `record.promise` to a `.then()`/`.catch()` chain) to `async` (returns `Promise<void>`, uses try/catch).
+Converted `startAgent` to `async` with `try/catch` and dissolved `RunHandle` into `Agent` methods.
 `spawn()` assigns `record.promise = this.startAgent(...)` instead of calling `startAgent()` synchronously.
+`Agent` gained run lifecycle methods: `completeRun`, `failRun`, `wireSignal`, `attachObserver`, `releaseListeners`, `setOnRunFinished`.
+Worktree setup was hoisted to callers (`spawn`, `drainQueue`) to preserve the synchronous-throw contract.
 
 - Depends on: #227
-- Target: `src/lifecycle/agent-manager.ts`
+- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/agent.ts`
 - Smell: C (raw promise callbacks)
-- Outcome: zero `.then()`/`.catch()` in `agent-manager.ts`
+- Outcome: zero `.then()`/`.catch()` in `agent-manager.ts`; `RunHandle` deleted; Agent owns run lifecycle
 
 ### Step 3: Replace onSessionCreated callback with observer method — [#229]
 
@@ -840,10 +759,10 @@ Move them to `ConcreteAgentRunner` construction.
 - Smell: C (relay-only dependencies)
 - Outcome: `AgentManager` loses 2 fields; `AgentManagerOptions` shrinks from 7 to 5 fields
 
-### Step 6: Unify resume() with RunHandle pattern — [#232]
+### Step 6: Unify resume() with Agent run lifecycle methods — [#232]
 
-After #227 moves `RunHandle` ownership to the `Agent`, `resume()` on `AgentManager` becomes a 4-line delegation to `agent.resume(runner, prompt, signal)`.
-The agent manages its own observer subscription lifecycle.
+After #228 dissolved `RunHandle` into Agent methods (`completeRun`, `failRun`, `releaseListeners`), `resume()` on `AgentManager` becomes a short delegation to `agent.resume(runner, prompt, signal)`.
+The agent manages its own observer subscription lifecycle using the same methods that `startAgent` uses.
 
 - Depends on: #227, #228
 - Target: `src/lifecycle/agent-manager.ts`
@@ -854,12 +773,12 @@ The agent manages its own observer subscription lifecycle.
 
 ```mermaid
 flowchart LR
-    S1["Step 1\nAgent with behavior"]
-    S2["Step 2\nasync startAgent"]
-    S3["Step 3\nonSessionCreated observer"]
-    S4["Step 4\nConcurrencyQueue"]
-    S5["Step 5\nrelay deps"]
-    S6["Step 6\nresume unification"]
+    S1["Step 1<br/>Agent with behavior"]
+    S2["Step 2<br/>async startAgent"]
+    S3["Step 3<br/>onSessionCreated observer"]
+    S4["Step 4<br/>ConcurrencyQueue"]
+    S5["Step 5<br/>relay deps"]
+    S6["Step 6<br/>resume unification"]
 
     S1 --> S2
     S1 --> S6
@@ -896,7 +815,7 @@ By this point the core is minimal and stable — the API boundary has been prove
 
 ## Refactoring history
 
-Phases 1–5 and 7–12 are complete.
+Phases 1–5, 7–14 are complete.
 Phase 6 (UI extraction to a separate package) is deferred.
 Detailed records are preserved in per-phase history files:
 
@@ -915,7 +834,7 @@ Detailed records are preserved in per-phase history files:
 | 11       | Closure factories to classes                        | Complete                                                                         | [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md)                 |
 | 12       | Complexity reduction and test fixture extraction    | Complete                                                                         | [phase-12-complexity-test-fixtures.md](history/phase-12-complexity-test-fixtures.md) |
 | 13       | Remaining structural smells                         | Complete                                                                         | [phase-13-remaining-smells.md](history/phase-13-remaining-smells.md)                 |
-| 14       | Strip policy from core                              | Planned                                                                          | —                                                                                    |
+| 14       | Strip policy from core                              | Complete                                                                         | [phase-14-strip-policy.md](history/phase-14-strip-policy.md)                         |
 | 15       | Domain model evolution                              | Planned                                                                          | —                                                                                    |
 | 16       | Invert dependencies                                 | Planned                                                                          | —                                                                                    |
 | 17       | Extract UI to separate package                      | Planned                                                                          | —                                                                                    |
@@ -936,7 +855,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 11           | #192, #193, #194, #195, #196                               | SessionContext, runtime queries, interface alignment, tool classes, runner/menu classes, index.ts simplification                                         |
 | Phase 12           | #205, #206, #207, #208                                     | renderWidgetLines, showAgentDetail, widget update, shared test fixtures                                                                                  |
 | Phase 13           | #214, #215, #216, #217, #218, #219                         | Closure-to-class, buildParentContext, startAgent decomp, overwrite guard, settings SDK, test duplication                                                 |
-| Phase 14           | #237, #238, #239                                           | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools                                                                         |
+| Phase 14           | #237, #238, #239, #242                                     | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools, rename Agent to subagent                                               |
 | Phase 15           | #227, #228, #229, #230, #231, #232                         | Agent domain model, async startAgent, onSessionCreated observer, ConcurrencyQueue, relay deps, resume unification                                        |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.

package/docs/architecture/history/phase-14-strip-policy.md

@@ -0,0 +1,49 @@
+# Phase 14: Strip policy from core
+
+## Summary
+
+Phase 14 removed tool and extension policy enforcement from pi-subagents.
+This code duplicated what pi-permission-system already provides with richer semantics (allow/ask/deny vs. binary hide).
+Removing it simplified `runAgent`, shrunk `AgentConfig` and `SessionConfig`, and prepared a cleaner codebase for Phase 15's domain-model work.
+
+All four steps are closed: [#237], [#238], [#239], [#242].
+
+## Steps
+
+### Step 1: Remove `disallowed_tools` — [#237]
+
+Removed the `disallowedTools` field from `AgentConfig` and all code that processed it.
+Users migrate to `permission:` frontmatter for tool restrictions.
+
+- Target: `types.ts`, `custom-agents.ts`, `session-config.ts`, `agent-runner.ts`, `ui/agent-config-editor.ts`, `ui/agent-creation-wizard.ts`
+- Outcome: single source of truth for access control in pi-permission-system
+
+### Step 2: Remove `extensions` filtering — [#238]
+
+Removed the `extensions: string[]` allowlist and simplified the field to a boolean.
+The `extensions: false` case (used by `isolated`) was retained for Phase 16.
+
+- Target: `types.ts`, `agent-runner.ts`, `session-config.ts`, `ui/agent-config-editor.ts`, `ui/agent-creation-wizard.ts`
+- Outcome: `filterActiveTools` reduced to two concerns: recursion guard and `extensions: false` passthrough
+
+### Step 3: Collapse `filterActiveTools` to recursion guard — [#239]
+
+With Steps 1–2 complete, `filterActiveTools` was reduced to its essential purpose: filtering `EXCLUDED_TOOL_NAMES` to prevent recursive agent spawning.
+
+- Removed `ToolFilterConfig` — the function no longer needs a config bag.
+- Removed the pre-bind filter call — extension tools aren't in the active set pre-bind.
+- Flattened `SessionConfig` — removed `toolFilter: ToolFilterConfig`; `toolNames` and `extensions` are top-level fields.
+- Target: `agent-runner.ts`, `session-config.ts`
+- Outcome: `filterActiveTools` is a one-liner; the pre-bind/post-bind dance is gone
+
+### Step 4: Rename `Agent` tool to `subagent` — [#242]
+
+Renamed the `Agent` tool to `subagent` to align with Pi's built-in tool naming convention (all lowercase).
+
+- Target: `tools/agent-tool.ts`, `lifecycle/agent-runner.ts`, `docs/`, `../pi-permission-system/docs/`
+- Outcome: all three tools use consistent lowercase naming
+
+[#237]: https://github.com/gotgenes/pi-packages/issues/237
+[#238]: https://github.com/gotgenes/pi-packages/issues/238
+[#239]: https://github.com/gotgenes/pi-packages/issues/239
+[#242]: https://github.com/gotgenes/pi-packages/issues/242