Skip to content

Token owner contracts, census and native RTK parity proposals #749

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
seathatflowsinourveins wants to merge 4 commits into from
Closed

Token owner contracts, census and native RTK parity proposals #749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7d8fcc1
docs: map native token and context owner contracts
seathatflowsinourveins Oct 5, 2026
77232a5
docs: include native schema discovery comparison
seathatflowsinourveins Oct 5, 2026
86869fb
docs: census Codex token use and propose owned routing handoff
seathatflowsinourveins Oct 6, 2026
425a378
docs: record native RTK decision and Claude permission gaps
seathatflowsinourveins Oct 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions docs/decisions/2026-10-05-native-token-context-owner-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Native token and context owner contracts (2026-10-05)

Decision: use the task contracts below as the single-owner research map for each client, and keep disputed owners provisional until the organic native arm and a matched comparison return. No component is excluded by this record. It changes no install, pin, client configuration or catalog verdict.

North-star action served: fresh native coding sessions choose adequate context tools without repository instruction carriers, supporting complex engineering and US-equities research. Coordinator: overlap-token, pinned GPT-6.1 Sol at ultra. Three bounded read-only workers checked routing sources, telemetry and completeness; the coordinator verified their material claims against original artifacts and pinned source. No consequential architecture change or escalation was accepted.

## Single-owner map

“Selected” below means the source-fit owner to evaluate for that information contract. It does not mean a measured quality winner or READY. Quality decides; release recency checks compatibility and does not replace quality evidence. Installed tools receive no protected incumbent status.

| Task contract | Claude Code selected owner | Codex selected owner | Alternatives considered and basis |
| --- | --- | --- | --- |
| Maintain the active conversation and compact it automatically | Native Claude compaction | Native Codex compaction | Context-mode and ai-memory retrieve captured material; they do not replace the native conversation state. Preserve native defaults [N1, N2]. |
| Discover deferred tool schemas | Native Claude tool search, subject to actual route exposure | Native Codex deferred-tool search, subject to actual route exposure | MCP-compressor is a conditional proxy challenger. Its wrapper/schema/invocation hops require a demonstrated gap and quality comparison before adding a layer [N3]. |
| Observe a short fixed result, mutate a file, or read exact bytes for editing | Native client tools | Native client tools | Additional compression or indexing adds work to a contract that requires the original. Context-mode's own descriptions leave these cases to native tools [C1]. |
| Condense a supported shell command while preserving the facts required by the task | RTK | RTK | Native caps can omit content; Headroom requires supplied content; context-mode becomes the owner when the task requires computation. RTK's upstream hooks can run without model naming, but fidelity and actual hook delivery still need qualification [R1]. |
| Parse or aggregate arbitrary large command, API, log, table or file data | Context-mode | Context-mode | Its computation runs before the derived answer enters context. RTK's supported-command filters and Headroom's compressor supply different operations [C1, H1]. Do not filter away inputs before required computation. |
| Search an already captured output or fetched-page knowledge base | Context-mode | Context-mode | It owns its indexed artifacts and retrieval provenance. A durable decision store or command filter is not a substitute for this artifact collection [C2]. |
| Answer bounded questions about large selected text, with recovery of requested original passages | Context-mode, provisional | Context-mode, provisional | File/path processing avoids resending full inline content. Headroom compress/retrieve and native bounded reads remain challengers on identical tasks; source fit does not settle omission quality or total cost [C1, H1]. |
| Consume the full exact original | Native original read | Native original read | Headroom compression plus full recovery expanded a retained artifact; client output truncation must not silently replace required bytes [E1, N2]. |
| Re-read an unchanged file | Native read baseline, provisional | Native read baseline, provisional | Headroom's optional read cache is a separate upstream modality, disabled by default and absent from the installed exposed surface. Compare it separately; enabling it is not the compression class's routing repair [H2]. |
| Recall durable decisions or prior work across sessions and clients | ai-memory interim, subject to the memory lane | ai-memory interim, subject to the memory lane | Context-mode timeline recall overlaps this task. The existing memory head-to-head remains decisive; no equivalent durable coverage has been demonstrated here [A1, C2]. |

