@counterposition/skill-pi 0.87.1 → 1.0.0

package/README.md

@@ -28,15 +28,16 @@ If you develop inside this repo, Pi already loads the skill via `.pi/settings.js
 
 ## What this covers
 
-Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. Settings, models, providers, and packages. Sessions, forks, and compaction. The SDK and RPC interface.
+Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. MCP servers, codemode, and nested tool calls. Settings, models, providers, classifiers, and packages. Sessions, forks, and compaction. The SDK and RPC interface. Checked against Pi 1.0.0.
 
 The reference material lives in `references/` as task-specific documents — not a single monolith, but pieces sized for injection into a conversation when relevant.
 
 ## Files
 
-| Path               | Purpose                               |
-| ------------------ | ------------------------------------- |
-| `SKILL.md`         | Trigger rules and routing description |
-| `references/`      | Task-specific Pi reference documents  |
-| `evals/evals.json` | Example evaluation cases              |
-| `LICENSE.md`       | GPLv3 license text                    |
+| Path               | Purpose                                       |
+| ------------------ | --------------------------------------------- |
+| `SKILL.md`         | Trigger rules and routing description         |
+| `references/`      | Task-specific Pi reference documents          |
+| `examples/`        | Extension examples that type-check against Pi |
+| `evals/evals.json` | Example evaluation cases                      |
+| `LICENSE.md`       | GPLv3 license text                            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@counterposition/skill-pi",
-  "version": "0.87.1",
+  "version": "1.0.0",
   "description": "Pi coding agent reference skill — extensions, settings, providers, SDK/RPC, packages, and .pi/ config",
   "keywords": [
     "ai-skill",
@@ -25,9 +25,18 @@
     "LICENSE.md",
     "package.json"
   ],
+  "type": "module",
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@types/node": "^25.5.0",
+    "typebox": "^1.3.16",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
   "engines": {
     "node": ">=24"
   },
@@ -40,9 +49,11 @@
     "lint": "pnpm run lint:docs",
     "lint:docs": "markdownlint-cli2 \"README.md\"",
     "lint:docs:fix": "markdownlint-cli2 --fix \"README.md\"",
-    "format": "oxfmt \"README.md\" \"package.json\"",
-    "format:check": "oxfmt \"README.md\" \"package.json\" --check",
-    "check": "pnpm run lint && pnpm run format:check && pnpm run pack:check",
+    "format": "oxfmt \"README.md\" \"package.json\" \"tests\" \"vitest.config.ts\"",
+    "format:check": "oxfmt \"README.md\" \"package.json\" \"tests\" \"vitest.config.ts\" --check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run lint && pnpm run format:check && pnpm run typecheck && pnpm run test && pnpm run pack:check",
     "pack:check": "pnpm pack --pack-destination ../../.pack"
   }
 }

package/skills/pi/README.md

@@ -28,15 +28,16 @@ If you develop inside this repo, Pi already loads the skill via `.pi/settings.js
 
 ## What this covers
 
-Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. Settings, models, providers, and packages. Sessions, forks, and compaction. The SDK and RPC interface.
+Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. MCP servers, codemode, and nested tool calls. Settings, models, providers, classifiers, and packages. Sessions, forks, and compaction. The SDK and RPC interface. Checked against Pi 1.0.0.
 
 The reference material lives in `references/` as task-specific documents — not a single monolith, but pieces sized for injection into a conversation when relevant.
 
 ## Files
 
-| Path               | Purpose                               |
-| ------------------ | ------------------------------------- |
-| `SKILL.md`         | Trigger rules and routing description |
-| `references/`      | Task-specific Pi reference documents  |
-| `evals/evals.json` | Example evaluation cases              |
-| `LICENSE.md`       | GPLv3 license text                    |
+| Path               | Purpose                                       |
+| ------------------ | --------------------------------------------- |
+| `SKILL.md`         | Trigger rules and routing description         |
+| `references/`      | Task-specific Pi reference documents          |
+| `examples/`        | Extension examples that type-check against Pi |
+| `evals/evals.json` | Example evaluation cases                      |
+| `LICENSE.md`       | GPLv3 license text                            |

