Attach declares the gateway first-party so Claude keeps its real context window

[philcunliffe]

Problem

With Claude Code attached to the HypAware gateway, a fresh session reports ~18% context after a one-word prompt; detached, the same setup reports ~4%.

The tokens are not the problem. Claude Code grants a native-1M model its 1M context window only when the ANTHROPIC_BASE_URL host is api.anthropic.com (or _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL is set). Behind any proxy it assumes 200k, so the same ~40k of startup context reads as 18% instead of 4%. It is not only cosmetic: context warnings and auto-compact fire against the wrong denominator and trigger far too early.

Root cause

The claude attach writer (hypaware-core/plugins-workspace/claude/src/settings.js) already compensates for one non-first-party default (ENABLE_TOOL_SEARCH, LLP 0045) but not for the assumed-window one, so pointing settings at http://127.0.0.1:<port> silently cuts the assumed window.

Fix

Attach also writes env._CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL = "1", under the same ownership rule as ENABLE_TOOL_SEARCH:

• only ever added when absent, or when a prior _hypaware marker recorded it as ours (so a re-attach keeps owning it),
• recorded in managed.env so the single core undo (detachClientFromDisk) removes exactly what attach added,
• a value the user set themselves is left untouched and stays out of the undo record.

The declaration is accurate: the gateway is a byte-transparent pass-through to api.anthropic.com, which is what the flag asserts, so the other first-party gating it flips (traceparent propagation, the context-1m beta header, an extended usage-limit header, and Anthropic-direct channels like error reporting, org policy limits, and memory-sync eligibility) is correct rather than a tolerated side effect. It does not gate credential choice: the oauth beta header and bearer/API-key selection ride the active session independent of this flag, so the declaration sends no secret anywhere it was not already going. (Corrected post-review: an earlier version of this line claimed the flag also gates "oauth beta headers", which round 2 of review found false; the code comment and LLP 0045 were fixed then, this body line is fixed here as part of triage.)

The two managed env additions are now one MANAGED_ENV_ADDITIONS table plus a single manageEnvAdditions ownership helper, so a third key cannot drift from the undo record.

LLP 0045 Part 3 gains the matching section (with the @ref from the code), including the honest caveat: the key is underscore-prefixed and undocumented (last verified against Claude Code 2.1.220), it fails soft, and the mitigation is to re-verify it if attached sessions start reporting an inflated percent again. The rejected alternative ([1m] model-name suffix) is recorded there too.

Tests

Regression tests fail on master and pass with the fix:

• test/plugins/claude-settings-attach.test.js
  • attach writes env._CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL = "1" and records it in the marker undo record
  • a user-owned value is left untouched and stays unmanaged
  • a re-attach keeps managing the key it owns
  • the existing managed-env assertions updated to the new managed set
• test/core/client-detach-disk.test.js
  • the core disk undo removes the managed key and does not stamp the restored base URL onto it

Verified failing-then-passing: on the pre-fix source these run 7 failures across the two files; with the fix, 31/31 pass.

Local checks

• npm test: 2796 pass, 8 pre-existing failures in test/core/leave-command.test.js that fail identically on unmodified master in this environment (environment-dependent, unrelated to this change).
• npm run typecheck: clean.
• npm run smoke -- claude_attach_detach fails on this branch and on unmodified master (pre-existing, on the SessionStart hook assertion), so it is not a regression from this change.

Note

Already-attached machines pick the key up on the next attach (re-attach on endpoint drift, rejoin, or a manual hyp attach); this change does not rewrite existing settings on its own.

Fixes#437

[philcunliffe]

Verdict: approve after the two fixes pushed below (8f8b5da)

The change is correct. The ownership refactor is behaviour-preserving for ENABLE_TOOL_SEARCH, detach removes exactly what attach added, and the regression tests genuinely fail without the fix. Two findings, both Low, both fixed on the branch. Nothing blocking.

What I verified (not just read)

