Skip to main content

Opus Cost Guard Hook (2026-05-17)

Opus Cost Guard Hook (2026-05-17)

MC: #101140 (AI Factory T-3 Priority 2)
Parent: Reality Anchor Doctrine v1
Owner: CodeCraft / Petter Graff
Hook File: ~/.claude/hooks/opus-cost-guard.sh
Date Shipped: 2026-05-17

Purpose

The Opus cost guard prevents routine specialist agent dispatches from using the Opus model ($9,790/day burn rate observed on 2026-05-14). ALAI Holding AS currently has zero revenue. At $9,790/day, runway burns before products ship revenue. This hook enforces model routing policy at the tool invocation boundary.

Petter Graff (T-3 Priority 2): "Opus waste burns cash daily. This is higher priority than 130 orphan tools cleanup because orphan tools waste storage; Opus waste burns cash."

How It Works

The hook is a PreToolUse filter on the Task tool:

  1. Reads JSON from stdin (tool call parameters)
  2. If tool_name != "Task" → allow (not a dispatch)
  3. Extracts subagent_type and model from tool_input
  4. If model is empty or not Opus → allow
  5. Checks override mechanisms (see below)
  6. Checks if subagent_type matches allowed list (novel architecture personas, /prompt-forge)
  7. Checks if subagent_type matches blocked list (routine specialists: codecraft, vizu, proveo, flowforge, skillforge, etc.)
  8. If blocked agent + Opus model → exit 2 (BLOCK) with error message
  9. Otherwise → allow

Every decision is logged to ~/.cache/opus-cost-guard-YYYYMMDD.log with timestamp, decision (ALLOW/BLOCK), subagent_type, model, and reason.

Allow / Block Matrix

Subagent Type Model=Opus Decision Rationale
petter-graff, martin-kleppmann, anthropic-chief-architect, openai-chief-architect ✓ ALLOW Novel architecture design requires Opus reasoning
prompt-forge (any persona) ✓ ALLOW High-stakes prompt engineering per ZAKON
codecraft, vizu, proveo, flowforge, skillforge, agentforge, finverge, securion, skybound, lexicon, datavera, axiom, resolver ✓ BLOCK Routine build/test/docs work — Sonnet sufficient
Any sonnet / haiku / empty ALLOW Not burning Opus budget

Override Mechanisms

Three ways to bypass the guard for exceptional cases:

1. Single-Use Override Token (60s TTL)

touch /tmp/opus-override-token
# Next Opus dispatch within 60s will be allowed
# Token is consumed after first use

Use case: CEO directive for specific one-off dispatch requiring Opus.

2. Environment Variable (Session-Wide)

export CLAUDE_OPUS_OVERRIDE=1
# All Opus dispatches in this session allowed

Use case: Architecture review session with multiple Petter/Kleppmann iterations.

3. Prompt Contains /prompt-forge

If the prompt text contains the string /prompt-forge, the dispatch is allowed. This catches skill invocations that route through /prompt-forge but may not have subagent_type set correctly.

Test Commands

# Test BLOCK (should fail with exit 2)
echo '{"tool_name":"Task","tool_input":{"subagent_type":"codecraft","model":"claude-opus-4"}}' | bash ~/.claude/hooks/opus-cost-guard.sh

# Test ALLOW (novel architecture)
echo '{"tool_name":"Task","tool_input":{"subagent_type":"petter-graff","model":"claude-opus-4"}}' | bash ~/.claude/hooks/opus-cost-guard.sh

# Test ALLOW (Sonnet)
echo '{"tool_name":"Task","tool_input":{"subagent_type":"codecraft","model":"sonnet"}}' | bash ~/.claude/hooks/opus-cost-guard.sh

# Test override token
touch /tmp/opus-override-token
echo '{"tool_name":"Task","tool_input":{"subagent_type":"codecraft","model":"claude-opus-4"}}' | bash ~/.claude/hooks/opus-cost-guard.sh
# Should ALLOW and consume token

Error Message Format

When blocked, the hook writes to stderr:

Opus blocked on routine dispatch (matched: codecraft). Use Sonnet (default).
Petter T-3 cost guard 2026-05-17.
Override: touch /tmp/opus-override-token (single-use, 60s TTL) or CLAUDE_OPUS_OVERRIDE=1

Audit Trail

All decisions logged to ~/.cache/opus-cost-guard-YYYYMMDD.log in format:

[2026-05-17T13:45:22Z] [opus-cost-guard] [BLOCK] subagent_type=codecraft model=claude-opus-4 matched_agent=codecraft
[2026-05-17T13:47:10Z] [opus-cost-guard] [ALLOW] Novel architecture persona 'petter-graff' — Opus permitted.
[2026-05-17T13:48:33Z] [opus-cost-guard] [ALLOW] Override token present (age=12s). subagent_type=codecraft. Consuming.

Cost Impact

Before guard (2026-05-14): $9,790/day (100% Opus for all dispatches)
After guard (projected): ~$500/day (Opus only for architecture reviews, Sonnet for builds)
Monthly savings: ~$278,700 → critical for zero-revenue startup

  • Parent MC: #101140 (Opus cost guard)
  • Hook System Reference: ~/.claude/projects/-Users-makinja/memory/reference_hook_system_2026-05-04.md
  • Cost Tracking: node ~/system/tools/cost-tracker.js summary today
  • AI Factory Audit: AI Factory Audit 2026-05-14
Back to top