feat(opencode): model capability tiers, honest context limits, structural stops, and budget telemetry

[linfangy-int]

Issue for this PR

N/A — fork-internal review PR for a patch series; relates to the upstream discussion about a model-tier capability field.

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

A 32-commit patch series making opencode work well with small (~4B) and mid-size (~30B) local models, which today fall through every model-specific code path. Each commit carries a stable item ID (A0…E7, B6) for review:

• Capability tiers (A0–A4): per-model tier: "minimal" | "default" (config, catalog field when available, or parameter-count heuristic; vendor-family models keep their existing prompts byte-identically). minimal = compact ~1.1k-token system prompt, reduced tool roster, grammar-safe tool schemas (no format/pattern/anyOf/$ref — llama.cpp GBNF-safe), pinned sampling. Per-model prompt and sampling config overrides.
• Honest context arithmetic (C1–C8): unset limit.context no longer silently disables compaction; proportional compaction reserve min(20k, max(2048, ctx*0.15)); truthful overflow recovery text; window-aware output-token fallback + per-request headroom clamp; format-aware token estimation replacing flat chars/4.
• Structural enforcement (B1–B5): max-steps now actually strips tools from the final request (the prompt already claimed this); deterministic plugin load order; plugin-hook error isolation; tier-scoped doom-loop tool stripping; mechanical JSON tool-call repair (smart quotes, trailing commas, brackets, snake_case keys).
• Text tool-call lifting (B6): stream middleware converting <tool_call>/fenced-JSON/bare-JSON call shapes into native tool calls for capabilities.toolcall === false or minimal-tier models — the first consumer of that catalog flag.
• Budget observability (D1–D5): GET /session/:id/context-budget (limits, reserve, usable, per-component baseline breakdown, next-request estimate), x-opencode-* telemetry headers on every provider request, typed budget/overflow/compaction events, and a session.turn.completed reconciliation event.

Why: stock opencode reserves a fixed 20k tokens for compaction (36% of a 56k window), assumes 32k output when limits are unset, estimates tokens at chars/4 (2.8x off on CSV), and sends a long vendor-tuned prompt plus full tool schemas (~28–34k tokens) — a small-context model ends up with ~5k usable tokens and compacts after every step. Loop guards are prose-only, which exactly the models that loop ignore.

How did you verify your code works?

• ~1,200 targeted tests across packages/opencode and packages/core (all new suites + touched existing suites), typecheck green in every touched package; frontier-regression tests assert vendor-model prompts/tools/schemas are byte-identical to upstream.
• Built the binary and smoke-tested: context-budget returns the specified arithmetic (reserve 8448, usable 48128 on a 56320 window; minimal baseline 5,181 tokens vs ~28–34k stock).
• End-to-end validation in a downstream embedding driving a 4B local model through an OpenAI-compatible router, on a 116-task agent benchmark: score 0.6134 → 0.6820, task error rate 35% → 6.9%, context-overflow failures 31 → 1.

Screenshots / recordings

N/A (no UI change).

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

---

Draft for review. A follow-up wave (config-owned tier rosters, token turn budgets, enforced subagent enums, headroom-aware reads) is under design review before implementation.
Draft for review.

Update: the follow-up wave has landed on this branch as W6 (commit d29b13a8fc) — config-owned tier rosters with a custom-tool exemption, token/wall-clock turn budgets routed through the existing max-steps stop, an enforced subagent_type enum, headroom-aware reads, honest budget-stop semantics for delegated tasks, and an optional expected_artifacts deliverable contract. Rationale and per-item detail are in the W6 comment; notably, the validation run reversed the roster decision — the narrow minimal roster proved protective, so it stays the default and widens only by explicit config.

[linfangy-int]

Follow-up wave (W6): structural bounds, enforced rosters, honest stop semantics

The wave flagged at the bottom of the PR description is now implemented, driven by an end-to-end validation run of this branch against a 4B local model on a 116-task agent benchmark. That run is also what changed one of the decisions below, so the reasoning is recorded inline in the code rather than only here.

What the validation run changed

The headline result held: score 0.6134 → 0.6820, error rate 35% → 6.9%, context-overflow failures 31 → 1. But two findings reshaped this wave:

1. The minimal roster is protective, not merely small. The run carried a patch restoring task to MINIMAL_TIER_TOOLS (the roster looked over-aggressive for an embedding product whose only route to subagents is task). That patch cost a research-task category 0.868 → 0.396: the model delegated work it should have done directly, then burned its step budget. A prompt-level fix scored 0.354 — worse. So the default roster stays narrow and is widened only by explicit configuration.
2. The failure mode moved rather than disappearing. 7 of the 8 remaining failures were timeouts, not overflow. One turn ran 70 steps / 1.83M tokens before the provider gave up. steps alone does not bound a turn.