1. The refactor did not silently change the pre-existing ENABLE_TOOL_SEARCH path. The old predicate was weOwnToolSearch || typeof env.ENABLE_TOOL_SEARCH !== 'string'; the new one skips on !weOwnIt && typeof env[key] === 'string'. Those are the same condition. The three unchanged ENABLE_TOOL_SEARCH behaviour assertions (test/plugins/claude-settings-attach.test.js:143, test/core/client-detach-disk.test.js:133, test/core/client-detach-disk.test.js:162) still pass untouched.

2. The env-ownership logic is sound. Attach adds a key only when absent or when the prior marker recorded it (hypaware-core/plugins-workspace/claude/src/settings.js:184-192); a user-set string is skipped and kept out of managed.env, so the generic core undo (src/core/config/client_detach_disk.js:163-183) never sees it. Detach removes a managed key only while the live value still equals what we wrote, restores prev_base_url for ANTHROPIC_BASE_URL only, and warns-and-leaves on an external override. I looked specifically for the strand/clobber cases and found none:

• user owns the key, then re-attach: still skipped, still unmanaged (test at :194)
• we own it, user deletes it, re-attach: re-added, still ours
• prior marker from the pre-PR version (no _CLAUDE_… recorded): weOwnIt false, user value respected
• manageEnvAdditions now runs beforeenv.ANTHROPIC_BASE_URL = baseUrl, but the table contains neither that key nor anything the base URL touches, so the reorder is inert.

3. The tests have teeth. On the pre-fix settings.js with the new tests: 7 failures / 31. With the fix: 31/31. I also mutation-tested the ownership guard — deleting the typeof env[key] === 'string' line makes both "leaves a user-owned … untouched and unmanaged" tests fail. So they are real regression tests, not constant assertions. (Note test/plugins/claude-settings-attach.test.js:194 passes vacuously on master, which is expected for a negative guard; the mutation test above is what proves it guards something.)

4. The @ref anchor resolves.LLP 0045#_claude_code_assume_first_party_base_url-keep-the-models-real-context-window matches the heading added at llp/0045-client-attach.design.md:270. The LLP section is honest about the flag: underscore-prefixed, undocumented, version-stamped (2.1.220), fail-soft, with the rejected [1m] alternative and an upstream tracking link recorded.

5. No other site enumerates the managed env keys. Grepped ENABLE_TOOL_SEARCH repo-wide: only this writer, the core undo's explanatory comment, the LLP, and tests. No drift-detection or status surface needed updating alongside.

6. npm test in a clean worktree: 2796 pass / 8 fail, and the 8 are the test/core/leave-command.test.js failures unrelated to these files (they fail on the central-config-layer teardown exit code). Identical before and after my fixes.

Findings

[Low] hypaware-core/plugins-workspace/claude/src/settings.js:144 — added line reintroduced a U+2014 em dash. The undo-record comment was rewritten by this PR and the rewritten line carries — leaving no orphaned …. CLAUDE.md forbids em dashes "anywhere: code, comments, JSDoc, strings, or docs". Fixed in 8f8b5da: replaced with a comma. I deliberately left the four pre-existing em dashes in that file (lines 16, 24, 123, 148) alone — out of scope for this PR.

[Low] llp/0045-client-attach.design.md:284-288 — the "declaration is accurate" claim is stated as unconditional, but it depends on config this code cannot see. This is the one substantive point, and it is the difference between the two keys in the table:

• ENABLE_TOOL_SEARCH asserts a property of the gateway (it forwards tool_reference untouched). Always true.
• _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL asserts a property of whatever the gateway forwards to. That is ordinary config: upstreams[].base_url is a free-form validated string (hypaware-core/plugins-workspace/ai-gateway/src/config.js:47), and https://api.anthropic.com is merely what the hyp init preset writes (hypaware-core/plugins-workspace/claude/src/index.js:358).

Attach writes the declaration unconditionally — attach(opts) only has port/version/stateFile/settingsPath/binPath in scope, not the gateway's upstream config — so an operator or org config that repoints that upstream makes the declaration false, and the other first-party behaviour the LLP says the flag gates (traceparent propagation, oauth beta headers) then applies to traffic that never reaches Anthropic.

