The pi-task section already explained the tool in depth. What was missing was
the decision: given a subtask, which mechanism, and why. Adds an end-user
section built on the L0-L4 ladder — the child's context volume is the axis that
explains nearly every observed good and bad behaviour — plus when to use
neither.
Carries the measured cost so the choice is priced, not guessed: 9 runs,
$0.669 total, $0.0027 (fast, refused an over-budget spec in 2.5s) to $0.165
(balanced, 87s). Includes the jq one-liner, and the warning that a crashed run
leaves no result.json — one of the ten here is exactly that, so a rollup must
tolerate missing files rather than assume runs == directories.
Records that fork spend is NOT in that tree (pi-fork aggregates from the
parent's own toolResult entries into the status bar), so the two mechanisms
report spend in two different places and nothing adds them up today.
pi-global-AGENTS.md gets one cheat-sheet bullet so the choice is visible
without loading a skill, and names pi-task as a CLI rather than a tool.
Both files also carry the inverted capability-floor trap ([] = floor on,
null = floor off).
Add pi-global-AGENTS.md, symlinked by install.sh to ~/.pi/agent/AGENTS.md
(pi's global-instructions file, loaded at every startup). Directs the agent
to read the pi-extensions skill at session start and carries a core
fork/recall cheat-sheet, since on-demand skill description-matching was
leaving the extensions under-utilised.
Symlinked (not cp'd) like keybindings.json: pi never rewrites AGENTS.md, and
the entrypoint re-runs install.sh on every container start, so the directive
self-heals across container recreation / volume wipes.
joakimp
Joakim Persson