@gotgenes/pi-subagents 7.8.1 → 8.0.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [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
@@ -179,7 +178,6 @@ All fields are optional — sensible defaults for everything.
 | `extensions`        | `true`         | Inherit 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
 
@@ -483,7 +480,7 @@ Each has a corresponding upstream PR:
    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.
+   Without this, the `extensions: string[]` allowlist branch was functionally dead for extension tools.
    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]
 
-### 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

package/docs/architecture/history/phase-13-remaining-smells.md

@@ -0,0 +1,88 @@
+# Phase 13: Remaining structural smells
+
+## Summary
+
+Phase 13 addressed the remaining 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].
+
+## Steps
+
+### Step 1: Convert remaining closure factories to classes — [#214]
+
+Three closure factories converted to classes, making their dependencies explicit as constructor parameters.
+
+| Factory → Class                                        | File                          |
+| ------------------------------------------------------ | ----------------------------- |
+| `createAgentConfigEditor()` → `AgentConfigEditor`      | `ui/agent-config-editor.ts`   |
+| `createAgentCreationWizard()` → `AgentCreationWizard`  | `ui/agent-creation-wizard.ts` |
+| `createSubagentsService()` → `SubagentsServiceAdapter` | `service/service-adapter.ts`  |
+
+- Outcome: 0 remaining closure factories (excluding pure-function factories)
+
+### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215]
+
+`buildParentContext` in `session/context.ts` was the only remaining fallow refactoring target.
+Extracted per-entry-type formatters: `formatMessageEntry()` and `formatCompactionEntry()`.
+
+- Target: `src/session/context.ts`
+- Outcome: cognitive complexity < 10, function < 15 LOC, 0 fallow refactoring targets
+
+### Step 3: Decompose `startAgent` in `agent-manager.ts` — [#216]
+
+`startAgent` had two mutable closure variables and duplicated finalization logic in `.then()`/`.catch()`.
+Introduced `RunHandle` lifecycle object (private to `agent-manager.ts`) that owns per-run cleanup state.
+`WorktreeState` gained `performCleanup()` to eliminate ask-tell at cleanup sites.
+
+Extracted:
+
+1. `RunHandle` class — owns `unsub`/`detachFn`, `complete()`, `fail()`, idempotent `fireOnFinished()`.
+2. `finalizeBackgroundRun()` — shared background finalization.
+3. `setupWorktree()` — worktree creation with strict failure.
+4. `flushPendingSteers()` — drain buffered steers on session creation.
+5. `WorktreeState.performCleanup()` — self-cleanup eliminating ask-tell.
+
+- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/worktree-state.ts`
+- Outcome: `startAgent` reduced to ~40 LOC; zero mutable `let` bindings in `.then()`/`.catch()`
+
+### Step 4: Extract overwrite guard from UI — [#217]
+
+Extracted the 20-line pattern duplicated between `agent-config-editor.ts` and `agent-creation-wizard.ts` into `writeAgentFile()` in `src/ui/agent-file-writer.ts`.
+
+- Target: new `src/ui/agent-file-writer.ts`
+- Outcome: 0 production clone groups (at the time; one internal group re-emerged later in `agent-config-editor.ts`)
+
+### Step 5: Push SDK boundary in `settings.ts` — [#218]
+
+Injected `agentDir: string` as a constructor parameter to `SettingsManager`, replacing the module-level `getAgentDir()` SDK call.
+
+- Target: `src/settings.ts`, `src/index.ts`
+- Outcome: `settings.ts` has 0 Pi SDK imports; `loadSettings`/`saveSettings` fully testable without SDK stubs
+
+### Step 6: Reduce test duplication — top 3 clone families — [#219]
+
+Extracted shared setup/assertion helpers for the three heaviest test clone families.
+
+- Target: `test/lifecycle/agent-manager.test.ts`, `test/conversation-viewer.test.ts`, `test/ui/agent-config-editor.test.ts`
+- Outcome: test duplication significantly reduced
+
+## Metrics change
+
+| Metric                     | Before                 | After                             |
+| -------------------------- | ---------------------- | --------------------------------- |
+| Health score               | 78/100 (B)             | 78/100 (B)                        |
+| Source files               | 53                     | 56                                |
+| Total LOC                  | 8,180                  | 8,382                             |
+| Dead code                  | 0 files, 0 exports     | 0 files, 0 exports                |
+| Maintainability index      | 90.7                   | 90.8                              |
+| Avg cyclomatic complexity  | 1.5                    | 1.4                               |
+| Fallow refactoring targets | 1                      | 0                                 |
+| Production duplication     | 0 clone groups         | 1 internal clone group (11 lines) |
+| Test duplication           | 59 groups, 1,046 lines | 38 groups, 645 lines (overall)    |
+| Churn hotspots             | 6 accelerating         | 1 accelerating (`index.ts`)       |
+
+[#214]: https://github.com/gotgenes/pi-packages/issues/214
+[#215]: https://github.com/gotgenes/pi-packages/issues/215
+[#216]: https://github.com/gotgenes/pi-packages/issues/216
+[#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

package/docs/plans/0237-remove-disallowed-tools.md

@@ -0,0 +1,180 @@
+---
+issue: 237
+issue_title: "Remove disallowed_tools from pi-subagents (Phase 14, Step 1)"
+---
+
+# Remove `disallowed_tools` from pi-subagents
+
+## Problem Statement
+
+The `disallowed_tools` frontmatter field and its runtime counterpart `disallowedSet` duplicate what pi-permission-system already provides via the `permission:` frontmatter with richer semantics (allow/ask/deny vs. binary hide).
+Removing it establishes a single source of truth for tool access control in pi-permission-system and simplifies `filterActiveTools`, `ToolFilterConfig`, and `AgentConfig`.
+
+## Goals
+
+- Remove the `disallowedTools` field from `AgentConfig` and all code that reads, parses, or serializes it.
+- Remove the `disallowedSet` field from `ToolFilterConfig` and the construction logic in `assembleSessionConfig`.
+- Remove the `disallowedSet` branch from `filterActiveTools` in `agent-runner.ts`.
+- Remove `disallowed_tools` from the agent config editor UI and the agent creation wizard.
+- Update README.md to remove all `disallowed_tools` references and add a migration note.
+- Update tests to remove `disallowedTools`/`disallowedSet` assertions and fixture data.
+- This is a **breaking change** — users with `disallowed_tools` in agent frontmatter must migrate to `permission:` frontmatter.
+
+## Non-Goals
+
+- Removing `extensions` filtering (Step 2, #238).
+- Collapsing `filterActiveTools` to a recursion guard (Step 3, #239).
+- Changing any pi-permission-system code — this issue is purely pi-subagents.
+- Adding deprecation warnings or runtime migration helpers — the architecture doc calls for clean removal.
+
+## Background
+
+### Phase 14 context
+
+This is Phase 14, Step 1 of the architecture roadmap in `docs/architecture/architecture.md`.
+Steps 1 and 2 (#237, #238) are independent; Step 3 (#239) depends on both.
+
+### Files involved
+
+| File                              | Role                                                                       |
+| --------------------------------- | -------------------------------------------------------------------------- |
+| `src/types.ts`                    | `AgentConfig.disallowedTools` field definition                             |
+| `src/config/custom-agents.ts`     | Parses `disallowed_tools` from YAML frontmatter                            |
+| `src/session/session-config.ts`   | `ToolFilterConfig.disallowedSet` + construction in `assembleSessionConfig` |
+| `src/lifecycle/agent-runner.ts`   | `filterActiveTools` denylist branch + guard conditions at two call sites   |
+| `src/ui/agent-config-editor.ts`   | Serializes `disallowedTools` to `disallowed_tools` frontmatter             |
+| `src/ui/agent-creation-wizard.ts` | Template text showing `disallowed_tools` as an available field             |
+| `README.md`                       | Feature list, frontmatter table, memory detection note, patch notes        |
+
+### `filterActiveTools` after this change
+
+With `disallowedSet` removed, the function simplifies:
+
+```typescript
+function filterActiveTools(
+  activeTools: string[],
+  config: ToolFilterConfig,
+): string[] {
+  const { toolNames, extensions } = config;
+  if (extensions === false) {
+    return activeTools;
+  }
+  const builtinToolNameSet = new Set(toolNames);
+  return activeTools.filter((t) => {
+    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
+    if (builtinToolNameSet.has(t)) return true;
+    if (Array.isArray(extensions)) {
+      return extensions.some((ext) => t.startsWith(ext) || t.includes(ext));
+    }
+    return true;
+  });
+}
+```
+
+The `extensions === false` branch becomes a trivial passthrough — no filtering at all.
+The guard condition at both call sites simplifies from `cfg.toolFilter.extensions !== false || cfg.toolFilter.disallowedSet` to `cfg.toolFilter.extensions !== false`.
+
+## Design Overview
+
+This is a pure removal — no new types, no new modules, no new behavior.
+Every change deletes or simplifies existing code.
+
+### Migration path
+
+Users currently using `disallowed_tools` in agent frontmatter migrate to pi-permission-system's `permission:` frontmatter:
+
+```yaml
+# Before
+disallowed_tools: bash
+
+# After
+permission:
+  bash: deny
+```
+
+## Module-Level Changes
+
+1. **`src/types.ts`** — Remove the `disallowedTools` field and its JSDoc comment from `AgentConfig`.
+2. **`src/config/custom-agents.ts`** — Remove the `disallowedTools: csvListOptional(fm.disallowed_tools)` line from the agent config construction.
+3. **`src/session/session-config.ts`** — Remove `disallowedSet` from the `ToolFilterConfig` interface.
+   Remove the `disallowedSet` construction block and its comment in `assembleSessionConfig`.
+   Remove `disallowedSet` from the `toolFilter` object literal.
+4. **`src/lifecycle/agent-runner.ts`** — Remove the `disallowedSet` destructure and denylist branches from `filterActiveTools`.
+   Simplify the `extensions === false` branch to `return activeTools`.
+   Simplify both guard conditions from `cfg.toolFilter.extensions !== false || cfg.toolFilter.disallowedSet` to `cfg.toolFilter.extensions !== false`.
+   Update comments that mention `disallowedTools denylist`.
+5. **`src/ui/agent-config-editor.ts`** — Remove the two lines that serialize `disallowedTools` to `disallowed_tools` frontmatter.
+6. **`src/ui/agent-creation-wizard.ts`** — Remove the `disallowed_tools:` line from the template text.
+7. **`README.md`** — Remove the "Tool denylist" feature bullet, the `disallowed_tools` row from the frontmatter table, the memory write-capability paragraph (memory was removed in #185; this reference is already stale), the `disallowed_tools` example in the memory section, and the `disallowedTools` mention in the Patch 2 notes.
+   Add a migration note under a "Migration" heading or in the breaking changes section.
+
+### Test files
+
+8. **`test/config/custom-agents.test.ts`** — Remove the two `disallowed_tools` tests ("parses disallowed_tools as csv list" and "disallowed_tools defaults to undefined when omitted").
+9. **`test/session/session-config.test.ts`** — Remove the `disallowedSet` assertion from the default config test and remove the entire "builds disallowedSet from agentConfig.disallowedTools" test.
+10. **`test/lifecycle/agent-runner-extension-tools.test.ts`** — Remove `disallowedTools` from both mock agent config objects.
+    Remove the three `disallowedTools`-specific tests ("post-bind re-filter respects disallowedTools denylist", "extensions: false still applies disallowedTools", "extensions: false with no disallowedTools skips the filter").
+    Update the file-level JSDoc comment.
+11. **`test/ui/agent-config-editor.test.ts`** — Remove `disallowedTools` from the test fixture and remove the `disallowed_tools` assertion.
+
+### Architecture docs
+
+12. **`docs/architecture/architecture.md`** — Mark Step 1 as complete (update the step heading or add a completion note).
+
+## Test Impact Analysis
+
+1. **Tests removed** — 7 tests that directly assert `disallowedTools`/`disallowedSet` behavior become meaningless and are deleted:
+   - `custom-agents.test.ts`: 2 tests (csv parsing, undefined default)
+   - `session-config.test.ts`: 1 test (`disallowedSet` construction) + 1 assertion in default config test
+   - `agent-runner-extension-tools.test.ts`: 3 tests (denylist for extension tools, denylist for built-in tools with `extensions: false`, filter skip with `extensions: false` + no denylist)
+   - `agent-config-editor.test.ts`: 1 assertion in the serialization test
+
+2. **Tests updated** — Several tests have `disallowedTools` in their mock fixtures but don't test it directly; those fixtures lose the field:
+   - `agent-runner-extension-tools.test.ts`: both mock config objects drop `disallowedTools`
+
+3. **Tests unchanged** — The remaining `agent-runner-extension-tools.test.ts` tests (`extensions: true`, `extensions: string[]` allowlist, `extensions: false` passthrough) remain valid — they test extension filtering, not the denylist.
+
+## TDD Order
+
+1. **Remove `disallowedTools` from `AgentConfig`** — Delete the field and JSDoc from `types.ts`.
+   Remove `disallowedTools` parsing from `custom-agents.ts`.
+   Remove the two `disallowed_tools` tests from `custom-agents.test.ts`.
+   Run `pnpm run check` to surface all downstream type errors.
+   Commit: `feat!: remove disallowedTools from AgentConfig`
+
+2. **Remove `disallowedSet` from `ToolFilterConfig` and `assembleSessionConfig`** — Delete the field from `ToolFilterConfig`, the construction block in `assembleSessionConfig`, and the `disallowedSet` key from the return literal.
+   Remove the `disallowedSet`-specific test and assertion from `session-config.test.ts`.
+   Run `pnpm run check`.
+   Commit: `refactor: remove disallowedSet from ToolFilterConfig`
+
+3. **Simplify `filterActiveTools` and guard conditions** — Remove the `disallowedSet` destructure and denylist branches from `filterActiveTools`.
+   Simplify the `extensions === false` branch to `return activeTools`.
+   Simplify both guard conditions to `cfg.toolFilter.extensions !== false`.
+   Update comments.
+   Remove the three `disallowedTools`-specific tests and update mock fixtures in `agent-runner-extension-tools.test.ts`.
+   Run tests: `pnpm vitest run`.
+   Commit: `refactor: remove disallowedSet branch from filterActiveTools`
+
+4. **Remove `disallowed_tools` from UI** — Remove serialization from `agent-config-editor.ts` and the template line from `agent-creation-wizard.ts`.
+   Remove `disallowedTools` from the test fixture and assertion in `agent-config-editor.test.ts`.
+   Run tests: `pnpm vitest run`.
+   Commit: `refactor: remove disallowed_tools from config editor and creation wizard`
+
+5. **Update README.md** — Remove all `disallowed_tools` references (feature bullet, frontmatter table row, stale memory paragraph, example, patch notes mention).
+   Add a migration note directing users to `permission:` frontmatter.
+   Commit: `docs: remove disallowed_tools from README and add migration note`
+
+6. **Mark Phase 14 Step 1 complete in architecture doc** — Update `docs/architecture/architecture.md` to reflect completion.
+   Commit: `docs: mark Phase 14 Step 1 complete in architecture`
+
+## Risks and Mitigations
+
+| Risk                                                                               | Mitigation                                                                                                                                                                  |
+| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Users with existing `disallowed_tools` frontmatter silently lose tool restrictions | Breaking change is intentional and documented; `feat!:` commit triggers a major version bump via release-please; README migration note directs to `permission:` frontmatter |
+| `filterActiveTools` behavior regresses for non-denylist paths                      | Steps 1–3 each run `pnpm run check` or `pnpm vitest run`; existing extension-filtering tests remain unchanged                                                               |
+| Stale references to `disallowed_tools` in docs or plans                            | Grep sweep in step 5 covers README; architecture doc updated in step 6; historical plan/retro files are left as-is (they document past state)                               |
+
+## Open Questions
+
+None — the issue's proposed change is unambiguous and the architecture doc provides detailed step-by-step guidance.

package/docs/retro/0219-reduce-test-duplication-top-3-clone-families.md

@@ -34,3 +34,31 @@ All 4 commits landed cleanly; full suite green at every step.
 - The `createSessionRunner` + `createRunResult` chain required careful identity-check verification: `createRunResult(sess)` calls `toAgentSession(sess)` which casts without creating a new object, so `toBe(session)` assertions in the execution-state tests still pass. ✓
 - ESLint auto-fixed two cosmetic issues on commit (`activity = undefined` → `activity` destructuring, `session as unknown` cast removal) — caught by pre-commit hooks, not a problem in practice.
 - The `assertRenderFitsWidths` helper in `conversation-viewer.test.ts` reduced the 10 render-safety tests from ~8 lines each to 1–4 lines each; the `setupDetail` helper in `agent-config-editor.test.ts` eliminated 3 repeated setup lines per test across 18 `showAgentDetail` tests.
+
+## Stage: Final Retrospective (2026-05-26T17:50:31Z)
+
+### Session summary
+
+All three stages (planning, TDD, ship) completed in a single session with zero user corrections.
+Four TDD commits landed cleanly, CI passed on first push, issue #219 closed, and `pi-subagents-v7.8.1` released.
+
+### Observations
+
+#### What went well
+
+- Clean incremental verification: `pnpm vitest run <file>` ran after every code change, full suite at the end.
+  No regressions at any step.
+- The plan's decision to keep gated runners inline proved correct — tests with `Promise.withResolvers` flow control stayed readable without abstraction.
+- The `write` tool was the right choice for `conversation-viewer.test.ts` and `agent-config-editor.test.ts` (pervasive changes), while `edit` with 16 targeted replacements worked cleanly for `agent-manager.test.ts` (scattered but formulaic substitutions).
+- Ship stage used `deepseek-v4-flash` for purely mechanical CI/release steps — appropriate model-task alignment.
+
+#### What caused friction (agent side)
+
+- `other` — ESLint pre-commit hooks auto-fixed two cosmetic patterns (`activity = undefined` → bare destructuring; `session as unknown` cast removal), requiring re-stage + re-commit.
+  Impact: ~10 seconds per occurrence, no rework.
+  This is routine and inherent to the workflow.
+
+#### What caused friction (user side)
+
+- None observed.
+  The user's three-stage prompt chain (`/plan-issue` → `/tdd-plan` → `/ship-issue`) provided sufficient context at each stage with no manual intervention needed.

package/docs/retro/0237-remove-disallowed-tools.md

@@ -0,0 +1,41 @@
+---
+issue: 237
+issue_title: "Remove disallowed_tools from pi-subagents (Phase 14, Step 1)"
+---
+
+# Retro: #237 — Remove disallowed_tools from pi-subagents
+
+## Stage: Planning (2026-05-27T00:52:26Z)
+
+### Session summary
+
+Produced a 6-step TDD plan to remove `disallowedTools` from `AgentConfig`, `disallowedSet` from `ToolFilterConfig`, and all parsing/serialization/UI/test code that references them.
+The plan covers 7 source files, 4 test files, README, and the architecture doc.
+
+### Observations
+
+- The issue label `pkg:pi-permission-system` was incorrect — all target files live in `packages/pi-subagents`.
+  Confirmed with the user that the plan targets pi-subagents.
+- The README still references `disallowed_tools` in the context of memory write-capability detection, but memory was already removed in #185.
+  The plan treats this as a stale reference to clean up.
+- After removing `disallowedSet`, the `filterActiveTools` `extensions === false` branch simplifies to a trivial passthrough (`return activeTools`), and both guard conditions at the call sites drop the `|| cfg.toolFilter.disallowedSet` arm.
+  This leaves the function in the exact shape that Step 3 (#239) expects.
+- The plan orders steps to follow the type dependency chain: `AgentConfig` first (surfaces all downstream errors), then `ToolFilterConfig`, then `filterActiveTools`, then UI, then docs.
+
+## Stage: Implementation — TDD (2026-05-27T00:59:19Z)
+
+### Session summary
+
+All 6 TDD steps completed in one session, producing 7 commits (6 planned + 1 fixup for dead code).
+Test count dropped from 983 to 978 (5 tests removed: 2 from `custom-agents.test.ts`, 1 from `session-config.test.ts`, 2 from `agent-runner-extension-tools.test.ts` after renaming one deleted test into a retained form).
+All checks (type check, lint, fallow dead-code gate) pass clean.
+
+### Observations
+
+- `csvListOptional` in `custom-agents.ts` was left dead after removing the `disallowedTools` parsing call; Biome flagged it as unused.
+  Removed as a separate `refactor:` commit since it couldn't be amended into the `feat!:` commit (later commits already on top of it).
+- One of the three deleted `agent-runner-extension-tools.test.ts` denylist tests ("extensions: false with no disallowedTools skips the filter") was reformulated into a new test ("extensions: false skips the filter entirely") rather than simply deleted, because it covers genuinely different behavior after the simplification: `extensions: false` now always skips the filter, not just when no denylist is present.
+  This adds coverage for the simplified code path.
+- The `filterActiveTools` `extensions === false` branch simplified from "apply denylist to built-in tools" to `return activeTools`, exactly as the plan specified.
+  Both guard conditions at the call sites simplified to `cfg.toolFilter.extensions !== false`.
+- No deviations from the plan's module-level changes list; all 7 source files and 4 test files were touched as specified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.8.1",
+  "version": "8.0.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/config/custom-agents.ts

@@ -58,7 +58,6 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       displayName: str(fm.display_name),
       description: str(fm.description) ?? name,
       builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
-      disallowedTools: csvListOptional(fm.disallowed_tools),
       extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
       skills: inheritField(fm.skills ?? fm.inherit_skills),
       model: str(fm.model),
@@ -110,14 +109,6 @@ function csvList(val: unknown, defaults: string[]): string[] {
   return parseCsvField(val) ?? [];
 }
 
-/**
- * Parse an optional comma-separated list field.
- * omitted → undefined; "none"/empty → undefined; csv → listed items.
- */
-function csvListOptional(val: unknown): string[] | undefined {
-  return parseCsvField(val);
-}
-
 /**
  * Parse an inherit field (extensions, skills).
  * omitted/true → true (inherit all); false/"none"/empty → false; csv → listed names.

package/src/lifecycle/agent-runner.ts

@@ -22,7 +22,7 @@ import type { ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 
 /**
- * Filter the session's active tool names according to extension/denylist rules.
+ * Filter the session's active tool names according to extension rules.
  *
  * Run twice - once before `bindExtensions` (filters built-in tools) and once after
  * (filters extension-registered tools, which only join the active set during
@@ -36,16 +36,13 @@ function filterActiveTools(
   activeTools: string[],
   config: ToolFilterConfig,
 ): string[] {
-  const { toolNames, extensions, disallowedSet } = config;
+  const { toolNames, extensions } = config;
   if (extensions === false) {
-    // Extensions disabled: only apply the denylist to built-in tools.
-    if (!disallowedSet) return activeTools;
-    return activeTools.filter((t) => !disallowedSet.has(t));
+    return activeTools;
   }
   const builtinToolNameSet = new Set(toolNames);
   return activeTools.filter((t) => {
     if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-    if (disallowedSet?.has(t)) return false;
     if (builtinToolNameSet.has(t)) return true;
     if (Array.isArray(extensions)) {
       return extensions.some((ext) => t.startsWith(ext) || t.includes(ext));
@@ -341,9 +338,9 @@ export async function runAgent(
   });
 
   // Filter active tools: remove our own tools to prevent nesting,
-  // apply extension allowlist if specified, and apply disallowedTools denylist.
+  // apply extension allowlist if specified.
   // First pass - over built-in tools, before bindExtensions registers extension tools.
-  if (cfg.toolFilter.extensions !== false || cfg.toolFilter.disallowedSet) {
+  if (cfg.toolFilter.extensions !== false) {
     const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
     session.setActiveToolsByName(filtered);
   }
@@ -367,9 +364,8 @@ export async function runAgent(
   // Extension-registered tools (added during bindExtensions) are not in the
   // session's active set when the first filter pass runs above. Without this
   // re-filter, the `extensions: string[]` allowlist branch never matches any
-  // extension tools and `extensions: true` lets non-allowlisted denylist
-  // entries slip in. Run the same filter against the post-bind active set.
-  if (cfg.toolFilter.extensions !== false || cfg.toolFilter.disallowedSet) {
+  // extension tools. Run the same filter against the post-bind active set.
+  if (cfg.toolFilter.extensions !== false) {
     const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
     session.setActiveToolsByName(refiltered);
   }

package/src/session/session-config.ts

@@ -21,14 +21,12 @@ import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "#src/types"
 /**
  * Tool filtering configuration — consumed by `filterActiveTools` in `agent-runner.ts`.
  *
- * Groups the three fields that travel together through the assembly→runner boundary:
- * the built-in tool allowlist, the optional denylist, and the extensions setting.
+ * Groups the two fields that travel together through the assembly→runner boundary:
+ * the built-in tool allowlist and the extensions setting.
  */
 export interface ToolFilterConfig {
   /** Built-in tool name allowlist for this agent type. */
   toolNames: string[];
-  /** Disallowed tool set from agentConfig. undefined when empty. */
-  disallowedSet: Set<string> | undefined;
   /** Resolved extensions setting: false | true | string[] allowlist. */
   extensions: boolean | string[];
 }
@@ -210,11 +208,6 @@ export function assembleSessionConfig(
   // tell the resource loader not to load them again.
   const noSkills = skills === false || Array.isArray(skills);
 
-  // Disallowed tools set (for filterActiveTools in runAgent)
-  const disallowedSet = agentConfig.disallowedTools
-    ? new Set(agentConfig.disallowedTools)
-    : undefined;
-
   // Model resolution: explicit option > config model string > parent model
   const model =
     options.model ??
@@ -229,7 +222,7 @@ export function assembleSessionConfig(
   return {
     effectiveCwd,
     systemPrompt,
-    toolFilter: { toolNames, disallowedSet, extensions },
+    toolFilter: { toolNames, extensions },
     model,
     thinkingLevel,
     noSkills,

package/src/types.ts

@@ -42,8 +42,6 @@ export interface AgentPromptConfig {
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
   builtinToolNames?: string[];
-  /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
-  disallowedTools?: string[];
   /** true = inherit all, string[] = only listed, false = none */
   extensions: true | string[] | false;
   /** true = inherit all, string[] = only listed, false = none */

package/src/ui/agent-config-editor.ts

@@ -53,8 +53,6 @@ export function buildEjectContent(cfg: AgentConfig): string {
   if (cfg.skills === false) fmFields.push("skills: false");
   else if (Array.isArray(cfg.skills))
     fmFields.push(`skills: ${cfg.skills.join(", ")}`);
-  if (cfg.disallowedTools?.length)
-    fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
   if (cfg.inheritContext) fmFields.push("inherit_context: true");
   if (cfg.runInBackground) fmFields.push("run_in_background: true");
   if (cfg.isolated) fmFields.push("isolated: true");

package/src/ui/agent-creation-wizard.ts

@@ -106,7 +106,6 @@ max_turns: <optional max agentic turns. 0 or omit for unlimited (default)>
 prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
 extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
 skills: <true (inherit all), false (none), or comma-separated skill names to preload into prompt. Default: true>
-disallowed_tools: <comma-separated tool names to block, even if otherwise available. Omit for none>
 inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
 run_in_background: <true to run in background by default. Default: false>
 isolated: <true for no extension/MCP tools, only built-in tools. Default: false>