I do not think the settings writer should police this; plumbing upstream config into it would be a real design change and is disproportionate. But the LLP asserting accuracy flatly leaves the assumption implicit. Fixed in 8f8b5da by recording it as a stated precondition: a paragraph in LLP 0045 Part 3 (llp/0045-client-attach.design.md:290) and a three-line note at MANAGED_ENV_ADDITIONS so the code and the doc agree.

Not findings, recorded so the next reviewer does not re-derive them

• Re-attach overwrites a value the user changed on a key we own (e.g. user sets ENABLE_TOOL_SEARCH=false while attached; the next attach restores true). Pre-existing and documented as "a re-attach keeps owning it" — this PR extends it to a second key without changing the rule.
• Downgrade orphans the key. Attach with this version, downgrade, re-attach: the old writer's marker drops _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL from managed.env while the key stays live, so a later detach strands it. Inherent to adding any managed key; downgrade is not a supported path.
• key in priorManagedEnv walks the prototype chain. Harmless — neither table key exists on Object.prototype, and JSON.parse will not set one. Pre-existing form.
• Key order in the user's settings.json shifts on a first attach (added keys now land before ANTHROPIC_BASE_URL). Cosmetic; left alone rather than churn the diff.

Pushed

2edd315..8f8b5da on fix/issue-437. Both fixes are comment/doc only — no behaviour change, no test change. Verified in the committed tree: the em dash is gone from settings.js:144, and llp/0045-client-attach.design.md:290 contains the new precondition paragraph. npm test after the fixes is byte-identical in outcome to before (2796 pass, same 8 unrelated failures).

[philcunliffe]

Neutral review, round 2 of 2 (final)

Head reviewed:8f8b5da9edf81a54d2794443067d7a191f240cb6
Verdict: approve with one finding, fixed in-round. New head after fix: baaaa382a9a765355955401eeffa01bbe995dd02.

Round 1 record: #438 (comment)

---

Round 1's own two fixes: both verified correct and complete

1. Em dash.git diff origin/master...8f8b5da has zero U+2014 in any added line. hypaware-core/plugins-workspace/claude/src/settings.js:147 now reads loading this plugin, leaving no orphaned .... The em dashes still present in the touched files (settings.js:16,24,123,148, most of llp/0045) are all unchanged pre-existing lines, so the rule is satisfied for this diff. Complete.

2. The LLP precondition wording matches what the code does. Checked against the code rather than taken on trust:

   • attach(opts) destructures { port, version, stateFile, settingsPath, binPath } only (settings.js:109). No upstream config is in scope, exactly as LLP 0045 states.
   • hyp init writes upstreams: [{ name: 'anthropic', base_url: 'https://api.anthropic.com', path_prefix: '/' }] as ordinary user-editable config (hypaware-core/plugins-workspace/claude/src/index.js:355-360). The gateway_upstream manifest contribution (hypaware-core/plugins-workspace/claude/hypaware.plugin.json:43) is consumed only by the walkthrough proposal path (src/core/cli/walkthrough.js:645-649); nothing pins the host at runtime.

   So "precondition, not invariant" is accurate. Accepted.

---

The substantive open question, judged independently

Round 1 left the unconditional first-party declaration as a documented precondition rather than a code check. I reach the same disposition, but on evidence rather than deference, and the PR's justification for it was partly wrong.

I read the predicate off the shipped Claude Code bundle installed in this environment (/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe, 2.1.215):

functionNd(){if(Z._CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL)return!0;returnGUn()}functionGUn(){lete=process.env.ANTHROPIC_BASE_URL;if(!e)return!0;returntPe(e)}functiontPe(e){try{lett=newURL(e).host;return["api.anthropic.com"].includes(t)}catch{return!1}}

The env var is one branch of a single is-first-party predicate. What it gates:

