specpi 0.36.4 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.37.0 - 2026-10-01
+
+- Pair with SpecPi Chat 0.19.0, which shows a codemode run as one tool card: the script, the tool calls it made and its output.
+- Move the reviewed Pi base to 1.0.0. Development fixtures, package checks and the docs pin `@earendil-works/pi-coding-agent`, `pi-ai` and `pi-tui` 1.0.0 in place of 0.84.4.
+- Pin `pi-goal-x` 0.32.0, which widens its declared Pi support from `<0.85.0` to `<2.0.0`; 0.31.2 refused Pi 1.0.
+- Turn on Pi's built-in codemode tool by default. Install and update add `+codemode` to `defaultTools` in Pi's settings, after `pi --version` confirms Pi 0.99 or later. Older Pi would read the entry as a plain tool list and lose its default tools, so the installer warns and adds nothing there. An existing choice is left alone: `defaultTools` that already names codemode (including `-codemode`), is empty or is not an array, or `-builtin:codemode` in `extensions`. Uninstall removes only the entry SpecPi added. Nested tool calls from codemode scripts pass through the same `tool_call` handlers as direct calls, so scope, the permission system and the LANCET guard still apply.
+
 ## 0.36.4 - 2026-10-01
 
 - Pin `specpi-lancet-guard` 0.6.0, which adds `/lancet-guard mode <ask|block>`. Choosing what a `risky` verdict does used to mean editing `~/.pi/lancet-guard.json` by hand; the command saves `risky` there and keeps the rest of the file. Ask stays the default. Block mode blocks a `risky` verdict and stops the agent, as the hard-deny rules do; `review` asks in both modes, and the local rules and a missing model block in both. Status shows the mode, and setting one warns when a trusted project's `.pi/lancet-guard.json` overrides it there. The model is unchanged, LANCET Nano v0.4.3, so updating needs no new `/lancet-guard setup`.

package/NPM_RELEASE.md

@@ -6,7 +6,7 @@ Publishing, tags, deprecation, ownership changes and GitHub Releases require exp
 
 ## Prepare
 
