Inherit active registered tools in spawn children

[grzegorznowak]

Summary

Spawned child agents now inherit the parent session's active registered executable tools, so delegation through spawn can keep legitimate MCP, extension, package/project, local extension, and built-in tool access while still blocking recursive session-control tools.

Requirements

• Compute inherited child tool access from active parent tools that are also registered executable tools in the Pi session.
• Preserve child-local notebook tools alongside inherited parent tool names.
• Keep spawn and handoff unavailable inside spawned children.
• Treat ChunkHound/MCP tools as examples of active registered tools, not as a hardcoded special case.
• Keep inactive, unregistered, or phantom parent-only tool names out of the child allowlist.
• Align spawn metadata, README, and changelog wording with the active registered/executable inheritance contract.

Acceptance criteria

• Spawn children inherit active registered built-in parent tools.
• Spawn children inherit active registered MCP/extension parent tools, including ChunkHound tools when they are registered and active.
• Spawn children inherit active registered package/project/local extension tools using the same source-agnostic rule.
• Spawn children exclude inactive registered tools and active names that are not registered executable tools.
• Spawn children exclude spawn and handoff unconditionally.
• Spawn children preserve child-local notebook tools.
• The real spawn execution path passes the computed parent-tool allowlist into the child session.
• Public tool metadata, README, and changelog describe the qualified active registered/executable behavior and recursive-tool exclusions.
• Automated agentic verification demonstrates a spawned child using an active registered non-builtin tool through the real spawn route.

Contract changes

• spawn child sessions now inherit active registered executable parent tools source-agnostically instead of only built-in tools.
• Child sessions still do not receive recursive spawn/handoff access, inactive tools, unregistered phantom names, or generic parent custom-tool forwarding.
• Documentation now states the qualified inheritance contract and uses ChunkHound/MCP as an example of registered tool inheritance.

Out of scope

• Pi core session creation changes.
• MCP bridge, ChunkHound, or tool registration behavior changes.
• Recursive spawn, handoff, or automatic handoff inside children.
• A user-facing settings UI or arbitrary spawn tool allowlist.
• Generic parent custom-tool forwarding.
• Making harness-only, inactive, or unregistered parent-only names available in children.

How to verify

From the package checkout, prepare the local Pi test loader and run:

python3 - <<'PY'
from pathlib import Path
loader = Path("test-loader.mjs").read_text()
loader = loader.replace(
    "/Users/ofri/.nvm/versions/node/v24.14.1/lib/node_modules/@earendil-works/pi-coding-agent",
    "/usr/local/share/nvm/versions/node/v24.14.0/lib/node_modules/@earendil-works/pi-coding-agent",
)
Path("/tmp/pi-agenticoding-test-loader.mjs").write_text(loader)
PY

node --loader /tmp/pi-agenticoding-test-loader.mjs --test \
  --test-name-pattern 'agentic e2e spawn child can use active registered non-builtin tool' \
  agenticoding.test.ts

node --loader /tmp/pi-agenticoding-test-loader.mjs --test \
  --test-name-pattern 'spawn|child tool|metadata|README|CHANGELOG' \
  agenticoding.test.ts

node --loader /tmp/pi-agenticoding-test-loader.mjs --test agenticoding.test.ts

Optional real-session confidence check: start Pi with spawn and an active registered MCP/extension tool such as a ChunkHound tool, spawn a child, and confirm the child can use that tool while still lacking recursive spawn/handoff access.

Epic reference

• Epic: pi-agenticoding
• Story: 04 — Inherit active registered tools in spawn children
• Step file: agent_coordination/epics/pi-agenticoding/story-04-inherit-trusted-spawn-tools.md

[ofriw]

Note: This review was generated by an AI agent. If you'd like to talk with other humans, drop by our Discord!

---

Nice direction overall, but I’m not comfortable approving this yet because the verification doesn’t fully support the contract the PR now claims. The main issue is the new non-builtin inheritance “e2e” coverage in agenticoding.test.ts: it still runs through a mocked child session factory, so it only proves that the tool name is passed into config, not that a spawned child can actually execute an inherited non-builtin tool through the real createAgentSession/tool stack. Since the README, changelog, and tool metadata now make a stronger user-facing promise around active registered non-builtin tools, I think we need at least one real contract-level test to back that up.

There’s also a smaller cleanup issue in CHANGELOG.md: main already has an ## [Unreleased] section near the bottom, and this PR adds a second one at the top, so merging as-is will leave duplicate unreleased sections. Requested changes are therefore: add one real boundary test for the new spawn inheritance contract, and fold the changelog note into the existing unreleased section instead of introducing a second header.

---

Attached is an agent optimized description of the changes in this PR - AGENT_REVIEW.md

[grzegorznowak]

FB-010 repair pushed in commit 463b3d3.

Summary:

• Replaced A10 mocked/config-only proof with a real parent spawn route test using default child createAgentSession / registered-tool execution stack.
• The deterministic child model now calls a project-local registered non-builtin agentic_e2e_probe tool and only returns AGENTIC_E2E_PROBE_OK after observing the real child toolResult.
• Folded the Story 04 changelog note into the single current ## [Unreleased] section.

Local verification:

• Focused A10: pass 1/1
• Focused story pattern: pass 45/45
• Full agenticoding.test.ts: pass 131/131
• Changelog ## [Unreleased] count: 1