Long-session context growth triggers Opus tool-call decoder-flip (malformed calls leak to captain); add context-threshold session breaking

[wenindoubt]

Problem

During a long continuous supervision session, firstmate (Opus 4.8 — claude-opus-4-8[1m], Claude Code 2.1.193) emitted malformed tool calls: the tool-call decoder flipped to legacy Anthropic XML syntax (<invoke name="Read"><parameter name="file_path">…</parameter></invoke>, prefixed by a stray junk token) instead of the harness's expected format. This happened twice in one session.

• Once the raw <invoke>…</invoke> text was rendered verbatim into the captain-visible transcript, the turn ended with no tool executed and no retry — to the captain it looked like firstmate had hung ("I'm not receiving anything back").
• Once the harness caught it ("Your tool call was malformed and could not be parsed. Please retry.") and recovery was clean.

Root cause (upstream)

This is the decoder-level model/harness regression tracked in anthropics/claude-code#49747 — "Opus 4.7 mixes legacy XML tool-use format into JSON tool calls on longer payloads." The upstream reporter confirmed it is not fixable from the prompt layer. Our session corroborates and broadens it:

• Persists on Opus 4.8 (not just 4.7).
• Hits built-in tools (Read), whole call as XML — not MCP-specific.
• Correlates with total context length (~500k tokens accumulated), even when the tool-call arguments are trivial (a single file path). So total context — not per-call payload size — is at least one independent trigger.

Why firstmate is unusually exposed

firstmate's core loop is long-lived by design: continuous supervision, heartbeats, and many small repeated tool calls (peek / wake-drain / status reads / watcher re-arm) that accumulate context indefinitely within a single session. That is exactly the long-context regime where the decoder-flip rate climbs, so firstmate trips this more often than a typical short session would.

Proposed mitigation: context-threshold session breaking

firstmate already guarantees that "a restart must be a non-event" (AGENTS.md §5): all truth lives in tmux, state/, data/backlog.md, data/secondmates.md, persistent secondmate homes, and treehouse — conversation memory is only a cache. We can exploit that invariant:

• Add a context-size guard: when firstmate's own context crosses a threshold (token count / context-% — observed trouble near ~500k tokens), proactively break the session and let the existing bootstrap + recovery protocol rebuild state in a fresh, smaller context.
• Minimum viable version: a guard / heartbeat line that warns the captain ("context is large; recommend a recovery-safe reset") and relies on the captain (or the /afk daemon) to /clear, after which recovery reconstructs everything.
• Stretch: an automatic recovery-safe reset where the harness permits an agent to trigger its own /clear/compaction.
• Net effect: caps the context regime that triggers the upstream glitch, and also lowers cost/latency on marathon sessions.

Open questions

• Threshold value, and how firstmate reads its own context size portably across harnesses (claude/codex/opencode/pi).
• Can an agent trigger its own recovery-safe /clear, or must this be captain-/daemon-initiated?
• Interaction with the /afk daemon (it owns the watcher while state/.afk exists) and with in-flight crewmates mid-session.

Evidence

• Upstream root cause: [BUG] Opus 4.7 mixes legacy XML tool-use format into JSON tool calls on longer payloads anthropics/claude-code#49747
• This session: Opus 4.8 claude-opus-4-8[1m], Claude Code 2.1.193; malformed <invoke name="Read"> leaked to the captain twice at ~500k tokens of context.

[wenindoubt]

Related design consideration: work decomposition (sequential vs parallel crewmates) and how it feeds session-context growth.

The triggering session ran a multi-item request through a single crewmate working the items in sequence, under one long-lived firstmate supervision session. Why it was bundled rather than fanned out across crewmates, and why that matters here:

How firstmate decides sequential vs parallel (AGENTS.md §7):

• Independent tasks — different files/subsystems, or different repos — get separate crewmates dispatched in parallel, each in its own isolated worktree with its own PR. No concurrency cap.
• Overlapping tasks — same repo and same files/subsystem — get serialized, often bundled into a single crewmate working them in order, to avoid (a) multiple worktrees fighting over the same files and (b) several conflicting PRs that then have to be reconciled.

In the triggering session the requested items all touched the same files within one repo, so firstmate correctly bundled them into one sequential crewmate. That is the right call for correctness — but it has a side effect relevant to this issue: one bundle means one long crewmate session and one long firstmate supervision session that accumulates context across the whole bundle, which is exactly the long-context regime that raises the decoder-flip rate described above.

Two takeaways for the proposed mitigation:

1. The sequential-vs-parallel judgment is firstmate's responsibility (overlap detection per §7), not the captain's. The captain should be able to submit all the work at once and let firstmate split or serialize it. Pushing that classification onto the captain ("only ask one thing at a time if it's sequential") would be a UX regression, not a fix — and it does not actually help, because:
2. Whether work is bundled (sequential) or fanned out (parallel), firstmate's own supervision context still grows with total work over the session's lifetime. Chunking the same total work into more, smaller captain messages does not meaningfully reduce firstmate's accumulated context. So the durable mitigation remains firstmate managing its own context (the threshold-based session break proposed above), independent of how the captain phrases or paces requests.

[wenindoubt]

Sharper variant: the crewmate's context, not just the supervisor's.

The bundling above has a more acute failure mode than firstmate's own context growth. When overlapping items are serialized into a single crewmate that works them in sequence, that one crewmate's context balloons — and the crewmate is the agent doing the heavy tool-calling (file reads, edits, test/sim runs, validation gates, review/re-review rounds). So it reaches the long-context decoder-flip regime described in this issue faster and harder than the supervisor does, and it also pays in cost and late-session quality decay.

Observed: a single bundled crewmate reached ~57% context with heavy spend on one multi-item request with deep iteration, well before its PR landed.

Bundle vs relay (for sequential / overlapping work):

• One long crewmate — keeps loaded files, the repro, and mental model across items; efficient for tightly-coupled iteration; but context balloons (cost + glitch risk + quality decay).
• Relay of fresh crewmates — crewmate A commits and pushes its branch, then hands off; firstmate spawns crewmate B on that branch for the next item. Each crewmate stays lean; the cost is re-orientation per crewmate plus spawn/teardown + branch-handoff overhead.

Proposed (extends the mitigation above to the crewmate layer):

1. The bundle-vs-relay choice is firstmate's, keyed on item coupling — loosely-coupled sequential items relay across fresh crewmates; tightly-coupled iteration stays in one. The captain should not have to pre-sort work or pace requests one-at-a-time to keep crewmate contexts small; that just relocates firstmate's judgment onto the captain.
2. A crewmate-level threshold handoff: when a live crewmate's context crosses a threshold mid-bundle, firstmate has it checkpoint (commit + push its branch) and hands the remaining work to a fresh crewmate continuing on the same branch — the crewmate-layer twin of the threshold-based session break proposed for the supervisor.

Note: firstmate does not do this auto-relay today — it bundles. So the only lever available now is the captain manually splitting requests, which works but offloads the sequencing/coupling judgment onto them.