-1. This candidate is SpecPi **0.36.4**, paired with the Chat **0.18.0** VSIX. Browser QA **0.3.0** and LANCET guard **0.6.0** are already independently published; do not republish or edit their source as part of this release. Choose an unused version; update `package.json`, the dated `CHANGELOG.md` entry, README, and the website. Check Chat's version and VSIX download links. Preserve historical changelog entries.
+1. This candidate is SpecPi **0.37.0**, paired with the Chat **0.19.0** VSIX. Browser QA **0.3.0** and LANCET guard **0.6.0** are already independently published; do not republish or edit their source as part of this release. Choose an unused version; update `package.json`, the dated `CHANGELOG.md` entry, README, and the website. Check Chat's version and VSIX download links. Preserve historical changelog entries.
 2. Validate:
 
     ```sh

package/README.md

@@ -28,7 +28,7 @@
 
 ---
 
-SpecPi 0.36.4 is a small starting point for the [Pi coding agent](https://pi.dev/). It is one opinionated setup for how the agent should work, not a marketplace of plugins.
+SpecPi 0.37.0 is a small starting point for the [Pi coding agent](https://pi.dev/). It is one opinionated setup for how the agent should work, not a marketplace of plugins.
 
 At the center are two built-in extensions. **Scope control** keeps each task to the files it said it would touch. The **improvement loop** turns repeated friction into small, tested changes to the setup, instead of letting prompts and workarounds pile up. Around those are eight hand-picked packages, each locked to an exact version and checked before anything installs, plus **SpecPi Chat**, a VS Code panel for working alongside the agent.
 
@@ -47,14 +47,13 @@ Everything it touches is written down, versioned, and easy to undo.
 
 Before the agent runs a shell command, [LANCET Nano](https://github.com/TannerMidd/LANCET-model), a 111M-parameter classifier, can check it on your own CPU. It reads Bash, PowerShell and cmd, takes about 10 ms for a typical command, needs no API key, sends nothing over the network, and costs nothing per check. Fixed rules settle the obvious cases first, blocking `rm -rf /` and passing `git status`, and the model scores the rest. A risky or uncertain verdict asks you before anything runs; `/lancet-guard mode block` blocks risky ones outright instead.
 
-| | LANCET Nano v0.4.3 |
-| --- | ---: |
-| Triage Score | 68.3 |
-| Safe commands wrongly stopped | 9.0% |
-| Cost per check | $0 |
-| Network | none |
+<p align="center">
+  <a href="https://tannermidd.github.io/SpecPi/lancet/">
+    <img src="https://tannermidd.github.io/SpecPi/media/lancet-comparison.webp" width="880" alt="Bar chart of Triage Score (higher is better) for 14 command guards on the same 7,911 commands. LANCET Nano v0.4.3 scores 68.3, catching 77.0% of risky commands while stopping 9.0% of safe ones. Next are Jev 38.9, verdict-shell-safety 32.4, Kestrel 30.7, ModernBERT bash 23.2, dcg 19.8, AutoShell-0.8B 19.2, Gyra 17.9, bash-classify 14.3, Laya 13.3, bev-decider 13.3, laya-cli-gate 12.5, sh-guard 10.9 and Shieldstral-1.0-3B 6.1.">
+  </a>
+</p>
 
-Both figures are taken across three benchmarks, 7,911 commands in total, weighted by size: lancet-bench-2-next (1,602 risky commands and their safe look-alikes), the ShellRisk-Bench test split, and a 513-command neutral set. The [Triage Score](https://github.com/TannerMidd/LANCET-model) gives a guard a point for each risky command it asks about or blocks, and shrinks in proportion once it stops more than 10% of safe commands. The guard ships off. Run `/lancet-guard setup` in Pi once to download the model (about 109 MB, verified by SHA-256) and switch it on. [How it works, what it costs, and its limits](https://tannermidd.github.io/SpecPi/lancet/).
+Every guard in the chart was scored once, at its own shipped setting, on the same three benchmarks, 7,911 commands in total, weighted by size: lancet-bench-2-next (1,602 risky commands and their safe look-alikes), the ShellRisk-Bench test split, and a 513-command neutral set. The [Triage Score](https://github.com/TannerMidd/LANCET-model) gives a guard a point for each risky command it asks about or blocks, and shrinks in proportion once it stops more than 10% of safe commands. The guard ships off. Run `/lancet-guard setup` in Pi once to download the model (about 109 MB, verified by SHA-256) and switch it on. [How it works, what it costs, and its limits](https://tannermidd.github.io/SpecPi/lancet/).
 
 ## Measured context
 
@@ -129,7 +128,7 @@ published figures.
 
 ## Install
 
-Requires Node.js 22.19+, Git, npm, and an existing Pi installation on PATH.
+Requires Node.js 22.19+, Git, npm, and an existing Pi installation on PATH. The base is tested with Pi 1.0.0.
 
 ```sh
 npm install --global specpi@latest
@@ -140,6 +139,8 @@ specpi doctor
 
 `plan` shows what will change without modifying anything. Restart Pi after install.
 