The items

Item	What it changes
W6-1	MINIMAL_TIER_TOOLS becomes a default, overridable per model via tier_tools: { include, exclude }. Plugin- and tool/-directory-contributed tools are exempt from the tier cut by default.
W6-2	subagent_type is published as a schema enum of the agents this agent may actually reach — enforce, don't instruct.
W6-3	New turn_tokens / turn_seconds agent budgets, both routed through the existing B1 structural stop rather than a second termination path.
W6-4	Request preparation publishes its budget arithmetic; Tool.Context.budget() exposes live remaining headroom, and read refuses a slice that would not fit, with the arithmetic and a narrower call to make.
W6-5	A subagent stopped by a budget returns state="max_steps" with partial output and recovery text, instead of leaking the raw stop directive to its parent.
W6-6	Optional expected_artifacts on a prompt; if the turn would go idle without them, the agent is told once, precisely what is missing.

Notes on the design choices

• W6-1 exempts custom tools but not built-ins. The tier cut exists to trim opencode's own surface for a small window. An integrator who registered a tool has already made that call, and silently dropping it turns an advertised capability into a no-op. exclude still wins, so an over-large custom roster remains trimmable. invalid is not removable — it is the LLM layer's landing slot for malformed tool calls and is never advertised to the model.
• W6-2 no-ops when the permitted set is empty. An empty enum is invalid JSON Schema and would reject every call; that case keeps the free-form field and fails at permission time with a message that explains itself. The enum survives the A3 grammar-safe lowering, so constrained decoders can enforce it at generation time.
• W6-3 reuses B1 rather than adding a stop. Whichever budget trips first, the next request goes out with the max-steps directive and no tools — one termination path, one set of semantics. Token accounting sums per-request usage the same way isOverflow does.
• W6-4 exists because compaction structurally cannot cover this. Proactive compaction triggers when accumulated history crosses usable; a single oversized tool result goes from under-budget to over-window inside one step and never crosses the trigger on the way up. Observed at 57,632 tokens against a 56,320 window. The guard reports the numbers and a concrete narrower call, because a fact about this file is more actionable to a small model than a rule it has to remember.
• W6-5 strips the directive because models restate it. "MAXIMUM STEPS REACHED / tools are disabled until next user input" reads to a parent as an instruction addressed to it, and the delegation gets surfaced as an unexplained failure even when real work was done.
• W6-6 nudges exactly once, and not at all when a budget already forced the text-only step — that turn has no tools left, so asking it to write a file would spend a request on something it cannot do.

Also included

script/build.ts gains --target <name> to build a single named target regardless of host platform (--single is host-only, so producing a Linux container binary from a Windows box previously meant a full 12-target run).

Verification

• Typecheck green in packages/opencode, packages/core, packages/schema.
• New unit suites for the roster filter, the subagent enum, and the turn-budget / headroom bookkeeping, plus an integration test asserting the advertised task schema carries the same roster its description lists.
• Full packages/opencode suite: 3390 pass / 29 fail across 263 files. All 29 failures are pre-existing and reproduce identically at the branch point (922a552fec) — verified by re-running the failing files on that commit and set-diffing the two failure sets, which leaves zero regressions. They are the known Windows-environment classes: symlink support (Glob, filesystem.resolve, snapshot symlink handling), the HttpApi SDK generated-client block, a Git-Bash path-translation assertion in tool/shell, and session/snapshot-tool-race.

[linfangy-int]

W6 validation on real hardware — best score yet, but a serious throughput regression

Second full end-to-end run of this branch on the PTL 32 GB box (4B local bundle, qwen3.5-4b, llama-server n_ctx=65536), same 116-task benchmark, same fixtures, same protocol as the run quoted in the PR description. Built from d29b13a8fc as 1.18.18-superclaw.2.

This time the roster came from config, not a source patch: tier_tools: { include: ["task"] } on the local model, nothing else. --target opencode-linux-x64-baseline worked exactly as intended — single Linux target from a Windows host, no 12-target run.

Three-way result

	baseline (stock 1.17.11)	superclaw.1 (2889cd7b93 + local roster patch)	superclaw.2 (W6, config-driven)
L2 mean	0.6134	0.6820	0.7053
Errored	41 (35 %)	8 (6.9 %)	12 (10.3 %)
ContextOverflow	31	1	2
UnknownError	10	7	10
L2 zeros	21	13	10
Perfect 1.000	13	16	17
Total task time	12.60 h	12.40 h	23.94 h
Mean per task	391 s	385 s	743 s
Tokens	—	44.5 M	67.9 M

W6-5 is confirmed, and the evidence isolates it

