@gotgenes/pi-subagents 8.0.0 → 9.0.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v9.0.0...pi-subagents-v9.0.1) (2026-05-27)
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#238](https://github.com/gotgenes/pi-packages/issues/238) ([84f2e49](https://github.com/gotgenes/pi-packages/commit/84f2e49c1c7a28e83ca556f377d7e3f970b8a5d2))
+
+## [9.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v8.0.0...pi-subagents-v9.0.0) (2026-05-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* extensions field in agent frontmatter no longer supports a comma-separated allowlist. Values like `extensions: pi-github-tools, colgrep` are coerced to `true` (inherit all). Users who relied on per-extension filtering should migrate to `permission:` frontmatter in pi-permission-system.
+
+### Features
+
+* narrow extensions type from union to boolean ([90350ab](https://github.com/gotgenes/pi-packages/commit/90350abef259f5494990c5796a005f2edba2163d))
+
+
+### Documentation
+
+* mark Phase 14 Step 2 complete in architecture ([fc8bc57](https://github.com/gotgenes/pi-packages/commit/fc8bc57788a3ade9ec2f74200973e5a811c48bb3))
+* plan remove extensions filtering ([#238](https://github.com/gotgenes/pi-packages/issues/238)) ([1f4046a](https://github.com/gotgenes/pi-packages/commit/1f4046a84a308e80472425b5ca9e83263ecc310a))
+* **retro:** add planning stage notes for issue [#238](https://github.com/gotgenes/pi-packages/issues/238) ([b2ce842](https://github.com/gotgenes/pi-packages/commit/b2ce842dcc999fd48f6aeb67c6d464750d6d87aa))
+* **retro:** add retro notes for issue [#237](https://github.com/gotgenes/pi-packages/issues/237) ([6be215e](https://github.com/gotgenes/pi-packages/commit/6be215e6f4d9307f94b5bb61c024292a8eb77469))
+* **retro:** add TDD stage notes for issue [#238](https://github.com/gotgenes/pi-packages/issues/238) ([87256db](https://github.com/gotgenes/pi-packages/commit/87256dbd97ba4a69267f2091896d959bef9ff9df))
+* simplify extensions field to boolean in README ([b4028d7](https://github.com/gotgenes/pi-packages/commit/b4028d7c203fce792238acb147709ad3c3d4d28e))
+
 ## [8.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.8.1...pi-subagents-v8.0.0) (2026-05-27)
 
 

package/README.md

@@ -175,7 +175,7 @@ All fields are optional — sensible defaults for everything.
 | `description`       | filename       | Agent description shown in tool listings                                                                                                                                                               |
 | `display_name`      | —              | Display name for UI (e.g. widget, agent list)                                                                                                                                                          |
 | `tools`             | all 7          | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools                                                                                                           |
-| `extensions`        | `true`         | Inherit MCP/extension tools. `false` to disable                                                                                                                                                        |
+| `extensions`        | `true`         | `true` to inherit all MCP/extension tools, `false` to disable                                                                                                                                          |
 | `skills`            | `true`         | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations)                                                |
 | `memory`            | —              | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents                                                                                                            |
 | `isolation`         | —              | Set to `worktree` to run in an isolated git worktree                                                                                                                                                   |
@@ -479,8 +479,7 @@ Each has a corresponding upstream PR:
 1. **Peer-dep migration to `@earendil-works/pi-*`** — `peerDependencies` and all imports point at `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` (the active scope on npm) instead of the deprecated `@mariozechner/pi-*` scope.
    Also fixes a latent bug where `ThinkingLevel` was imported from `pi-agent-core` (an undeclared transitive dep that breaks under pnpm).
    Upstream PR: [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71).
-2. **Post-`bindExtensions` active-tool re-filter** (`src/agent-runner.ts`) — `runAgent` re-runs its active-tool filter after `session.bindExtensions(...)` so extension-registered tools join the child's active tool set.
-   Without this, the `extensions: string[]` allowlist branch was functionally dead for extension tools.
+2. **Post-`bindExtensions` active-tool re-filter** (`src/agent-runner.ts`) — `runAgent` re-runs its active-tool filter after `session.bindExtensions(...)` so the `EXCLUDED_TOOL_NAMES` recursion guard applies to extension-registered tools (which join the active set during `bindExtensions`).
    Upstream PR: [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
 3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` prepends `<active_agent name="${config.name}"/>` to every assembled child system prompt (both `replace` and `append` modes).
    Downstream extensions like [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) parse this tag to resolve per-agent `permission:` frontmatter inside the child session.

package/docs/architecture/architecture.md

@@ -697,7 +697,7 @@ Remove the `disallowedTools` field from `AgentConfig` and all code that processe
 - Smell: A (responsibility overlap with pi-permission-system)
 - Outcome: users migrate to `permission:` frontmatter for tool restrictions; single source of truth for access control
 
-### Step 2: Remove `extensions` filtering — [#238]
+### Step 2: Remove `extensions` filtering — [#238] ✅ Complete
 
 Remove the `extensions: string[]` allowlist and simplify the field to a boolean.
 The `extensions: false` case (used by `isolated`) is retained in this step and removed in Phase 16.

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/0237-remove-disallowed-tools.md

@@ -39,3 +39,40 @@ All checks (type check, lint, fallow dead-code gate) pass clean.
 - 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,72 @@
+---
+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.
+
+## Stage: Final Retrospective (2026-05-27T01:48:04Z)
+
+### Session summary
+
+All three stages (planning, TDD, shipping) completed in a single continuous session.
+Six implementation commits landed as `pi-subagents-v9.0.0` (major bump from `feat!:`).
+Issue #238 closed; unblocks #239 (collapse `filterActiveTools`).
+
+### Observations
+
+#### What went well
+
+- The plan’s structure closely followed the successful #237 pattern, making execution predictable.
+- The implementer caught the type-narrowing cascade on the first `pnpm run check` and adapted immediately — no user intervention needed.
+- The `resolveBoolExtensions` helper extraction was a clean design choice that keeps `inheritField` reusable for `skills`.
+- ESLint auto-fix of `=== false` → `!` after the type narrowed to `boolean` was handled smoothly within the same commit.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (self-identified) — The planner did not apply the testing skill’s existing rule: “When a TDD plan lists separate steps that share a type definition, changing that type in step N breaks steps N+1…N+k.”
+  The plan assigned test-fixture fixes (removing `extensions: string[]` values) to steps 2–4, but the type change in step 1 broke them all immediately.
+  Impact: no rework — the implementer folded fixes into step 1 — but the plan’s step boundaries were misleading.
+- `missing-context` — The plan recommended `debugLog` for the deprecation warning without checking its function signature (`(context: string, err: unknown)`) or its debug-only behavior.
+  Impact: minor — switched to `console.warn` during implementation with no rework, but the plan was wrong.
+
+#### What caused friction (user side)
+
+- Nothing notable — no user corrections were needed across all three stages.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — Added type-narrowing-specific TDD planning rule: when a step narrows a union type, grep test files for fixtures using the removed variant and fold those fixes into the same step.

package/package.json

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

package/src/config/custom-agents.ts

@@ -58,7 +58,7 @@ 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),
-      extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+      extensions: resolveBoolExtensions(fm.extensions ?? fm.inherit_extensions),
       skills: inheritField(fm.skills ?? fm.inherit_skills),
       model: str(fm.model),
       thinking: str(fm.thinking) as ThinkingLevel | undefined,
@@ -109,6 +109,22 @@ function csvList(val: unknown, defaults: string[]): string[] {
   return parseCsvField(val) ?? [];
 }
 
+/**
+ * Resolve the `extensions` field to a boolean.
+ * CSV/array values (legacy allowlist syntax) are coerced to `true` with a warning.
+ */
+function resolveBoolExtensions(val: unknown): boolean {
+  const result = inheritField(val);
+  if (Array.isArray(result)) {
+    console.warn(
+      "[pi-subagents] extensions allowlist syntax is deprecated — treating as \"true\" (inherit all).\n" +
+        "Use \"permission:\" frontmatter in pi-permission-system for per-tool access control.",
+    );
+    return true;
+  }
+  return result;
+}
+
 /**
  * Parse an inherit field (extensions, skills).
  * omitted/true → true (inherit all); false/"none"/empty → false; csv → listed names.

package/src/lifecycle/agent-runner.ts

@@ -37,16 +37,13 @@ function filterActiveTools(
   config: ToolFilterConfig,
 ): string[] {
   const { toolNames, extensions } = config;
-  if (extensions === false) {
+  if (!extensions) {
     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;
   });
 }
@@ -299,7 +296,7 @@ export async function runAgent(
 
   const agentDir = io.getAgentDir();
 
-  // Load extensions/skills: true or string[] → load; false → don't.
+  // Load extensions/skills: true → load; false → don't.
   // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md - upstream's
   // buildSystemPrompt() re-appends both AFTER systemPromptOverride, which
   // would defeat prompt_mode: replace and isolated: true. Parent context, if
@@ -308,7 +305,7 @@ export async function runAgent(
   const loader = io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
-    noExtensions: cfg.toolFilter.extensions === false,
+    noExtensions: !cfg.toolFilter.extensions,
     noSkills: cfg.noSkills,
     noPromptTemplates: true,
     noThemes: true,
@@ -337,10 +334,9 @@ export async function runAgent(
     thinkingLevel: cfg.thinkingLevel,
   });
 
-  // Filter active tools: remove our own tools to prevent nesting,
-  // apply extension allowlist if specified.
+  // Filter active tools: remove our own tools to prevent nesting.
   // First pass - over built-in tools, before bindExtensions registers extension tools.
-  if (cfg.toolFilter.extensions !== false) {
+  if (cfg.toolFilter.extensions) {
     const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
     session.setActiveToolsByName(filtered);
   }
@@ -363,9 +359,9 @@ export async function runAgent(
   // Patch 2 (RepOne #443): re-filter active tools after bindExtensions.
   // Extension-registered tools (added during bindExtensions) are not in the
   // session's active set when the first filter pass runs above. Without this
-  // re-filter, the `extensions: string[]` allowlist branch never matches any
-  // extension tools. Run the same filter against the post-bind active set.
-  if (cfg.toolFilter.extensions !== false) {
+  // re-filter, EXCLUDED_TOOL_NAMES would not be applied to extension-registered
+  // tools. Run the same filter against the post-bind active set.
+  if (cfg.toolFilter.extensions) {
     const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
     session.setActiveToolsByName(refiltered);
   }

package/src/session/session-config.ts

@@ -27,8 +27,8 @@ import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "#src/types"
 export interface ToolFilterConfig {
   /** Built-in tool name allowlist for this agent type. */
   toolNames: string[];
-  /** Resolved extensions setting: false | true | string[] allowlist. */
-  extensions: boolean | string[];
+  /** Resolved extensions setting: true = inherit all, false = none. */
+  extensions: boolean;
 }
 
 /**

package/src/types.ts

@@ -42,8 +42,8 @@ export interface AgentPromptConfig {
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
   builtinToolNames?: string[];
-  /** true = inherit all, string[] = only listed, false = none */
-  extensions: true | string[] | false;
+  /** true = inherit all extensions, false = none */
+  extensions: boolean;
   /** true = inherit all, string[] = only listed, false = none */
   skills: true | string[] | false;
   model?: string;

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

@@ -47,9 +47,7 @@ export function buildEjectContent(cfg: AgentConfig): string {
   if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`);
   if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`);
   fmFields.push(`prompt_mode: ${cfg.promptMode}`);
-  if (cfg.extensions === false) fmFields.push("extensions: false");
-  else if (Array.isArray(cfg.extensions))
-    fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
+  if (!cfg.extensions) fmFields.push("extensions: false");
   if (cfg.skills === false) fmFields.push("skills: false");
   else if (Array.isArray(cfg.skills))
     fmFields.push(`skills: ${cfg.skills.join(", ")}`);

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

@@ -104,7 +104,7 @@ model: <optional model as "provider/modelId", e.g. "anthropic/claude-haiku-4-5-2
 thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit to inherit>
 max_turns: <optional max agentic turns. 0 or omit for unlimited (default)>
 prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
-extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
+extensions: <true (inherit all MCP/extension tools) or false (none). Default: true>
 skills: <true (inherit all), false (none), or comma-separated skill names to preload into prompt. Default: true>
 inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
 run_in_background: <true to run in background by default. Default: false>