These contracts describe a clean intended division, not an already non-overlapping deployment. Context-mode's native timeline instructions and ai-memory's prior-work instructions both advertise historical recall. No supported switch removing that overlap while retaining output processing was established. Native model-choice evidence and a source-native routing repair must settle that boundary [C2, A1].

Exact symbol references, conceptual code search, code graphs, syntax-pattern search and scoped Markdown retrieval stay with their owning lanes. A token tool processing their returned artifact does not acquire their indexing or search job. Their per-client owner decisions must be joined from those lanes rather than selected again here.

## Native routing surfaces

| Tool and reviewed identity | Upstream-native lever | Limit and candidate remediation |
| --- | --- | --- |
| Context-mode 1.0.169; plugin source `6f0cc6841c687e754059f36714a11233fda1a02b` | Tool descriptions, semantic skill and its own SessionStart/PreToolUse hooks [C1–C3] | Distinguish descriptions causing model choice from hooks redirecting a call. Clarify processing versus observation on a tool-native surface, then rerun the same task. Native history routing remains an overlap to test. |
| RTK 0.51.0; source `e001f773f80b22b7dc4c7a79521b30e35aaef026` | Claude's rewrite hook and Codex's `rtk hook codex`, using the upstream event/updated-input protocol [R1] | Passive rewriting is participation, not model-originated selection. Codex's installer also writes awareness files and rejects `--codex --hook-only`; F9 must resolve the native-only integration using supported upstream surfaces [R2]. |
| Headroom 0.37.0; source `32d7ca4577d599b8a5f811ada74cf31504302c9d` | Existing compression/retrieval tool descriptions [H1] | Constructor supplies no server instructions; compression requires inline content. No supported description override was found in the inspected CLI and pinned source. A description change would need an upstream-native change. Deployment hooks are not a selector for this MCP-only role. |
| ai-memory 2.5.2; source `7580b74d0fb9d14a6d949dc92f5ea8bb7feb3c83` | MCP initialize instructions, tool descriptions and independently installable semantic retrieval skills [A1, A2] | Static clients need explicit workspace/project scope. Use the skill-only native surface rather than an instructions-file installer; configuration and the memory comparison belong to their existing owners. |
| Native clients: Codex 0.160.0, observed Claude Code 2.1.289 | Built-in compaction and output handling [N1, N2] | No threshold changes. The branch's older Claude pin is 2.1.284; observation and pin remain separate. Output limits are not quality guarantees. |

No proposed remediation uses CLAUDE.md, AGENTS.md, a repository routing carrier, or a task prompt naming a tool. This record proposes levers; it applies none.

## Evidence and limits

The T1 look-back is historical standing-environment telemetry, not the amended native arm. It distinguishes accepted calls from rejected decisions: zero accepted calls cannot prove never selected. Automatic hook firings measure participation separately from model selection. Exact private artifact locators, counts and changing pilot observations remain in the lane's coordination report rather than being promoted into a public acceptance receipt.

The pilot grade and full suite have not returned at this checkpoint. Task completion, exposure, meaningful contribution and isolation still need adjudication. A source-known unavailable tool's zero cannot be treated as a routing failure.

Retained comparisons in [the token component cards](../token-efficiency-stack.json) are **exact artifact comparisons**:

| Tool | Historical artifact tokens, before → after | Qualification limit |
| --- | --- | --- |
| RTK | Claude subagent: 29,986 → 3,786; Codex worker: 25,386 → 4,278 | Answers passed on the selected six-command workload; historical pins, not current organic qualification. A separate 356 → 341 pair retained only 7 of 10 commit subjects. |
| Context-mode | 97,952 → 204 in each retained client lane | A bounded handbook summary, not full-original fidelity or a general quality comparison. |
| Headroom | Claude: 237,691 → 56,939; Codex: 210,316 → 14,611 | Selected output comparisons; the Claude retrieval was byte-identical. Another complete envelope was 5,105 → 2,732, but compression plus full recovery cost 18,777. |

These figures are not provider savings, current organic selection rates or additive reductions. [RTK's qualification receipt](../../evidence/receipts/rtk-051-qualification-20261004.json) reports 151/151 native inline self-tests, separately from local synthetic compatibility/deny fixtures. [Headroom's receipt](../../evidence/receipts/native-headroom-mcp-20260920.json) records upstream MCP operations on owned synthetic artifacts. This decision runs no new model acceptance or upstream test suite.

