Files
skills/docs/requirements/021-tokeneconomizer-by-default.md
T
Kevin Veen-BirkenbachandClaude Opus 5.5 41cdf0c40b feat(install): install TokenEconomizer by default at a pinned, patched commit (021)
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>
2026-11-17 18:48:25 +00:00

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)

  1. 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: tracking main (unreviewed hook code would run in every session outside the sandbox).
  2. 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.
  3. 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 of scripts/enable-plugins.js) and, when codex is on PATH, adds it to Codex (codex plugin marketplace add, codex plugin add). Rejected: one-off operator rows (not reproducible on another machine).
  4. Tool pruning: propose + protect: toolprune=propose globally; deny lists are only proposed, the operator applies one per repository with /tokeneconomizer:toolprune apply. toolprune_protect names 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.json after 60 idle minutes and could silently drop the hub approval tools), off.
  5. Micro-skills: envfacts: facts only from failures that repeat across sessions, no model calls. Rejected: on (paid proposer every 3 sessions per repository), off.
  6. 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.
  7. Global settings are written with the clone's own launcher (plugin/scripts/te config set ... --global), idempotent on every install.
  8. 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.
  9. 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.py starts python -m tokeneconomizer.plugin.cli with the repository as cwd, so a json.py or tokeneconomizer/ planted there runs outside the sandbox; write_json and _write_text in denylist.py follow a symlink planted at the .te.tmp name. patches/tokeneconomizer.patch sets PYTHONSAFEPATH=1 for that child and creates the temporary file with O_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 planted json.py running under plain python -m and not under PYTHONSAFEPATH=1, and the unpatched write_json overwriting a symlinked victim while the patched one leaves it untouched.
  • The private vulnerability report is drafted for the operator to send.

Install

  • make install with an empty clone path leaves ~/Repositories/github.com/microsoft/TokenEconomizer with HEAD equal 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.json holds enabledPlugins["tokeneconomizer@tokeneconomizer"] = true and the tokeneconomizer marketplace pointing at the clone; a second install changes nothing.
  • With codex on PATH, codex plugin list shows tokeneconomizer enabled; without codex, the install skips it with one line.
  • te config show --global (or its equivalent) reports toolprune=propose, microskills=envfacts and the protect list of decision 4.
  • The install prints the Codex /hooks approval in one line.

Live

  • /tokeneconomizer:status in a fresh Claude Code session in this repository reports the plugin active with the settings above.
  • After 10 prompts no file .claude/settings.local.json in any repository gained a deny rule written by the plugin.

Tests

  • Unit: tests/test_install.py covers 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 install into a temporary HOME with a fake codex and 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.