package/skills/pi/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: pi
-description: "Provides Pi-specific guidance for extensions, skills, `.pi/` config, `settings.json`, `models.json`, packages, providers, themes, SDK/RPC, sessions, and compaction in Pi, the coding agent. Use when the user mentions Pi or Pi-specific terms such as `.pi/`, `SKILL.md`, `createAgentSession()`, `thinkingLevel`, `session_before_compact`, `pi-ai`, `pi-tui`, `pi-agent-core`, or `pi-coding-agent`. Not for Raspberry Pi hardware, the math constant, or unrelated generic tooling."
+description: "Provides Pi-specific guidance for extensions, skills, `.pi/` config, `settings.json`, `models.json`, `mcp.json`, MCP servers, codemode, packages, providers, themes, SDK/RPC, sessions, and compaction in Pi, the coding agent. Use when the user mentions Pi or Pi-specific terms such as `.pi/`, `SKILL.md`, `createAgentSession()`, `thinkingLevel`, `session_before_compact`, `ctx.executeTool`, `pi-ai`, `pi-tui`, `pi-agent-core`, or `pi-coding-agent`. Not for Raspberry Pi hardware, the math constant, or unrelated generic tooling."
 license: GPLv3
 compatibility: "Pi-specific guidance for agents that support Agent Skills"
 ---
 
 # Pi Coding Agent
 
-Pi is a minimal terminal coding harness. Default tools: `read`, `bash`, `edit`, `write`; `grep`, `find`, `ls`, and the Windows `powershell` tool (Pi 0.84.3) are opt-in via the `defaultTools` setting or `--tools`. Modes: interactive (`pi`), print (`pi -p`), JSON (`--mode json`), RPC (`--mode rpc`), or embedded (`createAgentSession()`). Sub-agents, plan mode, permission flows, and MCP are intentionally left to extensions and Pi packages. Skill synced with Pi 0.87.1.
+Pi is a minimal terminal coding harness. Default tools: `read`, `bash`, `edit`, `write`; `grep`, `find`, `ls`, and the Windows `powershell` tool are opt-in via the `defaultTools` setting or `--tools`. Built-in extensions (Pi 0.99.0) add MCP servers, the `codemode` tool (model-written JavaScript that calls other tools), and `tool_search`. `codemode` and `tool_search` start inactive: enable them with `defaultTools`/`--tools`, or let MCP activate them when a server needs them. Modes: interactive (`pi`), print (`pi -p`), JSON (`--mode json`), RPC (`--mode rpc`), or embedded (`createAgentSession()`). Sub-agents, plan mode, and permission flows are intentionally left to extensions and Pi packages. Skill synced with Pi 1.0.0.
 
 Pi's philosophy: **adapt Pi to your workflows, not the other way around**.
 