GitHub latest-release checks on 2026-10-05 returned RTK 0.51.0, context-mode 1.0.169 and ai-memory 2.5.2. Headroom 0.37.0 remains behind latest stable 0.39.1. A release identity is a recency gate, not comparative quality. Historical landscape and convergence snapshots name Repomix, TOON and usage meters as separate candidate jobs; they provide no result overturning this map. The convergence critic also names MCP schema compression as a missing class; measure native tool deferral before proposing a proxy.

## Exclusion gates and contested comparison

No exclusion passes. Headroom in each client is an overlap watch candidate against context-mode/native selected-text handling; RTK on Codex has a native-only integration gap to resolve; context-mode on Claude cannot be excluded from its accepted zero. ai-memory remains a memory-lane question. Unique functionality must not be excluded by an overlapping subtask.

For each client, exclusion requires all three: never selected unprompted in the **complete native run**, another selected slot provides equivalent task-class coverage, and one upstream-native routing fix plus matched rerun does not change the result. An unavailable slot has an exposure defect; a selected-but-failed request has an execution defect. Neither is a “never selected” routing result. A unique never-selected slot is NOT-READY after its fix round.

Every exclusion must be overturned by a later organic selection, regression of the chosen equivalent, or an upstream-harness A/B favoring the excluded tool on that contract.

Proposed comparison: use the existing pinned promptfoo 0.123.1 workflow, or Inspect for full agent trajectories. Compare native handling, context-mode and Headroom separately on (a) parsing/aggregation and (b) overview plus exact recovery, then compare context-mode timeline with ai-memory for historical recall. Use the same unseen artifacts, fresh isolated native sessions, unnamed outcome prompts, tool-native surface hashes and valid indexes/scopes. Grade correctness, material omissions, requested quote recovery and recovery after context pressure before comparing elapsed time and complete provider usage. Record exposure, attempted selection, completed use, meaningful contribution and automatic hook participation separately. Preserve failed attempts and unknown usage. F9 owns routing changes; the pilot owner owns execution and adjudication. No new custom runner is authorized by this proposal.

## Primary sources

