specpi 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.25.0 - 2026-09-17
+
+- Hide the web access tools until needed. `web_search`, `source_check`, `fetch_content` and `get_search_content` are no longer offered to a session until `/webaccess on`; `/webaccess startup on` saves that choice. The working agreement, security model and wiki say so, and the agent asks the human to run it rather than attempting a hidden tool.
+- Re-measure first-call context from the complete installed base instead of first-party extensions alone. A default session sends 15,069 characters and the enabled profile (`/browser on`, `/delegate on`, `/webaccess on`) sends 40,203. The earlier 10,536-character figure omitted installed guidance and third-party pins and is corrected on the research page. The measurement, pins and method are published as `site/research/context-measurement.json`.
+- Add a capability chart that partitions the enabled profile's tool schema group by group: web access is the largest at 11,298 characters, ahead of Browser QA's fourteen tools at 8,046. Leaving the three opt-in groups hidden keeps 23,797 characters of tool schema out of every request.
+- Re-measure Oh My Pi on the same terms at 65,816 characters and keep it a measured row: HarnessTax covers Claude Code, Codex CLI and Pi only, so the fork was never a study figure.
+- Measure OpenCode on the same terms and add it to the first-call chart. Its default build-agent session sends 31,043 characters across 10 tools, about 5.6x stock Pi and about twice a default SpecPi, landing between a default SpecPi and the enabled profile. `scripts/measure-context.mjs --oc=<path to OpenCode's binary>` takes that row; the session title is pinned so the turn sends exactly one model call. The research page is rewritten in plainer language and the "For this base" section is restructured around subheads.
+- Stop `/scope` from racing the session restore. Restore retires scope immediately but only learns the repository root once `git rev-parse` returns; a contract declared in that window was recorded against the session cwd, and the replay that followed rejected its own entry as belonging elsewhere and silently turned scope off after reporting it set. Scope commands now wait for the restore in flight.
+
 ## 0.24.0 - 2026-09-16
 
 - Replace `pi-subagents@0.67.0` in the default base with first-party `specpi-delegation@0.2.0`, and add `specpi-experiments@0.1.0`. The base is now seven pinned packages; the other five are unchanged.

package/README.md

@@ -38,9 +38,36 @@ The setup optimizes for four things:
 - **Accuracy** — exact pins, checksum-tracked state, rollback on failure, and evidence over claims
 - **Improvement** — local observations become bounded, verified changes through `/harness-improvement`
 - **Efficiency** — subagent delegation, persistent goals, and browser QA handled by the right tools
+- **Lean default** — web access, browser QA, and delegation ship hidden; `/webaccess on`, `/browser on`, and `/delegate on` offer them per session
 
 Everything it manages is declared, versioned, and reversible.
 
