Watch agent-sdk for bridge `onApplyFlagSettings` callback (effort changes)

[yyq1025]

Context

Verified via spike (2026-05-30, agent-sdk 0.3.158) that claude.ai's web UI sends effort changes to BYOC bridge workers as apply_flag_settings control_requests, with payload:

{
  "subtype": "apply_flag_settings",
  "settings": { "effortLevel": "low" | "medium" | "high" | "max" }
}

The bridge SDK's internal handleServerControlRequest (in src/bridge/bridgeMessaging.ts) currently only dispatches 5 subtypes:

• initialize / set_model / set_max_thinking_tokens / set_permission_mode / interrupt

apply_flag_settings falls through to the default branch → SDK auto-replies with error: "unknown subtype". No inbound callback fires — AttachBridgeSessionOptions exposes onSetModel / onSetMaxThinkingTokens / onSetPermissionMode but no onApplyFlagSettings.

Empirical proof

Same spike also caught these subtypes claude.ai sends but the bridge SDK doesn't expose:

• apply_flag_settings (effort changes, 8 fires across two model variants)
• get_context_usage (web polls context usage, 6 fires)
• set_model extended payload format: "claude-opus-4-7[1m]" (1M context window suffix encoded into model string — already passes through via existing onSetModel, but new syntax)

apply_flag_settings is the highest-value gap — effort is now a real product feature on Opus 4.7+ / Sonnet 4.6+ and sidecode silently no-ops when the user changes it via the web UI.

What sidecode does for now

Nothing. Documented as a known limitation: effort changes on claude.ai do NOT propagate to sidecode bridged sessions; the worker uses its spawn-time default. Revisit on every agent-sdk minor bump.

Acceptance / close conditions

Check node_modules/@anthropic-ai/claude-agent-sdk/bridge.d.ts after each agent-sdk upgrade:

• AttachBridgeSessionOptions gains onApplyFlagSettings?: (settings: Partial<Settings>) => Promise<void> | void (or equivalent)
• OR a more general onSetSettings / per-key callback (onSetEffort?) lands

When either ships → wire it in packages/daemon/src/bridge/bridge-transport.ts BridgeInboundHandlers → route through BridgeService.onSetEffort → runtime.query?.applyFlagSettings({effortLevel}). Same pattern as the existing onSetModel wiring.

Notes

• Spike script lived at spikes/effort-probe.mjs (deleted post-verify, gitignored).
• Verified against current sidecode bridge stack (M2 read-in landed): cse_ session, attach bidirectional, all 7 SDK callbacks wired with logging, 8 effort changes from claude.ai → 0 callback fires → event-log readback revealed the apply_flag_settings subtype.

[yyq1025]

Update 2026-05-30 — additional auto-rejected subtype found + claude.ai UI behavior verified

While verifying the M2.6 `onSetPermissionMode` stub end-to-end, a second related gap surfaced:

Additional auto-rejected subtype: `get_context_usage`

The bridge SDK's auto-reject error string references `onGetContextUsage` (`"get_context_usage is not supported in this context (onGetContextUsage callback not registered)"`) — but `bridge.d.ts` exposes no such callback (grep 0 in 0.3.158). The SDK has `query.getContextUsage()` on the sidecode side (we can ask our query for its own usage), but no inbound-side hook to answer claude.ai's `get_context_usage` control_request.

Observed behavior: claude.ai's page polls `get_context_usage` every ~5 seconds — presumably to drive a "X / 200K tokens used" sidebar widget — and the response always errors. Same class of gap as `apply_flag_settings`: SDK has the underlying capability but no public inbound callback to plug in.

Watch for both on every agent-sdk bump

• `onApplyFlagSettings?: (settings: Partial) => Promise | void` (effort changes)
• `onGetContextUsage?: () => Promise | SDKControlGetContextUsageResponse` (context usage polling)
• OR a more general `onSetSettings` / `onGetState` family

Bonus: claude.ai's UI behavior with control_response errors

Verified empirically: when the bridge worker returns `{ok:false, error:"..."}` (e.g. our V0 `onSetPermissionMode` refuse), claude.ai shows zero UI feedback — no toast, no red, no error message. The selector visually stays at its prior value or reverts silently; the user just sees "nothing happened."

Implication for sidecode (not a SDK issue, just product context): any future sidecode→claude.ai user-visible signal must go via the transcript (synthesized system/assistant message), NOT via `control_response.error`. Our V0 stub copy is still worth keeping — it shows up in `/v1/code/sessions/{id}/events` readback for debugging — but treat it as a developer-facing log, not a user-facing message.

Spike scripts

`spikes/effort-probe.mjs` and `spikes/perm-mode-refuse.mjs` — both deleted post-verify, gitignored. Same recipe: reuse an existing cse_, attach bidirectional, wire all callbacks, change selectors on the web UI, readback events.

[yyq1025]

Update 2026-05-30 — corrected audit, depth check against bridge.mjs runtime

After the previous comment I dug deeper into the minified `bridge.mjs` runtime, since `bridge.d.ts` might be stale. The result is more nuanced:

Two distinct layers in the runtime

The bridge SDK has two relevant functions:

1. `Mj` (internal dispatcher) — destructures 12 callbacks from its context bag: `onInterrupt`, `onSetModel`, `onSetMaxThinkingTokens`, `onSetPermissionMode`, `onRenameSession`, `onSetColor`, `onFileSuggestions`, `onReadFile`, `onGetContextUsage`, `onMcpAuthenticate`, `onMcpOauthCallbackUrl`, `onMcpReconnect`, `onMcpStatus`. The dispatcher has `case` arms for each.
2. `attachBridgeSession` (public entry) — destructures only 8 from its options arg + plumbs only 5 into the `Mj` callsite: `onInterrupt`, `onSetModel`, `onSetMaxThinkingTokens`, `onSetPermissionMode`, `onRenameSession`.

Re-classified gap table

callback	in `Mj`	in `attachBridgeSession`	in `bridge.d.ts`	actual status
`onInterrupt` / `onSetModel` / `onSetMaxThinkingTokens` / `onSetPermissionMode`	✅	✅	✅	works
`onRenameSession`	✅	✅	❌	type-only gap — castable, works at runtime
`onGetContextUsage`	✅	❌	❌	same hard gap as `apply_flag_settings` — needs SDK plumbing
`onSetColor` / `onFileSuggestions` / `onReadFile` / `onMcp*`	✅	❌	❌	same — dispatcher has it, attach entry doesn't plumb

Spike verification

Spiked `onGetContextUsage` with a type-cast wiring + hardcoded fake `SDKControlGetContextUsageResponse`. claude.ai page sent 3 `get_context_usage` control_requests during the attach window. Callback fired 0 times — confirming the gap. The SDK's auto-reject error path likely persisted 3 error responses (my readback matcher used the wrong response shape so missed them, but the 0-fires result is independently conclusive).

Revised acceptance criteria

Two distinct asks:

• Plumb-through (hard gap, needs runtime change): `onGetContextUsage` + the rest of the dispatcher-internal-only callbacks. `onGetContextUsage` is the most user-visible — claude.ai's page polls it every ~5sec for a context-usage sidebar widget that today never resolves.
• Type-only gap (just `bridge.d.ts` catch-up): `onRenameSession` is already plumbed at runtime, just not exposed in `AttachBridgeSessionOptions`.