specpi 0.36.3 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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`.
+- The README's command guard section gives LANCET Nano v0.4.3's Triage Score across its three release benchmarks, 68.3 with 9.0% of safe commands stopped, as the LANCET page does, in place of its lancet-bench-2-next comparison with Jev. The README, the LANCET and Jev pages and the security model point to `/lancet-guard mode block` instead of the raw setting, and the LANCET page lists the command. SpecPi Chat stays at 0.18.0.
+
 ## 0.36.3 - 2026-09-30
 
 - Pin `specpi-lancet-guard` 0.5.0, which scores with LANCET Nano v0.4.3, a newly trained model in a new format. The guard's runtime is ported to v0.4.3's `classify.py`: the tokenizer loads `vocab.json` and `merges.txt`, a command longer than one 512-token window is read as overlapping windows, and bands come from the risk logit. PowerShell and cmd are now scored rather than always asking, so a PowerShell command LANCET does not flag runs; commands over 8,192 bytes still ask. A command longer than one window is scored but never cleared: review found that harmless lines put in front of a risky command pull it to `not_flagged` once it spans a second window, so a `not_flagged` verdict there asks, as every command that long did before. On lancet-bench-2-next, LANCET's new 3,204-command release benchmark, it catches 78.0% of risky commands, as v0.4.2 did, while stopping 12.4% of safe ones, against 20.0%; its Triage Score across three benchmarks is 68.3, against 54.4. On ShellRisk-Bench's test split it catches 64.8%, against 60.1%, at 3.0% stopped; on the neutral set it catches 85.8%, against 91.0%. Long commands cost about 0.3 s per window, 5 to 8 s at the byte limit; within one window, padding still moves some risky commands to `not_flagged`. The parity fixture is re-recorded with v0.4.3's runtime and gains PowerShell, cmd, window-boundary and byte-limit cases; the port matches it within 6.7e-16 in score and 1.8e-14 in risk logit, and CI decisions match on Linux, Windows and macOS. Users who update must run `/lancet-guard setup` again; a guard saved as on fails closed until they do. The README, security model, third-party notes and website now report lancet-bench-2-next, because lancet-bench-1 is retired and part of v0.4.3's training data. SpecPi Chat stays at 0.18.0.

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.3**, paired with the Chat **0.18.0** VSIX. Browser QA **0.3.0** and LANCET guard **0.5.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.3 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.
 
@@ -45,16 +45,15 @@ Everything it touches is written down, versioned, and easy to undo.
 
 ## A local command guard
 
-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.
+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 (local) | Jev (hosted, previous guard) |
-| --- | ---: | ---: |
-| Risky commands caught | 78.0% | 95.1% |
-| Safe commands wrongly stopped | 12.4% | 21.8% |
-| Cost per check | $0 | per request |
-| Network | none | every check |
+<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>
 
-Scores are from lancet-bench-2-next, LANCET's 3,204-command release benchmark of risky commands and their safe look-alikes, classifier alone. 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

@@ -62,7 +62,7 @@ Settings live in `<agent-dir>/specpi/jev/settings.json`, written atomically with
 
 `specpi-lancet-guard` is pinned in the base set and ships **off**. SpecPi writes nothing into its configuration: the package's own default is off, and only its own `/lancet-guard on` (this session) or `/lancet-guard on --global` (saved in `<home>/.pi/lancet-guard.json`) turns it on. An installer run never arms or disarms it, so a saved choice survives every update. `@gotgenes/pi-permission-system` stays pinned and decides every tool call whether the guard is on or off; the guard is a second, independent check: either one can block a call, so the guard never allows what the permission system would refuse.
 
-When on, local rules copied from `specpi-jev-guard` decide first -- hard-deny patterns block, provably read-only commands and the user's allow globs pass -- and LANCET Nano v0.4.3, a 111M-parameter CodeT5+ 220M classifier, scores the rest of `bash`, `powershell` and `background` commands in-process on the CPU through ONNX Runtime, reading Bash and PowerShell alike, so a PowerShell command it does not flag runs. `risky` asks (or blocks, if configured), `review` -- the band Nano is unsure about -- asks, `not_flagged` runs, and what LANCET cannot read (input over 8,192 bytes) asks. Longer commands are read in full, as overlapping 512-token windows, but never cleared: a `not_flagged` verdict on one asks, because harmless lines in front of a risky command pull it under the threshold once it spans a second window. Writes and edits to protected or out-of-workspace paths ask without a model call. With no UI, an ask becomes a block unless `uncertain` is `allow`. A missing, damaged or unloadable model blocks what the rules leave open: switching the guard on accepts that, and `/lancet-guard on` is refused until the model is installed. `not_flagged` is not a safety claim; on lancet-bench-2-next, LANCET's 3,204-command release benchmark, the classifier alone caught 78.0% of risky commands and stopped 12.4% of safe ones, against 95.1% and 21.8% for Jev, and credentials are among its weakest areas. Updating the guard to a release that pins a new model leaves the old model unused: a guard saved as on fails closed until `/lancet-guard setup` fetches the new one.
+When on, local rules copied from `specpi-jev-guard` decide first -- hard-deny patterns block, provably read-only commands and the user's allow globs pass -- and LANCET Nano v0.4.3, a 111M-parameter CodeT5+ 220M classifier, scores the rest of `bash`, `powershell` and `background` commands in-process on the CPU through ONNX Runtime, reading Bash and PowerShell alike, so a PowerShell command it does not flag runs. `risky` asks (or blocks, after `/lancet-guard mode block` saves `"risky": "block"`), `review` -- the band Nano is unsure about -- asks, `not_flagged` runs, and what LANCET cannot read (input over 8,192 bytes) asks. Longer commands are read in full, as overlapping 512-token windows, but never cleared: a `not_flagged` verdict on one asks, because harmless lines in front of a risky command pull it under the threshold once it spans a second window. Writes and edits to protected or out-of-workspace paths ask without a model call. With no UI, an ask becomes a block unless `uncertain` is `allow`. A missing, damaged or unloadable model blocks what the rules leave open: switching the guard on accepts that, and `/lancet-guard on` is refused until the model is installed. `not_flagged` is not a safety claim; on lancet-bench-2-next, LANCET's 3,204-command release benchmark, the classifier alone caught 78.0% of risky commands and stopped 12.4% of safe ones, against 95.1% and 21.8% for Jev, and credentials are among its weakest areas. Updating the guard to a release that pins a new model leaves the old model unused: a guard saved as on fails closed until `/lancet-guard setup` fetches the new one.
 
 Commands never leave the machine and are never executed by the guard. The only network access is `/lancet-guard setup`, run by a human: it downloads one ZIP from the pinned `TannerMidd/LANCET-model` GitHub release into a private staging directory, capped at its pinned size, and refuses it unless its SHA-256 matches the digest compiled into the package. Only then does the package's own small ZIP reader extract the six model files, each inflated to its pinned size and refused unless its own SHA-256 matches. GitHub is the only host involved, so it works where Hugging Face is blocked. The digests are checked again on every load. The package's one production dependency, `onnxruntime-node` 1.30.0, is pinned exactly; its install script would fetch CUDA libraries on Linux x64, so the installer sets `ONNXRUNTIME_NODE_INSTALL=skip`.
 
@@ -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.5.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,16 +21,16 @@ 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.5.0   | [TannerMidd/SpecPi](https://github.com/TannerMidd/SpecPi/tree/main/packages/lancet-guard) |
+| specpi-lancet-guard            | 0.6.0   | [TannerMidd/SpecPi](https://github.com/TannerMidd/SpecPi/tree/main/packages/lancet-guard) |
 
 Transitive dependencies and their notices remain in Pi's npm installation tree. Top-level pins do not freeze upstream dependency ranges or constitute a full transitive security audit. Pi invokes npm with its upstream package-management semantics, including dependency lifecycle scripts. Browser QA has no install hook: confirmed SpecPi install/update explicitly invokes its installed Node setup bin, unless acquisition or browser setup is skipped. It downloads package-pinned Chromium without installing OS libraries. BetterWright is optional/manual and retains its own Bun-based setup; SpecPi neither removes Bun nor deletes user-owned tools. Usage reporting and web packages make their own provider/service connections. Consult upstream licenses and security policies before redistributing their components.
 
 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.3",
+  "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/lancet-guard.mjs

@@ -15,7 +15,7 @@ import os from "node:os";
 import path from "node:path";
 
 /** Must match the pin in templates/settings.json. */
-export const GUARD_PIN = "npm:specpi-lancet-guard@0.5.0";
+export const GUARD_PIN = "npm:specpi-lancet-guard@0.6.0";
 
 export const RETIRED_GUARD_PIN = "npm:specpi-jev-guard@0.4.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,9 +4,9 @@
         "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.5.0"
+        "npm:specpi-lancet-guard@0.6.0"
     ]
 }