Skip to content

Token report: take the Codex hook engine from the stable hooks flag; drop the removed plugin_hooks step - #265

Merged
seathatflowsinourveins merged 2 commits into
mainfrom
claude/codex-hooks-flag-20260925
Sep 25, 2026
Merged

Token report: take the Codex hook engine from the stable hooks flag; drop the removed plugin_hooks step#265
seathatflowsinourveins merged 2 commits into
mainfrom
claude/codex-hooks-flag-20260925

Conversation

@seathatflowsinourveins

@seathatflowsinourveins seathatflowsinourveins commented Sep 25, 2026

Copy link
Copy Markdown
Collaborator

Scope

  • What this PR changes: tools/token-report/token_manifest.py now takes Codex's hook-engine state from the stable [features] hooks flag. Before, it required both hooks and the removed plugin_hooks, so a host that follows current Codex reported its hook engine as off. The dead codex features enable plugin_hooks step and the plugin_hooks = true template key are removed.
  • Base commit: 6752ede5 (origin/main)
  • Lane: lane:foundation
  • Owned paths touched:
    • tools/token-report/token_manifest.py and test_token_manifest.py
    • recipes/README.md
    • docs/token-session-handbook.md
    • docs/token-efficiency-stack.json
    • adoption/templates/codex.config.template.toml
    • the re-registrations in manifests/evidence.json

Evidence-class table

Claim Evidence class Command
On codex-cli 0.155.1, hooks is stable and on, and plugin_hooks is removed and off native_proven (native CLI output on this host) codex features list returned hooks stable true and plugin_hooks removed false
codex features enable plugin_hooks still exits 0 and writes the key, but the feature stays off native_proven, in a throwaway CODEX_HOME CODEX_HOME=$(mktemp -d) codex features enable plugin_hooks, then codex features list
The new derivation holds for absent, true, false, legacy codex_hooks, a non-boolean value and a non-table features synthetic test_codex_hook_engine_follows_the_stable_hooks_flag_not_removed_plugin_hooks

The #264 builder found the same semantics in the codex-rs source: hooks is Stage::Stable with default_enabled true, plugin_hooks is Stage::Removed, and codex_hooks is a legacy alias. tools/sota-convergence/codex_lane.py and the historical blueprint probes keep -c features.plugin_hooks=false. Disabling a removed feature is harmless and still isolates older clients.

Local commands run

$ python3 -m unittest discover -s tools/token-report -p test_token_manifest.py     # Ran 51 tests, OK (3.13); OK on /usr/bin/python3 3.12
$ uv run … -m unittest tests.test_render_config tests.test_adoption_status tests.test_release_pin_contents tests.test_adoption_docs_consistency tests.test_layer_verdicts tests.test_adoption_bootstrap_macos tests.test_adoption_launchd tests.test_ecosystem_manifest   # Ran 353, OK (skipped=21)
$ uv run … scripts/validate.py                 # passed
$ uv run … scripts/build_ecosystem.py --check  # passed
$ uv run … scripts/new_host_grand_list.py --check   # passed

Decision record

None. This corrects documentation and a reporter to match native client behaviour.

Host evidence

Not applicable. This host's ~/.codex/config.toml still carries the harmless dead key, and it was not edited.

Checklist

  • No workflow changes. [x] No secrets. [x] No paid surface. [x] Peer files preserved.
  • Independent review: the change is small and fully covered by the unit table above. Codex cross-family review is unavailable until 2026-09-30.

🤖 Generated with Claude Code

@seathatflowsinourveins seathatflowsinourveins added the lane:foundation Foundation lane: Claude/Codex setup, hosts, memory, RAG, research, workers label Sep 25, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 25, 2026

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

seathatflowsinourveins pushed a commit that referenced this pull request Sep 25, 2026
Scout @claude
Test that hooks outranks its legacy alias codex_hooks (review gap on #…
fa70702 
…265)

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
@seathatflowsinourveins

seathatflowsinourveins commented Sep 25, 2026

Copy link
Copy Markdown
Collaborator Author