@@ -18,12 +18,14 @@ Core packages on npm (source: [github.com/earendil-works/pi](https://github.com/
 | Package | Purpose |
 |---------|---------|
 | `@earendil-works/pi-ai` | Unified LLM API across 20+ providers |
-| `@earendil-works/pi-agent-core` | Agent runtime with tool execution and state |
+| `@earendil-works/pi-agent-core` | `Agent`, the agent loop, and the proxy stream (Pi 1.0.0 removed the experimental harness, sessions, and its `./node`/`./harness/*` subpaths) |
 | `@earendil-works/pi-tui` | Terminal UI components |
 | `@earendil-works/pi-coding-agent` | CLI, extensions, skills, sessions, settings (also exports `./client` for remote sessions and `./rpc-entry`) |
-| `@earendil-works/pi-web-ui` | Web components for chat interfaces |
+| `@earendil-works/pi-codemode` | QuickJS sandbox that runs model-written JavaScript against injected tools (Pi 0.99.0) |
+| `@earendil-works/pi-mcp` | Standalone MCP client: stdio and streamable HTTP, OAuth (Pi 0.99.0) |
 | `@earendil-works/pi-client` / `@earendil-works/pi-protocol` | Experimental remote-session client and wire protocol (Pi 0.84.0) |
 | `@earendil-works/pi-telemetry` | Vendor-neutral telemetry contracts (Pi 0.84.0) |
+| `@earendil-works/pi-durable` | Experimental durable agent harness: conversations, turns, and tool calls committed to storage and resumed after a crash (Pi 1.0.0; replaces the pi-agent-core harness) |
 
 ## File System Layout
 
@@ -32,6 +34,7 @@ Core packages on npm (source: [github.com/earendil-works/pi](https://github.com/
 ├── settings.json               # Global settings
 ├── auth.json                   # Credentials (0600 perms)
 ├── models.json                 # Custom provider/model definitions
+├── mcp.json                    # MCP servers (mcp-auth.json holds their OAuth tokens)
 ├── keybindings.json            # Keyboard shortcuts
 ├── extensions/                 # Auto-discovered
 ├── skills/                     # Auto-discovered
@@ -42,6 +45,7 @@ Core packages on npm (source: [github.com/earendil-works/pi](https://github.com/
 <project>/
 └── .pi/                        # Project-local config (overrides global)
     ├── settings.json
+    ├── mcp.json                # Project MCP servers (read only once trusted)
     ├── extensions/
     ├── skills/
     ├── prompts/
@@ -53,6 +57,7 @@ Core packages on npm (source: [github.com/earendil-works/pi](https://github.com/
 
 - **Extensions** — TypeScript modules with full system access. Hook into Pi's lifecycle to register tools, intercept calls, add commands, build UI. → `references/extensions.md`
 - **Skills** — Markdown capability packages (`SKILL.md` + frontmatter) following the Agent Skills standard. Pi loads names + descriptions into the system prompt; bodies load on demand. → `references/skills.md`
+- **MCP & codemode** — Built-in MCP client configured by `mcp.json` or `pi.registerMcpServer()`; server tools default to `codemode` exposure, reachable from `codemode` scripts rather than declared to the model. Codemode scripts get a tool's `structuredContent` when it declares `outputSchema`, and their nested calls still reach `tool_call` gates. → `references/mcp.md` and `references/codemode.md`
 - **Settings** — Hierarchical JSON: project `.pi/settings.json` merges over global `~/.pi/agent/settings.json`. → `references/settings.md`
 - **Packages** — Bundles of extensions/skills/prompts/themes via npm, git, or local paths. Installed with `pi install`. → `references/packages.md`
 - **Project trust** — Pi 0.79+ asks before loading project-local settings, resources, and packages; decisions persist in `~/.pi/agent/trust.json`. `--approve`/`--no-approve` override per run; `defaultProjectTrust` sets the non-interactive fallback. → `references/settings.md`
@@ -66,11 +71,13 @@ Core packages on npm (source: [github.com/earendil-works/pi](https://github.com/
 | Task | Reference |
 |------|-----------|
 | Writing an extension (tools, commands, events, UI) | `references/extensions.md` |
+| Connecting MCP servers (`mcp.json`, `pi mcp`, exposure) | `references/mcp.md` |
+| Codemode scripts, tool exposure, nested tool calls, permission gates for them | `references/codemode.md` |
 | Creating a skill | `references/skills.md` |
 | Configuring Pi (settings, env vars, CLI flags) | `references/settings.md` |
 | Building a shareable package | `references/packages.md` |
 | Embedding Pi programmatically | `references/sdk.md` |
-| Adding LLM providers or models | `references/providers.md` |
-| Looking for a recipe or pattern | `references/patterns.md` |
+| Adding LLM providers or models, classifiers, image models, virtual models | `references/providers.md` |
+| Looking for a recipe or pattern | `references/patterns.md` (compilable examples in `examples/`) |
 
-For exact CLI flags run `pi --help` or read the relevant reference. Resource flags (`--no-extensions`, `--no-skills`, `--no-context-files`, `--no-builtin-tools`, etc.) are documented in `references/settings.md`.
+For exact CLI flags run `pi --help` or read the relevant reference. Resource flags (`--no-extensions`, `--no-skills`, `--no-context-files`, `--no-builtin-tools`, etc.) are documented in `references/settings.md`; `--no-extensions` also disables the built-in extensions, and `-e builtin:<name>` loads one back.

package/skills/pi/evals/evals.json

@@ -27,6 +27,7 @@
         "Provides models.json with Ollama baseUrl containing localhost:11434",
         "Uses api type openai-completions (correct for Ollama)",
         "Includes model entry with id llama3.2",
+        "Writes models.json providers as an object keyed by provider id (e.g. \"ollama\"), not an array",
         "Provides settings.json with compaction.enabled set to false",
         "Sets sessionDir to ~/pi-sessions",
         "Correct file paths: ~/.pi/agent/models.json and ~/.pi/agent/settings.json"
@@ -45,6 +46,86 @@
         "SKILL.md uses relative paths to reference files",
         "Body routes to the correct reference doc based on the user's framework choice"
       ]
+    },
+    {
+      "id": 4,
+      "prompt": "Add the GitHub MCP server (https://api.githubcopilot.com/mcp/, token in GITHUB_TOKEN) to Pi for all my projects. It has ~90 tools, so keep them out of the model's tool list, but make search_code directly callable. Check that it works.",
+      "expected_output": "An entry in ~/.pi/agent/mcp.json under mcpServers with the url, an Authorization header referencing ${GITHUB_TOKEN}, a non-direct server exposure (codemode or deferred), and toolExposure making search_code direct; then pi mcp list to verify and /reload for a running session.",
+      "files": [],
+      "assertions": [
+        "Writes the server to ~/.pi/agent/mcp.json (global), not settings.json and not the project .pi/mcp.json",
+        "Uses the mcpServers object with a url field (streamable HTTP), not an sse type",
+        "Keeps the secret out of the file with \"Authorization\": \"Bearer ${GITHUB_TOKEN}\" (or pi mcp add --bearer-token-env-var GITHUB_TOKEN)",
+        "Sets server exposure to codemode or deferred (or the codemode-deferred alias) rather than direct",
+        "Uses toolExposure with \"search_code\": \"direct\"",
+        "Runs pi mcp list to verify the connection",
+        "Tells the user to /reload or start a new session so a running session connects",
+        "Does not tell the user to install an MCP extension or package, since MCP is built in"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "My Pi permission extension asks before every bash call. It works for direct calls, but when the model runs bash from a codemode script the approval lookup fails because my code searches the last assistant message for event.toolCallId. Fix the extension so codemode calls are gated too.",
+      "expected_output": "A tool_call handler that judges each call from the event itself, recognises nested calls by event.parentToolCallId (ids like <parent>/<n>), does not require the id to exist in the assistant message, does not auto-approve children because the codemode call was approved, and blocks when there is no UI.",
+      "files": [],
+      "assertions": [
+        "Keeps using the tool_call event and checks event.toolName === 'bash' (or isToolCallEventType('bash', event))",
+        "Explains that nested calls carry event.parentToolCallId and have ids of the form <parent id>/<n> that never appear in the transcript",
+        "Stops requiring the tool call id to be found in the last assistant message for nested calls",
+        "Reads the command from event.input for the nested call instead of parsing the codemode script",
+        "Does not approve a nested call just because the parent codemode call was approved",
+        "Does not rely on the nestedCalls record on the tool result for approval",
+        "Checks ctx.hasUI and returns { block: true, reason } when no UI is available",
+        "Notes that a blocked nested call makes the script's tools.bash() promise reject"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "I have a Pi extension tool `list_issues` that returns a text table. When the model calls it from codemode, the script gets a string it has to parse. Change the tool so codemode scripts get the issue objects, and keep the model's view readable.",
+      "expected_output": "The tool declares outputSchema (TypeBox) and returns structuredContent matching it on every result, alongside the existing text content; failures that still carry data use isError: true; read-only annotations are set.",
+      "files": [],
+      "assertions": [
+        "Adds an outputSchema built with typebox Type.Object/Type.Array",
+        "Returns structuredContent matching the schema on every result",
+        "Keeps model-facing text in content",
+        "Explains that codemode scripts receive structuredContent instead of the text only when outputSchema is declared",
+        "Uses isError: true (not a thrown error) for a failure that should still return data, or throws for plain failures",
+        "Keeps structuredContent JSON-compatible (no Date objects, Maps, or class instances)",
+        "Marks the tool with annotations such as readOnlyHint: true if it does not modify anything",
+        "Does not claim the model itself receives structuredContent"
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "Write a Pi extension that uses the Jev classifier to decide whether a user prompt is a question or a coding task, and sets a status line accordingly. It should not break when TypeSafe is down or the key is missing.",
+      "expected_output": "An extension that finds the classifier with ctx.modelRegistry.findOfType('classifier', 'typesafe', 'jev-latest'), calls ctx.modelRegistry.classify with a choice or bool question and ctx.signal, checks stopReason and the answer type before using probabilities, and falls back cleanly when the model is missing or the result is an error.",
+      "files": [],
+      "assertions": [
+        "Uses ctx.modelRegistry.findOfType('classifier', 'typesafe', 'jev-latest') or getModelOfType with type 'classifier'",
+        "Handles the classifier model being undefined",
+        "Calls ctx.modelRegistry.classify(model, { state, questions }, { signal })",
+        "Uses a valid question shape: type 'choice' with a criteria record, or type 'bool' with criteria { true, false }",
+        "Checks result.stopReason === 'stop' before reading answers, and handles 'error' and 'aborted'",
+        "Does not wrap classify() in try/catch as the only error handling, since it returns error results instead of rejecting",
+        "Checks the answer type (choice/bool) before reading probabilities or probability",
+        "Mentions TYPESAFE_API_KEY (or another Jev provider credential) as the auth requirement"
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "I'm embedding Pi with the SDK. My host sends user input with session.prompt() while idle and session.steer() while streaming, then waits for agent_settled before showing 'done'. Sometimes it hangs forever on inputs that one of my extensions handles as a command. I also drive a separate Pi over RPC. How do I fix both?",
+      "expected_output": "Explains dispositions: session.steer()/followUp() return 'queued' or 'handled'; session.prompt() returns nothing and resolves after an accepted run finishes, so the SDK host should await it instead of waiting for agent_settled; RPC prompt responses carry data.disposition 'started' | 'queued' | 'handled' (steer/follow_up 'queued' | 'handled'); on 'handled' no run started, so the client must not wait for agent_settled. Shows code that branches on the disposition.",
+      "files": [],
+      "assertions": [
+        "States that session.steer() and session.followUp() return 'queued' or 'handled'",
+        "States that an RPC prompt response has data.disposition of 'started', 'queued', or 'handled'",
+        "Explains that 'handled' means no run started for that input, so the client must not wait for agent_settled",
+        "Uses agent_settled (not agent_end) as the completion signal when a run did start",
+        "Shows RpcClient.prompt()/steer()/followUp() returning the disposition, or reads data.disposition from the raw response",
+        "Notes that session.prompt() resolves after an accepted run finishes",
+        "States that session.steer() and session.followUp() throw for extension commands, which must go through session.prompt()",
+        "Does not suggest a timeout as the fix"
+      ]
     }
   ]
 }

package/skills/pi/examples/classifier-gate.ts

@@ -0,0 +1,46 @@
+// A permission gate that asks a classifier model whether a bash command is destructive.
+import type { ClassifierContext } from "@earendil-works/pi-ai";
+import { type ExtensionAPI, isToolCallEventType } from "@earendil-works/pi-coding-agent";
+
+const QUESTIONS = {
+  destructive: {
+    type: "bool",
+    instructions: "Could running `command` delete or overwrite data the user may want to keep?",
+    criteria: { true: "Destructive", false: "Not destructive" },
+  },
+} satisfies ClassifierContext["questions"];
+
+// Highest P(destructive) that runs without asking. Tune it for your model and question.
+const MAX_ALLOWED_PROBABILITY = 0.2;
+
+export default function (pi: ExtensionAPI) {
+  pi.on("tool_call", async (event, ctx) => {
+    // Also fires for calls codemode scripts make; those carry event.parentToolCallId.
+    if (!isToolCallEventType("bash", event)) return;
+
+    const jev = ctx.modelRegistry.findOfType("classifier", "typesafe", "jev-latest");
+    let probability: number | undefined;
+    if (jev) {
+      // classify() never rejects: errors and aborts come back as stopReason.
+      const result = await ctx.modelRegistry.classify(
+        jev,
+        { state: { command: event.input.command }, questions: QUESTIONS },
+        { signal: ctx.signal },
+      );
+      if (result.stopReason === "aborted") return { block: true, reason: "Cancelled" };
+      const answer = result.stopReason === "stop" ? result.answers.destructive : undefined;
+      if (answer?.type === "bool" && Number.isFinite(answer.probability)) {
+        probability = answer.probability;
+      }
+    }
+
+    // Allow only a valid answer at or below the threshold; anything else needs a person.
+    if (probability !== undefined && probability >= 0 && probability <= MAX_ALLOWED_PROBABILITY) return;
+
+    const reason =
+      probability === undefined ? "Classifier unavailable" : "Classifier flagged the command";
+    if (!ctx.hasUI) return { block: true, reason: `${reason}; no UI to confirm` };
+    const ok = await ctx.ui.confirm(`${reason}. Run it?`, event.input.command);
+    if (!ok) return { block: true, reason: "Blocked by user" };
+  });
+}

package/skills/pi/examples/nested-tools.ts

@@ -0,0 +1,52 @@
+// A tool that runs other tools with ctx.executeTool() and keeps abort distinct from failure.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "read_many",
+    label: "Read many",
+    description: "Read several files in parallel through the read tool.",
+    parameters: Type.Object({
+      paths: Type.Array(Type.String(), { minItems: 1, maxItems: 20 }),
+    }),
+    // Declared to the model but never callable from other tools, so codemode cannot recurse into it.
+    exposure: "model-only",
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      // ctx.tools lists what ctx.executeTool() can reach: active direct tools plus every
+      // codemode/deferred tool. An inactive direct tool is not callable.
+      if (!ctx.tools.some((tool) => tool.name === "read")) {
+        throw new Error("read_many needs the read tool to be active");
+      }
+
+      let finished = 0;
+      const outcomes = await Promise.all(
+        params.paths.map(async (path) => {
+          // Each call runs tool_call/tool_result handlers (permission gates included) with
+          // parentToolCallId set to this call's id. It never rejects; failures come back as isError.
+          const outcome = await ctx.executeTool("read", { path }, { signal });
+          finished += 1;
+          onUpdate?.({
+            content: [{ type: "text", text: `Read ${finished}/${params.paths.length}` }],
+            details: undefined,
+          });
+          return { path, outcome };
+        }),
+      );
+
+      // Aborted nested calls also come back as isError. Rethrow the abort instead of reporting
+      // every file as failed.
+      signal?.throwIfAborted();
+
+      const failed = outcomes.filter(({ outcome }) => outcome.isError).map(({ path }) => path);
+      return {
+        content: outcomes.flatMap(({ path, outcome }) => [
+          { type: "text" as const, text: `--- ${path}${outcome.isError ? " (failed)" : ""}` },
+          ...outcome.result.content,
+        ]),
+        details: { failed },
+        isError: failed.length === params.paths.length,
+      };
+    },
+  });
+}

package/skills/pi/examples/structured-tool.ts

@@ -0,0 +1,61 @@
+// A tool that returns data: codemode scripts receive `structuredContent`, the model reads `content`.
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+
+const FileStatsResult = Type.Object({
+  files: Type.Array(
+    Type.Object({
+      path: Type.String(),
+      bytes: Type.Number(),
+      modified: Type.String({ description: "ISO 8601 timestamp" }),
+    }),
+  ),
+  missing: Type.Array(Type.String()),
+});
+
+type FileStatsResult = Static<typeof FileStatsResult>;
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "file_stats",
+    label: "File stats",
+    description: "Return the size and modification time of files in the working directory.",
+    parameters: Type.Object({
+      paths: Type.Array(Type.String(), { minItems: 1, maxItems: 100 }),
+    }),
+    outputSchema: FileStatsResult,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    namespace: { name: "fs_info", description: "Read-only file metadata" },
+    // Default exposure is "direct". "codemode" would keep it out of the model's tool list
+    // while scripts can still call it.
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const result: FileStatsResult = { files: [], missing: [] };
+      for (const path of params.paths) {
+        signal?.throwIfAborted();
+        try {
+          const stats = await stat(resolve(ctx.cwd, path));
+          result.files.push({ path, bytes: stats.size, modified: stats.mtime.toISOString() });
+        } catch (error: unknown) {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            result.missing.push(path);
+          } else {
+            throw error;
+          }
+        }
+      }
+
+      const lines = result.files.map((file) => `${file.path}: ${file.bytes} bytes`);
+      if (result.missing.length > 0) lines.push(`Missing: ${result.missing.join(", ")}`);
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: undefined,
+        structuredContent: result,
+        // A failure that still carries data: the model sees an error, scripts still get the object.
+        isError: result.files.length === 0,
+      };
+    },
+  });
+}