effect	evidence
native-1M window + context-1m-2025-08-07 beta (this PR's purpose)	`if(n==="firstParty"&&Nd()
ENABLE_TOOL_SEARCH optimistic default	if(!process.env.ENABLE_TOOL_SEARCH&&vn()==="firstParty"&&!Nd())
traceparent propagation	`function a1r(){return Nd()
anthropic-usage-limit: extended header	...&&vn()==="firstParty"&&Nd()&&et("tengu_lantern_spool",!1))zo["anthropic-usage-limit"]="extended"
error reporting to Anthropic	`function $Gc(){...if(vn()!=="firstParty"
org policy-limits fetch (and the permission defaults it feeds)	mFr() returns "custom_base_url" when !Nd(); D9(){return mFr()===void 0} gates the ${BASE_API_URL}/api/claude_code... fetch and Qi()
memory-sync eligibility	function vXh(){if(!Nd())return!1;...}

The PR's stated justification is wrong on one item. The code comment, LLP 0045 and the PR body all said the flag gates "traceparent propagation, oauth beta headers". It does not gate oauth beta headers. The beta list builder pushes $et = DT("oauth_auth","oauth-2025-04-20") on qo() (an active OAuth session), not on Nd():

if(qo()||oGn()&&!u1r()&&CH())t.push($et);

and the auth-header resolver wq() picks Authorization: Bearer <accessToken> / x-api-key from qo() / Ahe() without consulting Nd() at all.

Why that makes the precondition proportionate rather than a security problem. Because credential choice is not gated, the flag sends no secret to any host it was not already going to reach. Attach has already pointed ANTHROPIC_BASE_URL at the local gateway, and the gateway already forwards to whatever upstreams[].base_url says; that forwarding decision, credentials included, is made by the operator's config, not by this flag. If base_url is repointed at a non-Anthropic host, the extra traffic that host receives is a traceparent, an anthropic-usage-limit: extended header and a beta header. No secrets. The first-party-only side channels the flag re-enables (error reporting, policy limits, memory sync) target Anthropic's own API host, not the repointed upstream, so nothing leaks sideways there either.

The real residual harm is the window itself, and it runs in the unsafe direction: a repointed upstream that genuinely is 200k now gets warned about and auto-compacted far too late, and an over-long request fails at the upstream. That failure is loud (an upstream API error, not silent corruption), confined to a configuration the product does not otherwise support, and the only code fix is to plumb gateway upstream config into a settings writer that today receives a port. Disproportionate. Precondition is the right call.

---

Findings

LOW - the enumeration of what the flag gates was inaccurate and materially incomplete.hypaware-core/plugins-workspace/claude/src/settings.js:62-63 and llp/0045-client-attach.design.md:286-288 both claimed the flag gates "traceparent propagation, oauth beta headers" and leaned on that to argue accuracy. The oauth claim is false against 2.1.215 (evidence above) and the list omitted error reporting, the policy-limits fetch, memory-sync eligibility and the usage-limit header. This matters because the same LLP section instructs the next reader to re-verify the key against a future Claude Code release; sending them at the wrong list defeats the mitigation.

FIXED in baaaa38 (comment + doc only, no behaviour change): settings.jsMANAGED_ENV_ADDITIONS now carries the corrected list and the explicit "does not gate credential choice" note; llp/0045 gains a three-way breakdown (sent to upstream / sent to Anthropic / not gated at all) plus a bounded blast-radius paragraph recording the reasoning above.

Positive verification: git diff --stat 8f8b5da HEAD shows exactly settings.js (+13/-6 region) and llp/0045-client-attach.design.md changed; git show HEAD:<file> | grep "oauth beta headers" returns nothing in either file, and the replacement text (does *not* gate credential choice, Not gated by it at all: credential choice, blast radius of a false declaration) is present in the committed tree.

Reviewed and found clean

• Ownership / undo logic.manageEnvAdditions (settings.js:186-196) preserves the prior ENABLE_TOOL_SEARCH rule exactly (weOwnToolSearch || typeof !== 'string') and generalises it. Upgrade path checked: a pre-PR marker with managed.env = {ANTHROPIC_BASE_URL, ENABLE_TOOL_SEARCH} picks the new key up on re-attach; a marker where the user owned ENABLE_TOOL_SEARCH keeps not owning it. The core undo (src/core/config/client_detach_disk.js:161-185) already iterates managedEnv generically and special-cases ANTHROPIC_BASE_URL for the restore target, so a second managed addition needs no core change. Correct.
• @ref anchors. Both new refs (settings.js:135,136) resolve to real headings in llp/0045.
• Suite.npm test at baaaa38: 2796 pass / 8 fail, the 8 being the pre-existing test/core/leave-command.test.js failures that reproduce identically on origin/master in this environment. npm run typecheck clean. node --test test/plugins/claude-settings-attach.test.js test/core/client-detach-disk.test.js: 31/31.

Non-blocking observations, deliberately not fixed

• settings.js:191 gates ownership on typeof env[key] === 'string'. A user who writes a non-string value (e.g. "ENABLE_TOOL_SEARCH": true) has it overwritten and recorded as managed, so detach deletes it, which contradicts the "a value the user set themselves is left untouched" rule in the helper's own JSDoc. This is pre-existing behaviour that the PR faithfully preserved, the hole is narrow (Claude Code's env is a string map, so a non-string there is already invalid), and tightening it to key in env would change behaviour for ENABLE_TOOL_SEARCH too. Out of scope for a final review round on a different key.
• client_detach_disk.js:181 assigns warning as a single string, so if two managed env keys were both externally overridden only the last is reported. Pre-existing shape; this PR makes it marginally more reachable (2 to 3 managed keys). Fixing it changes the DetachFromDiskResult.warning contract.
• The PR body still contains the corrected-away claim ("the other first-party gating it flips (traceparent propagation, oauth beta headers)"). I am not permitted to edit PR bodies; the authoritative text in the code and LLP is now correct.

Unresolved for a human

Nothing blocking. One item to be aware of at merge time: the flag was verified here against Claude Code 2.1.215 (the version installed in this environment); the code comment claims "last verified 2.1.220". I could not check 2.1.220 directly. The predicate is present and behaves as documented in 2.1.215, so the claim is corroborated but not confirmed at the exact stated version.

Review cap reached (2 of 2 rounds). This PR is a draft; per policy I did not mark it ready or merge it.

[philcunliffe]

Neutral triage: PR can merge safely

Head reviewed: baaaa382a9a765355955401eeffa01bbe995dd02

Review hit its 2-round cap (round 1: #438 (comment), round 2: #438 (comment)) with four residual findings recorded as "not fixed in this PR". I re-derived each against the code at head rather than taking the recorded severity at face value.

Classification (all non-blocking)

1. Ownership gate clobbers/adopts a non-string user value (hypaware-core/plugins-workspace/claude/src/settings.js:196). Reproduced empirically: a hand-written "ENABLE_TOOL_SEARCH": true (JSON boolean) gets silently coerced to "true" and recorded as managed, so a later detach deletes it outright — real data loss, not theoretical. But this predicate is byte-identical to what already ships on master for ENABLE_TOOL_SEARCH alone (confirmed via round 1's mutation testing and my own read of the diff); this PR only extends the same rule to a second key, 1 exposed key to 2, not a new defect class. Preference, not a blocker.
2. Single warning string drops all but the last override notice (src/core/config/client_detach_disk.js:181). Already reachable pre-PR with 2 managed keys; this PR takes it to 3. Affects only a diagnostic message, not the actual on-disk protection (the externally-overridden value is still left alone either way). Preference.
3. Verified-version mismatch: settings.js:60-61 says "last verified 2.1.220"; the LLP 0045 paragraph round 2 added says "verified against 2.1.215". I independently confirmed the Claude Code bundle installed in this environment is 2.1.215, matching round 2's own investigation - the discrepancy is real but documentation-only, no runtime effect.
4. PR body false claim ("oauth beta headers"): confirmed the code and LLP no longer contain this claim (git grep at head returns nothing), but the PR body still did. Since the body is what a human reads at merge time, I corrected that one sentence in place (see the current body) - the rest of the body is untouched, verbatim.

All four are preference-level or documentation-only: none constitute wrong behavior, data loss caused by this PR, a security hole, a crash, or a perf regression relative to what already ships on master. npm test at head: 2796 pass / 8 fail, the 8 being the pre-existing test/core/leave-command.test.js failures - reproduced independently in a clean triage worktree, identical count and names. The two files' own regression tests: 31/31 pass.

Filed a follow-up issue enumerating all four (with file:line and the "why deferred" reasoning) so they don't get lost: #440

Per LLP 0017, this PR is judged safe to ship. Left as draft, not marked ready, not merged - that's a later tick's job.