@counterposition/skill-pi 0.87.1 → 0.99.1

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 0.99.1.
 
 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": "0.99.1",
   "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": "^0.99.1",
+    "@earendil-works/pi-coding-agent": "^0.99.1",
+    "@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 0.99.1.
 
 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 0.99.1.
 
 Pi's philosophy: **adapt Pi to your workflows, not the other way around**.
 
@@ -21,7 +21,8 @@ Core packages on npm (source: [github.com/earendil-works/pi](https://github.com/
 | `@earendil-works/pi-agent-core` | Agent runtime with tool execution and state |
 | `@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) |
 
@@ -32,6 +33,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 +44,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 +56,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 +70,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, codemode-deferred, 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, codemode-deferred, or deferred 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,88 @@
+# 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 v0.99.1: [cli.md#tools](https://github.com/earendil-works/pi/blob/v0.99.1/packages/coding-agent/docs/cli.md#tools), [extensions.md#tool-exposure](https://github.com/earendil-works/pi/blob/v0.99.1/packages/coding-agent/docs/extensions.md#tool-exposure), [settings.md#tools](https://github.com/earendil-works/pi/blob/v0.99.1/packages/coding-agent/docs/settings.md#tools), [codemode tool source](https://github.com/earendil-works/pi/blob/v0.99.1/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`/`codemode-deferred` 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. Names that are not identifiers are mangled (`my-tool` → `tools.my_tool`); `tools["my-tool"]` also works.
+- `ALL_TOOLS` lists `{ name, description }`. `await searchTools(query, { limit, namespace })` ranks tools with BM25; `await describeTool(name)` returns one declaration.
+- Output: `text(value)`, `image(dataUrlOrImageContent)`, `console.*`, and the returned value. `exit()` ends early and keeps output.
+- `store(key, value)` / `load(key)` keep JSON values across `codemode` calls. Successful scripts append a `codemode-store` custom entry, so values follow the session branch.
+- `models.getModelsOfType`, `getAvailableOfType`, `getModelOfType`, and `models.classify(model, { state, questions })` reach the model catalog and classifiers with session credentials (at most four classifications at a time). Their usage and cost are added to the `codemode` result.
+- 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 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 |
+
+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 script call runs through `ctx.executeTool()`, the same pipeline as a model-issued call:
+
+- 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.
+- Both built-ins use only `exposure`, `prepareLoadout()`, and `ctx.executeTool()`, so an extension can build the same behavior under another name.
+
+`@earendil-works/pi-codemode` publishes the sandbox (`CodemodeSandbox`) without Pi dependencies, for exposing any functions to model-written scripts.

package/skills/pi/references/extensions.md

@@ -103,6 +103,7 @@ Useful agent events:
 - `before_provider_headers` (Pi 0.80.4) — mutate `event.headers` in place after outgoing HTTP headers are assembled: set a key to a string to add/override, `null` to delete. Runs once per provider request; retries reuse the same headers
 - `before_provider_request`
 - `after_provider_response` — inspect the provider HTTP status and headers before stream consumption
+- `provider_stream_event` (Pi 0.99.0) — notification-only view of each parsed provider stream event before Pi normalizes it (`provider`, `api`, `model`, `data`). Treat `data` as read-only; handlers are awaited in stream order, so keep them fast. Not persisted
 - `model_select`
 - `thinking_level_select` — observe interactive thinking-level changes
 - `ui_prompt_start` / `ui_prompt_end` (Pi 0.84.4) — distinguish active agent work from time spent waiting on blocking `ctx.ui` prompts (`kind`: `select`/`confirm`/`input`/`editor`/`custom`)
@@ -121,6 +122,8 @@ Useful tool events:
 - `tool_result`
 - `tool_execution_end`
 
+Calls another tool makes through `ctx.executeTool()` (codemode scripts, orchestrating tools) fire the same tool events, so permission gates see them; see [Nested Calls and Permissions](codemode.md#nested-calls-and-permissions).
+
 Since Pi 0.86.0, tool-call `arguments` and result `details` must be JSON-compatible values (no `Date`, `Map`, class instances, `undefined` array slots); use `details: undefined` when there is nothing structured to keep. Tools registered without a parameter schema are rejected at registration.
 
 Tool results may include `terminate: true` to end the current tool batch without an automatic follow-up LLM turn — useful for tools that produce a structured final answer (see `examples/extensions/structured-output.ts` in the Pi repo). Since Pi 0.84.1, blocked `tool_call` results may also return `terminate: true`; the agent stops early only when every finalized result in the batch is terminating. Tools that make nested LLM calls can return their combined `Usage` as `usage` on the tool result — Pi persists it and includes it in footer, `/session`, and RPC session totals (Pi 0.81.0), and `tool_result` handlers may inspect or replace that value.
@@ -137,6 +140,7 @@ Tool results may include `terminate: true` to end the current tool batch without
 - `ctx.sessionManager` (read-only; `buildContextEntries()` returns active-branch entries with compaction applied, Pi 0.80.4)
 - `ctx.modelRegistry` / `ctx.model` / `ctx.thinkingLevel` / `ctx.scopedModels` (Pi 0.83.0) — `ctx.modelRegistry` is the synchronous extension-facing facade; its `refresh()` became `Promise<void>` in Pi 0.80.8 (await it before synchronous registry reads). Since Pi 0.84.x it also exposes `getProvider(id)` (effective pi-ai provider) and `getProviderAuth(id)` (API key, headers, base URL, provider-scoped env — no loaded model required). `ctx.scopedModels` is the read-only session model scope resolved from `--models`/`enabledModels` (`{ model, thinkingLevel? }[]`, empty when unscoped); prefer it over enumerating `getAvailable()` for model pickers
 - `ctx.modelRegistry.stream()` / `streamSimple()` / `complete()` (Pi 0.86.0) — nested model calls through configured providers with request-time auth; prefer `streamSimple()` for provider-neutral calls, pass `ctx.signal`, and report the combined `usage` on the tool result
+- `ctx.modelRegistry.findOfType(type, provider, id)`, `getModelsOfType()`, `getAvailableOfType()`, and `classify(model, { state, questions }, { signal })` (Pi 0.99.0) — classifier and image models live beside chat models; `classify()` never rejects, so check `result.stopReason` (see `references/providers.md`)
 - `ctx.hasUI` — `true` in TUI and RPC modes
 - `ctx.signal` — the active agent abort signal (or `undefined` when idle); pass it to `fetch`/model calls for abort-aware nested work
 - `ctx.isIdle()` / `ctx.hasPendingMessages()`
@@ -146,6 +150,8 @@ Tool results may include `terminate: true` to end the current tool batch without
 - `ctx.getSystemPrompt()`
 - `ctx.isProjectTrusted()` — the effective project trust decision, including temporary `--approve`/`--no-approve` decisions
 
+Tool `execute()` receives `ExtensionToolContext`, which adds `ctx.tools` (the tools this call can reach) and `ctx.executeTool(name, args, { signal?, onUpdate? })` (Pi 0.99.0). `executeTool()` runs validation and the `tool_call`/`tool_result` hooks like a model call and never rejects: unknown tools, validation errors, blocks, and thrown errors come back as `{ isError: true }`, including after an abort. The signal defaults to the calling tool's. Nested usage is added to the calling tool's result, so report only the tool's own `usage`.
+
 Use `CONFIG_DIR_NAME` (exported from `@earendil-works/pi-coding-agent`) instead of hardcoding `.pi` when building project config paths, e.g. `join(ctx.cwd, CONFIG_DIR_NAME, "my-extension.json")`.
 
 Command handlers receive `ExtensionCommandContext`, which extends the above with session-control methods that would deadlock from event handlers: `ctx.getSystemPromptOptions()` (inspect the base system-prompt inputs), `ctx.waitForIdle()`, `ctx.newSession()`, `ctx.fork()`, `ctx.switchSession()`, `ctx.navigateTree()`, and `ctx.reload()`.
@@ -181,12 +187,27 @@ Important rules:
 
 1. Truncate large output.
 2. Respect `signal.aborted`.
-3. Throw on failure instead of returning fake success.
-4. Use the file-mutation queue for write/edit style tools.
+3. Throw on failure instead of returning fake success, or return `isError: true` when the failure still carries data. A returned object without `isError` counts as success.
+4. Use the file-mutation queue (`withFileMutationQueue()`) for write/edit style tools.
 5. Put reconstructable state in `details`; it persists in session history.
 
+## Tool Exposure & Structured Results
+
+Pi 0.99.0 added fields for tools that other tools, codemode scripts, and permission extensions consume ([docs](https://github.com/earendil-works/pi/blob/v0.99.1/packages/coding-agent/docs/extensions.md#tool-exposure), [types](https://github.com/earendil-works/pi/blob/v0.99.1/packages/coding-agent/src/core/extensions/types.ts)):
+
+- `outputSchema` (TypeBox) plus `structuredContent` on every result: the model still reads `content`; codemode scripts receive `structuredContent` instead of text. Without `outputSchema`, scripts get the text. `structuredContent` must be JSON-compatible. A `tool_result` handler that replaces `content` must also return `structuredContent`, or it is dropped.
+- `isError: true` on a returned result: the model sees an error, while `details` and `structuredContent` are kept for the UI and scripts.
+- `exposure`: `direct` (default), `model-only`, `codemode`, `deferred`, or `hidden`. `direct` and `model-only` tools activate on registration; the others do not (`defaultActive: false` also keeps a `direct` tool inactive until `--tools`/`defaultTools`/`setActiveTools()` names it). Tools cannot be unregistered: re-register with `exposure: "hidden"` to withdraw one. The table of what each value declares and allows is in `references/codemode.md`.
+- `namespace: { name, description? }` groups related tools under one heading in the `codemode` description, as MCP servers do.
+- `annotations`: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, with MCP meanings. Missing hints mean "not read-only, may be destructive, open world". They are unverified; mark writes neither read-only nor casually idempotent.
+- `prepareLoadout(loadout)`: for tools that orchestrate others. Runs whenever the active tools change with `declared`, `callable`, and `registered` tools, and returns replacement `descriptions` and `hiddenDeclarations` (active tools left out of requests but still callable). The built-in `codemode` and `tool_search` use only this, `exposure`, and `ctx.executeTool()`.
+
+`pi.getAllTools()` reports each tool's `exposure`, `namespace`, and `annotations`. `pi.setActiveTools()` ignores unknown and `hidden` names. Compilable examples: `examples/structured-tool.ts` and `examples/nested-tools.ts`.
+
 ## Dynamic Tool Loading
 
+For tools the model should find on demand, prefer `exposure: "deferred"` with the built-in `tool_search` (Pi 0.99.0), or `exposure: "codemode"` for tools scripts call. `tool_search` is inactive by default: enable it with `"defaultTools": ["+tool_search"]` or `--tools`, or let a connected MCP server with `deferred` exposure turn it on. Without it, the model can reach `deferred` tools only through codemode. The manual loader pattern below still works.
+
 Pi 0.80.7 lets an extension register many tools while keeping only a small initial set active, then add more during execution — cache-friendly on models with native deferred loading. Lifecycle:
 
 1. Register every tool with `pi.registerTool()` (all appear in `pi.getAllTools()`).
@@ -311,6 +332,14 @@ pi.on("session_start", async (_event, ctx) => {
 });
 ```
 
+## MCP Servers
+
+`pi.registerMcpServer(name, config)` adds a server for the current session with the `mcp.json` entry shape; `pi.unregisterMcpServer(name)` closes it. Registrations are not saved, and an `mcp.json` server with the same name wins. Extensions that implement their own MCP client read `pi.getMcpServers()` on `session_start` and handle `mcp_servers_change`. See `references/mcp.md`.
+
+## Virtual Models
+
+`pi.registerVirtualModel({ provider, id, name, thinkingLevels?, route(request, ctx) })` (experimental, Pi 0.99.0) adds a selectable model that picks a physical model and thinking level for every request. See `references/providers.md#virtual-models`.
+
 ## Provider Integration
 
 Extensions can register or override providers:
@@ -341,6 +370,8 @@ pi.unregisterProvider("my-provider");
 
 Dynamic providers can implement `refreshModels(context)` (Pi 0.80.8) for model discovery: Pi calls it during catalog refresh (`/model`, `pi update --models`) and publishes the returned list; its models replace extension-provided `models`. Since Pi 0.84.0 the context is read-snapshot + generation-checked publication: read `context.stored` (the persisted provider snapshot) instead of `context.store`, and persist through `context.publish({ update?, persist? })` — `persist` omitted leaves storage unchanged, a `ModelsStoreEntry` writes it, `persist: null` deletes it. Config-form callbacks that only return models remain unchanged.
 
+A config-form `models` list replaces the provider's models across chat, image, and classifier operations (Pi 0.99.0). Omitted `type` means `"chat"`; image and classifier entries need an explicit `type` plus implementations keyed by `api` through `images`/`classifiers` (see `references/providers.md`).
+
 Since Pi 0.81.0, extensions can also register a complete pi-ai `Provider` via `pi.registerProvider(createProvider({...}))` — native auth (`login`/`resolve`), `getModels`, `refreshModels`, `filterModels`, and custom streaming. The registered provider becomes the composition base; `models.json` overrides still apply above it. Prefer this when you need real authentication or stream behavior rather than just a model list. The legacy config form (`name`, `baseUrl`, `apiKey`, `models`, `oauth`, `streamSimple`) remains supported. OAuth `refreshToken(credentials, signal)` callbacks must accept and honor the abort signal since Pi 0.84.0.
 
 If you need auth for a specific model request, use:
@@ -355,7 +386,9 @@ Custom `streamSimple` implementations receive a normalized `TranscriptContext` s
 
 ## Handy Patterns
 
-- Permission gates via `tool_call`
+- Permission gates via `tool_call` (they also see nested calls from codemode; see `references/codemode.md`)
+- Data tools for codemode via `outputSchema` + `structuredContent`
+- Orchestrating tools via `ctx.executeTool()` with `exposure: "model-only"`
 - Prompt injection via `before_agent_start` (`systemPromptOptions.sections`)
 - Model-context pruning via `context`, or durable omission via `context_edit` entries from `turn_end`/`agent_before_settle`
 - Branch or compaction customization via `session_before_tree` / `session_before_compact`