package/skills/pi/references/codemode.md

@@ -0,0 +1,92 @@
+# Codemode and Tool Search
+
+`codemode` is a built-in tool (Pi 0.99) that runs model-written JavaScript in a QuickJS sandbox. Scripts call Pi's other tools, filter their results, and return only what the model needs. `tool_search` declares tools the model cannot see yet. Checked against Pi v1.0.0: [codemode.md](https://github.com/earendil-works/pi/blob/v1.0.0/packages/coding-agent/docs/codemode.md), [cli.md#tools](https://github.com/earendil-works/pi/blob/v1.0.0/packages/coding-agent/docs/cli.md#tools), [extensions.md#tool-exposure](https://github.com/earendil-works/pi/blob/v1.0.0/packages/coding-agent/docs/extensions.md#tool-exposure), [settings.md#tools](https://github.com/earendil-works/pi/blob/v1.0.0/packages/coding-agent/docs/settings.md#tools), [codemode tool source](https://github.com/earendil-works/pi/blob/v1.0.0/packages/coding-agent/src/extensions/codemode/tool.ts).
+
+## Enable
+
+Both tools are registered inactive. The default tools stay `read`, `bash`, `edit`, `write`.
+
+```json
+{ "defaultTools": ["+codemode"] }
+```
+
+- `+name` adds to the default selection; `--tools` replaces it, so list everything: `pi --tools read,bash,edit,write,codemode`. `--tools` is an allowlist over every tool, including extension and MCP `mcp__*` tools: unlisted tools are not registered, so scripts can call only the listed ones.
+- The MCP extension activates `codemode` for servers with `codemode` exposure and `tool_search` for `deferred` servers (see `references/mcp.md`).
+- SDK sessions need `createCodemodeExtension()` / `createToolSearchExtension()` in the resource loader (see `references/sdk.md`).
+
+| Setting | Default | Effect |
+|---------|---------|--------|
+| `codemode.mode` | `"on"` | `on`: declared tools stay declared and their descriptions show the script call; `codemode` lists only undeclared tools. `only`: active built-in and extension tools are hidden from the model and listed in the `codemode` description instead |
+| `codemode.inlineBudget` | `3000` | Estimated tokens the `codemode` description may spend on tool declarations; the rest are found with `searchTools()`. `0` lists only namespaces |
+
+## Script API
+
+The script body is an async function: top-level `await` and `return` work.
+
+- `await tools.<name>(args)` calls a tool. Characters that are not valid in an identifier become `_` (`mcp__dev-radius__search` → `tools.mcp__dev_radius__search`).
+- Since Pi 1.0.0, reading a member of `tools`, `models`, or another global namespace that does not exist throws an error naming the close matches (`tools.Bash` suggests `tools.bash`). Check for a tool with `"name" in tools`; `typeof tools.name` now throws.
+- `ALL_TOOLS` lists `{ name, description }`. `await searchTools(query, { limit, namespace })` ranks tools with BM25; `await describeTool(name)` returns one declaration; `await describeNamespace(name)` returns `{ name, description?, instructions?, tools }` for a namespace such as an MCP server (`mcp__dev-radius`, `dev_radius`, and similar spellings all work).
+- Output: `text(value)`, `image(dataUrlOrImageContent)`, `console.*`, and the returned value. Since Pi 0.99.2 `image()` accepts only base64 PNG, JPEG, GIF, or WebP (a `data:` URL, `{ image_url }`, or an image block); it derives the MIME type from the image bytes, rejects remote URLs, and throws a `TypeError` for anything else, such as an SVG. `exit()` ends early and keeps output.
+- `store(key, value)` / `load(key)` keep JSON values across `codemode` calls (storing `undefined` deletes). Successful scripts append a `codemode-store` custom entry, so values follow the session branch. Limits: 262144 characters of JSON per value, 1048576 in total; do not store image data.
+- `models.getModelsOfType`, `getAvailableOfType`, `getModelOfType`, `models.classify(model, { state, questions })`, and `models.generateImages(model, { input })` (Pi 1.0.0) reach the model catalog, classifiers, and image models with session credentials. Both calls use only the model's `provider` and `id`, never throw on provider errors (check `stopReason`), and run at most four at a time per script. Their usage and cost are added to the `codemode` result. Show generated images with `image(block)` rather than printing `data`; they are not saved to disk, and generation can take minutes, so avoid a short `timeout_ms`.
+- Malformed `classify()`/`generateImages()` arguments are rejected with the expected shape, and an unknown model points to `models.getAvailableOfType()`.
+- An optional first line `// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}`. Output is capped at 10000 estimated tokens by default (start and end kept, full text in a temp file); there is no timeout unless set.
+- No timers, `fetch`, `process`, `require`, or modules. The VM has 256 MB of memory; a script awaiting a promise that can never settle fails at once; scripts cannot start other `codemode` scripts.
+
+The result starts with `Script completed` or `Script failed`, the wall time, and the output. A failed script keeps its partial output followed by `Script error:`.
+
+## What a Script Receives
+
+| Tool | `await tools.x(...)` resolves to |
+|------|--------------------------------|
+| Declares `outputSchema` | Its `structuredContent`, also when the result has `isError: true` |
+| MCP tool | The whole `CallToolResult` (`content`, `structuredContent`, `isError`) |
+| `bash` | `{ output, truncated, full_output_path?, exit_code, wall_time_seconds }`, also for non-zero exits; `output` holds up to 1 MiB |
+| Anything else | Its text content as one string |
+
+A failed, blocked, or invalid call without structured content rejects with an `Error` carrying the tool's error text. Catch it in the script (`Promise.allSettled` works) when partial results are useful.
+
+## Which Tools Are Callable
+
+"Active" means declared to the model (`pi.getActiveTools()`). "Callable" means reachable through `ctx.executeTool()`, which is how codemode calls tools. They are separate:
+
+| Tool `exposure` | Declared to the model | Callable by codemode/`ctx.executeTool()` |
+|-----------------|----------------------|-------------------------------------------|
+| `direct` (default) | While active | Only while active |
+| `model-only` | While active | Never; for tools that orchestrate other tools or ask the user |
+| `codemode` | Only if explicitly activated | Always, and listed in the `codemode` description |
+| `deferred` | After `tool_search` loads it | Always, but not listed; found by `tool_search`/`searchTools()` |
+| `hidden` | Never | Never |
+
+MCP tools with the default server `codemode` exposure are registered like `deferred` tools: callable, but not listed in the `codemode` description, so it stays the same while servers connect. Scripts find them with `searchTools()` or `describeNamespace()`.
+
+So an inactive `codemode`/`deferred` tool is still callable, while an inactive `direct` tool is unreachable from scripts. Because `codemode`/`deferred` tools do not depend on the active set, they stay callable after `/tree`, resume, and fork. `ctx.tools` in a tool's `execute()` lists exactly the callable tools.
+
+## Nested Calls and Permissions
+
+Each `tools.*` call runs through `ctx.executeTool()`, the same pipeline as a model-issued call. `models.classify()` and `models.generateImages()` do not: they run with the session's credentials and fire no `tool_call`/`tool_result` events, so a permission extension cannot gate them separately from the `codemode` call itself.
+
+- Argument validation, then `tool_call` and `tool_result` handlers, then `tool_execution_start`/`update`/`end` events.
+- Every event carries `parentToolCallId` (the `codemode` call's id); the nested call's `toolCallId` is `<parent id>/<n>`. Deeper calls nest the same way.
+- Nested calls are not transcript tool calls or results. Only the calling tool's result reaches the model. The session keeps a bounded `nestedCalls` record on that result (name, arguments, status, duration, error; never results; arguments over 8 KiB per call or 32 KiB per result omitted; at most 256 calls; `complete: false` when anything was dropped).
+- A `tool_call` block makes the script's `await tools.x()` reject. The script can continue.
+
+For a permission extension this means:
+
+- Judge a nested call from the live `tool_call` event (`event.toolName`, `event.input`, `event.parentToolCallId`). Do not look the id up in the last assistant message; it is not there.
+- Do not approve a child because its parent `codemode` call was approved, and do not parse the script to predict children.
+- `nestedCalls` is written after execution and may omit arguments; do not use it as the approval record.
+- In print/JSON mode (`ctx.hasUI === false`) there is no one to ask: block or apply a non-interactive policy.
+- `pi.getAllTools()` reports `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). They are unverified hints, useful for deciding which calls to confirm, not authority to skip policy.
+
+## Tool Search
+
+`tool_search` searches tools that are not declared (`codemode` and `deferred` exposure, such as MCP tools) with the same ranking as `searchTools()`, and declares the matches from the next model call on. Loaded tools are recorded like other tool changes and stay declared on that branch. Enable it with `"defaultTools": ["+tool_search"]` when no MCP server does.
+
+## Replacing or Disabling
+
+- An extension that registers a tool named `codemode` or `tool_search` replaces the built-in one.
+- `"extensions": ["-builtin:codemode"]` or `["-builtin:tool-search"]` disables one (note the hyphen in the extension name); `pi config` lists them under Built-in.
+- `codemode` uses only `exposure`, `prepareLoadout()`, and `ctx.executeTool()`, and `tool_search` only ranks registered tools (`pi.getAllTools()`) and adds matches with `pi.setActiveTools()`, so an extension can build either under another name.
+
+`@earendil-works/pi-codemode` publishes the sandbox (`CodemodeSandbox`) without Pi dependencies, for exposing any functions to model-written scripts.