+## Measured context
+
+The chart measures first-call context from a clean installation: all seven pinned packages, the installed working agreement, and discovered skills. “Enabled” means browser QA, delegation, and web access are switched on; no goal, scope, or improvement selection is active. The solid rows — including OpenCode and Oh My Pi, both measured as installed — are ours, taken from the request each harness actually sends through one local synthetic provider. The dimmed Codex CLI and Claude Code rows are HarnessTax's published figures, taken under the study's configuration: a reference, not a matched comparison. These are character counts, not tokens, spending, or task-quality scores. The research page [breaks the enabled profile down by capability](https://tannermidd.github.io/SpecPi/research/#specpi), so the cost of each switch is visible on its own.
+
+<p align="center">
+  <a href="https://tannermidd.github.io/SpecPi/research/#specpi">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://tannermidd.github.io/SpecPi/media/context-chart-dark.svg">
+      <img src="https://tannermidd.github.io/SpecPi/media/context-chart-light.svg" width="880" alt="Bar chart of characters sent on the first model call: Pi stock 5,521, SpecPi default 15,069, OpenCode 31,043, SpecPi enabled 40,203, Codex CLI 41,616, Oh My Pi 65,816, Claude Code 90,460.">
+    </picture>
+  </a>
+</p>
+<p align="center"><sub>Measured tool schemas + system/developer instructions · <code>node scripts/measure-context.mjs --chart --omp=&lt;path to Oh My Pi's cli.js&gt; --oc=&lt;path to OpenCode's binary&gt;</code> · <a href="site/research/context-measurement.json">Recorded measurements and package pins</a> · <a href="https://tannermidd.github.io/SpecPi/research/#specpi">Method and caveats</a></sub></p>
+
+The gap between the two SpecPi bars is not one decision, so the enabled profile's tool schema is also measured group by group. Browser QA's fourteen tools cost less together than web access's four:
+
+<p align="center">
+  <a href="https://tannermidd.github.io/SpecPi/research/#specpi">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://tannermidd.github.io/SpecPi/media/capability-chart-dark.svg">
+      <img src="https://tannermidd.github.io/SpecPi/media/capability-chart-light.svg" width="880" alt="Bar chart of tool-schema characters each capability adds: Pi built-ins 2,896, Improvement loop 4,214, Goals 1,315, Browser QA 8,046, Delegation 4,453, Web access 11,298. Browser QA, Delegation, Web access are hidden until switched on.">
+    </picture>
+  </a>
+</p>
+<p align="center"><sub>Every tool in the measured request belongs to exactly one group · Leaving all three opt-in groups hidden keeps 23,797 characters of tool schema out of every request</sub></p>
+
 ## Install
 
 Requires Node.js 22.19+, Git, npm, and an existing Pi installation on PATH.

package/SECURITY_MODEL.md

@@ -10,7 +10,7 @@ Scope records use Pi's current session branch. Restoring a branch does not creat
 
 ## Improvement authority and evidence
 
-Collection is off by default. Enabling it permits sanitized gap observations, not implementation. Only an exact human `/harness-improvement` selection authorizes a wishlist-sourced change. The selected contract is bound to the gap, source checkout, session, and selection generation.
+Collection is off by default. Enabling it permits sanitized gap observations, not implementation. Only an exact human `/harness-improvement` selection authorizes a wishlist-sourced change. The selected contract is bound to the gap, source checkout, session, and selection generation. Web access tools (`web_search`, `source_check`, `fetch_content`, `get_search_content`) are hidden until `/webaccess on`.
 
 Retirement requires source registry integration, unchanged verification policy, a matching contract, bounded source snapshots, `npm run check`, and closed registered validators. Receipts distinguish machine-observed gates from model-reported acceptance evidence. Stale selections, changed source, missing evidence, and failed checks reject retirement. A validator proves only the behavior it exercises; the human remains responsible for accepting the result. The loop never commits, publishes, or installs a resulting change automatically.
 

package/extensions/workflow-controls/index.ts

@@ -12,6 +12,13 @@ import {
 } from "./scope.mjs";
 
 import { readTaskContract, renderTaskContract } from "./task-contract.mjs";
+import {
+    WEB_TOOL_NAMES,
+    loadStartupActivation,
+    saveStartupActivation,
+    settingsPath,
+    syncActiveTools as syncWebAccessTools,
+} from "./web-access.mjs";
 const SCOPE_ENTRY = "specpi-scope-state";
 const SCOPE_STATUS = "specpi-scope";
 const MAX_PENDING_SCOPE = 40;
@@ -272,6 +279,11 @@ export default function workflowControls(pi: ExtensionAPI) {
         persistScope(ctx);
     };
 
+    // Restore empties scope first and only learns the real root once `git rev-parse` returns, so between those two
+    // moments `scope.root` is a guess at the session cwd: not yet canonical, and not yet the enclosing repository.
+    // A human command that declared scope in that gap recorded it under the guessed root, and the replay below then
+    // rejected its own branch entry as belonging elsewhere, silently retiring a contract the human was told was set.
+    // Scope commands therefore wait for `sessionRestore` rather than racing it.
     const restoreSession = async (ctx: ExtensionContext) => {
         sessionGeneration += 1;
         const origin = captureSession(ctx);
@@ -337,8 +349,24 @@ export default function workflowControls(pi: ExtensionAPI) {
         emitScopeStatus(ctx);
     };
 
-    pi.on("session_start", (_event, ctx) => restoreSession(ctx));
-    pi.on("session_tree", (_event, ctx) => restoreSession(ctx));
+    let sessionRestore: Promise<void> = Promise.resolve();
+    const beginRestore = (ctx: ExtensionContext) => {
+        // Waiters only need to know the restore is over; restoreSession reports its own failures.
+        sessionRestore = restoreSession(ctx).catch(() => {});
+    };
+
+    // Web access ships hidden. A missing or unreadable preference means off, and the
+    // gate only ever touches its own four tool names.
+    let webAccessEnabled = loadStartupActivation();
+    const applyWebAccess = () => syncWebAccessTools(pi, WEB_TOOL_NAMES, webAccessEnabled);
+
+    pi.on("session_start", (_event, ctx) => {
+        webAccessEnabled = loadStartupActivation();
+        applyWebAccess();
+        beginRestore(ctx);
+    });
+
+    pi.on("session_tree", (_event, ctx) => beginRestore(ctx));
 
     pi.on("session_shutdown", (_event, ctx) => {
         sessionGeneration += 1;
@@ -517,6 +545,9 @@ export default function workflowControls(pi: ExtensionAPI) {
                 .filter((value) => value.startsWith(prefix.trim().toLowerCase()))
                 .map((value) => ({ value, label: value })),
         handler: async (args, ctx) => {
+            // Read scope only after any restore in flight has settled: before that, both the default action and the
+            // root every branch below records are taken from a provisional, pre-Git-lookup guess.
+            await sessionRestore;
             const origin = captureSession(ctx);
             const [actionRaw, ...rest] = args.trim().split(/\s+/u).filter(Boolean);
             const action = actionRaw?.toLowerCase() || (scope.active ? "status" : "set");
@@ -749,4 +780,70 @@ export default function workflowControls(pi: ExtensionAPI) {
             }
         },
     });
+
+    pi.registerCommand("webaccess", {
+        description: "Offer or withdraw the web access tools, or choose whether they start offered",
+        getArgumentCompletions: (prefix: string) =>
+            ["on", "off", "status", "startup", "startup on", "startup off"]
+                .filter((value) => value.startsWith(prefix.trim().toLowerCase()))
+                .map((value) => ({ value, label: value })),
+        handler: async (args: string, ctx: ExtensionContext) => {
+            const [action = "status", choice, ...rest] = args.trim().split(/\s+/u).filter(Boolean);
+            if (rest.length || (choice && action.toLowerCase() !== "startup")) {
+                throw new Error("Usage: /webaccess [on|off|status|startup [on|off]]");
+            }
+
+            const verb = action.toLowerCase();
+            if (verb === "on" || verb === "off") {
+                webAccessEnabled = verb === "on";
+                applyWebAccess();
+                ctx.ui.notify(
+                    webAccessEnabled
+                        ? `Web access offered ${WEB_TOOL_NAMES.length} tools to this session (web_search, source_check, fetch_content, get_search_content). They add about 11 KB of tool schema to each request until /webaccess off.`
+                        : "Web access withdrew its tools from this session. Search and fetch now require /webaccess on.",
+                    "info",
+                );
+
+                return;
+            }
+
+            if (verb === "startup") {
+                if (!choice) {
+                    ctx.ui.notify(
+                        `Web access starts ${loadStartupActivation() ? "offered" : "withdrawn"}. Preference: ${settingsPath()}`,
+                        "info",
+                    );
+
+                    return;
+                }
+
+                if (!ctx.hasUI) {
+                    throw new Error("Startup changes require a human interactive command");
+                }
+
+                if (!["on", "off"].includes(choice.toLowerCase())) {
+                    throw new Error("Usage: /webaccess startup [on|off]");
+                }
+
+                saveStartupActivation(choice.toLowerCase() === "on");
+                ctx.ui.notify(
+                    choice.toLowerCase() === "on"
+                        ? "Web access tools will be offered in new Pi sessions, adding their schemas to every request. This session is unchanged."
+                        : "Web access tools will start withdrawn in new Pi sessions and their schemas will not be sent. This session is unchanged.",
+                    "info",
+                );
+
+                return;
+            }
+
+            if (verb !== "status") {
+                throw new Error("Usage: /webaccess [on|off|status|startup [on|off]]");
+            }
+
+            ctx.ui.notify(
+                `Web access is ${webAccessEnabled ? "offering" : "not offering"} its ${WEB_TOOL_NAMES.length} tools to this session, and starts ${loadStartupActivation() ? "offered" : "withdrawn"}.`,
+                "info",
+            );
+        },
+    });
 }

package/extensions/workflow-controls/web-access.mjs

@@ -0,0 +1,107 @@
+// pi-web-access registers four network tools (web_search, source_check, fetch_content,
+// get_search_content). Pi sends every active tool's schema on every request, so a project
+// that never searches would pay for them on every call. SpecPi therefore hides them behind
+// a saved preference that ships off, and `/webaccess on` turns them on for a session.
+//
+// This file is SpecPi's own control: it never modifies the installed package, never reads
+// Pi settings, credentials or session state, and a missing or unreadable file means off.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+export const WEB_TOOL_NAMES = Object.freeze(["web_search", "source_check", "fetch_content", "get_search_content"]);
+
+const MAX_SETTINGS_BYTES = 4096;
+
+function agentDirectory() {
+    const configured = process.env.PI_CODING_AGENT_DIR;
+
+    return path.resolve(configured && configured.length > 0 ? configured : path.join(os.homedir(), ".pi", "agent"));
+}
+
+function settingsFile() {
+    return path.join(agentDirectory(), "specpi", "web-access", "settings.json");
+}
+
+/** Refuses links and irregular files so the preference cannot redirect a write. */
+function regularFile(file) {
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) {
+        return false;
+    }
+
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > MAX_SETTINGS_BYTES) {
+        throw new Error("Unsupported web access settings file");
+    }
+
+    return true;
+}
+
+export function loadStartupActivation() {
+    try {
+        const file = settingsFile();
+        if (!regularFile(file)) {
+            return false;
+        }
+
+        const settings = JSON.parse(fs.readFileSync(file, "utf8"));
+
+        return settings?.schema === 1 && settings.startupActivation === true;
+    } catch {
+        return false;
+    }
+}
+
+export function saveStartupActivation(enabled) {
+    if (typeof enabled !== "boolean") {
+        throw new Error("Web access startup activation must be on or off.");
+    }
+
+    const file = settingsFile();
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (fs.existsSync(file)) {
+        regularFile(file);
+    }
+
+    const temporary = path.join(directory, `.settings.${randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify({ schema: 1, startupActivation: enabled })}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        fs.renameSync(temporary, file);
+    } finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+
+export function settingsPath() {
+    return settingsFile();
+}
+
+/**
+ * Add or remove the web tools from Pi's active set without disturbing any other
+ * extension's tools, including built-ins and the other first-party gates.
+ */
+export function syncActiveTools(pi, names, enabled) {
+    if (typeof pi?.getActiveTools !== "function" || typeof pi?.setActiveTools !== "function") {
+        return;
+    }
+
+    const owned = new Set(names);
+    const active = pi.getActiveTools();
+    const present = active.filter((name) => owned.has(name));
+    if (enabled && present.length === owned.size) {
+        return;
+    }
+
+    if (!enabled && present.length === 0) {
+        return;
+    }
+
+    const others = active.filter((name) => !owned.has(name));
+    pi.setActiveTools(enabled ? [...others, ...names] : others);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpi",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Scope control and a human-selected harness improvement loop for Pi",
   "author": "Tanner Middleton",
   "repository": {

package/scripts/specpi.mjs

@@ -37,6 +37,7 @@ const resourcePaths = [
     "extensions/workflow-controls/scope.mjs",
     "extensions/workflow-controls/task-contract.mjs",
     "extensions/workflow-controls/smoke.mjs",
+    "extensions/workflow-controls/web-access.mjs",
     "extensions/tool-wishlist/index.ts",
     "extensions/tool-wishlist/core.mjs",
     "extensions/tool-wishlist/verification.mjs",

package/templates/AGENTS.md

@@ -6,6 +6,7 @@
 - Write commits and pull requests the same way: a short, clear title and a brief explanation of what changed, why, and what was tested. Avoid boilerplate, inflated claims, and unnecessary implementation detail.
 - When `/scope` is active, keep outside-scope findings pending until the human allows once, acknowledges them with `/scope accept`, expands scope with `/scope add`, or clears it. Acknowledgement does not widen scope.
 - Treat wishlist observations as leads, not authorization. Start a wishlist-sourced change only from an exact `/harness-improvement` selection and follow `specpi-improve`. Record its contract before editing and retire only after its verification gate passes.
+- Web access tools (`web_search`, `source_check`, `fetch_content`, `get_search_content`) ship hidden. When the task needs search or fetch, ask the human to run `/webaccess on`; do not attempt a hidden tool.
 - Never inspect Pi authentication, provider credentials, trust decisions, sessions, missions, or history to improve the harness. Use only the active extension context and intended local improvement records.
 - Use observed files, diffs, tests, and runtime behavior as evidence. Run relevant checks, inspect the final diff, and obtain fresh read-only review when risk warrants it. Report results and residual risks without claiming more than the checks prove.
 - Do not commit, push, publish, deploy, or alter remote state unless explicitly requested.