# 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](https://docs.alai.no/books/system-architecture/page/reality-anchor-doctrine-v1-final)  
**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

<table id="bkmrk-subagent-type-model%3D"><thead><tr><th>Subagent Type</th><th>Model=Opus</th><th>Decision</th><th>Rationale</th></tr></thead><tbody><tr><td>petter-graff, martin-kleppmann, anthropic-chief-architect, openai-chief-architect</td><td>✓</td><td>**ALLOW**</td><td>Novel architecture design requires Opus reasoning</td></tr><tr><td>prompt-forge (any persona)</td><td>✓</td><td>**ALLOW**</td><td>High-stakes prompt engineering per ZAKON</td></tr><tr><td>codecraft, vizu, proveo, flowforge, skillforge, agentforge, finverge, securion, skybound, lexicon, datavera, axiom, resolver</td><td>✓</td><td>**BLOCK**</td><td>Routine build/test/docs work — Sonnet sufficient</td></tr><tr><td>Any</td><td>sonnet / haiku / empty</td><td>**ALLOW**</td><td>Not burning Opus budget</td></tr></tbody></table>

---

## 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

---

## Related

- **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](https://docs.alai.no/books/system-architecture/page/ai-factory-audit-2026-05-14-connection-map)