Independent review (separate Sonnet reviewer, read-only): ready. It hand-traced all 9 derivation cases, confirmed no remaining doc, template or test reference depends on the removed plugin_hooks lines, and matched all 6 re-registered manifest hashes. Its one gap was that no test sets hooks and codex_hooks to conflicting values. That case is now covered in fa70702 (hooks wins). Held for the v2026.09.25.1 release window.

This was referenced Sep 25, 2026
Merged
Open
@seathatflowsinourveins

seathatflowsinourveins commented Sep 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Counter semantics for the token-practice docs and reporter. This is evidence from #270 (merged), independently reviewed (agree ×4). I haven't edited this PR's files. Please fold in whatever fits at integration.

Receipts, generation 2, on wsl-authoring-20260923, 2026-09-25:

What each counter actually counts:

  • RTK total_saved is ceil(bytes/4) of raw output minus that of filtered output, uncapped (estimate_tokens and track at v0.49.0).
    • It is dominated by outliers. On this host the ten largest commands are 74.4% of 741M, and one grep is 28.7%.
    • Claude Code 2.1.282 shows up to 30,000 characters inline, otherwise a saved file with a preview of at most 2,000 characters. Modelled on that, the net difference is about 1.18% of the headline.
    • Suggestion: label rtk gain as an uncapped upper-bound estimate, not context tokens avoided.
  • Context Mode tokens_saved_lifetime is retained session events × 256 (TOKENS_PER_EVENT, in both the plugin bundle and build/server.js). It is a fixed per-event constant, not bytes kept out. The status line's "MB kept out" uses a different base.
  • jCodeMunch total_tokens_saved is a whole-file bytes/4 counterfactual. On this host all 59,640 come from get_symbol_source since 2026-09-20, which includes acceptance reads.
  • Headroom savings --json returns zeros both when the ledger is empty and when ~/.headroom/savings_events.jsonl does not exist. Check the file's existence before reporting "0 saved". The lifetime field is clamped to 30 days in code (MAX_RETENTION_DAYS = 30).

seathatflowsinourveins pushed a commit that referenced this pull request Sep 25, 2026
Scout @claude
Test that hooks outranks its legacy alias codex_hooks (review gap on #…
834cdb6 
…265)

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
@seathatflowsinourveins
seathatflowsinourveins force-pushed the claude/codex-hooks-flag-20260925 branch from fa70702 to 834cdb6 Compare September 25, 2026 19:13
Scout and others added 2 commits September 25, 2026 15:28
Scout @claude
Token report: derive the Codex hook engine from the stable hooks flag
8d037b5 
codex-cli 0.155.1 lists `hooks` as stable and on by default and
`plugin_hooks` as removed (always false). token_manifest.py required both
flags, so a host following current Codex (no plugin_hooks key) was
reported as having its hook engine off. The derivation now reads `hooks`
(legacy alias `codex_hooks`), defaulting to on when absent. The dead
`codex features enable plugin_hooks` step and template key are dropped
from the recipe, handbook, token-stack JSON and Codex config template;
codex_lane's isolation override is left as is (disabling a removed
feature is harmless and still isolates older clients).

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Scout @claude
Test that hooks outranks its legacy alias codex_hooks (review gap on #…
043b4e5 
…265)

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
@seathatflowsinourveins seathatflowsinourveins mentioned this pull request Sep 25, 2026
Merged
@seathatflowsinourveins
seathatflowsinourveins force-pushed the claude/codex-hooks-flag-20260925 branch from 834cdb6 to 043b4e5 Compare September 25, 2026 19:29
@seathatflowsinourveins
seathatflowsinourveins merged commit 61f9c53 into main Sep 25, 2026
23 checks passed
@seathatflowsinourveins
seathatflowsinourveins deleted the claude/codex-hooks-flag-20260925 branch September 25, 2026 19:45
@seathatflowsinourveins seathatflowsinourveins mentioned this pull request Sep 25, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

lane:foundation Foundation lane: Claude/Codex setup, hosts, memory, RAG, research, workers

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@seathatflowsinourveins