- **C1:** [context-mode execution description](https://github.com/mksglu/context-mode/blob/6f0cc6841c687e754059f36714a11233fda1a02b/src/server.ts#L1658) and [file-processing description](https://github.com/mksglu/context-mode/blob/6f0cc6841c687e754059f36714a11233fda1a02b/src/server.ts#L2056).
- **C2:** [context-mode capture/history retrieval description](https://github.com/mksglu/context-mode/blob/6f0cc6841c687e754059f36714a11233fda1a02b/src/server.ts#L2564) and [native timeline routing](https://github.com/mksglu/context-mode/blob/6f0cc6841c687e754059f36714a11233fda1a02b/hooks/routing-block.mjs#L31).
- **C3:** [context-mode skill](https://github.com/mksglu/context-mode/blob/6f0cc6841c687e754059f36714a11233fda1a02b/skills/context-mode/SKILL.md), [Codex hook](https://github.com/mksglu/context-mode/blob/6f0cc6841c687e754059f36714a11233fda1a02b/hooks/codex/pretooluse.mjs#L5) and [native integration documentation](https://github.com/mksglu/context-mode/blob/6f0cc6841c687e754059f36714a11233fda1a02b/README.md#L1404).
- **R1:** RTK 0.51.0 [Claude hook](https://github.com/rtk-ai/rtk/blob/v0.51.0/hooks/claude/README.md) and [Codex hook](https://github.com/rtk-ai/rtk/blob/v0.51.0/hooks/codex/README.md).
- **R2:** [RTK's Codex hook-only rejection](https://github.com/rtk-ai/rtk/blob/v0.51.0/src/hooks/init/mod.rs#L339).
- **H1:** Headroom 0.37.0 [server constructor](https://github.com/headroomlabs-ai/headroom/blob/v0.37.0/headroom/ccr/mcp_server.py#L387) and [compress/retrieve descriptions and input schema](https://github.com/headroomlabs-ai/headroom/blob/v0.37.0/headroom/ccr/mcp_server.py#L617).
- **H2:** [Headroom optional read-cache flag](https://github.com/headroomlabs-ai/headroom/blob/v0.37.0/headroom/ccr/mcp_server.py#L80) and [tool description](https://github.com/headroomlabs-ai/headroom/blob/v0.37.0/headroom/ccr/mcp_server.py#L673).
- **A1:** ai-memory 2.5.2 [scope and routing instructions](https://github.com/akitaonrails/ai-memory/blob/7580b74d0fb9d14a6d949dc92f5ea8bb7feb3c83/crates/ai-memory-mcp/src/server.rs#L164) and [initialize delivery](https://github.com/akitaonrails/ai-memory/blob/7580b74d0fb9d14a6d949dc92f5ea8bb7feb3c83/crates/ai-memory-mcp/src/server.rs#L5388).
- **A2:** [ai-memory semantic retrieval skill](https://github.com/akitaonrails/ai-memory/blob/7580b74d0fb9d14a6d949dc92f5ea8bb7feb3c83/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md#L3).
- **N1:** [Claude native context](https://code.claude.com/docs/en/how-claude-code-works), [Claude MCP output handling](https://code.claude.com/docs/en/mcp), and [Claude 2.1.289 release](https://github.com/anthropics/claude-code/releases/tag/v2.1.289). Claude's implementation is proprietary; these are release/documentation review, not open-source implementation review.
- **N2:** Codex [0.160.0 release](https://github.com/openai/codex/releases/tag/rust-v0.160.0), [compaction implementation](https://github.com/openai/codex/blob/a956835d020762cb2b570053af06f643a11c0ecc/codex-rs/core/src/compact.rs), [output truncation](https://github.com/openai/codex/blob/a956835d020762cb2b570053af06f643a11c0ecc/codex-rs/utils/output-truncation/src/lib.rs), and [official configuration reference](https://developers.openai.com/codex/config-reference/).
- **N3:** Codex 0.160.0 [deferred-registry search implementation](https://github.com/openai/codex/blob/a956835d020762cb2b570053af06f643a11c0ecc/codex-rs/core/src/tools/handlers/tool_search.rs#L59), [Claude native tool search and description limits](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search), and [MCP-compressor v0.33.0 wrapper/schema protocol](https://github.com/atlassian-labs/mcp-compressor/blob/v0.33.0/README.md). These source capabilities establish neither enabled host behavior nor measured schema savings.
- **E1:** [retained token cards](../token-efficiency-stack.json), [definitive manifest](../../evidence/artifacts/new-wsl-definitive-defaults-20261001/definitive-manifest.json), [landscape](../../catalogs/landscape/foundation.json), [convergence snapshot](../../catalogs/sota-convergence/manifest-20260929.json), [prior owner/default decision](2026-10-04-token-full-stack-owner-default.md#overlaps-this-decision-keeps) and [native compaction retained choice](2026-10-03-compaction-window-ab-retirement.md#h-standing-state).

## Completeness critic and overturn

The independent critic required distinct search contracts, actual-choice telemetry, output fidelity controls and automatic-hook accounting. Its schema-overhead finding fed a source sweep of native deferral versus MCP-compressor; native clients remain the source-fit first owner, and host exposure must be measured. The next sweep must cover direct MCP responses, fetched HTML, structured tables/logs, large single records, repeated reads, schema-description overhead, post-compaction recovery and durable-history contamination. A release or source showing a better native routing surface reopens that surface review; a quality-passing native-arm comparison overturns a provisional owner. A grade, source review or artifact-token reduction alone cannot declare the whole stack non-overlapping or READY.

## Operational census follow-up (2026-10-06)

TOKEN-STACK-VERIFY separately authorizes operational repository/F9 routing proposals. [The census/routing decision](2026-10-06-codex-token-census-routing-proposals.md) and its [review artifact](../proposals/2026-10-06-codex-token-routing.md) preserve the counts, source contracts and live template owner's handoff. Their harness-enabled after counts do not qualify the original U1 native-arm study, READY or exclusions. This dated owner map remains provisional on its original evidence gates.
Loading
Loading