docs: correct three recommendations that research overturned - #60
Merged
Merged
Conversation
Both harness documents told the next reader to do things that are wrong. Fixed with the evidence, rather than quietly reworded, so the reversals are auditable. 1. dynamicTools is no longer "the better fit" LOCAL-HARNESS-BACKENDS.md called Codex app-server's dynamicTools the better path for host-owned tools. Withdrawn. OpenAI's stability warning got BROADER in three months: the 2026-06-24 snapshot carried no production warning and scoped "experimental" to the WebSocket transport, while today's page covers the app-server command itself. app-server has no row at all in the Feature Maturity table. dynamicTools is double-experimental - gated behind capabilities.experimentalApi AND absent from the generated ThreadStartParams bindings, so the field must be hand-written against no type - and it has already changed wire shape once, leaving a LegacyDynamicToolSpec compat path where exposeToContext became the INVERTED deferLoading. There is no protocol version, no breaking-change log, and an open regression in the -c MCP path under app-server mode (openai/codex#39537). The counter-signal is recorded rather than buried: Zed's ACP adapter moved ONTO app-server and OpenAI's own IDE surfaces run on it, which is why this is "revisit in a quarter" and not "avoid". MCP cannot give us a tool living in our own process memory; when Office needs that, budget for re-porting dynamicTools at least once. 2. Driving the unmodified binary is not a safe harbour The doc said it was "the documented exception". Too confident. Anthropic began blocking third-party harnesses from Claude subscription billing on 2026-04-04 and the restriction is described as extending to all of them; OpenClaw is researching a --method cli path precisely because direct OAuth use has been blocked since then, and the same issue warns that spawning claude through the Agent SDK IS the pattern being restricted. Anthropic's June article still says subscription funds claude -p and the metering change is paused - the two together are a trajectory, not a guarantee. Consequences, both load-bearing: BYOK with the user's own key becomes the FIRST deliverable rather than the fallback, and Codex comes before Claude Code for business reasons rather than technical ones. 3. The /v1/providers routes I proposed already exist PROVIDER-AUTH.md proposed four new routes to expose the engine's login flow. They are already there as the server.integration group: GET /api/integration returns Integration.Info with a methods union (OAuthMethod | KeyMethod | EnvMethod) and a connections array, and connect/key, connect/oauth, the attempt status/complete/cancel routes and DELETE /api/credential complete it. Building /v1/providers would have been a duplicate surface over one credential store with two code paths to keep in agreement. A mapping table now records which existing route replaces each proposed one. So the engine side of BYOK is DONE and the real work is product-side - making an app use those routes instead of its own store. Office, Design, the extension, Query and Recall keep five stores that never read each other, which is the whole reason a user logs in again in every app; Cowork already does it right and is named as the pattern. Also folded in, from research rather than guesswork: no off-the-shelf wrapper is reusable (the only mature tools mapping is stale Rust, the popular one says in its README that function calling is unsupported, the third is GPL-3.0, and the 52.8k-star one never spawns the CLI - it stores the OAuth token and calls the vendor backend, which is exactly what April blocked). Two specifics ARE worth copying: pooled long-lived CLI processes, and launching with --tools "" --setting-sources "" --system-prompt <caller's>, which strips ~28k tokens of the harness's own agent prompt and is the concrete mechanism behind the chat tier. And claude -p's stream-json schema is now mapped, so the old "schema unverified" note is replaced by the real field locations, plus the warning that its credential precedence puts the OAuth login LAST - ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN and ANTHROPIC_PROFILE in the environment all silently take over billing, and --bare never reads the OAuth login at all. Same class of bug as the Codex env trap, opposite direction.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Both harness documents told the next reader to do things that are wrong. Fixed with the evidence rather than quietly reworded, so the reversals are auditable.
1.
dynamicToolsis no longer "the better fit". OpenAI's stability warning got broader in three months — the 2026-06-24 snapshot carried no production warning and scoped "experimental" to the WebSocket transport; today's page covers the app-server command itself. app-server has no row at all in the Feature Maturity table.dynamicToolsis double-experimental — gated behindcapabilities.experimentalApiand absent from the generatedThreadStartParamsbindings, so the field is hand-written against no type — and it already changed wire shape once, leavingLegacyDynamicToolSpecwhereexposeToContextbecame the inverteddeferLoading. No protocol version, no breaking-change log, open regression openai/codex#39537. The counter-signal is recorded, not buried: Zed's ACP adapter moved onto app-server, which is why this is "revisit in a quarter" rather than "avoid".2. Driving the unmodified binary is not a safe harbour. Anthropic began blocking third-party harnesses from Claude subscription billing on 2026-04-04, extending to all of them (claude-mem#1826). OpenClaw is researching a
--method clipath precisely because direct OAuth use is blocked, and the same issue warns that spawningclaudethrough the Agent SDK is the restricted pattern. Consequences: BYOK becomes the first deliverable, not the fallback, and Codex comes before Claude Code for business reasons.3. The
/v1/providersroutes I proposed already exist. They are theserver.integrationgroup —GET /api/integrationreturnsIntegration.Infowith amethodsunion (OAuthMethod | KeyMethod | EnvMethod) andconnections, andconnect/key,connect/oauth, the attempt routes andDELETE /api/credentialcomplete it. Building/v1/providerswould have been a duplicate surface over one credential store. A mapping table now records which existing route replaces each proposed one.So the engine side of BYOK is done — the real work is product-side, making an app use those routes instead of its own store. Cowork already does it right and is named as the pattern.
Also folded in from research: no off-the-shelf wrapper is reusable, but two specifics are worth copying — pooled long-lived CLI processes, and launching with
--tools "" --setting-sources "" --system-prompt <caller's>, which strips ~28k tokens of the harness's own agent prompt and is the concrete mechanism behind the chat tier. Andclaude -p'sstream-jsonschema is now mapped, replacing the old "unverified" note — including the warning that its credential precedence puts the OAuth login last, so stray env vars silently take over billing.