@gotgenes/pi-subagents 7.8.1 → 9.0.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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).
 
+## [9.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v8.0.0...pi-subagents-v9.0.0) (2026-05-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* extensions field in agent frontmatter no longer supports a comma-separated allowlist. Values like `extensions: pi-github-tools, colgrep` are coerced to `true` (inherit all). Users who relied on per-extension filtering should migrate to `permission:` frontmatter in pi-permission-system.
+
+### Features
+
+* narrow extensions type from union to boolean ([90350ab](https://github.com/gotgenes/pi-packages/commit/90350abef259f5494990c5796a005f2edba2163d))
+
+
+### Documentation
+
+* mark Phase 14 Step 2 complete in architecture ([fc8bc57](https://github.com/gotgenes/pi-packages/commit/fc8bc57788a3ade9ec2f74200973e5a811c48bb3))
+* plan remove extensions filtering ([#238](https://github.com/gotgenes/pi-packages/issues/238)) ([1f4046a](https://github.com/gotgenes/pi-packages/commit/1f4046a84a308e80472425b5ca9e83263ecc310a))
+* **retro:** add planning stage notes for issue [#238](https://github.com/gotgenes/pi-packages/issues/238) ([b2ce842](https://github.com/gotgenes/pi-packages/commit/b2ce842dcc999fd48f6aeb67c6d464750d6d87aa))
+* **retro:** add retro notes for issue [#237](https://github.com/gotgenes/pi-packages/issues/237) ([6be215e](https://github.com/gotgenes/pi-packages/commit/6be215e6f4d9307f94b5bb61c024292a8eb77469))
+* **retro:** add TDD stage notes for issue [#238](https://github.com/gotgenes/pi-packages/issues/238) ([87256db](https://github.com/gotgenes/pi-packages/commit/87256dbd97ba4a69267f2091896d959bef9ff9df))
+* simplify extensions field to boolean in README ([b4028d7](https://github.com/gotgenes/pi-packages/commit/b4028d7c203fce792238acb147709ad3c3d4d28e))
+
+## [8.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.8.1...pi-subagents-v8.0.0) (2026-05-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* The `disallowed_tools` frontmatter field is no longer supported. Users should migrate to pi-permission-system's `permission:`
+
+### Features
+
+* remove disallowedTools from AgentConfig ([6044552](https://github.com/gotgenes/pi-packages/commit/6044552db68180bf8a151c0f64c13f264f3dacb9))
+
+
+### Documentation
+
+* add Phase 14 issue links, anemic-model and lifecycle-object smells to discovery skill ([9831176](https://github.com/gotgenes/pi-packages/commit/983117652937dce08e61a6cf7624e35ccf8a0dcb))
+* mark Phase 14 Step 1 complete in architecture ([d24e3dd](https://github.com/gotgenes/pi-packages/commit/d24e3dd5c664e63a372f399f9e325f1bdf877022))
+* **pi-subagents:** add Phase 14 issue links ([#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)) ([b152a75](https://github.com/gotgenes/pi-packages/commit/b152a75dcd6596468c5c0aeca1b36ac33216dfa8))
+* **pi-subagents:** add target architecture vision and renumber phases 14-17 ([f7e5315](https://github.com/gotgenes/pi-packages/commit/f7e5315bbfb088d7a40637deead1811691dec1bd))
+* **pi-subagents:** archive Phase 13, update metrics for Phase 14 ([9d473db](https://github.com/gotgenes/pi-packages/commit/9d473db1b0e420fa52ce9d09bea7afff75331e58))
+* plan removal of disallowed_tools ([#237](https://github.com/gotgenes/pi-packages/issues/237)) ([9cb600c](https://github.com/gotgenes/pi-packages/commit/9cb600cad9c8cc7b1081b021f039b0f36b9f9a44))
+* remove disallowed_tools from README and add migration note ([9b3905f](https://github.com/gotgenes/pi-packages/commit/9b3905fbaa81db47633c0c8edf21ed3b766d5507))
+* **retro:** add planning stage notes for issue [#237](https://github.com/gotgenes/pi-packages/issues/237) ([85460dd](https://github.com/gotgenes/pi-packages/commit/85460dd72949d7da83eaf9ed2196ff5c41d92f7f))
+* **retro:** add retro notes for issue [#219](https://github.com/gotgenes/pi-packages/issues/219) ([2d92af5](https://github.com/gotgenes/pi-packages/commit/2d92af577c0cfb71c575a5c334df2347840b4a8d))
+* **retro:** add TDD stage notes for issue [#237](https://github.com/gotgenes/pi-packages/issues/237) ([f334538](https://github.com/gotgenes/pi-packages/commit/f3345383a76975f09c0ee689edcb5df286b76fc7))
+
 ## [7.8.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.8.0...pi-subagents-v7.8.1) (2026-05-26)
 
 

package/README.md

@@ -31,7 +31,6 @@ Run them in foreground or background, steer them mid-run, resume completed sessi
 - **Persistent agent memory** — three scopes (project, local, user) with automatic read-only fallback for agents without write tools
 - **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
 - **Skill preloading** — inject named skills into agent system prompts, discovered from `.pi/skills/`, `.agents/skills/`, and global locations (Pi-standard `<name>/SKILL.md` directory layout supported)
-- **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
 - **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML.
   Expandable to show full output
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
@@ -176,10 +175,9 @@ All fields are optional — sensible defaults for everything.
 | `description`       | filename       | Agent description shown in tool listings                                                                                                                                                               |
 | `display_name`      | —              | Display name for UI (e.g. widget, agent list)                                                                                                                                                          |
 | `tools`             | all 7          | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools                                                                                                           |
-| `extensions`        | `true`         | Inherit MCP/extension tools. `false` to disable                                                                                                                                                        |
+| `extensions`        | `true`         | `true` to inherit all MCP/extension tools, `false` to disable                                                                                                                                          |
 | `skills`            | `true`         | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations)                                                |
 | `memory`            | —              | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents                                                                                                            |
-| `disallowed_tools`  | —              | Comma-separated tools to deny even if extensions provide them                                                                                                                                          |
 | `isolation`         | —              | Set to `worktree` to run in an isolated git worktree                                                                                                                                                   |
 | `model`             | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`)                                                                                                                                       |
 | `thinking`          | inherit        | off, minimal, low, medium, high, xhigh                                                                                                                                                                 |
@@ -356,8 +354,6 @@ Agents with write tools get full read-write access.
 **Read-only agents** (no `write`/`edit` tools) automatically get read-only memory — they can consume memories written by other agents but cannot modify them.
 This prevents unintended tool escalation.
 
-The `disallowed_tools` field is respected when determining write capability — an agent with `tools: write` + `disallowed_tools: write` correctly gets read-only memory.
-
 ## Worktree Isolation
 
 Set `isolation: worktree` to run an agent in a temporary git worktree:
@@ -408,18 +404,19 @@ Traversal is byte-order sorted for deterministic resolution across filesystems.
 **Security:** symlinks are rejected at every layer (root, flat file, skill directory, `SKILL.md` inside a skill directory) — intentional deviation from Pi, which follows symlinks.
 Skill names with path-traversal characters (`..`, `/`, `\`, spaces, leading dot, >128 chars) are rejected.
 
-## Tool Denylist
+## Migrating from `disallowed_tools`
 
-Block specific tools from an agent even if extensions provide them:
+The `disallowed_tools` frontmatter field has been removed.
+Use [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system)'s `permission:` frontmatter instead — it provides richer semantics (allow/ask/deny vs. binary hide):
 
 ```yaml
----
-tools: read, bash, grep, write
-disallowed_tools: write, edit
----
-```
+# Before (no longer supported)
+disallowed_tools: bash
 
-This is useful for creating agents that inherit extension tools but should not have write access.
+# After
+permission:
+  bash: deny
+```
 
 ## Permission System Integration
 
@@ -482,8 +479,7 @@ Each has a corresponding upstream PR:
 1. **Peer-dep migration to `@earendil-works/pi-*`** — `peerDependencies` and all imports point at `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` (the active scope on npm) instead of the deprecated `@mariozechner/pi-*` scope.
    Also fixes a latent bug where `ThinkingLevel` was imported from `pi-agent-core` (an undeclared transitive dep that breaks under pnpm).
    Upstream PR: [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71).
-2. **Post-`bindExtensions` active-tool re-filter** (`src/agent-runner.ts`) — `runAgent` re-runs its active-tool filter after `session.bindExtensions(...)` so extension-registered tools join the child's active tool set.
-   Without this, the `extensions: string[]` allowlist branch was functionally dead for extension tools, and `extensions: true` with a `disallowedTools` denylist let denylisted extension tools slip through.
+2. **Post-`bindExtensions` active-tool re-filter** (`src/agent-runner.ts`) — `runAgent` re-runs its active-tool filter after `session.bindExtensions(...)` so the `EXCLUDED_TOOL_NAMES` recursion guard applies to extension-registered tools (which join the active set during `bindExtensions`).
    Upstream PR: [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
 3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` prepends `<active_agent name="${config.name}"/>` to every assembled child system prompt (both `replace` and `append` modes).
    Downstream extensions like [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) parse this tag to resolve per-agent `permission:` frontmatter inside the child session.

package/docs/architecture/architecture.md

@@ -22,6 +22,9 @@ This document describes the architecture of the pi-subagents fork: a focused, co
    No post-construction field writes from external code — if an object can't be instantiated ready-to-go, the prep work hasn't been done and the right dependencies haven't been identified.
 9. **State owns its mutations** — mutable state lives in a class whose methods enforce valid transitions and invariants.
    Free functions that mutate module-scoped variables, closure-captured bags-of-functions, and external writes to shared interfaces are replaced by classes that encapsulate the state they manage.
+10. **Open for extension, closed for modification** — pi-subagents is a minimal core that publishes events and a service API.
+    Other packages (pi-permission-system, a future UI extension, hypothetical OTel integration) hook into these events to add permissions, rendering, or telemetry.
+    Pi-subagents has zero knowledge of its consumers — dependency arrows point inward, never outward.
 
 ## Domain model
 
@@ -222,7 +225,7 @@ sequenceDiagram
 
 ## Module organization
 
-The extension has 53 source files organized into six domains plus entry-point wiring.
+The extension has 56 source files organized into six domains plus entry-point wiring.
 All eight domains have directories: `config/`, `session/`, `lifecycle/`, `observation/`, `service/`, `tools/`, `ui/`, and `handlers/`.
 Issue #164 moved the 26 previously flat root-level files into five new domain directories, reducing the root to 5 files + 8 directories.
 
@@ -260,6 +263,7 @@ src/
 │   ├── 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
@@ -272,7 +276,7 @@ src/
 │
 ├── service/                        cross-extension API boundary
 │   ├── service.ts                  SubagentsService interface + Symbol.for() accessors
-│   └── service-adapter.ts          SubagentsService wrapper around AgentManager
+│   └── service-adapter.ts          SubagentsServiceAdapter class wrapping AgentManager
 │
 ├── tools/                          LLM-facing tool implementations
 │   ├── agent-tool.ts               Agent tool definition, validation, dispatch
@@ -288,8 +292,8 @@ src/
 │   ├── agent-widget.ts             above-editor live status widget
 │   ├── widget-renderer.ts          pure rendering for widget
 │   ├── agent-menu.ts               /agents slash command menu
-│   ├── agent-config-editor.ts      agent detail/edit view
-│   ├── agent-creation-wizard.ts    agent creation (AI + manual)
+│   ├── agent-config-editor.ts      agent detail/edit view (AgentConfigEditor class)
+│   ├── agent-creation-wizard.ts    agent creation (AgentCreationWizard class)
 │   ├── conversation-viewer.ts      scrollable session overlay
 │   ├── message-formatters.ts       pure per-message-type formatters (extracted from conversation-viewer)
 │   ├── agent-activity-tracker.ts   live activity state tracker
@@ -335,8 +339,9 @@ They declare this package as an optional peer dependency and use dynamic import
 
 - The three tools: `Agent`, `get_subagent_result`, `steer_subagent`.
 - `AgentManager` — spawn, queue, abort, resume, concurrency control.
-- `agent-runner` — session creation, turn loop, tool filtering, extension binding (Patches 2 and 3), permission-system registration.
+- `agent-runner` — session creation, turn loop, extension binding.
 - `permission-bridge` — optional cross-extension bridge to `@gotgenes/pi-permission-system`; registers each child session with `SubagentSessionRegistry` before `bindExtensions()` so the permission system detects in-process children deterministically.
+  Scheduled for removal in Phase 16 — replaced by lifecycle events that consumers listen for.
 - `session-config` — pure configuration assembler (extracted from `agent-runner`).
 - `SubagentRuntime` — session-scoped state bag with methods.
 - `ParentSnapshot` — immutable snapshot of parent session state, captured once at spawn time.
@@ -430,22 +435,56 @@ The core emits events on `pi.events` that any extension can observe:
 
 These are fire-and-forget broadcast events — no request IDs, no reply channels.
 
+## Target architecture
+
+The long-term architectural direction is to make pi-subagents a **minimal core** with inverted dependencies.
+Today, pi-subagents reaches outward to pi-permission-system via a bridge module and owns tool/extension filtering logic that duplicates permission-system responsibilities.
+The target state eliminates this overlap and flips the dependency direction.
+
+### Core responsibilities (keep)
+
+- **Agent definitions** — name, model, thinking, system prompt, tools list.
+- **Prompt composition** — system prompt assembly, skill preloading into prompt.
+- **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).
+- **Lifecycle events** — emit events on `pi.events` when child sessions are created, completed, etc.
+- **Service API** — publish `SubagentsService` via `Symbol.for()` for cross-extension access.
+
+### Responsibilities to remove
+
+- **Tool policy** (`disallowed_tools`, `ToolFilterConfig.disallowedSet`) — access control belongs in pi-permission-system's `permission:` frontmatter.
+- **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
+- **Permission bridge** (`permission-bridge.ts`) — outbound coupling to pi-permission-system.
+  Replaced by lifecycle events that pi-permission-system listens for.
+- **Extension lifecycle control** (`extensions: false`, `isolated`) — extensions provide behavioral layers (permissions, formatting, context management) that benefit all agents.
+  Blanket-disabling them is a blunt instrument with no clear use case; tool restrictions belong in the permission system.
+
+### Composition model
+
+In the target state, pi-subagents publishes events and other packages hook in:
+
+- **pi-permission-system** listens for child session lifecycle events, applies per-agent policy (allow/ask/deny), gates tool calls at runtime.
+- **pi-subagents-ui** (future) subscribes to the service API, renders the widget, conversation viewer, and `/agents` menu.
+- **Any future extension** (OTel, auditing, cost tracking) hooks into the same events without pi-subagents knowing.
+
+This is achieved across three phases: Phase 14 (strip policy), Phase 16 (invert dependencies), and Phase 17 (extract UI).
+
 ## Current structural analysis
 
 ### Health metrics
 
-| Metric                     | Value                                |
-| -------------------------- | ------------------------------------ |
-| Health score               | 78/100 (B)                           |
-| Total LOC                  | 8,180 (53 files)                     |
-| Test LOC                   | 12,026                               |
-| Dead code                  | 0 files, 0 exports                   |
-| Maintainability index      | 90.7 (good)                          |
-| Avg cyclomatic complexity  | 1.5                                  |
-| P90 cyclomatic complexity  | 2                                    |
-| Production duplication     | 20 lines (1 clone group)             |
-| Test duplication           | 59 clone groups, 1,046 lines         |
-| Fallow refactoring targets | 1 (buildParentContext, cognitive 30) |
+| Metric                     | Value                             |
+| -------------------------- | --------------------------------- |
+| Health score               | 78/100 (B)                        |
+| Total LOC                  | 8,382 (56 files)                  |
+| Dead code                  | 0 files, 0 exports                |
+| Maintainability index      | 90.8 (good)                       |
+| Avg cyclomatic complexity  | 1.4                               |
+| P90 cyclomatic complexity  | 2                                 |
+| Production duplication     | 11 lines (1 internal clone group) |
+| Test duplication           | 38 clone groups, 634 lines        |
+| Fallow refactoring targets | 0                                 |
 
 ### Dependency bag inventory
 
@@ -471,28 +510,29 @@ Bags with 10+ fields are the highest priority for decomposition.
 
 Functions with cyclomatic complexity ≥ 21 (critical threshold):
 
-No functions remain above the critical threshold — all hotspots resolved in Phase 12.
+No functions remain above the critical threshold — all hotspots resolved in Phase 12. 6 functions remain at HIGH severity (CRAP ≥ 65); 13 at moderate.
 
 ### Churn hotspots
 
-Files with highest commit frequency × complexity (accelerating trend):
+Files with highest commit frequency × complexity:
 
 | Score | File                        | Commits | Trend          |
 | ----- | --------------------------- | ------- | -------------- |
-| 43.3  | `index.ts`                  | 81      | ▲ accelerating |
-| 26.0  | `ui/agent-menu.ts`          | 33      | ▲ accelerating |
-| 13.6  | `tools/agent-tool.ts`       | 41      | ▲ accelerating |
-| 13.3  | `ui/conversation-viewer.ts` | 16      | ▲ accelerating |
-| 12.6  | `ui/agent-config-editor.ts` | 10      | ▼ cooling      |
-| 11.7  | `ui/agent-widget.ts`        | 14      | ▲ accelerating |
+| 65.0  | `index.ts`                  | 128     | ▲ accelerating |
+| 9.1   | `ui/agent-widget.ts`        | 13      | ▼ cooling      |
+| 8.4   | `ui/conversation-viewer.ts` | 11      | ─ stable       |
+| 6.4   | `runtime.ts`                | 12      | ─ stable       |
+| 3.3   | `settings.ts`               | 4       | ─ stable       |
+| 2.9   | `handlers/lifecycle.ts`     | 11      | ─ stable       |
 
-Note: accelerating trends reflect recent refactoring phases, not feature churn.
-Once structural work stabilizes, these are expected to cool.
+Most files have cooled to stable after 13 phases of structural work.
+`index.ts` remains the sole accelerating hotspot — expected as the wiring entry point for each refactoring phase.
 
 ### Production duplication
 
 The prior clone group between `agent-runner.ts` and `message-formatters.ts` was resolved in #172.
-The 20-line clone group between `agent-config-editor.ts` and `agent-creation-wizard.ts` was resolved in #217 — extracted into `ui/agent-file-writer.ts` (`writeAgentFile`). 0 production clone groups remain.
+The 20-line clone group between `agent-config-editor.ts` and `agent-creation-wizard.ts` was resolved in #217 — extracted into `ui/agent-file-writer.ts` (`writeAgentFile`).
+One 11-line internal clone group remains within `agent-config-editor.ts` (lines 135–145 / 173–183).
 
 ### Proposed bag decompositions
 
@@ -619,123 +659,97 @@ See [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md) for det
 Phase 12 decomposed the three remaining high-complexity UI functions and extracted shared test fixtures.
 All four steps are closed: [#205], [#206], [#207], [#208].
 
-## Improvement roadmap (Phase 13)
-
-Phase 13 addresses the remaining fallow refactoring target, `agent-manager.ts` oversized method, production duplication, SDK boundary coupling, and the heaviest test clone families.
-Health score target: 80+ (A).
-
-### Findings summary
-
-| Finding                                                          | Category       | Impact | Risk | Priority |
-| ---------------------------------------------------------------- | -------------- | ------ | ---- | -------- |
-| 3 remaining closure factories (Phase 11 survivors)               | C: Coupling    | 4      | 2    | 16       |
-| `buildParentContext` cognitive 30 (only fallow target)           | B: Oversized   | 3      | 1    | 15       |
-| `startAgent` in agent-manager.ts (~130 LOC method)               | B: Oversized   | 4      | 3    | 12       |
-| Test duplication: 59 clone groups, 1,046 lines                   | D: Testability | 3      | 2    | 12       |
-| Overwrite guard duplicated across UI modules (20 lines)          | A: Redundant   | 2      | 1    | 10       |
-| `settings.ts` calls SDK function `getAgentDir()` at module level | C: Coupling    | 2      | 1    | 10       |
-
-### Step 1: Convert remaining closure factories to classes — [#214] ✓
+## Phase 13 (complete)
 
-Three closure factories converted to classes in [#214].
+Phase 13 addressed remaining closure factories, the last fallow refactoring target, oversized methods, production duplication, SDK boundary coupling, and test clone families.
+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.
 
-| Factory → Class                                        | File                          | Captures                                 |
-| ------------------------------------------------------ | ----------------------------- | ---------------------------------------- |
-| `createAgentConfigEditor()` → `AgentConfigEditor`      | `ui/agent-config-editor.ts`   | `fileOps`, `registry`, 2 dirs            |
-| `createAgentCreationWizard()` → `AgentCreationWizard`  | `ui/agent-creation-wizard.ts` | `fileOps`, `manager`, `registry`, 2 dirs |
-| `createSubagentsService()` → `SubagentsServiceAdapter` | `service/service-adapter.ts`  | `manager`, `resolveModel`, `runtime`     |
+## Improvement roadmap (Phase 14 — strip policy from core)
 
-- Smell: C (coupling — deps hidden in closure scope instead of explicit on class)
-- Outcome: 0 remaining closure factories (excluding pure-function factories), deps visible as constructor parameters
+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.
 
-### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215] ✓
-
-`buildParentContext` in `session/context.ts` is the only remaining fallow refactoring target.
-The function loops over branch entries with 3 type-check branches, each with sub-branches for role or summary.
-Extract per-entry-type formatters: `formatMessageEntry(entry)` and `formatCompactionEntry(entry)`.
-
-- Target: `src/session/context.ts`
-- Smell: B (oversized function)
-- Outcome: cognitive complexity < 10, function < 15 LOC
-
-### Step 3: Decompose `startAgent` in `agent-manager.ts` — [#216] ✓
-
-`startAgent` had two mutable closure variables (`unsubRecordObserver`, `detachParentSignal`) shared across three callbacks with duplicated finalization logic in `.then()`/`.catch()`.
-The fix introduced a `RunHandle` lifecycle object (private to `agent-manager.ts`) that owns the per-run cleanup state and exposes `complete()`/`fail()` as Tell-Don't-Ask methods.
-`WorktreeState` gained `performCleanup(worktrees, description)` to eliminate the ask-tell dance at cleanup sites.
+### Findings summary
 
-Extracted:
+| 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` runs twice (pre-bind + post-bind) to catch extension-registered tools | B: Complexity | 3      | 1    | 6        |
+| `ToolFilterConfig` exists solely to carry filtering state through the runner              | C: Accidental | 2      | 1    | 4        |
 
-1. `RunHandle` class — owns `unsub`/`detachFn`, `wireSignal()`, `attachObserver()`, `complete()`, `fail()`, idempotent `fireOnFinished()`.
-2. `finalizeBackgroundRun(record)` — shared `runningBackground--`, crash-safe observer notification, `drainQueue()`.
-3. `setupWorktree(id, record, isolation)` — worktree creation with strict failure.
-4. `flushPendingSteers(id, session)` — drain buffered steers on session creation.
-5. `WorktreeState.performCleanup(worktrees, description)` — self-cleanup eliminating ask-tell.
+### Step 1: Remove `disallowed_tools` — [#237] ✅ Complete
 
-- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/worktree-state.ts`
-- Smell: B (oversized method) + A (duplicated finalization logic in then/catch)
-- Outcome: `startAgent` reduced to ~40 LOC coordinator with zero mutable `let` bindings; `.then()`/`.catch()` are one-liners
+Remove the `disallowedTools` field from `AgentConfig` and all code that processes it.
 
-### Step 4: Extract overwrite guard from UI — [#217] ✓
+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.
 
-The 20-line pattern duplicated between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` checks file existence, prompts for confirmation, writes the file, reloads the registry, and notifies the user.
-Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, label)` function.
+- 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
 
-- Target: new `src/ui/agent-file-writer.ts`, consumers `src/ui/agent-config-editor.ts` and `src/ui/agent-creation-wizard.ts`
-- Smell: A (production duplication)
-- Outcome: 0 production clone groups
+### Step 2: Remove `extensions` filtering — [#238] ✅ Complete
 
-### Step 5: Push SDK boundary in `settings.ts` — [#218] ✓
+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.
 
-`globalPath()` calls `getAgentDir()` (a Pi SDK function) at invocation time.
-This hides a platform dependency inside a module that is otherwise pure configuration logic.
-Inject `agentDir: string` as a constructor parameter to `SettingsManager` and pass the global settings path from the boundary in `index.ts`.
+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: `src/settings.ts`, `src/index.ts`
-- Smell: C (platform type threading)
-- Outcome: `settings.ts` has 0 Pi SDK imports, `loadSettings`/`saveSettings` become fully testable without SDK stubs
+- 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 6: Reduce test duplication — top 3 clone families — [#219]
+### Step 3: Collapse `filterActiveTools` to recursion guard — [#239]
 
-The three heaviest remaining clone families after Phase 12:
+With Steps 1–2 complete, `filterActiveTools` has only two remaining branches: the `EXCLUDED_TOOL_NAMES` recursion guard and the `extensions === false` passthrough.
+Inline the `extensions === false` passthrough into the callsite and reduce the function to its essential purpose.
 
-1. `agent-manager.test.ts` — 16 clone groups, 160 duplicated lines.
-   Extract shared setup/assertion helpers into `test/helpers/manager-stubs.ts`.
-2. `conversation-viewer.test.ts` — 8 clone groups, 91 duplicated lines.
-   Extract entry-builder helpers into existing `test/helpers/` or inline factory.
-3. `agent-config-editor.test.ts` — 5 clone groups, 42 duplicated lines.
-   Extract shared setup helpers.
+1. Simplify `filterActiveTools` to filter only `EXCLUDED_TOOL_NAMES`.
+2. Remove `ToolFilterConfig` — the function no longer needs a config bag.
+3. Remove the pre-bind filter call — extension tools aren't in the active set yet, so filtering built-in tools pre-bind is only needed for denylist/allowlist logic that no longer exists.
+4. Keep a single post-bind filter call for the recursion guard.
+5. Simplify `SessionConfig` — remove the `toolFilter` field, keep `toolNames` as a flat field.
+6. Update tests.
 
-- Target: `test/lifecycle/agent-manager.test.ts`, `test/conversation-viewer.test.ts`, `test/ui/agent-config-editor.test.ts`
-- Smell: D (test duplication)
-- Outcome: test duplication reduced by ~200 lines (from 1,046 to < 850)
+- 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 dependency diagram
 
 ```mermaid
 flowchart LR
-    S1["Step 1\nclosure to class"]
-    S2["Step 2\nbuildParentContext"]
-    S3["Step 3\nstartAgent decomp"]
-    S4["Step 4\noverwrite guard"]
-    S5["Step 5\nsettings SDK"]
-    S6["Step 6\ntest duplication"]
-
-    S1 --> S4
-    S1 --> S6
-    S3 --> S6
-    S2 ~~~ S5
+    S1["Step 1\nRemove disallowed_tools"]
+    S2["Step 2\nRemove extensions filtering"]
+    S3["Step 3\nCollapse filterActiveTools"]
+
+    S1 --> S3
+    S2 --> S3
 ```
 
-### Tracks
+Steps 1 and 2 are independent and can proceed in parallel.
+Step 3 depends on both.
 
-1. **Track A — Structural** (Steps 1, 3): closure-to-class conversions and method decomposition.
-2. **Track B — Complexity and coupling** (Steps 2, 5): independent, can proceed in parallel with Track A.
-3. **Track C — Duplication** (Steps 4, 6): Step 4 depends on Step 1 (overwrite guard lives in files being converted); Step 6 depends on Steps 1 and 3 (production code they test changes first).
+[#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
 
-## Improvement roadmap (Phase 14)
+## Improvement roadmap (Phase 15 — domain model evolution)
 
-Phase 14 addresses the anemic domain model in the lifecycle layer.
+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.
@@ -839,26 +853,51 @@ flowchart LR
    Sequential — each depends on the previous.
 2. **Track B — Decoupling** (Steps 3, 4, 5): independent, can proceed in parallel with Track A.
 
+## Improvement roadmap (Phase 16 — invert dependencies)
+
+Phase 16 completes the architectural inversion by removing the outbound permission bridge and the `extensions: false` / `isolated` concepts.
+It depends on Phase 15's observer pattern (#229) as the replacement mechanism.
+
+Phase 16 is scoped but not yet broken into steps.
+Key changes:
+
+1. Remove `permission-bridge.ts` — the outbound coupling to pi-permission-system.
+2. Emit child session lifecycle events via the observer — pi-permission-system and other consumers listen for these events instead of being called.
+3. Remove `extensions: false` — all child sessions load all extensions.
+4. Dissolve or redefine `isolated` — without extension control and tool filtering, the concept either disappears or becomes purely about prompt composition (no skill preloading, no parent context inheritance).
+5. Update pi-permission-system to listen for child session events instead of being registered by the bridge.
+
+## Improvement roadmap (Phase 17 — extract UI)
+
+Phase 17 is the long-deferred UI extraction (originally Phase 6).
+The widget, conversation viewer, and `/agents` command menu move to a separate `pi-subagents-ui` extension that consumes the `SubagentsService` API.
+By this point the core is minimal and stable — the API boundary has been proven across Phases 14–16.
+
 ## Refactoring history
 
 Phases 1–5 and 7–12 are complete.
 Phase 6 (UI extraction to a separate package) is deferred.
 Detailed records are preserved in per-phase history files:
 
-| Phase | Title                                               | Status   | History                                                                              |
-| ----- | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
-| 1     | Export SubagentsService API boundary                | Complete | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                           |
-| 2     | Remove scheduling subsystem                         | Complete | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)                 |
-| 3     | Remove group-join, RPC; replace output-file         | Complete | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
-| 4     | Implement and publish SubagentsService              | Complete | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
-| 5     | Decompose index.ts                                  | Complete | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
-| 6     | Extract UI to separate package                      | Deferred | —                                                                                    |
-| 7     | Encapsulation and dependency narrowing              | Complete | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
-| 8     | Testability, display extraction, menu decomposition | Complete | [phase-8-testability.md](history/phase-8-testability.md)                             |
-| 9     | Observation consolidation, ctx elimination          | Complete | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
-| 10    | Domain organization, bag decomposition, complexity  | Complete | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
-| 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) |
+| Phase    | Title                                               | Status                                                                           | History                                                                              |
+| -------- | --------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| 1        | Export SubagentsService API boundary                | Complete                                                                         | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                           |
+| 2        | Remove scheduling subsystem                         | Complete                                                                         | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)                 |
+| 3        | Remove group-join, RPC; replace output-file         | Complete                                                                         | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
+| 4        | Implement and publish SubagentsService              | Complete                                                                         | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
+| 5        | Decompose index.ts                                  | Complete                                                                         | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
+| 6        | Extract UI to separate package                      | Deferred → Phase 17                                                              | —                                                                                    |
+| 7        | Encapsulation and dependency narrowing              | Complete                                                                         | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
+| 8        | Testability, display extraction, menu decomposition | Complete                                                                         | [phase-8-testability.md](history/phase-8-testability.md)                             |
+| 9        | Observation consolidation, ctx elimination          | Complete                                                                         | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
+| 10       | Domain organization, bag decomposition, complexity  | Complete                                                                         | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
+| 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                                                                          | —                                                                                    |
+| 15       | Domain model evolution                              | Planned                                                                          | —                                                                                    |
+| 16       | Invert dependencies                                 | Planned                                                                          | —                                                                                    |
+| 17       | Extract UI to separate package                      | Planned                                                                          | —                                                                                    |
 
 ### Structural refactoring issues
 
@@ -876,7 +915,8 @@ 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           | #227, #228, #229, #230, #231, #232                         | Agent domain model, async startAgent, onSessionCreated observer, ConcurrencyQueue, relay deps, resume unification                                        |
+| Phase 14           | #237, #238, #239                                           | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools                                                                         |
+| 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.
 
@@ -909,3 +949,9 @@ The upstream test suite is run periodically as a regression canary for the agent
 [#217]: https://github.com/gotgenes/pi-packages/issues/217
 [#218]: https://github.com/gotgenes/pi-packages/issues/218
 [#219]: https://github.com/gotgenes/pi-packages/issues/219
+[#227]: https://github.com/gotgenes/pi-packages/issues/227
+[#228]: https://github.com/gotgenes/pi-packages/issues/228
+[#229]: https://github.com/gotgenes/pi-packages/issues/229
+[#230]: https://github.com/gotgenes/pi-packages/issues/230
+[#231]: https://github.com/gotgenes/pi-packages/issues/231
+[#232]: https://github.com/gotgenes/pi-packages/issues/232