Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
Roadmap
Planned-but-unimplemented work for Claudish. Items here are deliberately scoped, with explicit trigger conditions — what needs to be true upstream or in our codebase before each item moves to active development. If a trigger condition isn't met, leave the item parked.
For shipped features see CLAUDE.md; for the engineering rationale behind them see ai-docs/architecture/. For ad-hoc research and validation sessions, see ai-docs/sessions/.
Session push notifications — removed 2026-10-16
Status: removed (10.7.0). The server no longer declares experimental: {"claude/channel": {}}
and sends no notifications/claude/channel frame; hosts poll list_sessions and read the session
records. Rationale and what replaced each fact: ai-docs/architecture/mcp-sessions.md ("Push
notifications were removed").
The old phases are closed with it: Phase 1 (the SEP-1686 forward-compat fields task_id,
status, created_at, last_updated_at on the channel frame) was deleted with the frame, and
Phase 2 (notifications/tasks/status behind CLAUDISH_NOTIFY_VIA_TASKS) and Phase 3 (flip the
default, drop the legacy method) have no legacy method left to migrate from.
Trigger to reconsider a push (all must hold):
- Claude Code delivers
notifications/tasks/status(SEP-1686) into the agent's context — not only the CLI UI — WITHOUT--channels,.mcp.jsonregistration or an interactive-only host. Those three gates are why the channel push reached almost no one. - The TypeScript MCP SDK ships a server-side helper for emitting it
(
modelcontextprotocol/typescript-sdk#1041). - A live
create_sessionrun shows the completion arriving in the orchestrator agent's context.
Effort if triggered: small. The facts are already in SessionManager (sessionEventFor, the
waits.jsonl transitions); a push is one subscriber on the pane's onTransition and onChange
hooks plus a payload builder and its wire-format test.
notifications/progress — shipped as a KEEPALIVE; the CLI-UI use case is still parked
Status: shipped 2026-08-14, on grounds the original parking decision never weighed. This item used to read "Optional: notifications/progress as a secondary CLI-UI signal — Parked". That feature is still not viable. What shipped is a different feature wearing the same notification.
The parking decision was right about rendering and wrong about relevance. Progress notifications render nowhere — that finding stands, re-confirmed on 2.1.231 — but they also reset the client's MCP idle timer, and nothing else claudish emits does. The old note's own footnote, "not entirely inert — it still resets the client's request timeout", turned out to be the whole reason to build it.
What re-opened it: measured 2026-08-14 against Claude Code 2.1.231
A real team call died with MCP server "plugin:claudish:claudish" tool "team" sent no response or progress for 1800s; aborting. Probe: three tools, identical 90s duration, CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=30000 throughout, differing only in what they put on the transport while working.
| Tool emits during the 90s | Outcome |
|---|---|
| nothing | aborted at 30s |
notifications/progress every 10s |
survived 90s → returned normally |
notifications/claude/channel every 10s |
aborted at 30s |
The silent/progress pair is the decisive comparison: same duration, same window, same server, same transport, one variable. The channel arm emitted 3 frames with no emit errors before being killed, so its abort is not an emission failure.
Channel and progress are therefore complementary, not alternatives — channel is the visible surface with no keepalive, progress is the invisible keepalive:
| visible to agent/human | resets idle timer | |
|---|---|---|
notifications/claude/channel |
✓ | ✗ |
notifications/progress |
✗ | ✓ |
Shipped: packages/cli/src/mcp/progress-heartbeat.ts — a time-driven 10s heartbeat, armed by the CallTool dispatch on team, run_prompt, and compare_models. Time-driven and not event-driven because team already emitted a channel frame on every state change and still died at exactly 1800s: a model that thinks for 30 minutes produces no state changes. Knobs, degradation rules, and the idle-window defaults are in CLAUDE.md ("The notifications/progress keepalive").
anthropics/claude-code#58687 is STALE. It reports that the client sends no _meta.progressToken, and was closed as not planned. On 2.1.231 the token is sent — observed value 2, in every probe arm, including runs against the older progress-regression-mock.ts.
Still open: rendering — original trigger condition #2 remains UNMET
Claude Code's MCP SDK fixes the strict-token-validation bug— met 2026-07-29 (verified on 2.1.220).- Claude Code ships UI/agent rendering for progress notifications from custom MCP servers (
anthropics/claude-code#4157,#51713) — still unmet, and this stays a live watch item. Progress displays nowhere, so the "secondary CLI-UI signal" this item was originally about does not exist yet. Re-run both probes on each client upgrade. If rendering returns, the heartbeat'smessagefield becomes user-visible for free, at which point its content rules (structural only — tool name, elapsed seconds, counts; never prompt text or paths) stop being a privacy precaution and start being a UX decision.
Measurement trail — how the conclusion was reached
Kept in full: the 2026-08-14 finding only overturns the relevance verdict, not the evidence underneath it.
2026-05-09, Claude Code 2.1.133 — two blockers, both fatal on the evidence then available:
- ❌ Claude Code does not render progress notifications anywhere observable. Verified 2026-05-09 against Claude Code 2.1.133 with
progress-regression-mock.ts'sslow_with_many_progresstool emitting 5 distinct progress messages over ~10s. Mid-flight pane capture showed no terminal-UI rendering. The agent reported verbatim: "I did not observe any progress messages during the call... nothing was surfaced to the agent context." Matches the Anthropic-attributed comment onanthropics/claude-code#4157: "Claude Code doesn't currently have a generic UI for displaying real-time progress from custom MCP servers." - ❌ The transport-kill regression is NOT fixed in 2.1.133 — earlier note that it was, was wrong. A first test on 2026-05-09 (
progress-regression-mock.ts'sslow_ping_with_progress+simple_ping) reported the regression resolved. That test was insufficient. It used sequentialawaitordering, putting all progress notifications strictly before the tool response, which avoids the race. The actual trigger documented inGLips/Figma-Context-MCP#362is concurrent or quick-succession tool calls where a progress notification arrives at the client after itsprogressTokencleanup has run. The MCP SDK then treats it as a protocol violation ("Connection error: Received a progress notification for an unknown token") and tears down stdio. This bug is documented as still affecting Claude Code 2.1.x in the field. Theteamuse case (N concurrent child sessions, each with its ownprogressToken) is the exact pattern that triggers the bug.
The conclusion drawn at the time — that this would both fire into a void and destabilize team — followed correctly from those two bullets. Both have since moved: the transport kill was fixed (below), and the team-concurrency premise was a misreading. team's N children are OS processes spawned by team-orchestrator.ts, not MCP requests; they carry no progressToken at all, so a team call has exactly one token and emits at most one frame per interval. The shipped heartbeat additionally keys no state by token, so parallel tools/call requests have nothing to collide over.
Re-measured 2026-07-29 against Claude Code 2.1.220 — one blocker is gone, one is confirmed harder
Probes: packages/cli/src/mcp-session/test-helpers/capability-probe.ts (agent context, -p) and
progress-regression-mock.ts driven through an interactive tmux session (terminal UI).
Full findings: ai-docs/sessions/dev-arch-20260729-171308-1dad34b5/capability-findings.md.
- ✅ Blocker 2 (transport kill) is FIXED. Emitting 3 progress notifications no longer tears down
stdio: the immediately-following
probe_pingcall returnedpong, with noSTDIN_ENDand no emit errors. The stated reason for parking — thatteam's concurrentprogressTokens would destabilize the transport — no longer holds. Caveat: the probe emitted from ONE tool call; true N-concurrent emission across simultaneous children is still unproven. - ❌ Blocker 1 (no rendering) CONFIRMED, now on both surfaces. Previously only agent context was
tested. Now both:
- Agent context (
-p): agent answered NO to seeing any ofPROBE-STEP-1/2/3while the server log shows all 3 emitted. - Interactive terminal UI: sampled the screen every 1.2 s for 31 s, spanning the full 7.5 s
emission window of
slow_with_many_progress. The tool row rendered as a static⏺ pmock - slow_with_many_progress (MCP)across 20 consecutive samples. Not one of the five messages ("scanning files", "parsing AST", "running checks", "aggregating results", "writing output") ever appeared.
- Agent context (
This matches anthropics/claude-code#51713 — MCP tool calls are unconditionally collapsed, showing
only the server/tool name with no streaming output. Per that issue, progress DID render up to
2.1.101 and regressed by 2.1.116; our original 2.1.133 measurement therefore landed inside the
regression window. #51713 is closed, but the regression is still live in 2.1.220.
Note notifications/progress is not entirely inert — it still resets the client's request timeout.
It simply has no display.
↑ That footnote was the whole answer, and it sat here unread for two weeks. A line written as a
caveat to a rejection was in fact the only reason to build the thing; the 2026-08-14 probe above
exists because a team run died at 1800s and sent someone back to re-read it. Worth generalising:
when parking an item, state what the mechanism does do, not only what it fails to do — the residual
capability is the part a future failure will need.
Superseded on the DISPLAY axis by: team reports live per-model stats over
notifications/claude/channel (measured working) plus a status.txt in the session directory. See
"Live team progress" below. That remains true and unchanged — channel is still the only mechanism
that reaches a reader. It is not, however, a substitute on the liveness axis, which is what the
2026-08-14 measurement settled.
References:
- Original empirical session:
ai-docs/sessions/dev-research-mcp-tool-progress-20260508-235612-8d9da3e8/(lost — session dirs are gitignored and died with their worktree) - Community-research session that surfaced the corrected understanding:
ai-docs/sessions/dev-research-mcp-progress-community-20260509-213410-c058a909/(lost — same) - Re-measurement against 2.1.220:
ai-docs/sessions/dev-arch-20260729-171308-1dad34b5/capability-findings.md(lost — same) - Idle-timeout measurement against 2.1.231 (the three-arm probe):
ai-docs/reports/mcp-progress-keepalive/findings.md - Keepalive implementation design:
ai-docs/reports/mcp-progress-keepalive/architecture.md - Test artifacts:
packages/cli/src/mcp-session/test-helpers/progress-regression-mock.ts,capability-probe.ts,capability-probe-2.ts - Field evidence of the transport-kill bug the latch defends against: https://github.com/GLips/Figma-Context-MCP/issues/362
- Stale
progressTokenclaim: https://github.com/anthropics/claude-code/issues/58687
Live team progress — shipped
team runs take minutes and, in --quiet print mode, children emit nothing until they finish. There
was previously no signal at all between "started" and "done". Two transports now carry live per-model
stats, chosen because they are the two that actually reach a reader:
| Transport | Reaches | Requires |
|---|---|---|
notifications/claude/channel |
the agent's context (renders as a <channel> block) |
the channel gating in CLAUDE.md — --channels, interactive, .mcp.json |
<session>/status.txt |
a human, via tail -f |
nothing; works headless and in CI |
notifications/progress carries none of this — it renders nowhere (2.1.220, unchanged on 2.1.231).
It now runs alongside as a pure keepalive, on the separate liveness grounds established above.
How per-model attribution works. token-tracker.ts writes tokens/cost to
~/.claudish/tokens-<port>.json, keyed to a port each child picks for itself, so an orchestrator
spawning N children could not tell which file belonged to which model. CLAUDISH_TOKEN_FILE now
overrides that path, and runModels points each child at <session>/stats/<id>.json.
Format — plain ASCII, no ANSI (channel frames render escapes literally):
team: 2 models, 2 done, 7s, 102.9k tok, $0.104
01 [email protected]… done 160B 48.1k/234 $0.049
02 grok-4.5 done 118B 54.6k/19 $0.055
Knobs: onProgress (callback) and progressIntervalSeconds (default 5) on TeamRunOptions.
A third transport reaches the polling orchestrator (v9.2.0). The two above reach an agent's
context and a human's terminal; neither reaches a caller polling team(mode:"status"), which is
how every review panel actually watches a run. That caller had only outputSize, which is written
once at completion and so reads 0 for a slot's whole life — and orchestrators read it as progress
and reported working slots as dead. live_output_bytes_by_slot now carries the same live count
status.txt shows, in the same unit outputSize ends up holding. See
ai-docs/architecture/team-lifecycle.md.
Implementation: packages/cli/src/team-stats.ts, wired in team-orchestrator.ts (ticker +
child env) and mcp-server.ts (ChannelNotifier passed into defineTools).
Optional: submit code-analysis plugin to Anthropic's channel allowlist
Status: not started. Anthropic-gated.
Today, Claudish-via-code-analysis@magus requires users to launch with --dangerously-load-development-channels plugin:code-analysis@magus for channel notifications to work. Each session shows a confirmation prompt. The friction is small but real.
Anthropic's official plugin marketplace accepts plugin submissions for inclusion in the global channel allowlist. Once accepted, users can switch to plain --channels plugin:code-analysis@magus (no dev flag, no confirmation).
Trigger condition: a user explicitly asks for the friction to go away, OR Claudish becomes used widely enough outside MadAppGang that the per-session prompt becomes a meaningful onboarding cost.
Counter-consideration: submitting to Anthropic's allowlist invites security review and ties our release cadence partially to theirs. Not worth doing for a small team's internal use.
Reference: research findings under ai-docs/sessions/dev-research-channel-config-alternatives-20260508-233443-3f43f254/ confirm this is the only documented path to remove the dev flag for individual users.
Gemini Code Assist: use fetchAvailableModels for the served set (CLOSED — moot)
fetchAvailableModels for the served setStatus: CLOSED as moot (2026-08-05). The gemini-codeassist provider was
removed entirely, so there is no longer a getServedCodeAssistModels() to
migrate. The endpoint's request shape — the trigger condition below — WAS
captured in the meantime (body { project }, not { metadata }) and is in
production use on the Antigravity path (getServedAntigravityModels in
auth/antigravity-user.ts). Retained for the record only.
Original status: not started
getServedCodeAssistModels() in auth/gemini-oauth.ts infers which models a
tier serves by reading the bucket list from retrieveUserQuota. That is an
inference, not an answer: it only reports models that have a quota bucket, and it
costs a quota round-trip on the auth path.
The backend exposes a purpose-built endpoint, v1internal:fetchAvailableModels.
Probing on 2026-08-01 confirmed it exists on both cloudcode-pa.googleapis.com
and daily-cloudcode-pa.googleapis.com — both answered HTTP 400 "Unknown name
metadata: Cannot find field" rather than 404, so the method is real and only its
request shape is unknown. Antigravity's logs show it in normal use.
Trigger condition: the quota-bucket inference produces a wrong served set in
practice (a served model missing from the list, or a listed model that 404s), OR
someone captures the correct fetchAvailableModels request shape.
Effort estimate: small once the payload shape is known — one function swap
behind the existing getServedCodeAssistModels() seam, with the quota-bucket
path kept as the fallback.
Gemini Code Assist: individuals/Ultra tier needs an Antigravity-issued token
Status: SHIPPED — the antigravity provider (ag@) reuses the Antigravity
CLI's own token. See CLAUDE.md → "Antigravity Provider (ag@)".
The finding that unblocked it: the two backend checks are independent —
loadCodeAssist gates on request IDENTITY (User-Agent + metadata.ideType),
but streamGenerateContent gates on the TOKEN'S OAuth CLIENT (headers can't fake
it — 403 PERMISSION_DENIED for a gemini-cli token no matter the identity). So
claudish does NOT spoof its way in; it reuses the user's own Antigravity token
(the same one the agy CLI mints) from the shared macOS keychain store, and
self-refreshes with client creds extracted at runtime from the user's local agy
binary — never shipped. Verified end-to-end on Google AI Ultra with
gemini-3.6-flash-high.
Remaining follow-up: Linux/Windows keyring backends (macOS security only
today). Still genuinely open.
Closed follow-up — a claudish login antigravity that does its own OAuth.
Not deferred: impossible. Antigravity's client secret is baked per agy
release and rotates on auto-update (proven — the extracted secret was revoked
within a day, and there is no dynamic client registration), so claudish can
never hold one. v7.33.0 ships the reachable version instead: claudish login antigravity installs and delegates to agy, which owns the whole credential
lifecycle. Refresh delegates the same way (agy models). Do not re-open this
expecting a claudish-native OAuth flow.
The two bundled claudish-usage SKILL.md copies are stale and never mention team
Status: not started.
skills/claudish-usage/SKILL.md and packages/cli/skills/claudish-usage/SKILL.md (the
latter shipped in the npm package's files array and installed into a project by
cli.ts:2408) were last touched at v4.5.1. Neither mentions team at all, and they have
drifted from each other on model ids (openai/gpt-5 vs openai/gpt-5.3).
They are NOT the plugin skill. The skill agents actually load is
plugins/claudish/skills/claudish-usage/SKILL.md in the magus-src repo, which is current
and which carries the team lifecycle documentation. So these two copies cannot teach a
wrong team procedure — they say nothing about team — but a user who runs the
install-skill path gets a document that is four major versions behind on everything else.
Found while fixing the outputSize-as-progress misreading (v9.2.0); deliberately left
alone there, because rewriting an unrelated stale document inside a bug fix is scope creep.
Trigger condition: someone reports confusion from the installed skill, OR the install-skill path is touched for any other reason. Whoever picks it up must first decide whether these copies should exist at all — a third copy of a document whose real home is another repo is the actual defect, and deleting them plus pointing the CLI at the plugin may be the correct fix rather than syncing a third copy forever.
Effort: small to decide, medium if the answer is "sync", small if the answer is "delete".
Adding a new roadmap item
Each item should follow the structure above:
- Status:
not started/blocked on upstream/in progress/shipped - Trigger condition: explicit and falsifiable. "When X happens" > "Someday". If you can't write a trigger condition, the item probably isn't ready to be on the roadmap yet.
- Reference: pointer to the research session, issue, or design doc with detail. Do not duplicate that detail here.
- Effort estimate (optional): rough sizing if the item moves toward action.
If a trigger condition has been met, move the item to In Progress and create the implementation tasks. If a trigger condition becomes irrelevant or wrong, delete the item rather than leave it stale.
Consolidate the two channel test-helper stand-ins
packages/cli/src/mcp-session/test-helpers/ now holds two helpers that can echo argv:
fake-claudish.ts— the original; consumed by BOTHchannel/session-manager.test.tsandteam-orchestrator.test.ts, the latter via--print-argvto assert the exact spawn contract including flag orderfake-channel-stream-json.ts— added 2026-08-22 during the stream-json transport rewrite, with its own--print-argv
Why this is parked rather than ignored. The duplication already caused one outage of the
guard it exists to protect. Migrating the channel tests to the new helper made --print-argv
look dead in the old one; removing it turned the two runModels — pinned spawn identity
tests red — and they failed EMPTY rather than asserting, so the assertions pinning the
--verbose-before---quiet invariant silently stopped RUNNING at exactly the moment the
argv change made that invariant most likely to break. A guard that cannot execute reads as
coverage. Restored the same day; a header comment on fake-claudish.ts now names both
consumers, which stops the specific recurrence but not the class.
Proposed shape (assessed 2026-08-22, not executed): keep fake-channel-stream-json.ts,
give it an explicit raw/immediate argv mode distinct from its framed mode, move the two
orchestrator tests onto it, then delete fake-claudish.ts after a repository-wide reference
check.
Trigger conditions — all must hold:
- No session is concurrently editing
team-orchestrator.test.ts(it moved twice on 2026-08-22 alone; this work rewrites two of its tests). - A repository-wide reference check finds no consumer of
fake-claudish.tsbeyond the two known test files — a third consumer changes the answer from "consolidate" to "document". - The seven channel regression guards (G1–G7) are green BEFORE starting, so any red during the move is attributable to the move.
Do not start if the only motivation is tidiness. The comment already prevents the known failure; this is worth doing when someone is in these files anyway, not as its own errand.
Ultracode pro-preset: broaden past the OpenRouter-only roster
Status: shipped, deliberately narrow.
--pro-on-ultracode applies a model's catalog provider-preset while a Claude Code
session is in ultracode. It reads BOTH halves of the fact from the slim catalog's
routeVariant — baseModelId says which model the preset applies to, preset
(reasoning.mode=pro) says what to send — via lookupVariantPresets() in
adapters/model-catalog.ts. There is no model name regex and no hardcoded payload;
the --model-params parser doubles as the preset parser.
The gate is PROVIDER-SCOPED, and today that means OpenRouter only. Measured against
the live catalog on 2026-08-27 (queryModels?catalog=slim), exactly 3 of 753 entries
carry a routeVariant, all three of them gpt-5.6-*-pro, all recorded on
provider: "openrouter". The base models are served much more widely —
gpt-5.6-sol lists openai, openrouter, opencode-zen and openai-codex — but each
-pro SKU exists on OpenRouter's roster alone.
Why scoped rather than applied everywhere — now measured, not assumed. Sending
reasoning.mode=pro to gpt-5.6-sol on each vendor (2026-08-27, real requests):
| Vendor | Result |
|---|---|
openrouter |
accepted (200) |
openai (api.openai.com/v1/responses) |
accepted (200) |
openai-codex (ChatGPT OAuth backend) |
400 — `reasoning.mode` is not supported with this model |
So the parameter is neither OpenRouter-only nor universal. Applying it unscoped would
hard-400 every ultracode turn on cx@, which is the single most likely route for this
model family. The provider gate is what prevents that.
oai@ accepting it means the CATALOG under-reports reality — the fix belongs in
models-index, not in a client-side exception list.
Trigger conditions (either is sufficient):
- models-index records a
routeVariantpreset (or an equivalent per-vendor preset field) on a non-OpenRouter vendor row for the same base model. The client change is then zero —lookupVariantPresets(model, provider)already returns it. - A live run proves the parameter is accepted on another host, at which point the
fact belongs in the catalog first (see
TASK_pro_preset_vendor_coverage.mdin the models-index repo), NOT in a claudish-side exception list.
Do not work around this by dropping the provider argument or adding a per-provider
allowlist in the CLI. That reintroduces exactly the hardcoded roster this design
removed, and feedback_backend_repo_boundary puts the data gap in the backend's repo.
Effort: none in claudish if trigger 1 lands. The gate already reads whatever the catalog says.
Reference: TASK_pro_preset_vendor_coverage.md (models-index repo).
--effort-override accepts only the seven canonical levels
Status: shipped, deliberately narrow.
--effort-override <level> pins reasoning effort verbatim and skips
clampToAdvertisedEffort(). It is NOT --effort — that name belongs to Claude Code
and claudish forwards it untouched in claudeArgs (pinned by
cli-passthrough.test.ts). The two compose: --effort says what to ask for,
--effort-override says do not clamp what I asked for.
It accepts only none|minimal|low|medium|high|xhigh|max, because the value flows
through the EffortLevel-typed pipeline in base-api-format.ts. A provider-specific
value outside that set has an existing escape hatch that needs no new flag:
--model-params reasoning_effort=<value>, which lands on the payload after every
adapter has finished.
Trigger condition: a provider ships a native effort vocabulary that is neither one
of the seven nor reachable by a single --model-params key — e.g. an effort knob whose
parameter NAME differs per dialect AND whose values are provider-specific. Only then
does a dialect-aware native-value path earn its complexity.
Do not widen EffortLevel itself to accommodate one provider. It is the canonical
vocabulary Claude Code emits, and the clamp table is what maps it onto each provider.
--advisor: a reasoning-only panel reply is recorded as a stub
Status: not started. Recorded as a known limitation of the any-model advisor work; the reply is now NAMED, not accepted.
A routed panel member's answer arrives as an Anthropic message from its chain, and
extractAdvice (packages/cli/src/handlers/advisor-route-plan.ts) takes only text blocks. A
reply with reasoning and no text is S4 with emptyReason: "reasoning-only" (or
max-tokens-during-reasoning when the output limit cut it off), and the stub text says so
(emptyAdviceReason, handlers/native-handler-advisor.ts). The main model receives a failure, not
advice, for a call that was billed (or drew on a subscription).
This is visible, not silent: the failure text names the model and the reason, the call raises one
warning, and the advisor_call record says stub with emptyReason and stopReason.
Why parked. The shape question is settled: each chain's stream parser hands reasoning to the
advisor as a thinking block. What remains is a product decision: reasoning without a final
answer is the model's working, not its conclusion, and whether it counts as advice is the owner's
call. If max-tokens-during-reasoning is what real runs show, the first remedy is the lowest
advertised reasoning effort for the advisor handler set, before a larger output budget.
Trigger condition: a real run shows a panel model returning reasoning with empty content, or a user reports stub advice from a reasoning model.
Must still hold after the change: a reply with no text at all stays stub; if reasoning is
accepted as advice, the advisor_call record says so, so a reader can tell it apart from an
answer.
Effort: small.
Reference: ai-docs/reports/advisor-build-report-20260911.md ("Known limitations").
openai-sse parser: one catch drops every per-chunk error without a log line
Status: not started. Found during the any-model advisor work; not specific to the advisor.
In packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts, the try at :534 opens
with JSON.parse(dataStr) and closes at :896 with } catch (e) {}. It covers the parse and
all chunk handling after it: usage, text deltas, reasoning, and tool calls. Any exception in
those 360 lines is dropped, and the loop moves to the next line. A malformed chunk, or a bug in
tool-call handling, can drop a tool call while the turn still ends with end_turn.
The raw chunk is logged verbatim at :528 under --debug, so the input survives. The fact that
it was dropped does not. openai-sse is the default stream format for every adapter that does
not override it (packages/cli/src/adapters/base-api-format.ts:605), so the effect reaches most
foreign providers. During the advisor work this cost a full investigation of the SSE log
truncation defect.
The catches at :267 and :270 are different: they guard enqueue and close on a stream
that can already be closed, and are correct.
Why parked. Out of scope for the advisor work, and the file is shared by every OpenAI-shaped provider, so a change needs its own test run across the stream-format fixtures.
Trigger condition: the next edit to openai-sse.ts, or any report of a tool call that
vanished or a turn that ended early on an OpenAI-shaped provider.
Must still hold after the change: one bad chunk still does not end the stream; the error is
logged with enough context to find the chunk in a debug log; the replayed fixtures in
format-translation.test.ts stay green.
Effort: small for a log line; medium if the try is narrowed to the parse.
Local bun run test skips the macOS bridge suite
Status: not started. Local only; CI is not affected.
package.json:23 runs bun run --cwd packages/cli test && bun run --cwd packages/macos-bridge test. On bun 1.4.0 the two displayWidth Unicode-oracle tests in
packages/cli/src/tui/viz/color.test.ts fail, the CLI suite exits non-zero, and && stops
before the bridge suite starts. A local bun run test therefore reports nothing about the
bridge.
CI pins bun 1.3.10 (.github/workflows/test.yml:58), where the CLI suite is green and the
bridge suite runs: run 34544453952 on the v9.3.0 merge printed Ran 3257 tests across 211 files, then Ran 20 tests across 1 file.
Why parked. Nothing is unguarded in CI today. The risk arrives when the CI pin moves to a
bun version where the two tests fail: CI then goes red and, the same way, stops running the
bridge suite.
Trigger condition: the CI bun pin is raised, or someone relies on a local run to check a
bridge change.
Must still hold after the change: the root test script still fails when either suite
fails; both suites report even when the first one fails.
Effort: small.
Regression test: a Responses stream that dies mid tool-call
Status: DONE. Fix shipped, unit test written and mutation-proven, and the client-side
behaviour verified end to end against a real Claude Code run (see
ai-docs/reports/truncated-toolcall-live-verification.md). Kept here for the method,
which is reusable for any "does the harness honour this wire signal" question.
The fix is in openai-responses-sse.ts: when openToolBlocks is non-empty in the
parser's catch block, the turn ends with an SSE error event instead of end_turn,
so Claude Code cannot execute a tool call whose argument JSON was cut mid-object.
Rationale and the evidence behind it: ai-docs/architecture/adapters.md, section
"A stream that dies mid tool-call".
Trigger condition: a stable connection to the Codex backend. Nothing else blocks it.
The spec (kept here because ai-docs/sessions/ does not survive a fresh clone):
Append one describe block to
packages/cli/src/handlers/shared/stream-parsers/openai-responses-sse.test.ts, reusing
its createMockContext / parseClaudeSseStream helpers. Derive the upstream body from
the REAL capture test-fixtures/sse-responses/gpt-5.6-sol-responses-turn1.sse — do not
hand-write SSE. In that fixture the first function_call item is added at line 94, its
first argument delta is line 97, and it completes at line 103.
- Test 1 — cut the fixture just after line 97, then
controller.error(new TypeError("The socket connection was closed unexpectedly")), which is the production error text. Assert: anevent: errorframe witherror.type === "api_error"; NOmessage_deltacarryingstop_reason: "end_turn"; atool_usecontent_block_startWAS emitted (or the test can pass vacuously by the tool never starting); every block start has exactly one matching stop. - Test 2 — cut during
response.output_text.delta, before anyfunction_callitem, and error the stream identically. Assertstop_reason: "end_turn"and a text block containing[Stream error:. This pins the branch that must NOT change.
Acceptance criterion: mutation-test it. Force the if (toolCallCutOff) condition to
false, confirm test 1 goes red and test 2 stays green, then restore the file by copy —
never git checkout or git stash, the index is shared with sibling worktrees.
VERIFIED 2026-09-10: Claude Code DOES discard a partial tool block on a mid-stream
error event. Measured before/after against the same mock upstream: released v9.0.8
executed the truncated Write and returned InputValidationError, while the fixed build
executed no tool at all and retried the turn. Method and raw evidence:
ai-docs/reports/truncated-toolcall-live-verification.md.
Picker: the all-filtered notice must say "no capability data", not "not chat-capable"
Status: not started. Found in the v10.1.1 release review (merge of the strict chat rule with v10.1.0's picker outcome states).
buildDiscoveredModelOutcome (model-selector.ts) returns all-filtered whenever every served row fails isReportedChatCapable, and DiscoveryNotice.tsx renders it as "served N models, none of them chat-capable". That wording dates from when an undescribed model counted as chat. Under the strict rule it also fires when nobody DESCRIBED the rows: LM Studio's picker path reads /v1/models (no type field) while --probe reads /api/v0/models and its type, so the two screens disagree about the same daemon. Hiding the rows is correct; the sentence is false. Carry the undescribed count (unavailableForMissingCapability already computes it for the probe path) on the variant and word the notice from it; optionally read LM Studio's type in the picker fetcher too.
Trigger condition: the next change to buildDiscoveredModelOutcome or DiscoveryNotice.tsx, or the first user report of a picker notice calling local models not chat-capable.
Picker tests: cover admission by catalog evidence alone
Status: not started. Found in the same review.
No picker-level test covers an openai-models-list provider (13 builtins plus LM Studio), whose discovered rows carry no reported and are admitted by the catalog alone; only the negative case is tested. model-selector-discovery.test.ts also now uses mock.module("…/all-models-cache.js") (contained, restored in afterAll), and its STATE C endpoint assertion is circular because the fixture sets the endpoint. Add a positive case (a served id the catalog fixture knows by alias is kept with no reported), assert the endpoint on a path the fixture does not control, and replace the module mock with a test-only catalog hook like catalog-client's _setCatalogEntriesForTest.
Trigger condition: before the next change to the discovered-row admission path, or with the item above.
MCP pane children: follow-ups deferred from the 10.4.0 migration
Status: not started. Deferred during code review of the pane migration (PR #288); each line names the
finding id in ai-docs/reports/mcp-magmux-panes/session-record/implementation-log.md ("Code-review fixes
(iteration 1)"), where the reason is recorded.
- Background-shell orphan between refreshes. A shell started and orphaned between two 2 s group refreshes
is never recorded in the pane's group file, so the watcher cannot reap it. Trigger: any report of a
leftover process after a pane closed, or the next change to
pane-registry.tsgroup snapshots. - A-L2 — shutdown reap ≈ 6–7 s instead of ≈ 3 s. Watchers already cover an early SIGKILL. Trigger: an MCP host that kills the server before ~7 s on shutdown.
- A-L5 — spurious re-wake after a screen-only settle. Needs a deterministic degraded-mode fixture. Trigger: a degraded (no-transcript) turn reported as a model re-wake in the field.
- A-L9 — a prompt starting
/wordis typed as a slash command. Needs a product decision (escape it, or document it). Trigger: the first prompt that starts with a slash but is not a command. - B-L4 —
run_idfalls back to the basename before the first flush. Needs the id minted before prehydrate. Trigger: the next change toteam(mode="run")start-up ordering. - C-L1 — an
invalid_argsspawn model is recorded aspane_lost. Trigger: the next change tocreate_sessionargument handling. - C-L5 — accounting freezes at the terminal transition. Outside observers read
tokens.json, so they are unaffected today. Trigger: a consumer that reads final tokens from the session row instead. - gpt-5-mini cost is estimated (
stats/*.jsonprices it at $2/$8 per M withis_estimated:true), socost_usdmay be overstated for it. Trigger: the catalog publishing real gpt-5-mini pricing. proxy-server.test.ts"keyless custom endpoint" timed out at 5 s in CI (once, on PR #288; it passes 3/3 locally; main's own CI also failed once on 2026-09-26, cause not checked). Trigger: a second CI failure of that test.
Pane sessions: follow-ups from the 10.7.0 MCP update
Status: not started. Evidence: ai-docs/reports/2026-10-16-mcp-update-validation.md. The turn
that never settled after its background agents finished mid-turn was fixed in 11.0.0 (a6739184).
Adopting magmux's --controller claude-code input gate, and the prompt typed twice under load,
were closed by the resize_session redesign: panes need magmux 0.17.0, every prompt goes through
one gated magmux send bound to the pane's own transcript, and the retype nudge
(PaneSession.nudge, awaitClearedBox) and the editorMode overlay key are gone
(ai-docs/architecture/pane-session.md).
- An upstream stream error is shown as assistant text, so the turn reads COMPLETED. A
create_sessionongpt-6.1-sol(cx@, claudish 10.6.3) ended its only turn with the assistant text[API Error: server_is_overloaded Our servers are currently overloaded. Please try again later.];upstreamErrorswas[],reasonnull, state COMPLETED, after 27 tool calls and no work done. A caller reading only the state takes it for a finished task. Trigger: find where the Responses stream converts a mid-streamerrorevent into a text block, and check it on 10.7.0 first. redactSecretsmisses three credential shapes. On 2026-10-20redact.tsleft these unmasked:x-api-key: <value>in a header,https://user:password@host, and a lowercase?token=<value>query (Authorization: Bearer <value>is masked).SlotRow.recentpasses a Bash command or WebFetch url through it; the same text is already on the child's screen viacapture_session, sorecentadds no exposure, but every caller ofredactSecretsshares the gap. Trigger: next change toredact.ts, or a report of a leaked key.
Pane children: an in-child mod as a state channel
Status: parked. Decided 2026-10-13 from the UI-independent-signals research
(ai-docs/reports/pane-ui-independent-signals.md, Layer 4).
A Claude Code mod loaded with --plugin-dir runs inside the pane child and reports busy (PromptHint
isWorking), dialog open (classic.PermissionRequest) and prompt submit directly, measured 11/11 in real
claudish panes. It is not used because it is the least stable surface measured: the engine's own types say
EARLY ACCESS, Anthropic can serve it off remotely with no local override (#99130 served it off on
2.1.288/289), it stays off until a folder's trust prompt is answered, and loading it delays SessionStart by
about 250 ms. Its $.prompt.submit is also not an input path for claudish: prompts are always typed or
pasted as a user would.
Trigger condition (all must hold): the mod API types drop "EARLY ACCESS"; #99130 is closed with the
remote switch removed or overridable; and the session registry reader (pane/session-registry.ts) has
shown a state it cannot express that a mod can.
Effort: medium — a mod bundle shipped with claudish, a per-pane socket in the control dir, and a "no mod heartbeat → registry/screen" fallback.