@gotgenes/pi-subagents 7.8.0 → 8.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/0219-reduce-test-duplication-top-3-clone-families.md

@@ -0,0 +1,162 @@
+---
+issue: 219
+issue_title: "Reduce test duplication — top 3 clone families (Phase 13, Step 6)"
+---
+
+# Reduce test duplication — top 3 clone families
+
+## Problem statement
+
+After Phase 12, three test files carry the heaviest remaining clone families in pi-subagents:
+
+1. `test/lifecycle/agent-manager.test.ts` (929 lines) — 16 clone groups, ~160 duplicated lines.
+   Repeated inline runner stubs, worktree stubs, and manager-lifecycle boilerplate.
+2. `test/conversation-viewer.test.ts` (307 lines) — 8 clone groups, ~91 duplicated lines.
+   Near-identical `ConversationViewer` construction in every test, plus repeated width-loop assertion patterns.
+3. `test/ui/agent-config-editor.test.ts` (471 lines) — 5 clone groups, ~42 duplicated lines.
+   Repeated `makeEditor()` + `makeMenuUI()` + `fileOps.findAgentFile.mockReturnValue(...)` setup.
+
+Total target: reduce test duplication by ~200 lines (from ~1,046 combined test-setup lines to < 850).
+
+## Goals
+
+- Extract shared setup and assertion helpers for the three target test files.
+- Reduce test duplication by ~200 lines without changing test semantics.
+- Follow the existing `test/helpers/` convention (factory + matching `.test.ts` file).
+
+## Non-goals
+
+- No production code changes.
+- No new test coverage — this is purely a refactoring of existing test infrastructure.
+- Not consolidating clone families in other test files beyond the top 3.
+- Not changing any assertion logic or test structure beyond replacing inline stubs with factory calls.
+
+## Background
+
+The project already has several shared test helpers in `test/helpers/`: `make-record.ts`, `mock-session.ts`, `ui-stubs.ts`, `runner-io.ts`, `stub-ctx.ts`, `make-deps.ts`.
+Each helper has a companion `.test.ts` file — this convention must be followed.
+
+Dependencies #214 (closure-to-class conversions) and #216 (startAgent decomposition) are both closed, so the production code these tests cover is stable.
+
+## Design overview
+
+### File 1: `agent-manager.test.ts` — extract to `test/helpers/manager-stubs.ts`
+
+Five clone families to extract:
+
+1. **Never-resolving runner** — `{ run: vi.fn().mockImplementation(() => new Promise(() => {})), resume: vi.fn() }` appears 5 times.
+   Extract as `createBlockingRunner(): AgentRunner`.
+
+2. **Session-creating runner** — runner that calls `opts.onSessionCreated?.(session)` and resolves.
+   Appears 5+ times with minor variations (some emit events through the session, some don't).
+   Extract as `createSessionRunner(session?: MockSession): AgentRunner` that calls `onSessionCreated` and returns a standard result.
+
+3. **Worktree stubs with path+branch** — `{ create: vi.fn().mockReturnValue({ path, branch }), cleanup: vi.fn(() => ({ hasChanges: false })), prune: vi.fn() }` appears 4 times identically, plus 1 variant with `create` returning `undefined`.
+   Extract as `createMockWorktrees(overrides?)`.
+
+4. **Standard run result shape** — `{ responseText: "done", session, aborted: false, steered: false }` is repeated in many runner factories.
+   Extract as `createRunResult(overrides?)`.
+
+5. **Gated runner** — uses `Promise.withResolvers` to control when the runner completes.
+   Appears 2 times.
+   Keep inline — too tightly coupled to individual test flow-control to generalize cleanly.
+
+Tests that construct custom runners with unique behavior (event-emitting runners in the `lifetimeUsage` and `compactionCount` tests) keep their inline stubs — those encode test-specific emission sequences that a shared factory would obscure.
+
+### File 2: `conversation-viewer.test.ts` — inline factory + assertion helper
+
+Two clone families to extract:
+
+1. **`ConversationViewer` construction** — 15 near-identical constructor calls with the same 8 fields.
+   Extract as an inline `createTestViewer(overrides?)` factory at the top of the test file.
+   The factory provides defaults for `tui`, `session`, `record`, `activity`, `theme`, `done`, `registry`, and `wrapText`, and accepts overrides including a convenience `width` and `messages` parameter.
+
+2. **Width-loop assertion** — the `for (const w of widths) { create viewer; assertAllLinesFit(viewer.render(w), w) }` pattern repeats in 10 "render width safety" tests.
+   Extract as an inline `assertRenderFitsWidths(messages, widths?, viewerOverrides?)` helper.
+
+These helpers stay inline (not in `test/helpers/`) because they depend on file-local helpers (`mockTui`, `mockSession`, `ansiTheme`) and are only used by this one test file.
+
+### File 3: `agent-config-editor.test.ts` — inline setup helper
+
+One clone family to extract:
+
+1. **Detail-test setup** — `makeEditor()` + `makeMenuUI([...])` + `fileOps.findAgentFile.mockReturnValue(...)` + optional `fileOps.read.mockReturnValue(...)` appears in ~18 tests.
+   Extract as an inline `setupDetail(selectResults, options?)` factory that returns `{ fileOps, editor, ui }` with pre-configured mocks.
+   Options: `filePath`, `fileContent`, `config` (merged into default via `createTestAgentConfig`).
+
+This stays inline because it's specific to the `showAgentDetail` test suite and depends on file-local `testRegistry` setup.
+
+## Module-level changes
+
+### New files
+
+| File                                 | Purpose                                                                                 |
+| ------------------------------------ | --------------------------------------------------------------------------------------- |
+| `test/helpers/manager-stubs.ts`      | `createBlockingRunner`, `createSessionRunner`, `createMockWorktrees`, `createRunResult` |
+| `test/helpers/manager-stubs.test.ts` | Smoke tests for the factories                                                           |
+
+### Modified files
+
+| File                                   | Change                                                                      |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| `test/lifecycle/agent-manager.test.ts` | Replace inline runner/worktree stubs with `manager-stubs` factories         |
+| `test/conversation-viewer.test.ts`     | Add `createTestViewer` + `assertRenderFitsWidths` inline, migrate all tests |
+| `test/ui/agent-config-editor.test.ts`  | Add `setupDetail` inline, migrate `showAgentDetail` tests                   |
+
+### Unchanged files
+
+No production source files are modified.
+No other test files are modified.
+
+## Test impact analysis
+
+1. **New unit tests**: `manager-stubs.test.ts` adds smoke tests verifying factory return shapes (blocking runner never resolves, session runner calls `onSessionCreated`, worktree factory returns the expected interface, run result contains the correct fields).
+2. **Simplified tests**: ~30 tests across the three files replace 3–6 lines of inline stub construction with 1-line factory calls.
+3. **Unchanged tests**: All existing test assertions remain identical — only the setup code changes.
+   Tests with custom runner behavior (event-emitting, gated, error-throwing) keep their inline stubs.
+
+## TDD order
+
+1. **Create `test/helpers/manager-stubs.ts` + `manager-stubs.test.ts`** Add `createBlockingRunner`, `createSessionRunner`, `createMockWorktrees`, `createRunResult`.
+   Add smoke tests verifying each factory's return shape and basic behavior.
+   Commit: `test: add manager-stubs helper factories (#219)`
+
+2. **Migrate `agent-manager.test.ts` to use manager-stubs** Replace 5 inline never-resolving runners with `createBlockingRunner()`.
+   Replace 4 identical worktree stubs with `createMockWorktrees()` / `createMockWorktrees({ create: ... })`.
+   Replace inline session-creating runners with `createSessionRunner(session)` where the test only needs `onSessionCreated` wiring.
+   Replace inline run-result objects with `createRunResult()` where the default shape suffices.
+   Run `pnpm vitest run test/lifecycle/agent-manager.test.ts` to verify green.
+   Commit: `test: migrate agent-manager tests to manager-stubs (#219)`
+
+3. **Add inline factories to `conversation-viewer.test.ts` and migrate** Add `createTestViewer(overrides?)` inline factory with defaults for all 8 constructor fields.
+   Add `assertRenderFitsWidths(messages, widths?, overrides?)` inline helper.
+   Migrate all 10 "render width safety" tests to use `assertRenderFitsWidths`.
+   Migrate all 5 "safety net" tests to use `createTestViewer`.
+   Run `pnpm vitest run test/conversation-viewer.test.ts` to verify green.
+   Commit: `test: reduce conversation-viewer test duplication (#219)`
+
+4. **Add inline `setupDetail` to `agent-config-editor.test.ts` and migrate** Add `setupDetail(selectResults, options?)` returning `{ fileOps, editor, ui }`.
+   Migrate `showAgentDetail` tests to use `setupDetail`.
+   Run `pnpm vitest run test/ui/agent-config-editor.test.ts` to verify green.
+   Commit: `test: reduce agent-config-editor test duplication (#219)`
+
+5. **Final verification** Run `pnpm vitest run` (full suite) to confirm no regressions.
+   Run `pnpm run check` to confirm no type errors.
+   Commit is not needed — this is a verification-only step.
+
+## Risks and mitigations
+
+1. **Factory defaults diverge from test intent** — If a shared factory's defaults don't match what an individual test expects, assertions silently pass or fail for the wrong reason.
+   Mitigation: diff all inline stubs against the proposed factory defaults before writing the factory.
+   Keep tests with unique mock behavior inline rather than force-fitting them into a factory.
+
+2. **Over-abstraction obscures test intent** — Extracting too many details into helpers makes tests harder to read.
+   Mitigation: only extract truly duplicated boilerplate (stub construction); keep test-specific setup and assertions inline.
+   The gated runner pattern stays inline for this reason.
+
+3. **Intermediate broken state** — Partially migrated test files may have import conflicts.
+   Mitigation: each TDD step fully migrates one file before committing.
+
+## Open questions
+
+None — the issue scope is well-defined and the dependencies are resolved.

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/0218-push-sdk-boundary-in-settings.md

@@ -33,3 +33,40 @@ All 970 tests pass; `settings.ts` now has 0 Pi SDK imports and all `PI_CODING_AG
 - **Test simplification was significant:** Removed `originalAgentDirEnv` save/restore scaffolding from 5 `describe` blocks; the test code shrank by 32 lines net.
 - **`/nonexistent` sentinel:** Tests that construct `SettingsManager` but never call `load()` pass `agentDir: "/nonexistent"` — a clear signal the field is unused in that scope.
 - Architecture doc Step 5 heading marked `✓` and folded into the last `feat:` commit by `pi-autoformat`.
+
+## Stage: Final Retrospective (2026-05-26T17:22:11Z)
+
+### Session summary
+
+Issue #218 went from plan to shipped release (`pi-subagents-v7.8.0`) in a single continuous session.
+Planning, TDD (2 feat commits + 1 doc commit), shipping, CI verification, issue close, and release-please merge all completed without user intervention beyond stage transitions.
+
+### Observations
+
+#### What went well
+
+- **Clean mechanical execution:** The entire change was 2 production files (`settings.ts`, `index.ts`) and 1 test file, with zero unexpected test breakage and zero rework commits.
+- **Test simplification payoff:** Removing `PI_CODING_AGENT_DIR` env var scaffolding from 5 `describe` blocks shrank the test file by 32 lines net — a tangible improvement in test readability.
+- **Ship stage model efficiency:** The `/ship-issue` stage ran on `deepseek-v4-flash`, which was appropriate for the purely mechanical push/CI/close/merge workflow.
+
+#### What caused friction (agent side)
+
+1. `wrong-abstraction` — The plan split steps 1 and 2 into separate commits, but changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` immediately broke `SettingsManager.load()` which calls it.
+   The agent recognized this during the red phase and combined them into one commit.
+   The existing testing skill rule ("When a TDD plan lists separate steps that share a type definition… fold them into one step") already covers this — the plan just didn't apply it.
+   Impact: added friction but no rework; recognized on first test run.
+2. `missing-context` — Attempted to add `| ✓ #218 |` as an extra column to one row of the architecture doc's findings table, creating a column-count mismatch.
+   The autoformatter reverted the broken table.
+   The agent then spent ~5 tool calls (`git show --stat`, `git status`, `grep` ×2, `read`) investigating what happened before switching to the Step 5 heading approach.
+   Impact: ~2 minutes of investigation; no rework beyond the heading edit.
+
+#### What caused friction (user side)
+
+- The user asked "Are we ready for shipping?"
+  which surfaced that the TDD retro stage notes were still uncommitted.
+  This was a useful checkpoint — the ship stage committed them before pushing.
+  Opportunity: the `/tdd-plan` prompt could commit retro notes as part of its final step, but the current flow (write notes, then commit in ship) is lightweight enough that enforcing it would add complexity for marginal gain.
+
+### Changes made
+
+1. Retro file updated at `packages/pi-subagents/docs/retro/0218-push-sdk-boundary-in-settings.md` — no other files changed.

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

@@ -0,0 +1,64 @@
+---
+issue: 219
+issue_title: "Reduce test duplication — top 3 clone families (Phase 13, Step 6)"
+---
+
+# Retro: #219 — Reduce test duplication — top 3 clone families
+
+## Stage: Planning (2026-05-26T20:00:00Z)
+
+### Session summary
+
+Analyzed duplication patterns in the three target test files (`agent-manager.test.ts`, `conversation-viewer.test.ts`, `agent-config-editor.test.ts`).
+Produced a 5-step TDD plan with shared `manager-stubs.ts` helper for runner/worktree factories, plus inline factories for the two UI test files.
+
+### Observations
+
+- The agent-manager test has the most diverse clone families (runner stubs, worktree stubs, run-result shapes) — these benefit from a shared helper file since the patterns are reused across 15+ describe blocks.
+- The conversation-viewer and config-editor duplication is more localized — inline factories within each test file are the right granularity to avoid over-extraction.
+- Gated runners (using `Promise.withResolvers`) were deliberately kept inline since they encode test-specific flow control that a factory would obscure.
+- Both dependencies (#214, #216) are closed, so the production code is stable and the tests won't shift under us during implementation.
+
+## Stage: Implementation — TDD (2026-05-26T17:42:41Z)
+
+### Session summary
+
+Completed all 4 TDD cycles: created `test/helpers/manager-stubs.ts` + `manager-stubs.test.ts` (13 smoke tests), migrated `agent-manager.test.ts`, `conversation-viewer.test.ts`, and `agent-config-editor.test.ts`.
+Test count delta: 970 → 983 (+13 from smoke tests).
+All 4 commits landed cleanly; full suite green at every step.
+
+### Observations
+
+- Target file line savings: `agent-manager.test.ts` −63, `conversation-viewer.test.ts` −58, `agent-config-editor.test.ts` −16; offset by +211 for the new helper files.
+  Net LOC is positive, but the _clone_ lines fallow detects are eliminated — the metric the issue targets.
+- 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.0",
+  "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.