@gotgenes/pi-subagents 10.0.0 → 10.0.1

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+## [10.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.0.0...pi-subagents-v10.0.1) (2026-05-27)
+
+
+### Documentation
+
+* mark Phase 14 Step 3 complete in architecture ([fb374ba](https://github.com/gotgenes/pi-packages/commit/fb374ba5829945a4d2f71d8a611bc5128cdd3bf1))
+* plan collapse filterActiveTools to recursion guard ([#239](https://github.com/gotgenes/pi-packages/issues/239)) ([411b22e](https://github.com/gotgenes/pi-packages/commit/411b22ef8186e5fe73bfa81672edfe473ad9d76a))
+* **retro:** add planning stage notes for issue [#239](https://github.com/gotgenes/pi-packages/issues/239) ([c0383b1](https://github.com/gotgenes/pi-packages/commit/c0383b1d9333b70d61a80b75cd1e6e2724d91ad3))
+* **retro:** add retro notes for issue [#242](https://github.com/gotgenes/pi-packages/issues/242) ([69c8cc2](https://github.com/gotgenes/pi-packages/commit/69c8cc269f6dfd6552aecb6d073ea86bb22267dd))
+* **retro:** add TDD stage notes for issue [#239](https://github.com/gotgenes/pi-packages/issues/239) ([f4098a0](https://github.com/gotgenes/pi-packages/commit/f4098a084564dd75bd683449a2aa3926ae36cba3))
+
 ## [10.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v9.0.1...pi-subagents-v10.0.0) (2026-05-27)
 
 

package/docs/architecture/architecture.md

@@ -453,7 +453,7 @@ The target state eliminates this overlap and flips the dependency direction.
 
 ### Responsibilities to remove
 
-- **Tool policy** (`disallowed_tools`, `ToolFilterConfig.disallowedSet`) — access control belongs in pi-permission-system's `permission:` frontmatter.
+- **Tool policy** (`disallowed_tools`) — access control belongs in pi-permission-system's `permission:` frontmatter.
 - **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
 - **Permission bridge** (`permission-bridge.ts`) — outbound coupling to pi-permission-system.
   Replaced by lifecycle events that pi-permission-system listens for.
@@ -496,7 +496,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done    |
 | `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done    |
 | `RunOptions`                | 9 (`RunContext` nested)                                | agent-runner                                      | ✓ done    |
-| `SessionConfig`             | 8 (ToolFilterConfig nested)                            | agent-runner (output of assembler)                | ✓ done    |
+| `SessionConfig`             | 8 (flat fields, ToolFilterConfig removed)              | agent-runner (output of assembler)                | ✓ done    |
 | `NotificationDetails`       | 10                                                     | notification                                      | Low (DTO) |
 | `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Low (SDK) |
 | `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done    |
@@ -677,8 +677,8 @@ Removing it simplifies `runAgent`, shrinks `AgentConfig` and `SessionConfig`, an
 | ----------------------------------------------------------------------------------------- | ------------- | ------ | ---- | -------- |
 | `disallowed_tools` duplicates pi-permission-system's `permission:` frontmatter            | A: Overlap    | 4      | 2    | 12       |
 | `extensions: string[]` allowlist is tool filtering disguised as lifecycle control         | A: Overlap    | 3      | 2    | 9        |
-| `filterActiveTools` runs twice (pre-bind + post-bind) to catch extension-registered tools | B: Complexity | 3      | 1    | 6        |
-| `ToolFilterConfig` exists solely to carry filtering state through the runner              | C: Accidental | 2      | 1    | 4        |
+| `filterActiveTools` ran twice (pre-bind + post-bind) to catch extension-registered tools  | B: Complexity | 3      | 1    | ✓ done   |
+| `ToolFilterConfig` existed solely to carry filtering state through the runner             | C: Accidental | 2      | 1    | ✓ done   |
 | `Agent` tool name is PascalCase — misaligns with Pi's lowercase built-in convention       | D: Convention | 2      | 1    | 3        |
 
 ### Step 1: Remove `disallowed_tools` — [#237] ✅ Complete
@@ -713,17 +713,17 @@ The `extensions: false` case (used by `isolated`) is retained in this step and r
 - Smell: A (tool filtering disguised as extension lifecycle control)
 - Outcome: `filterActiveTools` reduces to two concerns: recursion guard and `extensions: false` passthrough
 
-### Step 3: Collapse `filterActiveTools` to recursion guard — [#239]
+### Step 3: Collapse `filterActiveTools` to recursion guard — [#239] ✅ Complete
 
-With Steps 1–2 complete, `filterActiveTools` has only two remaining branches: the `EXCLUDED_TOOL_NAMES` recursion guard and the `extensions === false` passthrough.
-Inline the `extensions === false` passthrough into the callsite and reduce the function to its essential purpose.
+With Steps 1–2 complete, `filterActiveTools` had only two remaining branches: the `EXCLUDED_TOOL_NAMES` recursion guard and the `extensions === false` passthrough.
+Inlined the `extensions === false` passthrough into the callsite and reduced the function to its essential purpose.
 
-1. Simplify `filterActiveTools` to filter only `EXCLUDED_TOOL_NAMES`.
-2. Remove `ToolFilterConfig` — the function no longer needs a config bag.
-3. Remove the pre-bind filter call — extension tools aren't in the active set yet, so filtering built-in tools pre-bind is only needed for denylist/allowlist logic that no longer exists.
-4. Keep a single post-bind filter call for the recursion guard.
-5. Simplify `SessionConfig` — remove the `toolFilter` field, keep `toolNames` as a flat field.
-6. Update tests.
+1. Simplified `filterActiveTools` to filter only `EXCLUDED_TOOL_NAMES`.
+2. Removed `ToolFilterConfig` — the function no longer needs a config bag.
+3. Removed the pre-bind filter call — extension tools aren't in the active set pre-bind, so the guard is a no-op there.
+4. Kept a single post-bind filter call for the recursion guard.
+5. Flattened `SessionConfig` — removed `toolFilter: ToolFilterConfig`; `toolNames` and `extensions` are top-level fields.
+6. Updated tests.
 
 - Target: `agent-runner.ts`, `session-config.ts`
 - Smell: B (accidental complexity), C (two-pass filter dance)

package/docs/plans/0239-collapse-filter-active-tools.md

@@ -0,0 +1,217 @@
+---
+issue: 239
+issue_title: "Collapse filterActiveTools to recursion guard (Phase 14, Step 3)"
+---
+
+# Collapse `filterActiveTools` to recursion guard
+
+## Problem Statement
+
+With `disallowed_tools` (#237) and `extensions` filtering (#238) removed, `filterActiveTools` retains two branches that no longer justify a config bag or two-pass pre-bind/post-bind dance:
+
+1. The `extensions === false` early return — a passthrough that belongs at the callsite.
+2. The `EXCLUDED_TOOL_NAMES` recursion guard — the function's sole essential purpose.
+
+The `builtinToolNameSet` membership check always returns `true` now (no string-array `extensions` filtering remains), making it dead logic.
+`ToolFilterConfig` exists only to carry two fields (`toolNames`, `extensions`) through the assembler→runner boundary, but after this change they travel independently: `toolNames` feeds `createSession`, `extensions` feeds the resource loader's `noExtensions` flag, and neither is consumed by the filter function.
+
+## Goals
+
+- Reduce `filterActiveTools` to a one-liner: filter out `EXCLUDED_TOOL_NAMES`.
+- Delete the `ToolFilterConfig` interface.
+- Flatten `SessionConfig.toolFilter` back into two top-level fields: `toolNames` and `extensions`.
+- Remove the pre-bind filter call — without denylist/allowlist logic, filtering before `bindExtensions` serves no purpose.
+- Keep a single post-bind filter call for the recursion guard.
+- Update tests to reflect the simplified flow.
+
+## Non-Goals
+
+- Removing `extensions` from `SessionConfig` entirely — it's still needed for the `noExtensions` flag on the resource loader.
+- Renaming `EXCLUDED_TOOL_NAMES` or moving it to a separate module.
+- Phase 15 domain model changes (#227–#232) — those operate on the simplified codebase this change produces.
+
+## Background
+
+`filterActiveTools` was extracted as part of Phase 10 (#168) to group `toolNames`, `disallowedSet`, and `extensions` into a `ToolFilterConfig` bag.
+Issue #237 removed `disallowedSet`; #238 narrowed `extensions` from `true | string[] | false` to `boolean`.
+Both are now closed.
+
+The two-pass filter dance (Patch 2, RepOne #443) exists to catch extension-registered tools that join the active set during `bindExtensions`.
+With the only remaining filter logic being the `EXCLUDED_TOOL_NAMES` guard, a single post-bind pass suffices.
+
+Current `filterActiveTools` body:
+
+```typescript
+function filterActiveTools(
+  activeTools: string[],
+  config: ToolFilterConfig,
+): string[] {
+  const { toolNames, extensions } = config;
+  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;
+    return true;
+  });
+}
+```
+
+The `builtinToolNameSet` check is dead — both branches return `true`.
+The `!extensions` early return belongs at the callsite.
+
+### Affected files
+
+- `src/lifecycle/agent-runner.ts` — `filterActiveTools`, pre-bind/post-bind calls, `ToolFilterConfig` import
+- `src/session/session-config.ts` — `ToolFilterConfig` interface, `SessionConfig.toolFilter` field, assembler return literal
+- `test/lifecycle/agent-runner-extension-tools.test.ts` — pre-bind/post-bind assertions
+- `test/session/session-config.test.ts` — `toolFilter.*` assertions
+- `test/lifecycle/agent-runner.test.ts` — session mock (`setActiveToolsByName` calls)
+- `docs/architecture/architecture.md` — references to `ToolFilterConfig`, `filterActiveTools`, Phase 14 status
+
+## Design Overview
+
+### `filterActiveTools` simplification
+
+The function reduces to:
+
+```typescript
+function filterActiveTools(activeTools: string[]): string[] {
+  return activeTools.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
+}
+```
+
+No config parameter.
+The `extensions === false` guard moves to the callsite: `if (cfg.extensions)`.
+
+### `SessionConfig` flattening
+
+```typescript
+export interface SessionConfig {
+  effectiveCwd: string;
+  systemPrompt: string;
+  toolNames: string[];       // was toolFilter.toolNames
+  extensions: boolean;        // was toolFilter.extensions
+  model: unknown;
+  thinkingLevel: ThinkingLevel | undefined;
+  noSkills: boolean;
+  extras: PromptExtras;
+  agentMaxTurns: number | undefined;
+}
+```
+
+### `runAgent` callsite changes
+
+Before (two-pass):
+
+```typescript
+if (cfg.toolFilter.extensions) {
+  const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
+  session.setActiveToolsByName(filtered);
+}
+// ... bindExtensions ...
+if (cfg.toolFilter.extensions) {
+  const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
+  session.setActiveToolsByName(refiltered);
+}
+```
+
+After (single post-bind pass):
+
+```typescript
+// ... bindExtensions ...
+if (cfg.extensions) {
+  const filtered = filterActiveTools(session.getActiveToolNames());
+  session.setActiveToolsByName(filtered);
+}
+```
+
+Other `cfg.toolFilter.*` references update to `cfg.toolNames` and `cfg.extensions`.
+
+## Module-Level Changes
+
+### `src/session/session-config.ts`
+
+1. Delete the `ToolFilterConfig` interface.
+2. Replace `toolFilter: ToolFilterConfig` on `SessionConfig` with two flat fields: `toolNames: string[]` and `extensions: boolean`.
+3. Update the return literal in `assembleSessionConfig` from `toolFilter: { toolNames, extensions }` to `toolNames, extensions`.
+4. Update the JSDoc on `SessionConfig` — remove "Tool filtering cluster" comment.
+
+### `src/lifecycle/agent-runner.ts`
+
+1. Remove the `ToolFilterConfig` import.
+2. Simplify `filterActiveTools` to `(activeTools: string[]) => string[]` — just the `EXCLUDED_TOOL_NAMES` filter.
+3. Remove the pre-bind filter block (the first `if (cfg.toolFilter.extensions)` block).
+4. Update the post-bind filter block: `cfg.toolFilter.extensions` → `cfg.extensions`, remove the config argument from the `filterActiveTools` call.
+5. Update `noExtensions: !cfg.toolFilter.extensions` → `noExtensions: !cfg.extensions`.
+6. Update `tools: cfg.toolFilter.toolNames` → `tools: cfg.toolNames`.
+7. Update or remove the Patch 2 comments — the two-pass dance is gone; the remaining call is just a recursion guard.
+
+### `test/lifecycle/agent-runner-extension-tools.test.ts`
+
+1. Remove the pre-bind/post-bind ordering assertions — there is only one post-bind call now.
+2. Update `setActiveToolsByName` call count expectations from 2 to 1.
+3. Update assertions to check `setActiveToolsByName.mock.calls[0][0]` (was `calls[1][0]` for the second call).
+4. The `extensions: false` test continues to assert that `setActiveToolsByName` is not called.
+
+### `test/session/session-config.test.ts`
+
+1. Update `result.toolFilter.toolNames` → `result.toolNames`.
+2. Update `result.toolFilter.extensions` → `result.extensions`.
+
+### `test/lifecycle/agent-runner.test.ts`
+
+1. No structural changes needed — the session mock already has `setActiveToolsByName: vi.fn()`, and the default test config has `extensions: false` (so the filter doesn't run).
+   If any test asserts on `setActiveToolsByName` call counts, verify they still pass.
+
+### `docs/architecture/architecture.md`
+
+1. Update the Phase 14 Step 3 entry to mark it complete.
+2. Update the structural analysis table: `SessionConfig` field count changes, `ToolFilterConfig` is removed.
+3. Update the smell table to mark the two-pass filter and `ToolFilterConfig` smells as resolved.
+
+## Test Impact Analysis
+
+1. **New tests enabled:** None — the simplification doesn't introduce new testable surface.
+2. **Tests that become redundant:** The pre-bind/post-bind ordering test in `agent-runner-extension-tools.test.ts` — the pre-bind call is removed.
+   The test that the post-bind filter includes extension tools stays; it verifies the recursion guard runs after `bindExtensions`.
+3. **Tests that stay as-is:** The `extensions: false` skip test, the `EXCLUDED_TOOL_NAMES` exclusion test, all `session-config.test.ts` tests (with property path updates).
+
+## TDD Order
+
+1. **Flatten `SessionConfig` and delete `ToolFilterConfig`** — Replace `toolFilter: ToolFilterConfig` with `toolNames: string[]` and `extensions: boolean` on `SessionConfig`.
+   Delete the `ToolFilterConfig` interface.
+   Update the assembler return literal.
+   Update `session-config.test.ts` property paths (`result.toolFilter.toolNames` → `result.toolNames`, `result.toolFilter.extensions` → `result.extensions`).
+   Run `pnpm run check` to verify downstream compile errors (expected in `agent-runner.ts`).
+   Commit: `refactor: flatten SessionConfig and remove ToolFilterConfig`
+
+2. **Simplify `filterActiveTools` and remove pre-bind call** — Reduce `filterActiveTools` to `(activeTools: string[]) => string[]`.
+   Remove the `ToolFilterConfig` import.
+   Remove the pre-bind filter block.
+   Update the post-bind filter block to use `cfg.extensions` and pass no config to `filterActiveTools`.
+   Update `noExtensions` and `tools` references to `cfg.extensions` and `cfg.toolNames`.
+   Update `agent-runner-extension-tools.test.ts`: change `setActiveToolsByName` call count from 2 to 1, update assertion indices from `calls[1]` to `calls[0]`, remove the pre-bind/post-bind ordering test, update comments.
+   Verify `agent-runner.test.ts` still passes.
+   Commit: `refactor: simplify filterActiveTools to recursion guard`
+
+3. **Update architecture docs** — Mark Phase 14 Step 3 as complete.
+   Update `SessionConfig` field count and remove `ToolFilterConfig` references from the structural analysis.
+   Mark the two-pass filter and `ToolFilterConfig` smells as resolved.
+   Commit: `docs: mark Phase 14 Step 3 complete in architecture`
+
+## Risks and Mitigations
+
+1. **Pre-bind filter removal may miss a recursion-guard edge case** — If a subagent's own tools (`subagent`, `get_subagent_result`, `steer_subagent`) were in the built-in tool set before `bindExtensions`, removing the pre-bind filter could leave them active during the bind phase.
+   Mitigation: These tools are registered by this extension during `bindExtensions`, not before.
+   They cannot be in the pre-bind active set.
+   The post-bind filter is sufficient.
+
+2. **Flattening `SessionConfig` may break external consumers** — `SessionConfig` is not exported from the package entry point; it's an internal interface between `session-config.ts` and `agent-runner.ts`.
+   No external consumers exist.
+
+## Open Questions
+
+None — the issue's changes are unambiguous and all dependencies are complete.

package/docs/retro/0239-collapse-filter-active-tools.md

@@ -0,0 +1,37 @@
+---
+issue: 239
+issue_title: "Collapse filterActiveTools to recursion guard (Phase 14, Step 3)"
+---
+
+# Retro: #239 — Collapse filterActiveTools to recursion guard
+
+## Stage: Planning (2026-05-27T20:00:00Z)
+
+### Session summary
+
+Produced a 3-step TDD plan to flatten `SessionConfig.toolFilter` into top-level `toolNames` and `extensions` fields, simplify `filterActiveTools` to a one-liner recursion guard, remove the pre-bind filter call, and update architecture docs.
+Both dependencies (#237, #238) are confirmed closed.
+
+### Observations
+
+- The `builtinToolNameSet` membership check in `filterActiveTools` is fully dead code — both branches return `true` after #238 removed the `string[]` extensions path.
+- `ToolFilterConfig` is only imported by `agent-runner.ts` and never referenced in test files, so deletion is clean.
+- The pre-bind filter call is safe to remove because `EXCLUDED_TOOL_NAMES` tools (`subagent`, `get_subagent_result`, `steer_subagent`) are registered by this extension during `bindExtensions`, not before — they cannot appear in the pre-bind active set.
+- The `agent-runner-extension-tools.test.ts` file has 4 tests; 1 becomes structurally impossible (pre-bind/post-bind ordering) and the remaining 3 need assertion index adjustments (`calls[1]` → `calls[0]`).
+- `SessionConfig` is internal-only (not package-exported), so flattening has no external API impact.
+
+## Stage: Implementation — TDD (2026-05-27T22:00:00Z)
+
+### Session summary
+
+Completed all 3 TDD cycles: (1) flattened `SessionConfig` and deleted `ToolFilterConfig`, (2) simplified `filterActiveTools` to a one-liner and removed the pre-bind filter call, (3) updated architecture docs to mark Phase 14 Step 3 complete.
+Test count held at 977 (no net change — the extension-tools test file was rewritten, removing 1 test and updating 3 others while keeping the same total count).
+A follow-up skill maintenance commit updated `.pi/skills/package-pi-subagents/SKILL.md` to remove stale Patch 2 references.
+
+### Observations
+
+- The plan's step order (SessionConfig first → expected compile errors in `agent-runner.ts` → green after runner update) worked exactly as designed with no surprises.
+- `agent-runner.test.ts` needed no changes — the default test config has `extensions: false`, so the filter call never ran in those tests.
+- Pre-completion reviewer returned **WARN** for stale `package-pi-subagents` skill content: the "Patch 2 scheduled for removal" note and the `// Patch 2 (RepOne` grep instruction were both stale after #239 completion.
+  Fixed immediately as a follow-up `docs:` commit before writing retro notes.
+- `pnpm fallow dead-code` passed with 0 issues — no orphaned exports left behind.

package/docs/retro/0242-rename-agent-tool-to-subagent.md

@@ -35,3 +35,48 @@ Pre-completion reviewer returned **PASS**.
 - The general-purpose agent type's `displayName: "Agent"` in `default-agents.ts` and `agent-types.ts` fallback was correctly left unchanged; `display.test.ts` still passes with `"Agent"`.
 - The description body inside the `agent-tool.ts` template literal needed separate edits because the guideline lines are not tab-indented (inside a backtick template literal, tab indentation does not apply).
 - Pre-completion reviewer: PASS — all deterministic checks, conventional commits, documentation, code design, tests, Mermaid diagrams, and dead-code gate all passed.
+
+## Stage: Final Retrospective (2026-05-27T14:07:32Z)
+
+### Session summary
+
+Completed the full plan→TDD→ship→retro lifecycle for #242 in a single session.
+Released as `pi-subagents-v10.0.0` (major bump from `feat!:` breaking change).
+Found and fixed one stale `Agent` tool reference in `.pi/skills/pre-completion/SKILL.md`.
+
+### Observations
+
+#### What went well
+
+- Three-model pipeline (opus for planning, sonnet for TDD, deepseek-flash for shipping) matched task complexity to model capability with no quality issues.
+- The plan's distinction between tool name (`"Agent"`) and agent-type `displayName` (`"Agent"`) prevented false-positive test updates — 8 test files reference `"Agent"` but only 4 needed changes.
+- Pre-completion reviewer caught no issues (PASS), confirming thorough planning.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — Two failed `Edit` calls on `agent-tool.ts` line 175: the template literal's guideline lines have no tab indentation, but the agent initially assumed tab depth from the surrounding function.
+   Impact: 3 extra tool calls (grep to inspect actual indentation, then successful edit); no rework.
+   Self-identified.
+2. `wrong-abstraction` — Retro file edit duplicated Planning observations into the TDD stage because the `Edit` `oldText` matched from the Observations heading and the replacement included both old and new content.
+   Impact: 2 extra tool calls (read file, full `write` to fix); no rework.
+   Self-identified.
+3. `missing-context` — `.pi/skills/pre-completion/SKILL.md` line 32 references the `Agent` tool by name but was not in the plan's scope.
+   The plan checked pi-permission-system docs, `README.md`, and architecture docs but did not grep skill files for the old tool name.
+   Impact: discovered during retro; fixed as a retro change.
+
+#### What caused friction (user side)
+
+- None — the full pipeline ran with zero user corrections.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Pre-completion reviewer ran as a default-model subagent (292.7s, 36 tool uses, 63.9k tokens).
+  Appropriate for the judgment-heavy review task.
+  Ship stage on `deepseek-v4-flash` was notably efficient for purely mechanical work.
+- **Feedback-loop gap analysis** — Verification was incremental: baseline check before TDD, per-file tests after Red and Green phases, full suite after implementation, then check + lint + fallow.
+  No gaps.
+
+### Changes made
+
+1. `.pi/skills/pre-completion/SKILL.md` — updated stale `Agent` tool reference to `subagent` on line 32.
+2. `.pi/agents/pre-completion-reviewer.md` — added rename-grep heuristic to the Skills bullet under Forward documentation checks: "When the change renames a symbol, grep `.pi/skills/` and `.pi/prompts/` for the old name."

package/package.json

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

package/src/lifecycle/agent-runner.ts

@@ -15,37 +15,22 @@ import { registerChildSession, unregisterChildSession } from "#src/lifecycle/per
 import { extractAssistantContent } from "#src/session/content-items";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
-import { type AssemblerIO, assembleSessionConfig, type ToolFilterConfig } from "#src/session/session-config";
+import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
 import type { ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];
 
 /**
- * Filter the session's active tool names according to extension rules.
+ * Filter the session's active tool names: remove recursion-guard tools.
  *
- * Run twice - once before `bindExtensions` (filters built-in tools) and once after
- * (filters extension-registered tools, which only join the active set during
- * `bindExtensions`). Extracting this keeps the two callsites consistent and makes
- * the post-bind re-filter trivial.
+ * Run once after `bindExtensions` so extension-registered tools (added during
+ * `bindExtensions`) are also covered by the guard.
  *
  * @param activeTools  Names currently active on the session.
- * @param config       Tool filtering configuration from the assembled session config.
  */
-function filterActiveTools(
-  activeTools: string[],
-  config: ToolFilterConfig,
-): string[] {
-  const { toolNames, extensions } = config;
-  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;
-    return true;
-  });
+function filterActiveTools(activeTools: string[]): string[] {
+  return activeTools.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
 }
 
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
@@ -305,7 +290,7 @@ export async function runAgent(
   const loader = io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
-    noExtensions: !cfg.toolFilter.extensions,
+    noExtensions: !cfg.extensions,
     noSkills: cfg.noSkills,
     noPromptTemplates: true,
     noThemes: true,
@@ -329,18 +314,11 @@ export async function runAgent(
     settingsManager: io.createSettingsManager(cfg.effectiveCwd, agentDir),
     modelRegistry: snapshot.modelRegistry,
     model: cfg.model,
-    tools: cfg.toolFilter.toolNames,
+    tools: cfg.toolNames,
     resourceLoader: loader,
     thinkingLevel: cfg.thinkingLevel,
   });
 
-  // 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) {
-    const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
-    session.setActiveToolsByName(filtered);
-  }
-
   // Register with pi-permission-system's SubagentSessionRegistry before
   // bindExtensions() so isSubagentExecutionContext() hits the registry on the
   // first check during child extension initialization. Unregistered in the
@@ -356,14 +334,13 @@ export async function runAgent(
   // respect the active tool set. All ExtensionBindings fields are optional.
   await session.bindExtensions({});
 
-  // 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, 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);
+  // Apply recursion guard: remove our own tools from the child's active set.
+  // Runs after bindExtensions so extension-registered tools are included in the
+  // post-bind active set. Only needed when extensions are loaded (extensions: false
+  // means no extension tools were registered, so the guard is a no-op).
+  if (cfg.extensions) {
+    const filtered = filterActiveTools(session.getActiveToolNames());
+    session.setActiveToolsByName(filtered);
   }
 
   options.onSessionCreated?.(session);

package/src/session/session-config.ts

@@ -18,19 +18,6 @@ import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "#src/types"
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 
-/**
- * Tool filtering configuration — consumed by `filterActiveTools` in `agent-runner.ts`.
- *
- * Groups the two fields that travel together through the assembly→runner boundary:
- * the built-in tool allowlist and the extensions setting.
- */
-export interface ToolFilterConfig {
-  /** Built-in tool name allowlist for this agent type. */
-  toolNames: string[];
-  /** Resolved extensions setting: true = inherit all, false = none. */
-  extensions: boolean;
-}
-
 /**
  * IO collaborators injected into `assembleSessionConfig`.
  *
@@ -98,8 +85,10 @@ export interface SessionConfig {
   effectiveCwd: string;
   /** Fully-assembled system prompt string (ready for `systemPromptOverride`). */
   systemPrompt: string;
-  /** Tool filtering cluster — tool allowlist, denylist, and extensions setting. */
-  toolFilter: ToolFilterConfig;
+  /** Built-in tool name allowlist for this agent type. */
+  toolNames: string[];
+  /** Resolved extensions setting: true = inherit all, false = none. */
+  extensions: boolean;
   /**
    * Resolved model instance (undefined → use parent model as passed to SDK).
    * Opaque handle — the assembler passes it through without inspection.
@@ -222,7 +211,8 @@ export function assembleSessionConfig(
   return {
     effectiveCwd,
     systemPrompt,
-    toolFilter: { toolNames, extensions },
+    toolNames,
+    extensions,
     model,
     thinkingLevel,
     noSkills,