Attach: set ENABLE_TOOL_SEARCH=true so the gateway base URL doesn't force eager tool loading

Claude Code disables deferred tool loading whenever ANTHROPIC_BASE_URL is a
non-first-party host, sending every tool schema up front (~50k tokens of
per-session context bloat). The gateway is a pure pass-through that forwards
tool_reference blocks, so attach now sets ENABLE_TOOL_SEARCH=true to keep
deferred loading on.

Only manage the key when it is ours: a value the user set themselves is left
untouched and unrecorded, so detach never clobbers it. The core detach scopes
the prev_base_url restore to ANTHROPIC_BASE_URL only and removes any other
managed key, so it can't stamp the base URL onto ENABLE_TOOL_SEARCH.

Documents the rationale in LLP 0045.

Author: platypii

hypaware-core/plugins-workspace/claude/src/settings.js

@@ -96,20 +96,41 @@ export async function attach(opts) {
   const baseUrl = `http://127.0.0.1:${port}`
   const command = managedHookCommand(binPath, stateFile)
 
+  // Keep deferred tool loading on through the gateway. Claude Code turns it off
+  // whenever ANTHROPIC_BASE_URL is a non-first-party host - it assumes the proxy
+  // cannot forward `tool_reference` blocks and so sends every tool schema up
+  // front, tens of thousands of tokens of per-session context bloat. Our gateway
+  // is a pure pass-through that does forward them, so re-enable deferred loading
+  // with ENABLE_TOOL_SEARCH=true. Only manage the key when it is ours to manage:
+  // a value the user set themselves (and that a prior marker did not record as
+  // ours) is left untouched so detach never clobbers it, mirroring the
+  // back-up/restore rule for the base URL.
+  // @ref LLP 0045#enable_tool_search-keep-deferred-tool-loading-on-through-the-gateway [implements]: attach sets ENABLE_TOOL_SEARCH=true so the non-first-party base URL doesn't force eager tool-schema loading
+  const priorManagedEnv = priorMarker && isPlainObject(priorMarker.managed) && isPlainObject(priorMarker.managed.env)
+    ? /** @type {Record<string, unknown>} */ (priorMarker.managed.env)
+    : undefined
+  const weOwnToolSearch = priorManagedEnv ? 'ENABLE_TOOL_SEARCH' in priorManagedEnv : false
+  const manageToolSearch = weOwnToolSearch || typeof env.ENABLE_TOOL_SEARCH !== 'string'
+
   env.ANTHROPIC_BASE_URL = baseUrl
+  if (manageToolSearch) env.ENABLE_TOOL_SEARCH = 'true'
   installSessionContextHooks(value, command)
   // Self-describing undo record: enough for the format-aware core undo
-  // to restore-or-remove `env.ANTHROPIC_BASE_URL`, strip the managed
-  // hook entries, and delete the marker without loading this plugin —
-  // leaving no orphaned `hyp claude-hook` entries.
+  // to restore-or-remove `env.ANTHROPIC_BASE_URL`, remove the managed
+  // ENABLE_TOOL_SEARCH we added, strip the managed hook entries, and delete
+  // the marker without loading this plugin — leaving no orphaned
+  // `hyp claude-hook` entries.
   // @ref LLP 0045#part-3--reverse-runs-from-disk-the-marker-is-a-self-describing-undo-record [implements] — claude marker records prev_base_url + managed env/hook entries
   value[MARKER_KEY] = {
     attached_at: new Date().toISOString(),
     version,
     port,
     state_file: stateFile,
     managed: {
-      env: { ANTHROPIC_BASE_URL: baseUrl },
+      env: {
+        ANTHROPIC_BASE_URL: baseUrl,
+        ...(manageToolSearch ? { ENABLE_TOOL_SEARCH: 'true' } : {}),
+      },
       hooks: managedHookEntries(command),
     },
     ...(prevBaseUrl !== undefined ? { prev_base_url: prevBaseUrl } : {}),

llp/0045-client-attach.design.md

@@ -222,9 +222,10 @@ a self-describing undo record into its marker** — enough for a format-aware bu
 plugin-agnostic core routine to fully reverse:
 
 - **Claude (`json`):** the `_hypaware` marker records `prev_base_url` (the restore
-  target) plus the managed keys/hooks it added, so core can restore-or-remove
-  `env.ANTHROPIC_BASE_URL`, strip the managed `SessionStart`/… hook entries, and
-  delete the marker — leaving **no orphaned hooks** still pointing at
+  target) plus the managed env keys and hooks it added, so core can
+  restore-or-remove `env.ANTHROPIC_BASE_URL`, remove the managed
+  `ENABLE_TOOL_SEARCH` (see below), strip the managed `SessionStart`/… hook
+  entries, and delete the marker — leaving **no orphaned hooks** still pointing at
   `hyp claude-hook`. The backup is preserved idempotently across a re-attach:
   once we own the URL the current value is *our* gateway URL, so a re-attach keeps
   the marker's recorded original rather than overwriting it.
@@ -237,6 +238,32 @@ and how to replay an undo record, not "Claude" vs "Codex". The split is clean: a
 rich *write* (attach) needs the adapter (`ctx.clients`, Part 2); the *undo* is a
 marker-guided removal core does from disk.
 
+#### ENABLE_TOOL_SEARCH: keep deferred tool loading on through the gateway
+
+Pointing Claude Code at the gateway has a hidden cost. When `ANTHROPIC_BASE_URL`
+is a **non-first-party host**, Claude Code disables deferred (on-demand) tool
+loading by default — it assumes an arbitrary proxy cannot forward the
+`tool_reference` blocks that on-demand loading depends on, and instead sends
+**every tool schema up front**. With the full tool set that is tens of thousands
+of tokens of per-session context bloat, present on every request. The gateway
+itself is innocent: it is a pure pass-through that forwards `tool_reference`
+untouched; the switch is Claude Code's, keyed only on the base URL not being
+Anthropic's.
+
+So attach also writes `env.ENABLE_TOOL_SEARCH = "true"`, the documented override
+that re-enables deferred loading for proxies that do forward everything (ours
+does). Two rules keep this honest against the undo contract above:
+
+- **Only manage the key when it is ours.** If the user already set
+  `ENABLE_TOOL_SEARCH` themselves and no prior marker recorded it as ours, attach
+  leaves their value untouched and does **not** record it in `managed.env`. This
+  is the same never-clobber-a-user-value stance the base URL takes, minus a
+  backup: we only ever *add* the key when it was absent.
+- **`prev_base_url` restores the base URL only.** It is the sole managed key with
+  a backed-up prior. The undo therefore restores `ANTHROPIC_BASE_URL` to
+  `prev_base_url` but *removes* any other managed key (like `ENABLE_TOOL_SEARCH`)
+  rather than stamping the base URL onto it.
+
 **There is exactly one undo implementation, and it lives in core.** Both call
 sites use it — the reconciler's `reverse()` *and* the manual `hyp detach` command
 (`runClientLifecycle`'s detach branch routes through the core undo via the

src/core/config/client_detach_disk.js

@@ -154,13 +154,17 @@ async function detachJsonMarker({ settingsPath, markerKey, fs }) {
     for (const [key, ourVal] of Object.entries(managedEnv)) {
       const current = envObj[key]
       if (current === ourVal) {
-        // The value we wrote is still live: restore the recorded prior, or
-        // remove the key when the attach had no pre-existing value to back up.
-        if (prevBaseUrl !== undefined) {
+        // The value we wrote is still live. `prev_base_url` is the restore
+        // target for ANTHROPIC_BASE_URL only - it is the one managed key that
+        // backs up a pre-existing value. Every other managed key (e.g.
+        // ENABLE_TOOL_SEARCH) is one attach only ever added when it was absent,
+        // so it is removed, never restored. Applying prev_base_url to every key
+        // would wrongly stamp the base URL onto them.
+        if (key === 'ANTHROPIC_BASE_URL' && prevBaseUrl !== undefined) {
           envObj[key] = prevBaseUrl
           restoredValue = prevBaseUrl
         } else {
-          removed = typeof current === 'string' ? current : String(current)
+          if (key === 'ANTHROPIC_BASE_URL') removed = typeof current === 'string' ? current : String(current)
           delete envObj[key]
         }
       } else if (typeof current === 'string') {

test/core/client-detach-disk.test.js

@@ -112,6 +112,48 @@ test('claude undo of a no-pre-existing-URL attach round-trips to empty', async (
   }
 })
 
+test('claude undo removes managed ENABLE_TOOL_SEARCH without stamping the restored base URL onto it', async () => {
+  const home = await stageHome()
+  try {
+    // A pre-existing foreign base URL means prev_base_url is set. Detach must
+    // restore ANTHROPIC_BASE_URL to it *and* drop ENABLE_TOOL_SEARCH - never
+    // apply prev_base_url to the tool-search key.
+    const original = { env: { ANTHROPIC_BASE_URL: 'https://foreign.example/api' } }
+    const settingsPath = await writeClaudeSettings(home, JSON.stringify(original, null, 2) + '\n')
+    await claudeAttach({ ...ATTACH, settingsPath })
+
+    // Sanity: the fixture the adapter wrote actually set the tool-search key.
+    const attached = JSON.parse(await fs.readFile(settingsPath, 'utf8'))
+    assert.equal(attached.env.ENABLE_TOOL_SEARCH, 'true')
+
+    await detachClientFromDisk({ descriptor: CLAUDE_DESCRIPTOR, homeDir: home })
+
+    const parsed = JSON.parse(await fs.readFile(settingsPath, 'utf8'))
+    assert.equal(parsed.env.ANTHROPIC_BASE_URL, 'https://foreign.example/api')
+    assert.equal('ENABLE_TOOL_SEARCH' in parsed.env, false)
+  } finally {
+    await fs.rm(home, { recursive: true, force: true })
+  }
+})
+
+test('claude undo leaves a user-owned ENABLE_TOOL_SEARCH in place', async () => {
+  const home = await stageHome()
+  try {
+    // The user set ENABLE_TOOL_SEARCH themselves, so attach never managed it;
+    // detach must not remove it.
+    const original = { env: { ENABLE_TOOL_SEARCH: 'false' } }
+    const originalText = JSON.stringify(original, null, 2) + '\n'
+    const settingsPath = await writeClaudeSettings(home, originalText)
+    await claudeAttach({ ...ATTACH, settingsPath })
+
+    await detachClientFromDisk({ descriptor: CLAUDE_DESCRIPTOR, homeDir: home })
+
+    assert.equal(await fs.readFile(settingsPath, 'utf8'), originalText)
+  } finally {
+    await fs.rm(home, { recursive: true, force: true })
+  }
+})
+
 test('claude undo strips marker + managed keys/hooks from a hand-written fixture (no plugin loaded)', async () => {
   const home = await stageHome()
   try {

test/plugins/claude-settings-attach.test.js

@@ -42,10 +42,20 @@ test('attach records the managed env + hook entries into the marker undo record'
     const result = await attach({ ...ATTACH, settingsPath })
     assert.equal(result.changed, true)
 
+    // The gateway base URL is written live, and ENABLE_TOOL_SEARCH=true is set
+    // so the non-first-party base URL doesn't make Claude Code eager-load every
+    // tool schema.
+    const attached = JSON.parse(await fs.readFile(settingsPath, 'utf8'))
+    assert.equal(attached.env.ANTHROPIC_BASE_URL, 'http://127.0.0.1:4123')
+    assert.equal(attached.env.ENABLE_TOOL_SEARCH, 'true')
+
     const marker = await readMarker(settingsPath)
-    // Managed env value is the gateway URL we wrote — the core undo
-    // matches the live value against it before removing.
-    assert.deepEqual(marker.managed.env, { ANTHROPIC_BASE_URL: 'http://127.0.0.1:4123' })
+    // Managed env values are what we wrote — the core undo matches the live
+    // value against them before removing.
+    assert.deepEqual(marker.managed.env, {
+      ANTHROPIC_BASE_URL: 'http://127.0.0.1:4123',
+      ENABLE_TOOL_SEARCH: 'true',
+    })
 
     // Every managed hook spec is recorded with its command, and the
     // PostToolUse entry carries its matcher so the undo strips exactly
@@ -92,13 +102,57 @@ test('attach omits prev_base_url when there was no pre-existing base URL', async
     const marker = await readMarker(settingsPath)
     assert.equal('prev_base_url' in marker, false)
     // The managed undo record is still present so the core undo can
-    // remove (not restore) the gateway URL.
+    // remove (not restore) the gateway URL and ENABLE_TOOL_SEARCH.
+    assert.deepEqual(marker.managed.env, {
+      ANTHROPIC_BASE_URL: 'http://127.0.0.1:4123',
+      ENABLE_TOOL_SEARCH: 'true',
+    })
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('attach leaves a user-owned ENABLE_TOOL_SEARCH untouched and unmanaged', async () => {
+  const { dir, settingsPath } = await stage()
+  try {
+    await fs.writeFile(
+      settingsPath,
+      JSON.stringify({ env: { ENABLE_TOOL_SEARCH: 'false' } }, null, 2)
+    )
+
+    await attach({ ...ATTACH, settingsPath })
+
+    // The user's own value is respected, not overwritten, and it is not
+    // recorded as ours — so detach will never remove it.
+    const attached = JSON.parse(await fs.readFile(settingsPath, 'utf8'))
+    assert.equal(attached.env.ENABLE_TOOL_SEARCH, 'false')
+
+    const marker = await readMarker(settingsPath)
     assert.deepEqual(marker.managed.env, { ANTHROPIC_BASE_URL: 'http://127.0.0.1:4123' })
   } finally {
     await fs.rm(dir, { recursive: true, force: true })
   }
 })
 
+test('re-attach keeps managing an ENABLE_TOOL_SEARCH it owns', async () => {
+  const { dir, settingsPath } = await stage()
+  try {
+    await attach({ ...ATTACH, settingsPath })
+    // Our own 'true' is now live; the second attach must recognize it as ours
+    // (recorded in the prior marker) and keep managing it, not mistake it for a
+    // user value to leave alone.
+    await attach({ ...ATTACH, settingsPath })
+
+    const marker = await readMarker(settingsPath)
+    assert.deepEqual(marker.managed.env, {
+      ANTHROPIC_BASE_URL: 'http://127.0.0.1:4123',
+      ENABLE_TOOL_SEARCH: 'true',
+    })
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true })
+  }
+})
+
 test('idempotent re-attach keeps the original prev_base_url, not the gateway URL', async () => {
   const { dir, settingsPath } = await stage()
   try {