The research category recovered 0.396 → 0.874, essentially back to its 0.868 baseline — while task stayed enabled.

task	baseline	sc.1	sc.2	delegated in sc.2
task_executive_lookup	1.000	0.000	1.000	['local-file-agent']
task_pricing_research	0.890	0.000	0.900	['local-file-agent']
task_competitive_research	0.750	0.180	0.820	['local-file-agent']
task_stock	1.000	1.000	1.000	['local-file-agent']
task_events	0.700	0.800	0.650	['local-file-agent']

All five still delegate to local-file-agent — the same routing that scored 0.000 before. Same delegation, different outcome, so the variable is W6-5's stripping of the raw stop directive, not a change in routing. The roster/delegation trade I reported last time was not a real trade; the cost was the leaked "MAXIMUM STEPS REACHED / tools are disabled" text being read by the parent as an instruction to itself.

W6-1 also behaved better than my hand-written list: the custom-tool exemption automatically kept confirm_file_protection, which my patch had missed and which is the entry point for the protected-file flow. Live roster (13 tools): bash, confirm_file_protection, edit, get_mcp_status, glob, grep, ocr, parse_pdf, read, sc_search_web, task, todowrite, write; webfetch/websearch correctly absent. Tier/limit arithmetic unchanged and correct (tier=minimal, usable=48128, reserve=8448).

The regression: runs got ~2× slower and 9 tasks now pin the timeout ceiling

Total task time nearly doubled and 30 tasks ran >10 min slower than sc.1. Nine tasks sat at or near the harness's 2700 s per-task limit, against one in sc.1:

task	sc.1	sc.2
task_meeting_council_budget	80 s (idle)	2641 s (idle)
task_log_ssh_user_activity	346 s (idle)	2761 s (timeout)
task_log_mapreduce_jobs	156 s (idle)	2099 s (idle)
task_log_mapreduce_slow_tasks	437 s (idle)	2676 s (idle)
task_earnings_analysis	497 s (idle)	2681 s (idle)
task_log_ssh_successful	567 s (idle)	2762 s (timeout)
task_log_ssh_unusual_times	804 s (idle)	2761 s (timeout)

12 failures, 9 of them new relative to sc.1, and 10 of 12 are UnknownError: The operation timed out — the timeout class is now the whole failure surface. Two (task_csv_temp_trend, task_log_ssh_successful) completed at both baseline and sc.1 and fail here.

csv_analysis also fell 0.760 → 0.659 across 26 tasks, broadly rather than via one outlier: task_csv_gdp_regions 0.775 → 0.000, task_csv_stock_best_worst 0.875 → 0.275, task_csv_cities_filter 0.900 → 0.550, task_csv_life_exp_change 0.945 → 0.608.

Leading hypothesis, not a finding: W6-4. The clustering is suggestive — the worst-hit tasks are log_* and csv_*, i.e. exactly the large-fixture reads W6-4 now refuses, and a refusal that the model answers with another slightly-narrower read would produce precisely this signature (many more requests, far more tokens, no overflow, eventual timeout). Overflow did stay near zero (2), so the guard is doing its job on the metric it targets; the question is what the model does after being refused. I have not verified the retry pattern in the trajectories yet.

Two caveats on all of the above: n = 1 per configuration, and this benchmark has demonstrably high run-to-run variance (task_events has now scored 0.700 / 0.800 / 0.650 and task_meeting_council_votes produced three different outcomes across three runs; the judge needed 7 variance retries here vs 4 last time). Per-category deltas on n=5 categories should be read as directional only.

Not exercised

I deliberately changed one variable, so W6-3 (turn_tokens/turn_seconds) and W6-6 (expected_artifacts) were left unconfigured. Given that the timeout class is now the entire remaining failure surface and 9 tasks pin the ceiling, W6-3 looks like the directly relevant lever and is the obvious next arm.

Per-category

category	baseline → sc.1 → sc.2	n	Δ vs sc.1
research	0.868 → 0.396 → 0.874	5	+0.478
coding	0.720 → 0.775 → 0.899	5	+0.124
productivity	0.771 → 0.852 → 0.922	7	+0.070
meeting_analysis	0.481 → 0.535 → 0.584	28	+0.049
log_analysis	0.652 → 0.680 → 0.691	30	+0.011
analysis	0.708 → 0.787 → 0.783	9	−0.004
writing	0.888 → 0.907 → 0.863	5	−0.045
csv_analysis	0.507 → 0.760 → 0.659	26	−0.101

Artifacts: runs/arm_A_20260818_091736/ (judge, tokens, by-turn model, workspace snapshot). Happy to pull specific trajectories if the W6-4 hypothesis is worth chasing.