docs: pi 0.84.3 runtime mechanics, isolation baseline, personality layering, gateway patterns

Establishes this repository as the authoritative source for Pi agent configuration across scenarios, starting with the documentation layer. Key verified findings (probe harness included, zero model tokens): - The skills section of the system prompt is emitted only when an active tool named 'read' exists (system-prompt.js:59,113). Therefore --no-tools silently makes every SKILL.md unreachable and --skill a no-op. - registerTool accepts a plain JSON Schema object, so tool definitions can be served from a backend instead of duplicated in TypeScript. - An extension can shadow a built-in tool by name, which is how a dedicated agent gets a path-restricted 'read' while still satisfying the rule above. - .pi/SYSTEM.md replaces pi's coding-assistant prompt, but the replacement branch contributes neither the tool list nor the guidelines. - Without --no-skills/--no-extensions, user-global resources leak into every scenario; probed leak was find-skills, modsearch, summarize. Measured effect of the full baseline: system prompt 2619 -> 960 characters, coding-assistant framing and pi-docs paths removed, skill finally reachable. Secrets are guarded by scripts/verify-no-secrets.sh, installed as a pre-commit hook. Backups deliberately live outside the repository.
2026-08-26 22:47:53 -07:00
commit cbba8faabc
13 changed files with 1202 additions and 0 deletions
@@ -0,0 +1,60 @@
+### C · Curator 现状 (--no-tools)
+```
+flags: --no-tools
+PROBE_ALL_TOOLS=[]
+PROBE_ACTIVE_TOOLS=[]
+PROBE_SP_HAS_SKILLS=false
+PROBE_SP_HAS_PROBE_SKILL=false
+PROBE_SP_HAS_AGENTS=true
+PROBE_SP_HAS_CODING_ASSISTANT=true
+PROBE_SP_HAS_SYSTEM_MD=false
+PROBE_SP_HAS_PI_DOCS=true
+PROBE_SP_LEN=1859
+PROBE_SKILLNAMES=[]
+```
+
+### A · --no-builtin-tools，无隔离旗标
+```
+flags: --no-builtin-tools
+PROBE_ALL_TOOLS=["read[cli]","bash[builtin]","powershell[builtin]","edit[builtin]","write[builtin]","grep[builtin]","find[builtin]","ls[builtin]","probe_plain_schema[cli]"]
+PROBE_ACTIVE_TOOLS=["probe_plain_schema","read"]
+PROBE_SP_HAS_SKILLS=true
+PROBE_SP_HAS_PROBE_SKILL=false
+PROBE_SP_HAS_AGENTS=true
+PROBE_SP_HAS_CODING_ASSISTANT=true
+PROBE_SP_HAS_SYSTEM_MD=false
+PROBE_SP_HAS_PI_DOCS=true
+PROBE_SP_LEN=3413
+PROBE_SKILLNAMES=["find-skills","modsearch","summarize"]
+```
+
+### F · +--no-skills --skill
+```
+flags: --no-builtin-tools --no-skills --skill /tmp/pi-probe/.pi/skills/probe-skill
+PROBE_ALL_TOOLS=["read[cli]","bash[builtin]","powershell[builtin]","edit[builtin]","write[builtin]","grep[builtin]","find[builtin]","ls[builtin]","probe_plain_schema[cli]"]
+PROBE_ACTIVE_TOOLS=["probe_plain_schema","read"]
+PROBE_SP_HAS_SKILLS=true
+PROBE_SP_HAS_PROBE_SKILL=true
+PROBE_SP_HAS_AGENTS=true
+PROBE_SP_HAS_CODING_ASSISTANT=true
+PROBE_SP_HAS_SYSTEM_MD=false
+PROBE_SP_HAS_PI_DOCS=true
+PROBE_SP_LEN=2619
+PROBE_SKILLNAMES=["probe-skill"]
+```
+
+### I · 目标最终组合 (+.pi/SYSTEM.md +--approve)
+```
+flags: --no-builtin-tools --no-skills --skill /tmp/pi-probe/.pi/skills/probe-skill --approve
+PROBE_ALL_TOOLS=["read[cli]","bash[builtin]","powershell[builtin]","edit[builtin]","write[builtin]","grep[builtin]","find[builtin]","ls[builtin]","probe_plain_schema[cli]"]
+PROBE_ACTIVE_TOOLS=["probe_plain_schema","read"]
+PROBE_SP_HAS_SKILLS=true
+PROBE_SP_HAS_PROBE_SKILL=true
+PROBE_SP_HAS_AGENTS=true
+PROBE_SP_HAS_CODING_ASSISTANT=false
+PROBE_SP_HAS_SYSTEM_MD=true
+PROBE_SP_HAS_PI_DOCS=false
+PROBE_SP_LEN=960
+PROBE_SKILLNAMES=["probe-skill"]
+```
+
@@ -0,0 +1,2 @@
+CURATOR_SYSTEM_MARKER
+你是一个测试用的专用 agent，不是编码助手。
@@ -0,0 +1,7 @@
+---
+name: probe-skill
+description: PROBE_SKILL_MARKER - a probe skill used only to verify that pi surfaces the skills section in the system prompt under a given flag combination.
+---
+
+# Probe Skill Body
+PROBE_SKILL_BODY_MARKER
@@ -0,0 +1,2 @@
+# Probe Workspace
+AGENTS_MARKER_PRESENT
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+run() { L="$1"; shift; echo "### $L"; echo '```'; echo "flags: $*"; printf '{"id":"1","type":"get_state"}\n' | timeout 60 /home/claw/.npm-global/bin/pi --mode rpc --no-session --no-extensions -e /tmp/pi-probe/probe-ext.ts --no-prompt-templates --no-themes --provider zenmux --model openai/gpt-5.6-luna "$@" 2>&1 >/dev/null | grep -E "^PROBE_"; echo '```'; echo; }
+run "C · Curator 现状 (--no-tools)" --no-tools
+run "A · --no-builtin-tools，无隔离旗标" --no-builtin-tools
+run "F · +--no-skills --skill" --no-builtin-tools --no-skills --skill /tmp/pi-probe/.pi/skills/probe-skill
+run "I · 目标最终组合 (+.pi/SYSTEM.md +--approve)" --no-builtin-tools --no-skills --skill /tmp/pi-probe/.pi/skills/probe-skill --approve
@@ -0,0 +1,50 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Probe 1: does registerTool accept a PLAIN JSON Schema object (not TypeBox)?
+const plainJsonSchema = {
+  type: "object",
+  properties: { q: { type: "string", description: "probe query" } },
+  required: ["q"],
+} as any;
+
+export default function probe(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "probe_plain_schema",
+    label: "Probe Plain Schema",
+    description: "Probe tool declared with a raw JSON Schema object.",
+    promptSnippet: "probe_plain_schema: raw JSON Schema probe",
+    parameters: plainJsonSchema,
+    async execute() {
+      return { content: [{ type: "text" as const, text: "PROBE_PLAIN_OK" }], details: {} };
+    },
+  });
+
+  // Probe 2: override the builtin `read`
+  pi.registerTool({
+    name: "read",
+    label: "Restricted Read",
+    description: "RESTRICTED_READ_OVERRIDE probe.",
+    promptSnippet: "read: restricted read override",
+    parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] } as any,
+    async execute(_id, params: any) {
+      return { content: [{ type: "text" as const, text: `RESTRICTED_READ_CALLED ${params.path}` }], details: {} };
+    },
+  });
+
+  pi.on("session_start", async (_e, ctx) => {
+    const all = pi.getAllTools().map((t) => `${t.name}[${(t as any).sourceInfo?.source ?? "?"}]`);
+    const active = pi.getActiveTools();
+    const sp = ctx.getSystemPrompt?.() ?? "";
+    console.error("PROBE_ALL_TOOLS=" + JSON.stringify(all));
+    console.error("PROBE_ACTIVE_TOOLS=" + JSON.stringify(active));
+    console.error("PROBE_SP_HAS_SKILLS=" + String(sp.includes("available_skills")));
+    console.error("PROBE_SP_HAS_PROBE_SKILL=" + String(sp.includes("PROBE_SKILL_MARKER")));
+    console.error("PROBE_SP_HAS_AGENTS=" + String(sp.includes("AGENTS_MARKER_PRESENT")));
+    console.error("PROBE_SP_HAS_CODING_ASSISTANT=" + String(sp.includes("expert coding assistant")));
+    console.error("PROBE_SP_HAS_SYSTEM_MD=" + String(sp.includes("CURATOR_SYSTEM_MARKER")));
+    console.error("PROBE_SP_HAS_PI_DOCS=" + String(sp.includes("Pi documentation")));
+    console.error("PROBE_SP_LEN=" + String(sp.length));
+    const names = [...sp.matchAll(/<name>([^<]+)<\/name>/g)].map(m=>m[1]);
+    console.error("PROBE_SKILLNAMES=" + JSON.stringify(names));
+  });
+}