@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0232-agent-resume-internal-observer-lifecycle.md

@@ -1,180 +0,0 @@
----
-issue: 232
-issue_title: "Agent.resume() with internal observer lifecycle (Phase 15, Step 6)"
----
-
-# Agent.resume() with internal observer lifecycle
-
-## Problem Statement
-
-After #229 (`Agent.run()` absorbs `startAgent`), the agent owns its entire run lifecycle but `AgentManager.resume()` still duplicates the observer subscribe/use/release pattern that `run()` handles internally.
-The manager manually calls `subscribeAgentObserver`, wraps `runner.resume()` in a try/catch/finally, marks completion/error, and unsubscribes — the same acquire → use → release resource shape `Agent.run()` already encapsulates.
-This is the last "manager reaches into Agent" duplication in the Phase 15 roadmap (priority 8, smell A: redundant pattern).
-
-## Goals
-
-- Add `Agent.resume(prompt, signal?)` that owns its observer subscription lifecycle, mirroring `run()`'s internal wiring.
-- Reduce `AgentManager.resume()` to a guard-plus-delegation method (no `subscribeAgentObserver`, no try/finally).
-- Preserve the existing public contract of `AgentManager.resume()` exactly: same signature, same `Agent | undefined` return, same behavior when the record or session is missing.
-- Keep the change non-breaking (`feat:`, not `feat!:`).
-
-## Non-Goals
-
-- No change to `runner.resume()` / `resumeAgent()` in `agent-runner.ts`.
-- No change to the abort semantics of resume — the parent `signal` continues to flow straight through to `runner.resume({ signal })` (resume does not route through the agent's `abortController`, matching today's behavior).
-- No queue interaction on resume — resume is not subject to the concurrency queue, so `onStarted`/`onRunFinished` are not fired (unchanged from today).
-- No full rewrite of the stale `AgentManager`/`Agent` class diagram in `architecture.md` — that diagram already diverged in #229 (missing `run()`, stale `setupWorktree`/`completeRun`/`setOnRunFinished` signatures); a comprehensive diagram refresh is out of scope here.
-
-## Background
-
-Relevant modules (all under `packages/pi-subagents/src/`):
-
-- `lifecycle/agent.ts` — the `Agent` class.
-  Already owns the per-run listener state (`_unsub`, `_detachFn`), the `attachObserver(unsub)` / `releaseListeners()` pair, `resetForResume(startedAt)` (which calls `releaseListeners()`), and `markCompleted` / `markError`.
-  Holds `_runner` and `observer` (an `AgentLifecycleObserver`) from construction (#229).
-  `Agent.run()` is the template to follow: it wires the observer via `attachObserver(subscribeAgentObserver(session, this, { onCompact: (r, info) => this.observer?.onCompacted?.(r, info) }))`.
-- `lifecycle/agent-manager.ts` — `AgentManager.resume()` currently does the manual subscribe/try-finally dance and imports `subscribeAgentObserver` solely for that.
-- `observation/record-observer.ts` — `subscribeAgentObserver(session, record, options)` returns an unsubscribe function; observes `tool_execution_end`, `message_end`, `compaction_end`.
-- `lifecycle/agent-runner.ts` — `AgentRunner.resume(session, prompt, options?)` returns `Promise<string>` (the response text).
-
-Constraint from AGENTS.md / `package-pi-subagents` skill: pi-subagents is a narrow core; this is a pure internal refactor (Tell-Don't-Ask, "state owns its mutations") with no policy or API-surface change.
-
-### Observer routing equivalence
-
-The manager's old resume wired compaction to the `AgentManagerObserver`:
-
-```typescript
-subscribeAgentObserver(session, record, {
-  onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
-});
-```
-
-`Agent.resume()` instead routes through the per-agent `AgentLifecycleObserver` (`this.observer?.onCompacted?.`), exactly as `run()` does.
-That lifecycle observer is built by `AgentManager.buildObserver()`, whose `onCompacted` forwards to `this.observer?.onAgentCompacted(agent, info)`.
-Net routing is identical — compaction events still reach the manager-level `AgentManagerObserver.onAgentCompacted`.
-
-## Design Overview
-
-### `Agent.resume()`
-
-```typescript
-async resume(prompt: string, signal?: AbortSignal): Promise<void> {
-  if (!this._runner) {
-    throw new Error("Agent not configured for execution — missing runner");
-  }
-  const session = this.session;
-  if (!session) {
-    throw new Error("Agent not configured for resume — missing session");
-  }
-
-  this.resetForResume(Date.now()); // sets running, clears result/error, releases stale listeners
-  this.attachObserver(subscribeAgentObserver(session, this, {
-    onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
-  }));
-
-  try {
-    const responseText = await this._runner.resume(session, prompt, { signal });
-    this.markCompleted(responseText);
-  } catch (err) {
-    this.markError(err);
-  } finally {
-    this.releaseListeners();
-  }
-}
-```
-
-Decision model:
-
-- `resetForResume()` already calls `releaseListeners()`, so any leftover handle from a prior run/resume is cleared before the new subscription is attached.
-- The new subscription handle is stored via `attachObserver()` (reusing the `_unsub` slot shared with `run()`), and released in `finally` via `releaseListeners()`.
-- Errors are captured (`markError`) rather than rethrown — `resume()` resolves like `run()`.
-- The two guards (missing runner, missing session) mirror `run()`'s guard style.
-  They are defensive: the manager guards `agent?.session` before delegating, so the session guard is unreachable in normal flow but protects the invariant for direct `Agent.resume()` callers/tests.
-
-### `AgentManager.resume()` (delegation)
-
-```typescript
-async resume(id: string, prompt: string, signal?: AbortSignal): Promise<Agent | undefined> {
-  const agent = this.agents.get(id);
-  if (!agent?.session) return undefined;
-  await agent.resume(prompt, signal);
-  return agent;
-}
-```
-
-Edge cases preserved:
-
-- Missing record → `undefined` (no throw).
-- Record present but no session → `undefined` (no throw).
-- Session present → delegate, return the agent.
-
-After this change `agent-manager.ts` no longer references `subscribeAgentObserver` — that import must be removed.
-`this.runner` is still used by `spawn()` (passed to the `Agent` constructor), so the `runner` field stays.
-
-## Module-Level Changes
-
-- `src/lifecycle/agent.ts`
-  - Add the public async method `resume(prompt: string, signal?: AbortSignal): Promise<void>` (placed near `run()` per the stepdown rule).
-  - No new imports — `subscribeAgentObserver` is already imported for `run()`.
-- `src/lifecycle/agent-manager.ts`
-  - Replace the body of `resume()` with the guard-plus-delegation form above.
-  - Remove the now-unused `import { subscribeAgentObserver } from "#src/observation/record-observer";`.
-  - No other methods change.
-- `src/lifecycle/agent-runner.ts` — unchanged.
-- `src/observation/record-observer.ts` — unchanged.
-- `docs/architecture/architecture.md` — light doc touch:
-  - In the class diagram, update `AgentManager.resume(id, snapshot, exec)` → `resume(id, prompt, signal)` and add `Agent.resume(prompt, signal)` (and, while there, `Agent.run()`, which #229 omitted).
-  - Mark Step 6 in the Phase 15 roadmap table/section as complete (`✅`).
-  - Note: the class diagram has pre-existing staleness from #229; this touch only corrects the resume-related entries, not the whole diagram.
-
-Symbol-removal check: the only removed symbol is the `subscribeAgentObserver` import in `agent-manager.ts`.
-`grep` confirms `subscribeAgentObserver` is still imported and used in `agent.ts` and defined in `record-observer.ts`, so the export stays live.
-
-No file in Module-Level Changes is claimed unchanged in Non-Goals (the Non-Goals list `agent-runner.ts` and `record-observer.ts`, which are genuinely untouched).
-
-## Test Impact Analysis
-
-This is an extraction/relocation of behavior from the manager into the agent.
-
-1. New unit tests enabled — `Agent.resume()` can now be tested directly on `Agent` (file `test/lifecycle/agent.test.ts`), which was previously impossible because resume logic lived only in the manager.
-   New direct coverage:
-   - `resume()` transitions to `completed` and sets `result` from the runner's response text.
-   - `resume()` transitions to `error` (and does not throw) when `runner.resume()` rejects.
-   - `resume()` subscribes the record-observer to the session (usage/compaction events accumulate on the agent) and releases the subscription in `finally` (handle cleared after completion and after error).
-   - `resume()` throws on missing runner / missing session (guard symmetry with `run()`).
-   - Compaction during resume forwards through `this.observer?.onCompacted?.`.
-
-2. Existing tests that become redundant — none should be deleted.
-   The two manager-level resume tests in `test/lifecycle/agent-manager.test.ts` (`resume() also accumulates usage and increments compactions on the same record` and `calls injected runner.resume when resuming an agent`) now exercise the delegation + observer-forwarding integration rather than the inlined logic.
-   They stay as integration coverage of `AgentManager.resume()` → `Agent.resume()` and the `onCompacted` → `onAgentCompacted` routing.
-   `test/helpers/make-deps.test.ts` (calls `manager.resume(...)`) stays.
-
-3. Existing tests that must stay as-is — the manager-level resume tests above genuinely exercise the manager's guard + delegation seam and the observer routing through `buildObserver`, which the agent-level tests do not cover.
-
-## TDD Order
-
-1. `test/lifecycle/agent.test.ts` — add `Agent.resume()` happy-path + error + guard tests, then implement `Agent.resume()` in `agent.ts`.
-   Covers: completed/result on success, error (no throw) on rejection, observer subscribe + `releaseListeners()` in `finally`, compaction forwarding via `onCompacted`, and the missing-runner / missing-session guards.
-   At this point both the new `Agent.resume()` and the old `AgentManager.resume()` body coexist (lift-and-shift: introduce the new method alongside the old logic).
-   Commit: `feat: add Agent.resume() with internal observer lifecycle`
-2. `test/lifecycle/agent-manager.test.ts` — keep the existing resume tests green, then collapse `AgentManager.resume()` to the guard-plus-delegation form and remove the unused `subscribeAgentObserver` import in the same commit.
-   Removing the import and rewriting the body must land together — the type checker flags the unused import immediately, and the existing manager-level resume tests verify the delegation still satisfies the same contract.
-   Commit: `refactor: delegate AgentManager.resume() to Agent.resume()`
-3. `docs/architecture/architecture.md` — update the class diagram resume entries (and add `Agent.run()`/`Agent.resume()`), mark Step 6 complete.
-   Commit: `docs: mark Phase 15 Step 6 (Agent.resume) complete`
-
-## Risks and Mitigations
-
-- Risk: observer routing diverges (compaction events stop reaching `onAgentCompacted`).
-  Mitigation: the existing manager-level test `resume() also accumulates usage and increments compactions on the same record` asserts `compactionCount` after resume; it stays green only if routing is preserved.
-- Risk: listener leak if `releaseListeners()` is missed on the error path.
-  Mitigation: `releaseListeners()` is in `finally`; a dedicated agent-level test asserts the unsub handle is released after both success and error.
-- Risk: behavior change in abort handling if resume is rerouted through `abortController`.
-  Mitigation: explicitly keep `signal` flowing straight to `runner.resume({ signal })` (Non-Goal), identical to today.
-- Risk: removing the `subscribeAgentObserver` import while another caller still needs it.
-  Mitigation: `grep` confirms `agent.ts` is the only other importer and `record-observer.ts` still exports it.
-
-## Open Questions
-
-- Whether to later refresh the full `AgentManager`/`Agent` class diagram in `architecture.md` (stale since #229).
-  Deferred — out of scope for this issue; a focused follow-up can resync the whole diagram.

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

@@ -1,180 +0,0 @@
----
-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

@@ -1,191 +0,0 @@
----
-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.