---
status: resolved
parent: "[[004-pi-subagents-pi-extension-ecosystem-research]]"
blocked-by: []
tags:
  - ticket/research
---

# Pi fork research

## Question

What is pi-fork, what context-engineering model does it offer, and can its approach help Pi subagents preserve useful context isolation without coupling the subagent mechanism to Herdr?

## Resolution

## Findings

The likely authoritative source is `elpapi42/pi-fork` at `https://github.com/elpapi42/pi-fork`.
The repository package name is `pi-fork`, version `0.1.0`, and the package description is `Cache-friendly fork tool for Pi coding agent`.
Citation: GitHub API for `elpapi42/pi-fork` and `/tmp/pi-fork-research/package.json`.

`pi-fork` is a Pi extension that registers a `fork` tool.
Its README describes it as a context-management extension first and a parallelism extension second.
Citation: `/tmp/pi-fork-research/README.md`.

The core model is active-branch snapshotting.
The extension captures `ctx.sessionManager.getHeader()` and `ctx.sessionManager.getBranch()`, serializes them to temporary JSONL, and starts a child `pi --mode json -p --session <tmp/fork.jsonl>` with the delegated task appended as the final user message.
Citation: `/tmp/pi-fork-research/src/index.ts` and `/tmp/pi-fork-research/src/runner.ts`.

This differs from the official Pi subagent example.
The official example starts isolated child processes with `--no-session` plus optional agent system prompts, while `pi-fork` gives the child the current active conversation branch and keeps the child's tool-heavy transcript out of the parent history.
Citation: Pi `examples/extensions/subagent/README.md`, Pi `examples/extensions/subagent/index.ts`, and `/tmp/pi-fork-research/README.md`.

`pi-fork` uses a structured return contract: `Result`, `Output`, `Evidence`, and `Learnings`.
Its prompt emphasizes decision-useful evidence, ruled-out paths, assumptions, validation meaning, and reusable learnings.
Citation: `/tmp/pi-fork-research/src/runner.ts`.

The repository includes an in-process runtime proposal, but it warns that in-process execution shares memory, extension module state, model registry, event loop, and cancellation surfaces.
It recommends preserving subprocess fallback for strict isolation and per-child environment behavior.
Citation: `/tmp/pi-fork-research/IN_PROCESS_RUNTIME_PROPOSAL.md`.

## Implications

`pi-fork` is highly relevant to the desired context-engineering behavior.
It suggests the subagent primitive should not be defined only as a named persona with a blank context.
A default mode that forks the active branch, runs noisy work elsewhere, and returns a dense evidence-bearing report may better match frequent spawning to keep the parent context clean.

This context model does not require Herdr.
Herdr can remain an optional presentation and lifecycle adapter layered around a host-neutral Pi fork or subagent core.

A future design should consider combining `pi-fork`'s active-branch snapshot model with optional agent overlays for model, tools, instructions, and persistence.
