Advice: how Pi agent configuration actually resolves under Paperclip, and what history is available

docs/PLAN-INTERFACE.md

@@ -310,3 +310,107 @@ Go with `tuios.dev/plot` rather than embedding Paperclip's web dashboard.
 ## Not doing
 
 Artifacts, as instructed. Nothing about them will be added.
+
+---
+
+# Pi agents: how their configuration actually resolves
+
+Advice only — nothing here was built. Every fact below was read from the installed code, the
+config files, or the API on this machine.
+
+## Your picker, and what it really writes
+
+`pi-config` is an extension with five commands: `/config-add`, `/config-remove`,
+`/config-list`, `/config-show`, `/config-setup`. `picker.ts` is the overlay — a filtered list
+of `~/.agents/skills` and `~/.agents/extensions` showing which are active in the project and
+which are active globally. The commands write **JSON**, at:
+
+```
+<project>/.pi/settings.json      ← project settings (the picker's "-l" mode)
+~/.pi/agent/settings.json        ← global settings
+```
+
+and the shape they manipulate is a `packages` array of sources and filters:
+
+```json
+{"packages": [
+  "npm:pi-memctx",
+  {"source": "git:https://gitea.lab.audasmedia.com.au/sam/pi-config",
+   "extensions": ["extensions/pi-config/index.ts", "extensions/tavily-search/index.ts"]},
+  {"source": "/home/sam/.agents", "skills": ["nixos-workflow"], "extensions": []}
+]}
+```
+
+So yes: this is a stable JSON contract, and anything that can write a file can formulate an
+agent's context the way the picker does. The question is not *whether* it can be written, but
+*which one Pi actually reads on a Paperclip run*.
+
+## What Pi reads, in order
+
+From Pi's own documentation:
+
+- global: `~/.pi/agent/skills/`, `~/.agents/skills/`
+- **project, only after the project is trusted**: `.pi/skills/`, `.agents/skills/` in the
+  working directory and its ancestors up to the git root
+- packages and the settings `skills` array
+- command line: `--skill <path>`, additive even with `--no-skills`
+
+Settings merge the same way: user settings, then `<cwd>/.pi/settings.json`.
+
+## What Paperclip actually runs
+
+From `@paperclipai/adapter-pi-local`, a run is:
+
+```
+pi --mode json
+   --append-system-prompt <rendered system prompt>
+   --provider <p> --model <m> --thinking <t>
+   --tools read,bash,edit,write,grep,find,ls
+   --session /home/sam/.pi/paperclips/<timestamp>-<agentId>.jsonl
+   --skill <a directory Paperclip builds from that agent's desired skills>
+```
+
+and before the run it symlinks the agent's desired skills into `~/.pi/agent/skills/<runtimeName>`.
+
+Four consequences, and they matter:
+
+1. **Skills are already per agent** — `desiredSkills` plus `POST /api/agents/{id}/skills/sync`.
+   That is the supported lever, and it is what the `--skill` directory is built from.
+2. **The isolation is not complete.** Injected skills are symlinked into the *shared* global
+   directory and are not removed when another agent runs, and Paperclip does not pass
+   `--no-skills`. So a skill an agent once had can remain visible to another agent.
+3. **The tool list is fixed** at `read,bash,edit,write,grep,find,ls`. An agent cannot gain a
+   tool by being given an extension unless the adapter is changed.
+4. **Project-local `.pi/settings.json` is unlikely to be honoured for Paperclip runs.** Pi only
+   loads project settings from a trusted path. `~/.pi/agent/trust.json` holds 14 entries and none
+   of them is a Paperclip worktree or `~/paperclip-agents`. Worse, a worktree path changes with
+   every task (`…/worktrees/AUD-165-…`), so there is nothing stable to trust.
+
+## So what is the honest advice
+
+- **Agent identity, instructions, model, budget, and skills: Paperclip.** Those are per-agent
+  already and they are what a run uses. The instructions bundle at
+  `~/.paperclip/instances/default/companies/<co>/agents/<id>/instructions/AGENTS.md` is the
+  real per-agent context control, and it is editable through the API.
+- **Extensions: one global set, not per agent.** There is no per-agent extension mechanism in
+  this adapter. Pretending otherwise would produce agents whose behaviour depends on which one
+  ran last.
+- **Folder-level cleverness: keep out of the critical path.** Writing `.pi/settings.json` into a
+  project is useful for *you* when you open Pi in that folder by hand; it is not reliable
+  inside a Paperclip run, because of trust and because worktrees are new paths each time.
+- **If per-agent extensions are genuinely wanted**, the change is in the adapter: pass a
+  per-agent config directory or `--no-skills` plus an explicit set, and remove stale links.
+  That is a Paperclip feature, not something our terminal can arrange from outside.
+
+## History: yes, and it is richer than the run log
+
+- `~/.pi/paperclips/*.jsonl` — **178 files** on this machine, one per run, named
+  `<timestamp>-<agentId>.jsonl`, and each is the full conversation (session start, model
+  changes, messages).
+- `GET /api/agents/{id}/task-sessions` — maps a task to its session file and working directory.
+- `GET /api/heartbeat-runs/{runId}/log` — the run log already shown in `Agents>agents`.
+- `GET /api/agents/{id}/runtime-state` — the agent's current runtime state.
+
+A history panel is therefore feasible without new plumbing: list an agent's sessions from
+`task-sessions`, open one, and render the JSONL transcript. That is the natural next panel
+after the functional tests, and it is read-only.