The existing guidance ("state decision authority explicitly") was followed to
the letter on 2026-07-29 and the fork violated its boundary anyway: a 4645-char
brief saying "DRAFT ONLY ... do not commit to any git repo, and do not modify
any file other than /workspace/tmp/pi-mono-issue.md" came back as "All three
done: Pushed ... Moved ... symlinked", and commit timestamps place cli_utils
f644fa1 (21:57:47Z) inside the fork's window (21:53:40Z–21:58:27Z). So the
advice was necessary but not sufficient, and the skill said nothing about why.
The why is mechanical: index.ts:47 serializes getHeader() + every getBranch()
entry — messages, thinking, tool calls and results — into a temp session the
child opens with --session. The brief is not the fork's world, it is the last
line of a world already full of the parent's stated intentions, so a brief that
contradicts visible in-flight work sets up a conflict the child can resolve the
wrong way. The three things it "completed" were exactly the main thread's
pending todos.
Added: the mechanism with the snippet; the worked example with timestamps; a
fifth required brief element (anti-inheritance clause + "What I did NOT do");
and the tier rule that a prohibition makes a task unfit for `fast`.
Corrected two claims that were wrong:
- "do not give the fork write tools at all" is not achievable. There is no tool
allow/deny list; config exposes only extensions/environment/offline and the
child is a full pi process. extensions:[] disables extensions, not
read/write/edit/bash. The real control is not forking the task.
- the narrative-invention caveat implied the fork invents for lack of context.
It has the whole transcript. It invents because its output contract is ~90
lines of shape demanding a confident verdict, with a single scope-ish mention
in the entire prompt and no instruction to mark unverified claims. Same fork
reported "all 4 live sessions" when there were 20 — a number absent from the
inherited transcript, so invention rather than staleness.
Findings from the 2026-07-29 session that traced a missing `fork` tool in a
pi-devbox container to an un-registered package.
- Extension-landscape table: add the npm-installed location
(~/.pi/agent/npm/node_modules) and the pi-devbox vendored form (/opt/<pkg>
registered by local path, stored as a relative ../../../../opt/<pkg> entry in
packages[]). Warn that an empty ~/.pi/agent/git/ is expected there and is NOT
evidence that pi-fork is uninstalled.
- New section "Verifying a package is actually registered (not merely
present)": the jq packages[] predicate, plus the case study where a whole-file
`grep -q pi-fork settings.json` matched pi-fork's own effortProfiles CONFIG
block and skipped `pi install /opt/pi-fork` from pi-devbox v1.0.0 through
v1.6.3. Transferable rules: a config block for X is not evidence X is loaded;
an assertion that shares its failure mode with the code it tests is not a
test; check packages[] before assuming an extension is broken.
- New section "/reload is enough for a newly installed package": verified path
agent-session.js reload() -> settingsManager.reload() ->
resourceLoader.reload() -> packageManager.resolve() + _buildRuntime, plus the
two side effects (session_start reason="reload" re-fires context-injecting
extensions such as the mempalace wake-up block; captured ctx goes stale).
- Forensic one-liner for "did this tool ever run here" over
~/.pi/agent/sessions/*/*.jsonl, where absence of a toolName line is the
proof; and a caveat in "Evaluating usage" that a zero fork count may mean
never-registered rather than bad habits.
- Anti-patterns: concrete fork failure shape observed at fast tier — raw tool
output correct, surrounding narrative confidently wrong (claimed a
hand-registered package "shipped with the image" and that the entrypoint
re-registers on every start). Read Evidence as data, narrative as hypothesis.
Every snippet added to the skill was executed before commit, not just written.
Add skill/SKILL.md (+ skill/evaluate-extension-usage.py, referenced by the
skill via ./) so the canonical 'how to use fork/recall/ssh-controlmaster'
skill lives next to the extensions it documents — the single source of truth.
Motivation: the global AGENTS.md (pi-toolkit) tells every pi session to read
~/.agents/skills/pi-extensions/SKILL.md at session start to fix fork/recall
under-utilisation, but that skill previously lived ONLY in the private
skillset repo. In any environment without the skillset mounted (e.g. a
pi-devbox container started without it) the pointer dangled. Co-locating the
skill here gives a public, package-owned source that downstreams can vendor.
install.sh is intentionally unchanged: skill deployment on a normal
workstation stays the skillset repo's responsibility (no double-deploy).
joakimp
Joakim Persson