feat(skill): the harness doctrine as a worked implementation — Pi; v0.9.0

[sshlg]

What

Two references in agent-harness: pi.md and pi-sdk.md.

Every other file in that skill states a rule. Pi is small enough to read and complete enough to have made each of those decisions in public — so these read it end to end and match each mechanism to the rule it instantiates. That second half is the point; without it this would be a stale copy of pi.dev.

pi.md — the harness

Pi mechanism	Implements
sessions as a JSONL tree (8-hex id, parentId, v3, BranchSummaryEntry)	time travel and forking — agent-orchestrator/references/runtime.md
contextTokens > contextWindow - reserveTokens, defaults 16,384 / 20,000	the compaction ladder — with what the ladder adds that Pi leaves to you
settings that merge rather than replace	precedence without copies that drift
project trust, and no sandbox by design	layers.md's delegation thesis, stated by the project itself

The sandbox section quotes Pi directly:

"prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by pi."

For an audit this changes the finding — "no permission model" here is a delegation, not a defect, so you audit what surrounds the process. The three containerization patterns are compared by where credentials end up, which is the question that actually decides between them.

pi-sdk.md — the programmable half

createAgentSession(), ModelRuntime, SessionManager, defineTool(), DefaultResourceLoader; RPC command groups and the full event lifecycle; JSON mode's delta-only records and why; the ExtensionAPI surface.

The eight seams are the reason this file exists — the places a real harness lets you implement doctrine the rest of the pack only describes:

• tool_call can block → the per-hop permission gate; called out as the most important one for an audit, because it is where a per-tool, per-caller policy can actually live
• tool_result is a middleware chain → tool-output offload and token efficiency
• context → rewrite messages before the provider call
• three provider hooks → routing, proxying, cost attribution

Plus the traps that bite once each: waiting on agent_end instead of agent_settled; ignoring extension_ui_request and hanging the agent; splitting JSONL on anything but \n (Pi's own warning); reusing a ctx after session replacement.

Evidence

• 16 doc pages + the package source, read 2026-08-15, all 16 verified 200. The only non-resolving URLs in either file are the two deliberate placeholders inside custom-provider examples (api.my-llm.com, proxy.example.com) — stated rather than rounded to "all green"
• python3 test/validate.py → OK: agent-stack structurally valid (10 checks, 4 skill(s), v0.9.0)
• three plants watched failing against the new files (stamp removal ×2, dangling link)
• body 150 ln / ~2235 tok; description 807/1024, inside the family's 970 working budget

The repository's own front-matter gate earned its keep here: a first draft of the description landed at 1066 chars and the repo-gate hook refused the write before it could reach CI.

One claim, with its limit stated

Pi discovers skills from ~/.agents/skills/ — this machine's ssheleg hub, 72 entries, every family skill carrying the name and description front matter Pi requires. Recorded as a fact about the path and the front matter, not as an observed load: Pi is not installed here.

The reference also names Pi's documented divergence from the Agent Skills standard (a skill name may differ from its directory) and warns that make-skill's validator enforces the strict rule — so a skill built to Pi's leniency fails the family gate.

🤖 Generated with Claude Code