specpi 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+- Measure the DeepSeek Harness on the same terms and add it to the first-call chart. Its default session sends 31,743 characters across 25 tools, about 5.7x stock Pi and within 700 characters of OpenCode. `scripts/measure-context.mjs --dsh=<path to its bin>` takes that row, declared through the harness's own patch layer; its auxiliary session-title request is excluded because it carries no tool schema. The Oh My Pi row is carried forward from the same-terms run while its runtime's dependency resolution stays broken upstream.
+
+## 0.26.0 - 2026-09-17
+
+- Let the agent ask for a withdrawn tool group instead of working around it. Hiding web access and Browser QA keeps 19,344 characters of tool schema out of every request, but it also hides them from the agent, so a session that turns out to need one had no way to say so. The new `request_capability` tool names the withdrawn groups and asks the human, who may decline; accepting offers that group's tools from the agent's next message, for the rest of the session. It grants nothing on its own: it refuses without an interactive human, and a decline leaves the session unchanged. `/webaccess on` and `/browser on` are unchanged. Delegation is not requestable, because its own package requires a human command to bind a model.
+- Stop asking about a capability you always allow. `/capability allow <name>` records a standing grant so `request_capability` offers that group without a prompt, `/capability ask <name>` restores the prompt, and `/capability` shows which groups are offered and which are granted. Recording a grant needs an interactive command, a grant that fires announces itself, and headless sessions are still refused: the grant removes the prompt, not the human.
+- Bump `specpi-browser-qa` to 0.3.0 and move the base pin to match. Its fourteen tools no longer carry `promptSnippet` or `promptGuidelines`; that guidance moved into the tool descriptions, which travel with the schema. Pi rebuilds the system prompt when an activated tool carries prompt metadata, and that rebuild invalidates the provider's cached prefix even where deferred tool schemas are supported — so the metadata made every mid-session activation more expensive than it needed to be. Behavior is unchanged. `pi-web-access` is a third-party package and still carries its own prompt metadata, so activating web access mid-session continues to rebuild the prompt.
+
+## 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

@@ -28,18 +28,47 @@
 
 ---
 
