@gotgenes/pi-subagents 7.8.1 → 9.0.0

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/plans/0238-remove-extensions-filtering.md

@@ -0,0 +1,191 @@
+---
+issue: 238
+issue_title: "Remove extensions filtering from pi-subagents (Phase 14, Step 2)"
+---
+
+# Remove `extensions` filtering from pi-subagents
+
+## Problem Statement
+
+The `extensions: string[]` allowlist in agent configuration is tool filtering disguised as extension lifecycle control.
+Extensions always initialize via `bindExtensions()` — the allowlist only hides their tools from the active set afterward, which is pi-permission-system's responsibility.
+Simplifying `extensions` from `true | string[] | false` to `boolean` removes this overlap and makes pi-permission-system the sole authority for tool access control.
+
+## Goals
+
+- Simplify `extensions` from `true | string[] | false` to `boolean` in `AgentConfig`, `ToolFilterConfig`, and all related code.
+- Remove the `Array.isArray(extensions)` branch from `filterActiveTools` in `agent-runner.ts`.
+- Remove extensions array handling from the agent config editor and creation wizard.
+- Update custom agent frontmatter parsing to coerce array values to `true` (with a deprecation warning).
+- Update tests to remove `extensions: string[]` assertions and fixture data.
+- This is a **breaking change** — users with `extensions: <csv-list>` in agent frontmatter lose per-extension filtering.
+
+## Non-Goals
+
+- Collapsing `filterActiveTools` to a recursion guard (Step 3, #239).
+- Removing `extensions: false` — it is retained here (used by `isolated`) and dissolved in Phase 16.
+- Changing any pi-permission-system code — this issue is purely pi-subagents.
+- Removing Patch 2 (post-bind re-filter) — it still serves the `EXCLUDED_TOOL_NAMES` recursion guard when `extensions === true`.
+  Issue #239 collapses the two-pass dance.
+
+## Background
+
+### Phase 14 context
+
+This is Phase 14, Step 2 of the architecture roadmap in `docs/architecture/architecture.md`.
+Steps 1 (#237, completed) and 2 (#238) are independent; Step 3 (#239) depends on both.
+
+### Files involved
+
+| File                              | Role                                                                        |
+| --------------------------------- | --------------------------------------------------------------------------- |
+| `src/types.ts`                    | `AgentConfig.extensions` field type                                         |
+| `src/config/custom-agents.ts`     | Parses `extensions` from YAML frontmatter via `inheritField()`              |
+| `src/session/session-config.ts`   | `ToolFilterConfig.extensions` type + passthrough in `assembleSessionConfig` |
+| `src/lifecycle/agent-runner.ts`   | `filterActiveTools` array branch + Patch 2 comment                          |
+| `src/ui/agent-config-editor.ts`   | Serializes `extensions` array to frontmatter                                |
+| `src/ui/agent-creation-wizard.ts` | Template text describing `extensions` field options                         |
+| `README.md`                       | Frontmatter table row, Patch 2 notes                                        |
+
+### `filterActiveTools` after this change
+
+```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;
+    return true;
+  });
+}
+```
+
+The `Array.isArray(extensions)` branch is gone.
+The `builtinToolNameSet.has(t)` check becomes redundant (always returns true for builtins, falls through to `return true` for non-builtins) — but simplifying further is #239's scope.
+
+### Custom agent frontmatter migration
+
+The `inheritField()` function currently parses CSV values into `string[]`.
+After this change, it must still accept array values gracefully: coerce them to `true` and emit a warning so users know to update their frontmatter.
+
+## Design Overview
+
+This is primarily a removal — no new types, no new modules.
+The one piece of new behavior is the deprecation warning when `inheritField` encounters an array value for `extensions`.
+
+### `inheritField` change
+
+Currently `inheritField` is shared between `extensions` and `skills` parsing.
+Since `skills` still supports `string[]`, the function itself cannot change.
+Instead, the call site for `extensions` will post-process: if `inheritField` returns `string[]`, coerce to `true` and log a warning.
+
+### Type change scope
+
+`AgentConfig.extensions` changes from `true | string[] | false` to `boolean`.
+`ToolFilterConfig.extensions` changes from `boolean | string[]` to `boolean`.
+Both are narrowing changes — existing `true` and `false` values remain valid.
+
+## Module-Level Changes
+
+1. **`src/types.ts`** — Change `extensions` type from `true | string[] | false` to `boolean`.
+   Update JSDoc comment to remove the `string[] = only listed` description.
+2. **`src/config/custom-agents.ts`** — After calling `inheritField(fm.extensions ?? fm.inherit_extensions)`, coerce `string[]` results to `true` and emit a `debugLog` warning.
+   The warning informs users that `extensions: <csv-list>` is no longer supported and treated as `extensions: true`.
+3. **`src/session/session-config.ts`** — Change `ToolFilterConfig.extensions` type from `boolean | string[]` to `boolean`.
+   Update the JSDoc comment.
+   The `assembleSessionConfig` passthrough `const extensions = options.isolated ? false : agentConfig.extensions;` works without changes since the type narrows.
+4. **`src/lifecycle/agent-runner.ts`** — Remove the `Array.isArray(extensions)` branch (lines 47–49) from `filterActiveTools`.
+   Update the Patch 2 comment (line 366) that references `extensions: string[]`.
+   Update the comment at line 341 ("apply extension allowlist if specified").
+5. **`src/ui/agent-config-editor.ts`** — Remove the `else if (Array.isArray(cfg.extensions))` branch (lines 51–52) from `buildEjectContent`.
+6. **`src/ui/agent-creation-wizard.ts`** — Simplify the `extensions:` line in the template text from `<true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>` to `<true (inherit all MCP/extension tools) or false (none). Default: true>`.
+7. **`README.md`** — Simplify the `extensions` row in the frontmatter table to document boolean-only.
+   Update Patch 2 notes to remove `extensions: string[]` reference.
+8. **`src/config/default-agents.ts`** — No changes needed; all defaults already use `extensions: true`.
+
+### Test files
+
+9. **`test/config/custom-agents.test.ts`** — Update the "handles extension allowlist" test: change expectation from `toEqual(["web-search", "mcp-server"])` to `toBe(true)` since CSV values now coerce to `true`.
+   Add a test verifying the deprecation warning is emitted.
+10. **`test/session/session-config.test.ts`** — Update the "isolated:true forces extensions to false even for string[] extension list" test: since `AgentConfig.extensions` no longer supports `string[]`, simplify this test to use `extensions: true` and verify `isolated` still forces it to `false`.
+    The test name changes to reflect the boolean type.
+11. **`test/lifecycle/agent-runner-extension-tools.test.ts`** — Remove the "post-bind re-filter respects extensions: string[] allowlist" test (line 139).
+    Change the `extensions` type annotation in the mutable config mock (line 26) from `boolean | string[]` to `boolean`.
+    Update the file-level JSDoc comment to remove `extensions: string[]` references.
+12. **`test/ui/agent-config-editor.test.ts`** — Remove the "emits 'extensions: \<list\>' when extensions is an array" test.
+13. **Test fixtures** — All test helper defaults already use `extensions: false` or `extensions: true`; no fixture changes needed beyond the tests listed above.
+
+### Architecture docs
+
+14. **`docs/architecture/architecture.md`** — Mark Step 2 as complete.
+
+## Test Impact Analysis
+
+1. **Tests removed** — 2 tests that directly assert `extensions: string[]` behavior:
+   - `agent-runner-extension-tools.test.ts`: "post-bind re-filter respects extensions: string[] allowlist"
+   - `agent-config-editor.test.ts`: "emits 'extensions: \<list\>' when extensions is an array"
+
+2. **Tests updated** — 3 tests that reference `extensions: string[]` in fixtures or assertions:
+   - `custom-agents.test.ts`: "handles extension allowlist" → expectation changes to `true`
+   - `session-config.test.ts`: "isolated:true forces extensions to false even for string[] extension list" → uses `true` instead of array
+   - `agent-runner-extension-tools.test.ts`: mock config type annotation narrows
+
+3. **Tests added** — 1 test:
+   - `custom-agents.test.ts`: verifies deprecation warning when array value is provided
+
+4. **Tests unchanged** — All other `extensions: true` and `extensions: false` tests remain valid since the boolean cases are preserved.
+
+## TDD Order
+
+1. **Narrow `extensions` type in `AgentConfig` and `ToolFilterConfig`** — Change `extensions` from `true | string[] | false` to `boolean` in `types.ts`.
+   Change `ToolFilterConfig.extensions` from `boolean | string[]` to `boolean` in `session-config.ts`.
+   Update JSDoc comments.
+   Run `pnpm run check` to surface all downstream type errors.
+   Commit: `feat!: narrow extensions type from union to boolean`
+
+2. **Remove array branch from `filterActiveTools`** — Remove the `Array.isArray(extensions)` branch.
+   Update the Patch 2 comment and the pre-bind filter comment.
+   Remove the "post-bind re-filter respects extensions: string[] allowlist" test.
+   Narrow the mock config type annotation in `agent-runner-extension-tools.test.ts`.
+   Update the file-level JSDoc.
+   Run tests: `pnpm vitest run`.
+   Commit: `refactor: remove extensions array branch from filterActiveTools`
+
+3. **Coerce array values in custom agent frontmatter** — Update the `extensions` assignment in `custom-agents.ts` to coerce `string[]` results from `inheritField` to `true` with a deprecation warning.
+   Update the "handles extension allowlist" test expectation from array to `true`.
+   Add a test for the deprecation warning.
+   Update the "isolated:true forces extensions to false even for string[] extension list" test in `session-config.test.ts` to use `extensions: true`.
+   Run tests: `pnpm vitest run`.
+   Commit: `refactor: coerce extensions array values to true with deprecation warning`
+
+4. **Remove extensions array from UI** — Remove the `Array.isArray(cfg.extensions)` branch from `buildEjectContent`.
+   Simplify the `extensions:` line in the creation wizard template.
+   Remove the "emits 'extensions: \<list\>'" test from `agent-config-editor.test.ts`.
+   Run tests: `pnpm vitest run`.
+   Commit: `refactor: remove extensions array from config editor and creation wizard`
+
+5. **Update README** — Simplify the `extensions` frontmatter table row to document boolean-only.
+   Update Patch 2 notes to remove `extensions: string[]` reference.
+   Commit: `docs: simplify extensions field to boolean in README`
+
+6. **Mark Phase 14 Step 2 complete** — Update `docs/architecture/architecture.md`.
+   Commit: `docs: mark Phase 14 Step 2 complete in architecture`
+
+## Risks and Mitigations
+
+| Risk                                                                             | Mitigation                                                                                                                                   |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Users with `extensions: <csv-list>` silently lose per-extension filtering        | `feat!:` commit triggers major version bump; frontmatter parser emits deprecation warning and coerces to `true`; README documents the change |
+| `filterActiveTools` behavior regresses for boolean paths                         | Steps 1–4 each run type checks or tests; `extensions: true` and `extensions: false` tests are unchanged                                      |
+| Type annotation `boolean | string[]` in test mock causes tsc errors after step 1 | Step 2 narrows the annotation in the same commit that removes the array branch                                                               |
+
+## Open Questions
+
+None — the issue's proposed change and the architecture doc's step description are unambiguous.

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,78 @@
+---
+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.
+
+## Stage: Final Retrospective (2026-05-27T01:12:34Z)
+
+### Session summary
+
+Three-stage lifecycle (planning → TDD → ship) completed in one session for Phase 14, Step 1.
+All 6 TDD steps landed in 7 commits (6 planned + 1 fixup for dead `csvListOptional`).
+Test count: 983 → 978 (−5).
+Released as `pi-subagents-v8.0.0` (major bump from the `feat!:` breaking change).
+
+### Observations
+
+#### What went well
+
+- The plan's type-dependency-chain ordering (AgentConfig → ToolFilterConfig → `filterActiveTools` → UI → docs) meant each step produced the exact downstream type errors expected for the next step, with zero surprises.
+  This ordering pattern is worth preserving for future removal issues.
+- Incremental verification ran after every step: `pnpm run check` after type changes, `pnpm vitest run <file>` after logic changes, full suite + lint + fallow at the end.
+  No regressions discovered at the final sweep.
+- The reformulation of one deleted test into "extensions: false skips the filter entirely" added coverage for the simplified code path rather than just deleting it.
+  Good judgment call during implementation.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan said "remove `disallowedTools: csvListOptional(fm.disallowed_tools)`" from `custom-agents.ts` but did not check whether `csvListOptional` had other callers.
+  It was the sole call site, so the function became dead code.
+  Biome caught it at the final lint sweep, requiring a separate `refactor:` commit (`f1ee7c1`).
+  Impact: one unplanned commit; no rework but added friction.
+  Self-identified at final lint.
+  Root cause: the `plan-issue.md` template had a rule for grepping removed *exports* but not for checking private-function orphans.
+
+#### What caused friction (user side)
+
+- No friction observed — the user's involvement was limited to confirming the target package (pi-subagents vs pi-permission-system) during planning, which was an appropriate clarification given the incorrect `pkg:` label on the issue.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — Added rule: when a step removes a call to a private function, grep the file for other callers and list the function for removal if the removed call was the sole call site.

package/docs/retro/0238-remove-extensions-filtering.md

@@ -0,0 +1,39 @@
+---
+issue: 238
+issue_title: "Remove extensions filtering from pi-subagents (Phase 14, Step 2)"
+---
+
+# Retro: #238 — Remove extensions filtering from pi-subagents
+
+## Stage: Planning (2026-05-27T01:31:01Z)
+
+### Session summary
+
+Produced a 6-step TDD plan for narrowing `extensions` from `true | string[] | false` to `boolean` across `AgentConfig`, `ToolFilterConfig`, `filterActiveTools`, custom agent frontmatter parsing, UI serialization, and tests.
+The plan mirrors the structure of the completed #237 plan (Step 1 of Phase 14) and explicitly defers `filterActiveTools` collapse to #239.
+
+### Observations
+
+- The `pkg:pi-permission-system` label on this issue is intentional context (pi-permission-system becomes the sole tool-policy authority) but all code changes are in pi-subagents.
+- The `inheritField()` helper is shared between `extensions` and `skills` parsing — it cannot be simplified since `skills` still supports `string[]`.
+  The plan coerces at the call site instead.
+- After removing the `Array.isArray(extensions)` branch, the `builtinToolNameSet.has(t)` check in `filterActiveTools` becomes logically redundant (both branches return `true`), but simplifying further is #239's scope.
+- Only 2 tests are removed and 3 updated; the boolean paths (`true`/`false`) are well-covered and unchanged.
+
+## Stage: Implementation — TDD (2026-05-27T01:39:43Z)
+
+### Session summary
+
+All 6 TDD steps completed across 6 commits.
+Test count went from 978 to 977 (net −1: 2 removed, 1 added for the deprecation warning).
+Full suite: 62 files, 977 tests, all passing; type check and lint clean.
+
+### Observations
+
+- **Plan deviation — step consolidation**: The type narrowing in step 1 caused immediate `tsc` errors in test files that the plan assigned to steps 2–4 (the `string[]`-specific tests in `agent-runner-extension-tools.test.ts`, `session-config.test.ts`, and `agent-config-editor.test.ts`).
+  All test fixes were folded into the step 1 commit to keep the build green at every commit.
+  Steps 2–4 became purely production-code changes.
+- **Plan deviation — deprecation warning**: The plan said to use `debugLog` for the deprecation warning, but `debugLog` is debug-only (requires `PI_SUBAGENTS_DEBUG=1`) and its signature requires an error object as the second argument. `console.warn` was used instead, which is user-visible without special env vars and testable with `vi.spyOn`.
+- **ESLint auto-fix in step 2**: ESLint rewrote `extensions === false` to `!extensions` and `cfg.toolFilter.extensions === false` to `!cfg.toolFilter.extensions` after the type narrowed to `boolean`.
+  Both are semantically identical; the changes were staged and included in the same commit.
+- The `resolveBoolExtensions` helper in `custom-agents.ts` is a clean seam — if `skills` is ever also simplified to `boolean`, the same pattern applies.

package/package.json

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