Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

cli: tell a Claude agent on a Local model, in words, that its built-in web tools are gone

Kelvin8983854a86b6
diff --git a/cli/src/lib/gridLaunch.spec.ts b/cli/src/lib/gridLaunch.spec.ts
index 3774be390..dd8cf40bf 100644
--- a/cli/src/lib/gridLaunch.spec.ts
+++ b/cli/src/lib/gridLaunch.spec.ts
@@ -103,8 +103,14 @@ describe('the launch each engine gets', () => {
ANTHROPIC_AUTH_TOKEN: WIRE.apiKey,
ANTHROPIC_MODEL: 'GLM-4.7-Flash',
},
- // The built-in web tools no grid can run — see "takes Claude Code's built-in web tools away".
- args: ['--disallowedTools=WebSearch,WebFetch'],
+ args: [
+ // The built-in web tools no grid can run — see "takes Claude Code's built-in web tools away".
+ '--disallowedTools=WebSearch,WebFetch',
+ // …and the words that tell the model so, delivered to a resumed conversation too — see "tells
+ // Claude Code in its system prompt".
+ '--system-prompt-snapshot', 'off',
+ '--append-system-prompt', expect.stringContaining('WebSearch'),
+ ],
// No MCP url in this override, so no web tools — and the app is told so.
webSearch: 'unavailable',
})
@@ -657,6 +663,61 @@ describe('web tools (grid ADR 0041)', () => {
expect(launchOf('claude', WITH_MCP).args).not.toContain('--disallowedTools=WebSearch')
})
+ it('tells Claude Code in its system prompt that the built-in web tools are gone — on every grid launch', () => {
+ // `--disallowedTools` empties the tool LIST of them, and the list is not the only place a model
+ // reads tool names from. A conversation moved onto a grid mid-way still carries the `WebSearch`
+ // turns it had on the Subscription model, and a model imitates those ahead of reading the list —
+ // seen on a real pane (2026-09-16, Claude Code 2.1.273, a DeepSeek model resumed after three
+ // `WebSearch` turns on Sonnet 5): one response carrying three `WebSearch` calls, each refused "No
+ // such tool available", before the next turn found `mcp__harness__web_search`. The list of that
+ // request had no `WebSearch` in it; the history did. So the prompt says so in words.
+ for (const override of [OVERRIDE, WITH_MODEL, WITH_MCP]) {
+ const args = launchOf('claude', override).args
+ const at = args.indexOf('--append-system-prompt')
+ expect(at, 'claude was not given --append-system-prompt').toBeGreaterThanOrEqual(0)
+ const prompt = args[at + 1] as string
+ expect(prompt).toContain('WebSearch')
+ expect(prompt).toContain('WebFetch')
+ // Earlier turns are the whole problem, so the text names them rather than leaving the model to
+ // weigh a tool list against a history that contradicts it.
+ expect(prompt).toMatch(/earlier turns/)
+ // Principle 4 of the plan: a model narrates its system prompt back to the user ("WebSearch got
+ // disabled mid-session. I'll use the harness web search tool instead."), so "grid" is not in it.
+ expect(prompt.toLowerCase()).not.toContain('grid')
+ }
+ })
+
+ it('makes that prompt reach a conversation the agent was already in the middle of', () => {
+ // Claude Code records the system prompt on a conversation's first request and replays the record
+ // on every later request and resume, "even when a later launch passes different text"
+ // (`--system-prompt-snapshot`, default `on`, 2.1.273). Measured 2026-09-16 on a resumed session:
+ // with `--append-system-prompt` alone the model never saw the text and no new record was written;
+ // with `--system-prompt-snapshot off` on the same launch it did — and a later launch WITHOUT the
+ // flag (the move back to the Subscription model) replayed the original record, so nothing said
+ // on the grid follows the agent off it. A move onto a grid is nearly always such a resume.
+ for (const override of [OVERRIDE, WITH_MODEL, WITH_MCP]) {
+ const args = launchOf('claude', override).args
+ const at = args.indexOf('--system-prompt-snapshot')
+ expect(at, 'claude was not given --system-prompt-snapshot').toBeGreaterThanOrEqual(0)
+ expect(args[at + 1]).toBe('off')
+ }
+ })
+
+ it('points the prompt at the harness tools only when they were wired', () => {
+ const promptOf = (override: GridLaunchOverride): string => {
+ const args = launchOf('claude', override).args
+ return args[args.indexOf('--append-system-prompt') + 1] as string
+ }
+ // With a server: name the replacements, so the model has somewhere to go.
+ expect(promptOf(WITH_MCP)).toContain('mcp__harness__web_search')
+ expect(promptOf(WITH_MCP)).toContain('mcp__harness__web_read')
+ // Without one — a degraded launch, or an older desktop — naming a tool the model was not given
+ // would send it down the same road as the dead one, so the prompt says there are no web tools.
+ expect(promptOf(WITH_MODEL)).not.toContain('mcp__harness__')
+ expect(promptOf(WITH_MODEL)).toMatch(/no web tools/)
+
+ })
+
it("pre-approves the harness web tools for Claude Code, so a permission mode cannot take them away", () => {
// The tools are the daemon's own gift to the agent, and Claude Code's permission system does not
// know that: in `default` mode every call prompts, and in `auto` mode the classifier DENIED
@@ -682,9 +743,14 @@ describe('web tools (grid ADR 0041)', () => {
})
it('adds no web tools when the desktop sends no mcpUrl', () => {
- // An older desktop, and the no-regression promise: no server it did not ask for. Claude's one flag
- // is not a web tool but the removal of one no grid can run — see the test above.
- expect(launchOf('claude', WITH_MODEL).args).toEqual(['--disallowedTools=WebSearch,WebFetch'])
+ // An older desktop, and the no-regression promise: no server it did not ask for. Claude's flags
+ // are not web tools but the removal of two no grid can run, and the words that say so — with no
+ // replacement named, since none was wired. See the tests above.
+ expect(launchOf('claude', WITH_MODEL).args).toEqual([
+ '--disallowedTools=WebSearch,WebFetch',
+ '--system-prompt-snapshot', 'off',
+ '--append-system-prompt', expect.not.stringContaining('mcp__harness__'),
+ ])
expect(launchOf('claude', WITH_MODEL).env.GRID_API_KEY).toBeUndefined()
expect(launchOf('grok', WITH_MODEL).configDir!.files[0]!.content).not.toContain('mcp_servers')
expect(launchOf('copilot', WITH_MODEL).args).toEqual([])
diff --git a/cli/src/lib/gridLaunch.ts b/cli/src/lib/gridLaunch.ts
index d0f95be0b..4b92dec04 100644
--- a/cli/src/lib/gridLaunch.ts
+++ b/cli/src/lib/gridLaunch.ts
@@ -48,6 +48,7 @@ import type { AgentEngine } from '../engines/types.js'
import {
CLAUDE_ALLOW_WEB_TOOLS_ARG,
CLAUDE_DISALLOW_WEB_TOOLS_ARG,
+ claudeGridPromptArgs,
CODEX_DISABLE_WEB_SEARCH_ARGS,
mcpServersConfig,
codexMcpArgs,
@@ -559,35 +560,43 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
// The grid CLI's own launch target (`autonomous-grid/shared/launch/claude.py`), so these are the
// vendor's names as that team verified them rather than this repo's reading of them.
claude: {
- build: (override) => ({
- env: {
- ANTHROPIC_BASE_URL: anthropicBaseUrl(override.baseUrl),
- // The bearer variable, and ONLY it. Claude Code warns when ANTHROPIC_AUTH_TOKEN and
- // ANTHROPIC_API_KEY are both set, and the relay prefers the Bearer header anyway — so
- // ANTHROPIC_API_KEY would decide nothing, while colliding with the variable a user's own
- // Anthropic key lives in.
- ANTHROPIC_AUTH_TOKEN: override.apiKey,
- // `grid launch claude` deliberately sets no model variable, on the grounds that a launcher
- // has no standing to choose a user's model. That reasoning does not carry here: the desktop
- // app ASKED, and this is the answer. Left unset when the user picked no model.
- ...(override.model ? { ANTHROPIC_MODEL: override.model } : {}),
- // Only when there are web tools to reach: the variable exists to be referenced by the config
- // below, and setting it otherwise would leave a key in the pane that nothing reads.
- ...(override.mcpUrl ? { [GRID_KEY_VAR]: override.apiKey } : {}),
- },
- args: [
- // On every grid launch, web tools or not: the built-in search is an Anthropic server tool
- // that no grid runs, and the built-in fetch summarises through a model the grid does not
- // serve. See `CLAUDE_DISALLOW_WEB_TOOLS_ARG`.
- CLAUDE_DISALLOW_WEB_TOOLS_ARG,
- // With the server comes its approval: a tool the daemon wired in and a permission mode then
- // refuses is worse than no tool at all. See `CLAUDE_ALLOW_WEB_TOOLS_ARG`.
- ...(override.mcpUrl
- ? ['--mcp-config', mcpServersConfig(override.mcpUrl, GRID_KEY_VAR), CLAUDE_ALLOW_WEB_TOOLS_ARG]
- : []),
- ],
- webSearch: webSearchWhenWired(override),
- }),
+ build: (override) => {
+ const webSearch = webSearchWhenWired(override)
+ return {
+ env: {
+ ANTHROPIC_BASE_URL: anthropicBaseUrl(override.baseUrl),
+ // The bearer variable, and ONLY it. Claude Code warns when ANTHROPIC_AUTH_TOKEN and
+ // ANTHROPIC_API_KEY are both set, and the relay prefers the Bearer header anyway — so
+ // ANTHROPIC_API_KEY would decide nothing, while colliding with the variable a user's own
+ // Anthropic key lives in.
+ ANTHROPIC_AUTH_TOKEN: override.apiKey,
+ // `grid launch claude` deliberately sets no model variable, on the grounds that a launcher
+ // has no standing to choose a user's model. That reasoning does not carry here: the desktop
+ // app ASKED, and this is the answer. Left unset when the user picked no model.
+ ...(override.model ? { ANTHROPIC_MODEL: override.model } : {}),
+ // Only when there are web tools to reach: the variable exists to be referenced by the config
+ // below, and setting it otherwise would leave a key in the pane that nothing reads.
+ ...(override.mcpUrl ? { [GRID_KEY_VAR]: override.apiKey } : {}),
+ },
+ args: [
+ // On every grid launch, web tools or not: the built-in search is an Anthropic server tool
+ // that no grid runs, and the built-in fetch summarises through a model the grid does not
+ // serve. See `CLAUDE_DISALLOW_WEB_TOOLS_ARG`.
+ CLAUDE_DISALLOW_WEB_TOOLS_ARG,
+ // With the server comes its approval: a tool the daemon wired in and a permission mode then
+ // refuses is worse than no tool at all. See `CLAUDE_ALLOW_WEB_TOOLS_ARG`.
+ ...(override.mcpUrl
+ ? ['--mcp-config', mcpServersConfig(override.mcpUrl, GRID_KEY_VAR), CLAUDE_ALLOW_WEB_TOOLS_ARG]
+ : []),
+ // And the words. An agent moved here mid-conversation reads `WebSearch` off its own history
+ // before it reads the list, so the prompt names what is gone and — when one was wired — what
+ // replaces it, delivered past the recorded prompt a resume would otherwise replay. See
+ // `claudeGridPromptArgs`.
+ ...claudeGridPromptArgs(webSearch === 'on'),
+ ],
+ webSearch,
+ }
+ },
},
// Codex configures its provider entirely on the command line — `-c key=value` overrides anything
diff --git a/cli/src/lib/gridWebMcp.ts b/cli/src/lib/gridWebMcp.ts
index 56f0991f0..9cdb6086e 100644
--- a/cli/src/lib/gridWebMcp.ts
+++ b/cli/src/lib/gridWebMcp.ts
@@ -43,7 +43,12 @@
* authentication with nothing naming why.
*/
-import { HARNESS_MCP_SERVER_NAME, HARNESS_MCP_TOOL_NAMES } from './harnessWebTools.js'
+import {
+ HARNESS_MCP_SERVER_NAME,
+ HARNESS_MCP_TOOL_NAMES,
+ HARNESS_WEB_READ_TOOL_NAME,
+ HARNESS_WEB_SEARCH_TOOL_NAME,
+} from './harnessWebTools.js'
/**
* The variable Codex reads its header out of.
@@ -148,6 +153,72 @@ export const CLAUDE_DISALLOW_WEB_TOOLS_ARG = '--disallowedTools=WebSearch,WebFet
*/
export const CLAUDE_ALLOW_WEB_TOOLS_ARG = `--allowedTools=${HARNESS_MCP_TOOL_NAMES.join(',')}`
+/**
+ * What a Claude Code agent on a grid is told about the web in its system prompt, and the flag that
+ * makes Claude Code deliver it to a conversation already under way.
+ *
+ * [CLAUDE_DISALLOW_WEB_TOOLS_ARG] takes `WebSearch` and `WebFetch` out of the tool LIST, and the list
+ * is not the only place a model reads tool names from. An agent is moved onto a grid mid-conversation
+ * far more often than launched onto one, and the conversation it resumes carries every turn it had
+ * on the Subscription model — `WebSearch` calls that SUCCEEDED, results and all. A model imitates
+ * those ahead of reading the list. Seen on a real pane (2026-09-16, Claude Code 2.1.273,
+ * `deepseek/deepseek-v4-flash-0731` resumed after three `WebSearch` turns on Sonnet 5): the first
+ * response carried three `WebSearch` calls, each refused "No such tool available: WebSearch", and
+ * only the next turn reached for `mcp__harness__web_search`. That request's tool list had no
+ * `WebSearch` in it — read off the transcript's own `prompt_snapshot` record; the history did.
+ *
+ * So the prompt says it in words: which tools are gone, that earlier turns are no evidence they are
+ * back, and what to call instead. Words lower the odds; they cannot make them zero, because the
+ * history is exactly what `--resume` exists to keep. The only zero is a history that never held
+ * `WebSearch` — routing the Subscription model's web through this server too — and that is a product
+ * decision, not this module's.
+ *
+ * ⚠️ **`--append-system-prompt` alone never reaches a resumed conversation.** Claude Code records
+ * the system prompt on a conversation's first request and replays that record on every later request
+ * and resume, "even when a later launch passes different text" (`--system-prompt-snapshot`, default
+ * `on`, `claude --help` 2.1.273). Measured 2026-09-16 on a session resumed with
+ * `--append-system-prompt` carrying a marker: the model answered that no marker was present and no
+ * new record was written; with `--system-prompt-snapshot off` on the same launch it answered with
+ * the marker. A later launch WITHOUT the flag — the move back to the Subscription model — replayed
+ * the original record, so nothing said here follows the agent off the grid. `off` gives up the
+ * prompt's cache stability, which a grid relay does not offer anyway: `cache_read_input_tokens` was
+ * 0 on every grid response in that transcript.
+ *
+ * Two texts, because a degraded launch (no MCP url) has nothing to point at: naming a tool the model
+ * was not given would send it down the same road as the dead one. Neither says "grid" — a model
+ * narrates its system prompt back to the user ("WebSearch got disabled mid-session. I'll use the
+ * harness web search tool instead."), and the user's vocabulary is "Subscription" and "Local".
+ *
+ * Two tokens each, unlike the tool-list flags above: `<prompt>` and `<on|off>` take exactly one
+ * value, so nothing after them can be swallowed — and the two-token form is the one measured. Argv is
+ * positional all the way to `exec "$@"` (`engineLaunch.ts`), so the spaces and backticks in the text
+ * never meet a shell.
+ */
+export const CLAUDE_SYSTEM_PROMPT_SNAPSHOT_OFF_ARGS: readonly string[] = ['--system-prompt-snapshot', 'off']
+
+/** The sentence both texts share: the tools, the history, and the instruction. */
+const CLAUDE_WEB_TOOLS_GONE = 'The built-in `WebSearch` and `WebFetch` tools are not available in this session, '
+ + 'even where earlier turns of this conversation used them — do not call them'
+
+function claudeGridSystemPrompt(webToolsWired: boolean): string {
+ if (!webToolsWired) {
+ return `This session has no web tools. ${CLAUDE_WEB_TOOLS_GONE}; `
+ + 'tell the user the web cannot be searched or read from here instead.'
+ }
+ return `Web tools in this session come from the \`${HARNESS_MCP_SERVER_NAME}\` MCP server only: `
+ + `\`${HARNESS_WEB_SEARCH_TOOL_NAME}\` searches the web and \`${HARNESS_WEB_READ_TOOL_NAME}\` reads pages. `
+ + `${CLAUDE_WEB_TOOLS_GONE}; call the \`${HARNESS_MCP_SERVER_NAME}\` tools instead.`
+}
+
+/**
+ * The prompt for a Claude Code grid launch, and the flag that lets it through — see
+ * [CLAUDE_SYSTEM_PROMPT_SNAPSHOT_OFF_ARGS]. [webToolsWired] is whether the launch carries the server
+ * (`webSearch: 'on'`), so the text and the status the app shows cannot disagree.
+ */
+export function claudeGridPromptArgs(webToolsWired: boolean): string[] {
+ return [...CLAUDE_SYSTEM_PROMPT_SNAPSHOT_OFF_ARGS, '--append-system-prompt', claudeGridSystemPrompt(webToolsWired)]
+}
+
/**
* Codex's native `web_search`, turned off on every Codex agent launched onto a grid.
*
diff --git a/cli/src/lib/harnessWebTools.ts b/cli/src/lib/harnessWebTools.ts
index c03ca9eba..b971f3e42 100644
--- a/cli/src/lib/harnessWebTools.ts
+++ b/cli/src/lib/harnessWebTools.ts
@@ -32,12 +32,18 @@ const WEB_READ_TOOL = 'web_read'
*/
const mcpToolName = (tool: string): string => `mcp__${HARNESS_MCP_SERVER_NAME}__${tool}`
+/** `mcp__harness__web_search` — the name a Claude Code or Codex agent calls, and is told to call. */
+export const HARNESS_WEB_SEARCH_TOOL_NAME = mcpToolName(WEB_SEARCH_TOOL)
+
+/** `mcp__harness__web_read`, likewise. */
+export const HARNESS_WEB_READ_TOOL_NAME = mcpToolName(WEB_READ_TOOL)
+
/**
* The server's tools as an engine names them — the list a launch pre-approves. Exactly the two the
* control plane serves, by name rather than as a server-wide `mcp__harness` rule: a tool the server
* grows later is one nobody here has looked at, and it should prompt like any other.
*/
-export const HARNESS_MCP_TOOL_NAMES: readonly string[] = [mcpToolName(WEB_SEARCH_TOOL), mcpToolName(WEB_READ_TOOL)]
+export const HARNESS_MCP_TOOL_NAMES: readonly string[] = [HARNESS_WEB_SEARCH_TOOL_NAME, HARNESS_WEB_READ_TOOL_NAME]
/** The canonical card the desktop and web already render, and the input shape it reads. */
export interface HarnessWebToolCard {
@@ -47,8 +53,8 @@ export interface HarnessWebToolCard {
/** Which native card a tool name from this server maps to, or null for any other tool. */
export function harnessWebToolKind(name: string | undefined): HarnessWebToolCard['tool'] | null {
- if (name === mcpToolName(WEB_SEARCH_TOOL)) return 'WebSearch'
- if (name === mcpToolName(WEB_READ_TOOL)) return 'WebFetch'
+ if (name === HARNESS_WEB_SEARCH_TOOL_NAME) return 'WebSearch'
+ if (name === HARNESS_WEB_READ_TOOL_NAME) return 'WebFetch'
return null
}
diff --git a/docs/plans/2026-09-15-005-harness-grid-websearch-plan.md b/docs/plans/2026-09-15-005-harness-grid-websearch-plan.md
index e0cdbbd4c..737a96feb 100644
--- a/docs/plans/2026-09-15-005-harness-grid-websearch-plan.md
+++ b/docs/plans/2026-09-15-005-harness-grid-websearch-plan.md
@@ -233,6 +233,50 @@ harness cannot intercept. No client detection, no per-client text.
---
+## Change 7 — the words (added 2026-09-16, after the first end-to-end run)
+
+`cli/src/lib/gridWebMcp.ts`, `cli/src/lib/gridLaunch.ts`, `gridLaunch.spec.ts`; grid-apis
+`web_mcp.py`, `tests/test_web_mcp.py`.
+
+**What the run showed.** Change 2 removes `WebSearch`/`WebFetch` from the tool *list*, and the list
+is not the only place a model reads tool names from. An agent moved to a Local model mid-conversation
+resumes with every turn it had on the Subscription model, `WebSearch` calls that succeeded included,
+and a model imitates those ahead of reading the list. Session `1768dbeb…` (Claude Code 2.1.273,
+`deepseek/deepseek-v4-flash-0731` resumed after three `WebSearch` turns on Sonnet 5): the request's
+tool list had no `WebSearch` — read off the transcript's `prompt_snapshot` — and the first response
+still carried three `WebSearch` calls, each refused "No such tool available", before the next turn
+found `mcp__harness__web_search`. One wasted turn; Claude Code's refusal is local and costs no
+request.
+
+**Two mitigations, neither a guarantee.** The history is what `--resume` exists to keep, so words can
+lower the odds and not zero them. Zero would need a history that never held `WebSearch` — routing the
+Subscription model's web through `harness` too — which is a product decision this plan does not take.
+
+1. **Claude Code's system prompt, on every Local launch** (`claudeGridPromptArgs`): which tools are
+ gone, that earlier turns are no evidence they are back, and — only when the server was wired —
+ what to call instead. No "grid" in it: a model narrates its prompt back to the user.
+ ⚠️ **`--append-system-prompt` alone does not reach a resumed conversation.** Claude Code records
+ the system prompt on a conversation's first request and replays the record on every later request
+ and resume, "even when a later launch passes different text" (`--system-prompt-snapshot`, default
+ `on`). Measured 2026-09-16 on a resumed session: without `--system-prompt-snapshot off` the model
+ never saw the text and no new record was written; with it, it did; and a later launch without the
+ flag — the move back to Subscription — replayed the original record, so nothing said on the Local
+ model follows the agent off it. `off` gives up prompt-cache stability the relay does not offer
+ anyway (`cache_read_input_tokens: 0` on every Local response in that transcript).
+2. **The tool descriptions on the control plane** name the built-in tools they stand in for —
+ Claude Code's `WebSearch`/`WebFetch`, the `web_search` built into Codex — and say opencode's
+ `websearch`/`webfetch` keep working (they never go through the model vendor). A description rides
+ in the `tools` array of every request, so unlike a system prompt it survives a resume; it is the
+ only text that reaches Codex too. Still no product name (the Change 6 test holds).
+
+| Q | Decision |
+|---|---|
+| Q21 | Words on every Claude Local launch, both variants; `--system-prompt-snapshot off` alongside |
+| Q22 | Descriptions name the dead built-ins precisely, per harness, and name opencode's as alive |
+| Q23 | Not taken: routing Subscription web through `harness` (the only zero); rewriting the transcript before `--resume`; a `PreToolUse` hook (cannot fire for a tool that is not offered) |
+
+---
+
## Failure modes
| Condition | Where | What happens |