make install clones microsoft/TokenEconomizer at the commit in plugins-lock.json, applies patches/tokeneconomizer.patch (child CLI under PYTHONSAFEPATH, temp files opened with O_EXCL|O_NOFOLLOW; upstream issue microsoft/TokenEconomizer#260), installs the plugin for Claude Code and, with codex on the PATH, for Codex, and sets toolprune=propose with a protect list and microskills=envfacts globally. A dirty clone stays untouched and fails the install; a host without git or python3 skips the step. Requirement 021, README and six install tests; the council-root install test stubs the step. 🎯 Fix: 91 % 💥 Break: 4 % 💸 Tokens: – ⏱️ Velocity: – 🛡️ Security: 100 % 🏆 Score: 87 🚦 Gate: ✅ 90/5, tokens and velocity <= 100, security 100 % Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.0 KiB
7.0 KiB
021 - TokenEconomizer by Default
User Story
As the operator running many agent sessions across repositories, I want
microsoft/TokenEconomizer installed and on by default for Claude Code and
Codex in every repository through the skills make install, so that sessions
stop paying for failing loops and rediscovered repository facts, without any
tool silently disappearing from an agent.
Decisions (operator-confirmed 2026-11-17; do not re-litigate)
- Source and pin: microsoft/TokenEconomizer (MIT), pinned to commit
b57d03f81585a18b936a0eaecbd1eb51cdcecf71. The pin is one constant in the skills repository; raising it is a reviewed change. Rejected: trackingmain(unreviewed hook code would run in every session outside the sandbox). - Supply-chain gate: a MEDUSA scan of the pinned commit and a kvb-check-legal pass come before the first install; a critical finding stops the rollout. The README badge says Apache 2.0, the LICENSE file says MIT; the LICENSE file governs.
- Install path: the skills
make install(TARGET = HOME) clones it to~/Repositories/github.com/microsoft/TokenEconomizer(pkgmgr layout) at the pin, enables it for Claude Code in~/.claude/settings.local.json(the caveman/ponytail mechanism ofscripts/enable-plugins.js) and, whencodexis on PATH, adds it to Codex (codex plugin marketplace add,codex plugin add). Rejected: one-off operator rows (not reproducible on another machine). - Tool pruning: propose + protect:
toolprune=proposeglobally; deny lists are only proposed, the operator applies one per repository with/tokeneconomizer:toolprune apply.toolprune_protectnames the tools that are rare but critical here:AskUserQuestion,Artifact,Skill,Agent,ToolSearch,mcp__kvb-orchestrator__*,mcp__codebase-memory-mcp__*,mcp__plugin_codebase-memory_*. Rejected:auto(writes deny rules into.claude/settings.local.jsonafter 60 idle minutes and could silently drop the hub approval tools),off. - Micro-skills: envfacts: facts only from failures that repeat across
sessions, no model calls. Rejected:
on(paid proposer every 3 sessions per repository),off. - Loop guard: plugin default (on): the judge runs through the agent only when a turn shows loop signs; it redirects once and never stops a turn.
- Global settings are written with the clone's own launcher
(
plugin/scripts/te config set ... --global), idempotent on every install. - Codex hook approval stays manual: Codex asks once per hook change
(
/hooks, Trust all); the install prints that step in one line. Rejected: editing Codex's trust store by script. - Local security patch until upstream fixes it (operator pick
2026-11-17 "1 und 2", after the review in decision 2): the pin carries
two holes.
context.pystartspython -m tokeneconomizer.plugin.cliwith the repository as cwd, so ajson.pyortokeneconomizer/planted there runs outside the sandbox;write_jsonand_write_textindenylist.pyfollow a symlink planted at the.te.tmpname.patches/tokeneconomizer.patchsetsPYTHONSAFEPATH=1for that child and creates the temporary file withO_CREAT|O_EXCL|O_NOFOLLOW; the install applies it on top of the pin, and a clone that differs from pin plus patch is refused, left as found. Both holes go to Microsoft through its private channel (aka.ms/SECURITY.md), never a public issue; the patch is dropped once a fixed upstream commit is pinned. Rejected: parking the rollout until upstream fixes it; installing unpatched.
Approach
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes" --> S1
subgraph S["🛡️ S · Supply-chain gate"]
S1["🔎 MEDUSA scan of the pinned commit"] --> S2["⚖️ kvb-check-legal"]
S2 --> S3{"🚦 No critical finding?"}
S3 -- "🔴 critical" --> SX["⛔ Stop, report to operator"]
end
S3 -- "🟢 clean" --> A1
subgraph A["🛠️ A · make install"]
A1["📥 Clone or move to the pin"] --> A2["🔌 Enable for Claude Code"]
A2 --> A3["🔌 Add to Codex when present"]
A3 --> A4["⚙️ Global settings: propose, protect, envfacts"]
A4 --> A5{"🧪 Install tests green?"}
A5 -- "🔴 no: fix" --> A1
end
A5 -- "🟢 yes" --> B1
subgraph B["🧪 B · Live check"]
B1["🖥️ Operator runs make install"] --> B2["✅ /tokeneconomizer:status in a repo"]
B2 --> B3["🤝 Codex /hooks trust"]
B3 --> BF{"💬 Operator feedback?"}
BF -- "✏️ changes" --> A1
end
BF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
Acceptance Criteria
Supply chain
- A MEDUSA scan of the pinned commit is saved under
.state/evidence/tokeneconomizer/and reports no critical finding, or the rollout stopped with the finding reported. - kvb-check-legal names the MIT licence of the pinned commit.
- Under
.state/evidence/tokeneconomizer/, a probe shows the plantedjson.pyrunning under plainpython -mand not underPYTHONSAFEPATH=1, and the unpatchedwrite_jsonoverwriting a symlinked victim while the patched one leaves it untouched. - The private vulnerability report is drafted for the operator to send.
Install
make installwith an empty clone path leaves~/Repositories/github.com/microsoft/TokenEconomizerwithHEADequal to the pin.- A clone at another commit is moved to the pin and patched; a clone with changes beyond the patch is left as found, patch included, with a warning and a non-zero install status.
~/.claude/settings.local.jsonholdsenabledPlugins["tokeneconomizer@tokeneconomizer"] = trueand thetokeneconomizermarketplace pointing at the clone; a second install changes nothing.- With
codexon PATH,codex plugin listshows tokeneconomizer enabled; withoutcodex, the install skips it with one line. te config show --global(or its equivalent) reportstoolprune=propose,microskills=envfactsand the protect list of decision 4.- The install prints the Codex
/hooksapproval in one line.
Live
/tokeneconomizer:statusin a fresh Claude Code session in this repository reports the plugin active with the settings above.- After 10 prompts no file
.claude/settings.local.jsonin any repository gained a deny rule written by the plugin.
Tests
- Unit:
tests/test_install.pycovers the settings merge (marketplace, enabled plugin, idempotence) and the pin logic (fresh, moved, dirty) against a local bare repository standing in for GitHub. - Integration:
make installinto a temporary HOME with a fakecodexand a local clone source asserts the settings file, the clone pin and the global TokenEconomizer settings. - E2E: n/a: needs a signed-in agent; covered by the operator's live check.