-SpecPi is a small base for the [Pi coding agent](https://pi.dev/), assembled from deliberate choices about how the agent should work — not a curated marketplace.
+SpecPi 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.
 
-Two first-party extensions set the terms: **scope control**, which holds each task to the files it declared, and an **improvement loop**, which turns recurring friction into tested, evidence-backed harness changes instead of accumulated prompts and workarounds. Around them sit seven hand-picked packages, each pinned to an exact version and verified before any transaction completes, and **SpecPi Chat**, a VS Code frontend for working beside the agent.
+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 seven 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.
 
-The setup optimizes for four things:
+It focuses on five things:
 
-- **Control** — declared scope, tool permissions, and confirmation-gated lifecycle commands
-- **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
+- **Control:** clear scope, tool permissions, and lifecycle commands that ask before they change anything
+- **Accuracy:** exact version pins, checksums on state, rollback on failure, and proof over promises
+- **Improvement:** local notes become small, checked changes through `/harness-improvement`
+- **Efficiency:** delegation, persistent goals, and browser QA handled by the right tool for the job
+- **Lean default:** web access, browser QA, and delegation stay off until you need them. Turn them on for a session with `/webaccess on`, `/browser on`, and `/delegate on` — or let the agent ask when it hits the need, and answer the prompt
 
-Everything it manages is declared, versioned, and reversible.
+Everything it touches is written down, versioned, and easy to undo.
+
+## Measured context
+
+This chart shows first-call context from a clean install: all seven pinned packages, the working agreement, and the skills Pi finds. "Enabled" means browser QA, delegation, and web access are switched on, with no goal, scope, or improvement selection active.
+
+The solid rows are measured by us, from the request each setup actually sends through one local test provider. That includes OpenCode, the DeepSeek Harness, and Oh My Pi, all measured as installed. The faded Codex CLI and Claude Code rows come from HarnessTax's published numbers, measured under their own setup. Treat those as a rough reference, not a head-to-head test. These are character counts. They say nothing about tokens, cost, or how well each tool does the job. The research page [breaks down the enabled setup by feature](https://tannermidd.github.io/SpecPi/research/#specpi), so you can see what each switch costs 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, DeepSeek Harness 31,743, 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; --dsh=&lt;path to the DeepSeek Harness bin&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 comes from a few separate switches, so the enabled tools are also measured group by group. For example, the fourteen browser QA tools add up to less than the four web access tools:
+
+<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
 

package/SECURITY_MODEL.md

@@ -8,9 +8,15 @@ The human declares project-relative paths. Interactive `write` and `edit` calls
 
 Scope records use Pi's current session branch. Restoring a branch does not create new authority or accept pending drift. An improvement contract can supply paths only through the human's `/scope task` command.
 
+## Capability requests
+
+Optional tool groups ship withdrawn. The `request_capability` tool lets the model name a withdrawn group instead of silently working around it; it never grants one. Activation requires a human decision, either accepted in the moment or recorded earlier as a standing grant, so the tool refuses in headless sessions and a declined prompt leaves the session unchanged. Activation is additive, offers only the named group's tools, and lasts for the session: it writes no startup preference, and the next session starts from the saved preference as before. Delegation is not requestable, because its own package requires a human command to bind a model. Acceptance offers the tools; it is not a per-call permission, and the Permission System continues to govern what those tools may do.
+
+`/capability allow <name>` records a standing grant so that group is offered without a prompt, and `/capability ask <name>` returns it to prompting. Recording either requires an interactive human command, and a grant that fires still announces itself in the session. Grants live in `<agent-dir>/specpi/capabilities/settings.json`, written atomically with owner-only permissions; links and irregular files are refused, and an unreadable file, a foreign schema or an unknown capability name reads as no grant. A standing grant removes the prompt, not the requirement for a human: headless sessions are still refused, so a granted capability cannot be activated by an unattended run. It also does not offer the group at startup — the model must still ask, and the group stays withdrawn until it does.
+
 ## 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 a human offers them, through `/webaccess on` or by accepting a `request_capability` prompt.
 
 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.
 
@@ -28,7 +34,7 @@ Legacy migration restores only recorded settings ownership, preserves differing
 
 ## Browser QA package
 
-`packages/browser-qa` is an independently released Node-native Pi package extracted from the retired browser tools. The installer acquires the immutable `specpi-browser-qa@0.2.0` release through Pi; its source and dependencies are not bundled in SpecPi's npm artifact. Its fourteen tools ship withdrawn: until a human runs `/browser on`, or saves `/browser startup on`, Pi is offered no browser tool and the model cannot launch a browser at all. Delegation ships off on the same basis, so neither package's tools reach a default session. Its explicit setup downloads Playwright Chromium, and its doctor performs offline rendering, image-comparison and accessibility smoke checks. It uses package-local dependency resolution and the standard Playwright browser cache rather than SpecPi's retired managed runtime. No Pi settings, credentials or personal profiles are migrated. The ephemeral context is not OS/network isolation; pages can reach localhost and private networks. See the package's [security documentation](packages/browser-qa/SECURITY.md) for artifact retention, best-effort redaction, permission and cleanup limits. This is QA tooling, not general-browser feature parity. BetterWright remains optional/manual. Normal updates restore recorded pre-existing entries and remove only unchanged SpecPi-added BetterWright entries; modified entries, personal browsers, profiles, cookies, and user-owned tools are not migrated or deleted.
+`packages/browser-qa` is an independently released Node-native Pi package extracted from the retired browser tools. The installer acquires the immutable `specpi-browser-qa@0.3.0` release through Pi; its source and dependencies are not bundled in SpecPi's npm artifact. Its fourteen tools ship withdrawn: until a human runs `/browser on`, saves `/browser startup on`, or accepts a `request_capability` prompt, Pi is offered no browser tool and the model cannot launch a browser at all. Delegation ships off on the same basis, so neither package's tools reach a default session. Its explicit setup downloads Playwright Chromium, and its doctor performs offline rendering, image-comparison and accessibility smoke checks. It uses package-local dependency resolution and the standard Playwright browser cache rather than SpecPi's retired managed runtime. No Pi settings, credentials or personal profiles are migrated. The ephemeral context is not OS/network isolation; pages can reach localhost and private networks. See the package's [security documentation](packages/browser-qa/SECURITY.md) for artifact retention, best-effort redaction, permission and cleanup limits. This is QA tooling, not general-browser feature parity. BetterWright remains optional/manual. Normal updates restore recorded pre-existing entries and remove only unchanged SpecPi-added BetterWright entries; modified entries, personal browsers, profiles, cookies, and user-owned tools are not migrated or deleted.
 
 ## VS Code frontend
 

package/THIRD_PARTY.md

@@ -18,7 +18,7 @@ SpecPi requests exact npm dependency saves for these pins and checks installed t
 | Package                        | Version | Upstream                                                                  |
 | ------------------------------ | ------- | ------------------------------------------------------------------------- |
 | pi-web-access                  | 0.29.0  | [nicobailon/pi-web-access](https://github.com/nicobailon/pi-web-access)   |
-| specpi-browser-qa              | 0.2.0   | [TannerMidd/SpecPi](https://github.com/TannerMidd/SpecPi/tree/browser-qa-v0.1.0/packages/browser-qa) |
+| 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)                     |

package/extensions/workflow-controls/capabilities.mjs

@@ -0,0 +1,104 @@
+// SpecPi withdraws optional tool groups so their schemas stay out of every request. A human
+// normally restores one with /webaccess or /browser, which requires knowing up front that the
+// session will need it. This table lets the model name a withdrawn group instead, so the need
+// surfaces as a confirmation prompt at the moment it arises.
+//
+// Activation remains additive and human-confirmed. This file owns no preference and no state:
+// it maps a capability name to the tool names its owning package registered, and reports what
+// is already active.
+
+import { WEB_TOOL_NAMES } from "./web-access.mjs";
+
+/**
+ * Browser QA's fourteen tools, fixed by the pinned specpi-browser-qa release. Names absent
+ * from Pi's registry are ignored by setActiveTools, so a core-only install degrades to a
+ * clear "not installed" result rather than a broken activation.
+ */
+export const BROWSER_TOOL_NAMES = Object.freeze([
+    "browser_accessibility",
+    "browser_open",
+    "browser_set_viewport",
+    "browser_snapshot",
+    "browser_click",
+    "browser_fill",
+    "browser_diagnostics",
+    "browser_press",
+    "browser_select_option",
+    "browser_wait_for",
+    "browser_screenshot",
+    "browser_save_baseline",
+    "browser_compare_screenshot",
+    "browser_close",
+]);
+
+/**
+ * Delegation is deliberately absent. `/delegate on` binds a model and host and refuses
+ * without an interactive human, and the delegate tool re-synchronizes the active set from
+ * the package's own state when it finishes, so a tool-name activation would undo itself.
+ * Delegation needs an activation path inside its own package.
+ */
+export const CAPABILITIES = Object.freeze({
+    web: {
+        label: "Web access",
+        tools: WEB_TOOL_NAMES,
+        schemaCost: "about 11 KB of tool schema per request",
+        summary: "search the web and fetch page or source content",
+        command: "/webaccess",
+    },
+    browser: {
+        label: "Browser QA",
+        tools: BROWSER_TOOL_NAMES,
+        schemaCost: "about 8.7 KB of tool schema per request",
+        summary: "open pages in an isolated browser to verify rendering, behavior and accessibility",
+        command: "/browser",
+    },
+});
+
+export const CAPABILITY_NAMES = Object.freeze(Object.keys(CAPABILITIES));
+
+export function capabilityNames() {
+    return [...CAPABILITY_NAMES];
+}
+
+export function findCapability(name) {
+    if (typeof name !== "string") {
+        return undefined;
+    }
+
+    return Object.hasOwn(CAPABILITIES, name.trim().toLowerCase())
+        ? { id: name.trim().toLowerCase(), ...CAPABILITIES[name.trim().toLowerCase()] }
+        : undefined;
+}
+
+/** A capability counts as active only when every tool it owns is active. */
+export function capabilityActive(activeTools, capability) {
+    const active = new Set(activeTools);
+
+    return capability.tools.every((name) => active.has(name));
+}
+
+/**
+ * Tools the capability would add. An empty list means the group is already fully active, or
+ * that its package is not installed; the caller distinguishes the two by checking the
+ * registry.
+ */
+export function missingTools(activeTools, capability) {
+    const active = new Set(activeTools);
+
+    return capability.tools.filter((name) => !active.has(name));
+}
+
+/**
+ * Whether Pi has the capability's tools registered at all. Registered-but-inactive is the
+ * normal withdrawn state; entirely unregistered means the package is not installed.
+ */
+export function capabilityInstalled(allToolNames, capability) {
+    const known = new Set(allToolNames);
+
+    return capability.tools.some((name) => known.has(name));
+}
+
+/** One catalogue line per capability, for the tool description and its error results. */
+export function describeCapabilities() {
+    return CAPABILITY_NAMES.map((id) => `${id}: ${CAPABILITIES[id].summary}`).join("; ");
+}

package/extensions/workflow-controls/capability-policy.mjs

@@ -0,0 +1,110 @@
+// A human who always says yes to the same capability prompt is not making a decision, they are
+// clearing an obstacle. This file stores the standing answer: capabilities the human has chosen
+// to grant without being asked again.
+//
+// The preference is SpecPi's own file. It never reads Pi settings, credentials or session state,
+// a missing or unreadable file means "ask about everything", and an unknown capability name in a
+// stored file is ignored rather than trusted.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { CAPABILITY_NAMES } from "./capabilities.mjs";
+
+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", "capabilities", "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 capability settings file");
+    }
+
+    return true;
+}
+
+/**
+ * Capabilities granted without a prompt. Names that no longer exist are dropped, so retiring a
+ * capability cannot leave a stored grant pointing at a different one later.
+ */
+export function loadAutoAllowed() {
+    try {
+        const file = settingsFile();
+        if (!regularFile(file)) {
+            return [];
+        }
+
+        const settings = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (settings?.schema !== 1 || !Array.isArray(settings.autoAllow)) {
+            return [];
+        }
+
+        return settings.autoAllow.filter((name) => CAPABILITY_NAMES.includes(name));
+    } catch {
+        return [];
+    }
+}
+
+export function autoAllowed(capabilityId) {
+    return loadAutoAllowed().includes(capabilityId);
+}
+
+export function saveAutoAllowed(names) {
+    if (!Array.isArray(names) || names.some((name) => !CAPABILITY_NAMES.includes(name))) {
+        throw new Error("Unknown capability");
+    }
+
+    const file = settingsFile();
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (fs.existsSync(file)) {
+        regularFile(file);
+    }
+
+    const autoAllow = [...new Set(names)].sort();
+    const temporary = path.join(directory, `.settings.${randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify({ schema: 1, autoAllow })}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        fs.renameSync(temporary, file);
+    } finally {
+        fs.rmSync(temporary, { force: true });
+    }
+
+    return autoAllow;
+}
+
+/** Add one capability to the standing grants. Returns the stored list. */
+export function allowCapability(capabilityId) {
+    return saveAutoAllowed([...loadAutoAllowed(), capabilityId]);
+}
+
+/** Return one capability to prompting. Returns the stored list. */
+export function askCapability(capabilityId) {
+    if (!CAPABILITY_NAMES.includes(capabilityId)) {
+        throw new Error("Unknown capability");
+    }
+
+    return saveAutoAllowed(loadAutoAllowed().filter((name) => name !== capabilityId));
+}
+
+export function policyPath() {
+    return settingsFile();
+}

package/extensions/workflow-controls/index.ts

@@ -1,6 +1,17 @@
 import path from "node:path";
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { truncateToWidth } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import {
+    CAPABILITY_NAMES,
+    capabilityActive,
+    capabilityInstalled,
+    describeCapabilities,
+    findCapability,
+    missingTools,
+} from "./capabilities.mjs";
+import { allowCapability, askCapability, autoAllowed, loadAutoAllowed, policyPath } from "./capability-policy.mjs";
 import {
     canonicalRoot,
     compareWorktreeSnapshots,
@@ -12,6 +23,13 @@ import {
 } from "./scope.mjs";
 
 import { readTaskContract, renderTaskContract } from "./task-contract.mjs";
+import {
+    WEB_TOOL_NAMES,
+    loadStartupActivation,
+    saveStartupActivation,
+    settingsPath,
+    syncActiveTools as syncToolGroup,
+} from "./web-access.mjs";
 const SCOPE_ENTRY = "specpi-scope-state";
 const SCOPE_STATUS = "specpi-scope";
 const MAX_PENDING_SCOPE = 40;
@@ -272,6 +290,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 +360,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 = () => syncToolGroup(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 +556,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 +791,271 @@ 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",
+            );
+        },
+    });
+
+    // Withdrawn tool groups are invisible to the model, so a session that turns out to need
+    // one has no way to say so. This tool names the withdrawn groups and asks the human to
+    // restore one. It grants nothing on its own: without an interactive human it refuses, and
+    // a declined prompt leaves the session exactly as it was.
+    //
+    // Pi records tools added during a tool call and offers them from the next assistant
+    // message, so activation must be additive; removing here would cost the cached prefix.
+    const activateCapability = (capabilityId: string) => {
+        const capability = findCapability(capabilityId);
+        if (!capability) {
+            return;
+        }
+
+        if (capability.id === "web") {
+            webAccessEnabled = true;
+            applyWebAccess();
+
+            return;
+        }
+
+        syncToolGroup(pi, capability.tools, true);
+    };
+
+    pi.registerTool({
+        name: "request_capability",
+        label: "Request Capability",
+        description: `Ask the user to restore a withdrawn SpecPi tool group for this session. Available groups — ${describeCapabilities()}. Their tools are hidden to keep each request small, so request a group only when the current task actually needs it, and continue without it if the user declines. The restored tools are usable from your next message and stay available until the session ends. Delegation is not requestable here; ask the user to run /delegate on.`,
+        parameters: Type.Object(
+            {
+                capability: StringEnum(CAPABILITY_NAMES, {
+                    description: "Withdrawn tool group to request",
+                }),
+                reason: Type.String({
+                    minLength: 5,
+                    maxLength: 200,
+                    description: "What in the current task needs this group; shown to the user in the prompt",
+                }),
+            },
+            { additionalProperties: false },
+        ),
+        async execute(_toolCallId, params: any, _signal, _onUpdate, ctx: ExtensionContext) {
+            const capability = findCapability(params.capability);
+            if (!capability) {
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `Unknown capability. Available: ${CAPABILITY_NAMES.join(", ")}.`,
+                        },
+                    ],
+                    isError: true,
+                    details: { activated: false, capability: String(params.capability ?? "") },
+                };
+            }
+
+            const active = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+            if (capabilityActive(active, capability)) {
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `${capability.label} is already available. Use its tools directly.`,
+                        },
+                    ],
+                    details: { activated: false, capability: capability.id, alreadyActive: true },
+                };
+            }
+
+            const registered = typeof pi.getAllTools === "function" ? pi.getAllTools().map((tool) => tool.name) : [];
+            if (registered.length > 0 && !capabilityInstalled(registered, capability)) {
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `${capability.label} is not installed in this session, so it cannot be restored. Continue without it.`,
+                        },
+                    ],
+                    details: { activated: false, capability: capability.id, installed: false },
+                };
+            }
+
+            if (!ctx.hasUI) {
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `${capability.label} stays withdrawn: restoring it needs an interactive user. Continue without it.`,
+                        },
+                    ],
+                    details: { activated: false, capability: capability.id, headless: true },
+                };
+            }
+
+            // A standing grant replaces the prompt, not the human: it records a decision this
+            // human already made, and only an interactive command can record one.
+            const standing = autoAllowed(capability.id);
+            const pending = missingTools(active, capability);
+            const accepted =
+                standing ||
+                (await ctx.ui.confirm(
+                    `Allow ${capability.label} for this session?`,
+                    `The agent asked to ${capability.summary}. Reason given: ${safeMessage(params.reason)}\n\nThis offers ${pending.length} tool${pending.length === 1 ? "" : "s"} for the rest of this session and adds ${capability.schemaCost}. Withdraw them again with ${capability.command} off.`,
+                ));
+            if (!accepted) {
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `The user declined ${capability.label}. Continue the task without it and do not ask again for this task.`,
+                        },
+                    ],
+                    details: { activated: false, capability: capability.id, declined: true },
+                };
+            }
+
+            activateCapability(capability.id);
+            // A standing grant skips the dialog, so say what happened; a capability must never
+            // turn itself on without the human seeing it.
+            if (standing) {
+                ctx.ui.notify(
+                    `${capability.label} offered to this session by a standing grant. Withdraw it with ${capability.command} off, or stop granting it with /capability ask ${capability.id}.`,
+                    "info",
+                );
+            }
+
+            return {
+                content: [
+                    {
+                        type: "text" as const,
+                        text: `${capability.label} is available from your next message: ${capability.tools.join(", ")}.`,
+                    },
+                ],
+                details: { activated: true, capability: capability.id, tools: [...capability.tools], standing },
+            };
+        },
+    });
+
+    pi.registerCommand("capability", {
+        description: "Show withdrawn tool groups, or stop being asked before granting one",
+        getArgumentCompletions: (prefix: string) =>
+            ["status", ...CAPABILITY_NAMES.flatMap((name) => [`allow ${name}`, `ask ${name}`])]
+                .filter((value) => value.startsWith(prefix.trim().toLowerCase()))
+                .map((value) => ({ value, label: value })),
+        handler: async (args: string, ctx: ExtensionContext) => {
+            const [action = "status", name, ...rest] = args.trim().split(/\s+/u).filter(Boolean);
+            const verb = action.toLowerCase();
+            if (rest.length || (name && verb === "status") || (!name && verb !== "status")) {
+                throw new Error(
+                    `Usage: /capability [status|allow <name>|ask <name>] (names: ${CAPABILITY_NAMES.join(", ")})`,
+                );
+            }
+
+            if (verb === "allow" || verb === "ask") {
+                const capability = findCapability(name);
+                if (!capability) {
+                    throw new Error(`Unknown capability. Names: ${CAPABILITY_NAMES.join(", ")}`);
+                }
+
+                // Recording a standing grant is the decision itself, so it needs a human at the
+                // keyboard exactly as the startup preferences do.
+                if (!ctx.hasUI) {
+                    throw new Error("Capability policy changes require a human interactive command");
+                }
+
+                if (verb === "allow") {
+                    allowCapability(capability.id);
+                    ctx.ui.notify(
+                        `${capability.label} will be offered whenever the agent asks for it, without a prompt. This session is unchanged until it asks. Undo with /capability ask ${capability.id}.`,
+                        "info",
+                    );
+
+                    return;
+                }
+
+                askCapability(capability.id);
+                ctx.ui.notify(
+                    `${capability.label} will prompt again before it is offered. Tools already offered to this session stay until ${capability.command} off.`,
+                    "info",
+                );
+
+                return;
+            }
+
+            if (verb !== "status") {
+                throw new Error(
+                    `Usage: /capability [status|allow <name>|ask <name>] (names: ${CAPABILITY_NAMES.join(", ")})`,
+                );
+            }
+
+            const active = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+            const granted = loadAutoAllowed();
+            const lines = CAPABILITY_NAMES.map((id) => {
+                const capability = findCapability(id)!;
+                const offered = capabilityActive(active, capability) ? "offered" : "withdrawn";
+
+                return `${id}: ${offered}, ${granted.includes(id) ? "granted without asking" : "asks first"}`;
+            });
+            ctx.ui.notify(`${lines.join(" · ")}. Policy: ${policyPath()}`, "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.26.0",
   "description": "Scope control and a human-selected harness improvement loop for Pi",
   "author": "Tanner Middleton",
   "repository": {

package/scripts/packages.mjs

@@ -19,7 +19,7 @@ export function runBrowserQA(agentDir, command) {
         const installed = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
         if (
             installed.name !== "specpi-browser-qa" ||
-            installed.version !== "0.2.0" ||
+            installed.version !== "0.3.0" ||
             installed.bin?.["specpi-browser-qa"] !== "./bin/browser-qa.mjs"
         ) {
             throw new Error("Missing or changed pinned Browser QA bin metadata");

package/scripts/specpi.mjs

@@ -37,6 +37,9 @@ 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/workflow-controls/capabilities.mjs",
+    "extensions/workflow-controls/capability-policy.mjs",
     "extensions/tool-wishlist/index.ts",
     "extensions/tool-wishlist/core.mjs",
     "extensions/tool-wishlist/verification.mjs",
@@ -469,7 +472,7 @@ async function doctor() {
     const errors = [];
     if (manifest.basePackages?.length) {
         errors.push(...checkBasePackages(agentDir, readJson(settingsPath, {})));
-        if (manifest.basePackages.includes("npm:specpi-browser-qa@0.2.0")) {
+        if (manifest.basePackages.includes("npm:specpi-browser-qa@0.3.0")) {
             try {
                 runBrowserQA(agentDir, "doctor");
             } catch (error) {

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 and Browser QA tools ship hidden to keep each request small. When the task genuinely needs one, call `request_capability`; it asks the human, who may decline. Continue without the capability if they do, and do not attempt a hidden tool. The human can also run `/webaccess on` or `/browser on` directly. Delegation is not requestable this way; ask the human to run `/delegate on`.
 - 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.

package/templates/settings.json

@@ -1,7 +1,7 @@
 {
     "packages": [
         "npm:pi-web-access@0.29.0",
-        "npm:specpi-browser-qa@0.2.0",
+        "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",