+Install also turns on Pi's built-in [codemode](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/codemode.md) tool, which lets the model run a short sandboxed script that calls several tools at once. It does this by adding `+codemode` to `defaultTools` in Pi's `settings.json`, only on Pi 0.99 or later. To keep it off, put `-codemode` there instead; SpecPi leaves an existing choice alone, and uninstall removes only the entry it added.
+
 Full setup options, package details, and requirements: [website](https://tannermidd.github.io/SpecPi/#install).
 
 ## Where things live

package/SECURITY_MODEL.md

@@ -82,10 +82,12 @@ Wishlist records remain local under `<agent-dir>/specpi/`. Sanitization and salt
 
 Package acquisition requests exact npm dependency saves through the child process environment and verifies the installed top-level versions before completing the transaction. A mismatch fails the operation and triggers managed-state rollback. Upstream transitive dependency ranges remain outside this pinning guarantee.
 
-`plan` is read-only. Installation, updates, and removal require confirmation or `--yes`. SpecPi manages its two first-party extension families, improvement skill, manifest, AGENTS marker block, and the eight package entries listed in `templates/settings.json`. Normal install/update runs `pi install npm:<name>@<pin>` for every default package. Only package entries are merged; existing resource filters and unrelated settings are retained. `--skip-package-install` allows a core-only install or preserves an already configured base during update, skipping Chromium setup too. Confirmed install/update otherwise invokes the installed Browser QA Node bin with bounded subprocesses to download Chromium and check readiness. `--skip-browser-install` skips that setup only; doctor still checks readiness. SpecPi never passes `--with-deps`, auto-installs OS libraries, or installs/removes Bun. No new shell profile integration is installed.
+`plan` is read-only. Installation, updates, and removal require confirmation or `--yes`. SpecPi manages its two first-party extension families, improvement skill, manifest, AGENTS marker block, and the eight package entries listed in `templates/settings.json`. Normal install/update runs `pi install npm:<name>@<pin>` for every default package. Only package entries and one `defaultTools` entry are merged; existing resource filters and unrelated settings are retained. `--skip-package-install` allows a core-only install or preserves an already configured base during update, skipping Chromium setup too. Confirmed install/update otherwise invokes the installed Browser QA Node bin with bounded subprocesses to download Chromium and check readiness. `--skip-browser-install` skips that setup only; doctor still checks readiness. SpecPi never passes `--with-deps`, auto-installs OS libraries, or installs/removes Bun. No new shell profile integration is installed.
 
 Managed configuration and files are locked and backed up before mutation; first-party writes are atomic and checksum-tracked. Failure restores the saved configuration and first-party files. Package acquisition runs upstream package-manager scripts and may leave downloads, dependency changes, or external script effects even after configuration rollback. Those effects, including downloaded browser-cache bytes, are outside SpecPi's transaction and survive uninstall. Updates require `--force` before replacing modified retained resources. Retired resources are backed up before deactivation; pre-install files are restored where ownership records identify them. Old runtime directories are moved into backups without inspecting their contents. Backups and private evidence remain after uninstall and can contain sensitive local material.
 
+Install and update, including core-only runs, add `+codemode` to `defaultTools` so Pi's built-in codemode tool is on. The installer first reads `pi --version` and adds nothing below Pi 0.99, which would read the entry as a plain tool list and drop its default tools. It also adds nothing when `defaultTools` already names codemode in any form (including `-codemode`), is empty (no built-in tools), is not an array, or when `extensions` contains `-builtin:codemode`. The manifest records only whether `defaultTools` existed before; uninstall removes `+codemode` and deletes the key only if SpecPi created it. Codemode runs model-written JavaScript in Pi's QuickJS sandbox, whose only capability is calling the session's tools. Each nested call goes through the same `tool_call` and `tool_result` handlers as a direct call, so `/scope`, the permission system and the LANCET guard see and can block it; an isolated Pi 1.0.0 session with a faux provider confirmed a nested `bash` call reaches `tool_call` with a `<parent>/<n>` id and that a block rejects it inside the script. Codemode is itself one more tool to these gates; under the permission system it falls to the `"*"` fallback unless a rule names it.
+
 Legacy migration restores only recorded settings ownership, preserves differing user values, and removes only the SpecPi shell marker block before applying the new base. The installer does not enumerate or modify authentication, provider credential stores, trust, sessions, missions, history, or unrelated private evidence. Normal updates deliberately reapply the default package pins, retaining the original entry for removal. Uninstall restores only package entries that still match the last installed value; user edits are preserved. Downloaded packages and tools are not deleted. Resources that SpecPi never owned require separate human management.
 
 ## Browser QA package

package/THIRD_PARTY.md

@@ -5,13 +5,13 @@ SpecPi's npm artifact contains first-party source and no bundled runtime depende
 - `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, and `@earendil-works/pi-tui`: MIT, from [Pi](https://github.com/earendil-works/pi).
 - `typebox`: MIT, from [TypeBox](https://github.com/sinclairzx81/typebox).
 
-Development fixtures pin Pi packages to **0.84.4** and TypeBox to **1.3.7**. Host installations retain their upstream licenses and manage provider connections themselves. SpecPi does not install or configure providers.
+Development fixtures pin Pi packages to **1.0.0** and TypeBox to **1.3.7**. Host installations retain their upstream licenses and manage provider connections themselves. SpecPi does not install or configure providers.
 
 Development formatting uses Prettier **3.9.6** (MIT), ESLint **10.9.1** (MIT), `@stylistic/eslint-plugin` **5.10.0** (MIT), `@typescript-eslint/parser` **8.68.0** (BSD-2-Clause), and TypeScript **6.0.3** (Apache-2.0). Exact versions are recorded in `package.json`; installed packages retain upstream notices. Git and Node.js are external prerequisites.
 
 ## Default packages
 
-Reviewed on 2026-09-16 against published npm metadata and integrity-verified source archives, and `specpi-lancet-guard` 0.6.0, which replaces `specpi-jev-guard` 0.4.0, from source in this repository. All eight top-level packages declare the MIT license. Pins are authoritative in `templates/settings.json`.
+Reviewed on 2026-09-16 against published npm metadata and integrity-verified source archives, and `specpi-lancet-guard` 0.6.0, which replaces `specpi-jev-guard` 0.4.0, from source in this repository. `pi-goal-x` 0.32.0 was reviewed on 2026-10-01 against its 0.31.2 archive: it widens Pi support to `<2.0.0` and adds goal scheduling and prompt-cache retention, with no new network, process or install-script use. All eight top-level packages declare the MIT license. Pins are authoritative in `templates/settings.json`.
 
 SpecPi requests exact npm dependency saves for these pins and checks installed top-level versions before completing installation. The override applies to package acquisition without changing the user's global npm configuration.
 
@@ -21,7 +21,7 @@ SpecPi requests exact npm dependency saves for these pins and checks installed t
 | specpi-browser-qa              | 0.3.0   | [TannerMidd/SpecPi](https://github.com/TannerMidd/SpecPi/tree/browser-qa-v0.3.0/packages/browser-qa) |
 | specpi-delegation              | 0.2.0   | [TannerMidd/SpecPi](https://github.com/TannerMidd/SpecPi/tree/main/packages/delegation) |
 | specpi-experiments             | 0.1.0   | [TannerMidd/SpecPi](https://github.com/TannerMidd/SpecPi/tree/main/packages/experiments) |
-| pi-goal-x                      | 0.31.2  | [tmonk/pi-goal-x](https://github.com/tmonk/pi-goal-x)                     |
+| pi-goal-x                      | 0.32.0  | [tmonk/pi-goal-x](https://github.com/tmonk/pi-goal-x)                     |
 | @sreetej510/pi-usage           | 0.10.0  | [Sreetej510/pi-extensions](https://github.com/Sreetej510/pi-extensions)   |
 | @gotgenes/pi-permission-system | 32.0.2  | [gotgenes/pi-packages](https://github.com/gotgenes/pi-packages)           |
 | specpi-lancet-guard            | 0.6.0   | [TannerMidd/SpecPi](https://github.com/TannerMidd/SpecPi/tree/main/packages/lancet-guard) |
@@ -30,7 +30,7 @@ Transitive dependencies and their notices remain in Pi's npm installation tree.
 
 Pi Lens is no longer a default package. Normal updates retire only unchanged entries added by SpecPi; independent or modified entries and downloaded bytes remain, with their upstream notices. Restart Pi to unload Lens.
 
-The combined base is tested with Pi 0.84.4. Pi Goal X declares Pi `>=0.83.0 <0.85.0`; compatibility with newer hosts is not assumed. SpecPi's former custom browser, structural-search, background-task, and native command-guard implementations, DonSeTch, and Pi themes have been removed; command gating is the pinned `specpi-lancet-guard` package's. Its delegation and experiment implementations were not discarded: they now ship as the independent `specpi-delegation` and `specpi-experiments` packages described below. Removal restores owned package settings but does not delete downloaded upstream packages or tools. Retired private runtimes remain in local backups with their notices.
+The combined base is tested with Pi 1.0.0. Pi Goal X declares Pi `>=0.83.0 <2.0.0`; compatibility with newer hosts is not assumed. SpecPi's former custom browser, structural-search, background-task, and native command-guard implementations, DonSeTch, and Pi themes have been removed; command gating is the pinned `specpi-lancet-guard` package's. Its delegation and experiment implementations were not discarded: they now ship as the independent `specpi-delegation` and `specpi-experiments` packages described below. Removal restores owned package settings but does not delete downloaded upstream packages or tools. Retired private runtimes remain in local backups with their notices.
 
 ## Network services
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpi",
-  "version": "0.36.4",
+  "version": "0.37.0",
   "description": "Scope control and a human-selected harness improvement loop for Pi",
   "author": "Tanner Middleton",
   "repository": {
@@ -94,9 +94,9 @@
     "check": "npm run format:check && npm run check:syntax && npm test && npm run check:package && npm run check:vscode"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-ai": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-ai": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
     "typebox": "1.3.7",
     "playwright": "1.62.1",
     "@stylistic/eslint-plugin": "5.10.0",

package/scripts/lib.mjs

@@ -75,6 +75,64 @@ export function restorePackageChanges(current, changes, warnings = []) {
     return result;
 }
 
+export const CODEMODE_ENTRY = "+codemode";
+// Pi 0.99.0 added codemode and `+name` entries in defaultTools. Older Pi reads "+codemode" as a
+// plain tool name that replaces its defaults, which would leave the session with no built-in tools.
+export const CODEMODE_MIN_PI = [0, 99, 0];
+
+export function supportsCodemode(version) {
+    if (!Array.isArray(version)) {
+        return false;
+    }
+
+    for (let index = 0; index < CODEMODE_MIN_PI.length; index += 1) {
+        if (version[index] !== CODEMODE_MIN_PI[index]) {
+            return version[index] > CODEMODE_MIN_PI[index];
+        }
+    }
+
+    return true;
+}
+
+// Adds "+codemode" to defaultTools unless the user already decided about codemode or built-in tools.
+// Returns what was there before so uninstall can take back only SpecPi's entry.
+export function enableCodemode(settings) {
+    if (Array.isArray(settings.extensions) && settings.extensions.includes("-builtin:codemode")) {
+        return { skipped: "extension-disabled" };
+    }
+
+    const current = settings.defaultTools;
+    if (current !== undefined && !Array.isArray(current)) {
+        return { skipped: "invalid" };
+    }
+
+    // An empty list turns every built-in tool off; adding a +name entry would turn the defaults back on.
+    if (Array.isArray(current) && current.length === 0) {
+        return { skipped: "no-builtin-tools" };
+    }
+
+    if ((current || []).some((entry) => ["codemode", "+codemode", "-codemode"].includes(entry))) {
+        return { skipped: "configured" };
+    }
+
+    settings.defaultTools = [...(current || []), CODEMODE_ENTRY];
+
+    return {
+        change: { beforeExists: current !== undefined, ...(current === undefined ? {} : { before: current }) },
+    };
+}
+
+// The settings-change record restoreSettingChanges understands. The path and entry are fixed here, never
+// read from the manifest, so a stale or edited manifest cannot point a restore at another setting.
+export function codemodeSettingChange(record) {
+    return {
+        path: ["defaultTools"],
+        beforeExists: record?.beforeExists === true,
+        ...(record?.beforeExists === true && Array.isArray(record.before) ? { before: record.before } : {}),
+        managedArrayEntries: [CODEMODE_ENTRY],
+    };
+}
+
 function markerRange(text, start, end) {
     const startIndex = text.indexOf(start);
     const endIndex = text.indexOf(end);

package/scripts/packages.mjs

@@ -66,7 +66,7 @@ export function packageChanges(before, after) {
     });
 }
 
-export function installBasePackages(agentDir) {
+function resolvePiCommand() {
     const requested = process.env.SPECPI_PI || "pi";
     const hasPath = path.isAbsolute(requested) || /[/\\]/.test(requested);
     const suffixes =
@@ -78,15 +78,74 @@ export function installBasePackages(agentDir) {
         : (process.env.PATH || process.env.Path || "")
               .split(path.delimiter)
               .flatMap((directory) => suffixes.map((suffix) => path.resolve(directory, `${requested}${suffix}`)));
-    const command = candidates.find((file) => fs.existsSync(file) && fs.statSync(file).isFile());
+
+    return candidates.find((file) => fs.existsSync(file) && fs.statSync(file).isFile());
+}
+
+function runPi(command, args, options) {
+    if (/\.[cm]?js$/i.test(command)) {
+        return spawnSync(process.execPath, [command, ...args], options);
+    }
+
+    if (process.platform === "win32" && /\.(cmd|bat)$/i.test(command)) {
+        // Environment expansion keeps paths with spaces and shell metacharacters one quoted argument.
+        const env = { ...options.env };
+        const line = [command, ...args]
+            .map((value, index) => {
+                if (/["\r\n]/.test(value)) {
+                    throw new Error("Unsupported quote or newline in Pi command path");
+                }
+
+                const key = `SPECPI_PACKAGE_ARG_${index}`;
+                env[key] = value;
+
+                return `"%${key}%"`;
+            })
+            .join(" ");
+
+        return spawnSync(line, [], {
+            ...options,
+            env,
+            shell: process.env.ComSpec || process.env.COMSPEC || "cmd.exe",
+        });
+    }
+
+    return spawnSync(command, args, options);
+}
+
+// The version of the Pi CLI SpecPi would install with, or undefined when it cannot be read.
+export function piVersion(agentDir) {
+    const command = resolvePiCommand();
+    if (!command) {
+        return undefined;
+    }
+
+    try {
+        const result = runPi(command, ["--version"], {
+            cwd: agentDir,
+            env: { ...process.env, PI_CODING_AGENT_DIR: agentDir },
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 30_000,
+            windowsHide: true,
+        });
+        const match = result.status === 0 ? /^\s*v?(\d+)\.(\d+)\.(\d+)\b/u.exec(result.stdout || "") : null;
+
+        return match ? match.slice(1, 4).map(Number) : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+export function installBasePackages(agentDir) {
+    const command = resolvePiCommand();
     if (!command) {
         throw new Error("Pi was not found. Install Pi, put pi on PATH, or set SPECPI_PI to its CLI path.");
     }
 
     for (const source of basePackages) {
         console.log(`Installing ${source}`);
-        const args = ["install", source];
-        const options = {
+        const result = runPi(command, ["install", source], {
             cwd: agentDir,
             // Later installs must not re-resolve earlier pins through npm's default caret ranges.
             env: {
@@ -101,33 +160,7 @@ export function installBasePackages(agentDir) {
             },
             stdio: "inherit",
             windowsHide: true,
-        };
-        let result;
-        if (/\.[cm]?js$/i.test(command)) {
-            result = spawnSync(process.execPath, [command, ...args], options);
-        } else if (process.platform === "win32" && /\.(cmd|bat)$/i.test(command)) {
-            // Environment expansion keeps paths with spaces and shell metacharacters one quoted argument.
-            const values = [command, ...args];
-            const line = values
-                .map((value, index) => {
-                    if (/["\r\n]/.test(value)) {
-                        throw new Error("Unsupported quote or newline in Pi command path");
-                    }
-
-                    const key = `SPECPI_PACKAGE_ARG_${index}`;
-                    options.env[key] = value;
-
-                    return `"%${key}%"`;
-                })
-                .join(" ");
-            result = spawnSync(line, [], {
-                ...options,
-                shell: process.env.ComSpec || process.env.COMSPEC || "cmd.exe",
-            });
-        } else {
-            result = spawnSync(command, args, options);
-        }
-
+        });
         if (result.error || result.status !== 0) {
             throw new Error(
                 `Pi installation failed for ${source}: ${result.error?.message || `exit ${result.status}`}`,

package/scripts/specpi.mjs

@@ -10,19 +10,29 @@ import {
     AGENTS_START,
     SHELL_END,
     SHELL_START,
+    codemodeSettingChange,
     deepEqual,
     deletePath,
+    enableCodemode,
     readPath,
     removeManagedBlock,
     restorePackageChanges,
     setPath,
     sha256,
+    supportsCodemode,
     upsertManagedBlock,
 } from "./lib.mjs";
 import { validateCapabilityRegistry } from "../extensions/tool-wishlist/registry.mjs";
 import { runValidator } from "../extensions/tool-wishlist/validators.mjs";
 import { acquireSpecPiLock } from "./lock.mjs";
-import { basePackages, checkBasePackages, installBasePackages, packageChanges, runBrowserQA } from "./packages.mjs";
+import {
+    basePackages,
+    checkBasePackages,
+    installBasePackages,
+    packageChanges,
+    piVersion,
+    runBrowserQA,
+} from "./packages.mjs";
 import { RETIRED_GUARD_NOTICE, RETIRED_GUARD_PIN, retiredGuardWasOn } from "./lancet-guard.mjs";
 import {
     applyShellToolMapping,
@@ -84,8 +94,9 @@ Usage:
   specpi doctor
   specpi uninstall [--yes]
 
-Installs /scope, the harness improvement loop, and eight pinned packages.
-The base is tested with Pi 0.84.4. Run specpi plan to see package versions.
+Installs /scope, the harness improvement loop, and eight pinned packages,
+and turns on Pi's codemode tool. The base is tested with Pi 1.0.0.
+Run specpi plan to see package versions.
 --skip-package-install installs only the core, or preserves an existing base on update.
 --skip-browser-install skips Chromium setup, not package acquisition or doctor checks.
 --force replaces modified retained resources after backing them up.
@@ -205,6 +216,9 @@ function printPlan(options = {}) {
     console.log(
         `  ${permissionConfigFile(agentDir)} (one shellTools entry, only when the permission system is installed, so bash rules apply to background jobs)`,
     );
+    console.log(
+        `  ${settingsPath} (adds "+codemode" to defaultTools on Pi 0.99 or later, unless defaultTools already mentions codemode, is empty, or codemode is disabled; uninstall removes only that entry)`,
+    );
     const wanted = new Set(managedFiles().map(([, target]) => target));
     for (const target of Object.keys(manifest?.files || {})) {
         if (!wanted.has(target)) {
@@ -235,7 +249,7 @@ function printPlan(options = {}) {
             : "After package acquisition, run the installed Browser QA Node bin to download Chromium and verify offline rendering, pixel comparison, and accessibility. No Bun or OS library installation.",
     );
     console.log(
-        "Only package settings are merged. No theme or shell integration. Wishlist collection starts off. Backups precede mutation; downloaded packages, browser-cache bytes and upstream script effects cannot be rolled back or removed by uninstall.",
+        "Only package settings and that defaultTools entry are merged. No theme or shell integration. Wishlist collection starts off. Backups precede mutation; downloaded packages, browser-cache bytes and upstream script effects cannot be rolled back or removed by uninstall.",
     );
 }
 
@@ -260,6 +274,44 @@ function restoreLegacySettings(manifest, warnings) {
     writeJson(settingsPath, settings, existingMode(settingsPath, 0o600));
 }
 
+// Takes back the "+codemode" entry a previous install added, leaving the rest of defaultTools alone.
+function restoreCodemodeSetting(manifest, warnings) {
+    if (!manifest?.codemodeSetting) {
+        return;
+    }
+
+    const settings = readJson(settingsPath, {});
+    restoreSettingChanges(settings, [codemodeSettingChange(manifest.codemodeSetting)], warnings);
+    writeJson(settingsPath, settings, existingMode(settingsPath, 0o600));
+}
+
+// Turns on Pi's codemode tool through defaultTools. Returns the manifest record, or undefined when
+// nothing was added because the user already chose, or Pi is too old to read the entry safely.
+function applyCodemodeSetting(warnings) {
+    const version = piVersion(agentDir);
+    if (!supportsCodemode(version)) {
+        warnings.push(
+            `Codemode left off: it needs Pi 0.99 or later, and ${version ? `Pi ${version.join(".")} was found` : "the Pi version could not be read"}. Update Pi, then run specpi update.`,
+        );
+
+        return undefined;
+    }
+
+    const settings = readJson(settingsPath, {});
+    const result = enableCodemode(settings);
+    if (result.skipped === "invalid") {
+        warnings.push("Codemode left off: defaultTools in settings.json is not an array; preserved it as it is.");
+    }
+
+    if (!result.change) {
+        return undefined;
+    }
+
+    writeJson(settingsPath, settings, existingMode(settingsPath, 0o600));
+
+    return result.change;
+}
+
 function removeLegacyShell(manifest) {
     if (manifest?.shellRc && fs.existsSync(manifest.shellRc)) {
         const result = removeManagedBlock(fs.readFileSync(manifest.shellRc, "utf8"), SHELL_START, SHELL_END);
@@ -317,9 +369,9 @@ async function mutate(options, operation) {
             ...files.map(([, target]) => target),
             ...Object.keys(previous?.files || {}),
         ];
-        if (!options.skipPackages || previous?.settingsChanges?.length || previous?.packageChanges?.length) {
-            watched.push(settingsPath);
-        }
+        // Always watched: codemode's defaultTools entry is added on every install and update, and
+        // removed on uninstall, whether or not packages are installed.
+        watched.push(settingsPath);
 
         if (previous?.shellRc) {
             watched.push(previous.shellRc);
@@ -338,6 +390,7 @@ async function mutate(options, operation) {
         const warnings = [];
         const preserveBase = operation !== "uninstall" && options.skipPackages && previous?.basePackages?.length;
         restoreLegacySettings(preserveBase ? { ...previous, packageChanges: [] } : previous, warnings);
+        restoreCodemodeSetting(previous, warnings);
         removeLegacyShell(previous);
         let packageState = preserveBase
             ? {
@@ -402,6 +455,8 @@ async function mutate(options, operation) {
             removeShellToolMapping(agentDir);
         }
 
+        const codemodeSetting = operation === "uninstall" ? undefined : applyCodemodeSetting(warnings);
+
         injectTestFailure("after-settings");
         const records = {};
         const wanted = new Set(files.map(([, target]) => target));
@@ -481,6 +536,7 @@ async function mutate(options, operation) {
                 blockFiles: { agents: previous?.blockFiles?.agents || { existed: transaction.get(agentsPath).exists } },
                 files: records,
                 ...packageState,
+                ...(codemodeSetting ? { codemodeSetting } : {}),
                 backups: [...(previous?.backups || []), path.relative(stateDir, backupDir)],
             });
         }

package/templates/settings.json

@@ -4,7 +4,7 @@
         "npm:specpi-browser-qa@0.3.0",
         "npm:specpi-delegation@0.2.0",
         "npm:specpi-experiments@0.1.0",
-        "npm:pi-goal-x@0.31.2",
+        "npm:pi-goal-x@0.32.0",
         "npm:@sreetej510/pi-usage@0.10.0",
         "npm:@gotgenes/pi-permission-system@32.0.2",
         "npm:specpi-lancet-guard@0.6.0"