Cost Governor - Subagent Budget Control

Pre-flight cost estimation for subagent spawns and approval gates. Prevents API overspend and surprise billing. Budget control for sessions_spawn calls. Dail...

Security Scan

The skill's requirements, files, and instructions are coherent with its stated purpose: pre-flight cost estimation, logging, and gating of subagent spawns — it does not request credentials or install arbitrary code from remote sources.

Purpose & Capability

Name/description align with what the skill does: estimation functions, logging to a workspace note, and a CLI summary. The included JS libraries (cost-tracker, cost-summary) are exactly what you'd expect for this functionality. No unrelated binaries, services, or credentials are requested.

Instruction Scope

Instructions direct the agent to estimate costs, write/read the workspace tracking file (~/.openclaw/workspace/notes/cost-tracking.md), optionally set DAILY_BUDGET in a workspace .env, and integrate with sessions_spawn and cron. This stays within the stated purpose. One notable item: the SKILL.md suggests adding a budget line to the system prompt to enforce stops ("Daily API budget: $XX. Stop spawning subagents if estimated total exceeds this"). A static scanner flagged that pattern as 'system-prompt-override' — in this context it appears to be a user-facing recommendation to put budget guidance in the system prompt (which is a plausible operational approach) but modifying the system prompt is powerful and should be done intentionally.

Install Mechanism

There is no remote install step or download URL; the package is instruction+local JS files. That is low risk compared to remote installation. The included scripts are plain Node.js and operate on local files; no external network calls or downloads are present in the code.

Credentials

The skill requests no credentials or environment variables. It suggests writing a DAILY_BUDGET to a workspace .env as an optional convenience — this is proportional for a budget-enforcement tool. It reads and writes files in the user's workspace only (no access to system-wide credentials or unrelated config paths).

Persistence & Privilege

always is false and the skill can be invoked autonomously (default). It does not request permanent elevated privileges, does not modify other skills' config, and does not write to system-wide settings beyond user workspace files and optional cron entries (cron addition is user-driven in README).

Scan Findings in Context

[system-prompt-override] expected: The SKILL.md recommends adding a budget enforcement line to the system prompt to stop spawning when a threshold is reached. A prompt-injection detector flagged that pattern; here it's a user-facing suggestion to change the system prompt for governance. That is plausible for this tool but is a high-impact action — users should deliberately control any system-prompt edits.

Assessment

This skill appears to do exactly what it claims: estimate costs, require approval over a small threshold, and log to a workspace note. It does not request secrets or reach out to remote endpoints. Before installing: 1) Review the included JS files (lib/cost-tracker.js, bin/cost-summary.js) yourself — they operate on ~/.openclaw/workspace and append/update cost-tracking.md; 2) Back up or create a dedicated workspace path to avoid accidental writes to other notes; 3) Prefer configuring budget via the workspace .env or skill config rather than blindly pasting enforcement text into your global system prompt — changing system prompts is powerful and can affect other agent behavior; 4) If you enable cron jobs or automated invocation, test the scripts manually first (run node bin/cost-summary.js --daily) to confirm behavior; 5) If you want stricter guarantees, require manual approval (do not allow autonomous agent invocations) or lower the approval threshold. Overall, the package is coherent and low-risk, but exercise normal caution when allowing automated changes to prompts or adding scheduled tasks.

Cost Governor - Subagent Cost Control

Pre-flight cost checks before spawning subagents. Tracks spend. Gates expensive operations. Prevents surprise $300+ bills.

Files Included

• SKILL.md — This file (agent instructions)
• README.md — Human-readable setup guide
• cost-tracking-template.md — Copy this to notes/cost-tracking.md to get started
• lib/cost-tracker.js — Core estimation and logging library
• bin/cost-summary.js — CLI: daily/monthly spend summary

Problem Solved

You spawn a subagent for "research passive income ideas" on Opus. 30 minutes later: $12 gone. This skill estimates cost before execution, requires approval for expensive tasks (>$0.50), and tracks all spend.

When to Use

• Before spawning any subagent — estimate cost, log it
• Daily spend review — summarize costs vs budget
• Post-task reconciliation — compare estimated vs actual

Core Rules

1. Every subagent spawn >$0.50 estimated requires explicit user approval
2. All spawns get logged to $WORKSPACE/notes/cost-tracking.md
3. Estimates use multipliers from historical data (see Cost Model)
4. No silent expensive operations — always surface cost before execution

Cost Model

Based on historical data from cost-tracking.md:

Task Type	Base Estimate	Multiplier	Effective Estimate
Creative (open-ended)	Token estimate	7.5x	Apply to all creative tasks
Research (bounded)	Token estimate	3x	Web search + synthesis
Technical (structured)	Token estimate	2x	Code, config, structured output
Simple (template)	Token estimate	1.5x	Fill-in, short responses

Model cost rates (approximate per 1K tokens):

• Claude Opus: ~$0.075 input / $0.375 output
• Claude Sonnet: ~$0.003 input / $0.015 output
• GPT-4: ~$0.03 input / $0.06 output
• Grok 4.1 Fast Reasoning: ~$0.003 input / $0.015 output
• Claude Haiku 4.5: ~$0.0008 input / $0.004 output

Estimation Formula

estimated_cost = (estimated_output_tokens / 1000) * output_rate * task_multiplier

Example:

• Task: Creative writing (5000 tokens estimated on Opus)
• Calculation: (5000 / 1000) * $0.375 * 7.5 = $14.06
• Action: Require approval (>$0.50 threshold)

Setup

1. Create cost tracking file:

mkdir -p ~/.openclaw/workspace/notes
touch ~/.openclaw/workspace/notes/cost-tracking.md

2. Add header to cost-tracking.md:

# Cost Tracking Log

| Date | Task | Model | Est. | Actual | Ratio | Notes |
|------|------|-------|------|--------|-------|-------|

3. Set your daily budget (optional):

echo "DAILY_BUDGET=20.00" >> ~/.openclaw/workspace/.env

Usage

Pre-Flight Check (Before Spawning)

User: "Research passive income methods"
Agent: Checking cost... Estimated $3.50 (Research task, Opus, ~3K tokens * 3x multiplier). Approve?
User: Yes
Agent: [spawns, logs to cost-tracking.md]

Daily Spend Dashboard

Run manually or via cron:

## Daily Spend — 2026-02-21
| Task | Model | Est. | Actual | Ratio |
|------|-------|------|--------|-------|
| PassiveIncomeResearch | Opus | $3.50 | $4.20 | 1.2x |
| AIHardwareResearch | Sonnet | $0.80 | $0.65 | 0.8x |
**Total:** $4.30 est / $4.85 actual
**Budget remaining:** $15.15 / $20.00 daily

Post-Task Reconciliation

After each subagent completes:

1. Check actual cost (if available via /status)
2. Log to cost-tracking.md
3. Update multipliers if ratio is consistently off

Triggers

• Pre-spawn gate: Before sessions_spawn, estimate and log. If >$0.50, ask user.
• Cron (daily, optional): Summarize daily spend, flag overruns.
• Post-task: Log actual cost, update multipliers if data available.

Approval Gate Flow

1. Estimate cost using model + task type + multiplier
2. If estimate ≤ $0.50 → proceed, log silently
3. If estimate > $0.50 → present estimate to user, wait for "approve" / "yes"
4. Log decision (approved/rejected/modified) to tracking file

Budget Alerts

Set a daily budget cap. When spend exceeds it, the agent stops spawning and notifies you.

Setup: Add to your workspace config or mention it in system prompt:

"Daily API budget: $XX. Stop spawning subagents if estimated total exceeds this."

Cron-based daily summary (optional): Add to your cron:

# Daily cost summary at 11 PM
0 23 * * * node ~/.openclaw/workspace/skills/cost-governor/bin/cost-summary.js --daily

Anti-Patterns (What NOT to Do)

• ❌ Spawning Opus for simple lookups (use Sonnet or Haiku)
• ❌ Open-ended creative tasks without cost ceiling ("write a novel")
• ❌ Multiple subagents when one suffices
• ❌ Skipping post-task reconciliation
• ❌ Ignoring consistent ratio mismatches (update multipliers!)

Advanced: Custom Multipliers

Edit multipliers in your cost-tracking.md header:

## Multipliers (Updated 2026-02-21)
- Creative: 10x (our tasks run long)
- Research: 2.5x (bounded queries)

Agent reads these on each check.

Integration with Other Skills

• sessions_spawn: Always run cost check before spawning
• AGENTS.md: Log cost in agent entry ("Last used: $X.XX")
• Cron jobs: Wrap expensive recurring tasks with cost gates

Troubleshooting

Q: Estimates are consistently off A: Update multipliers in cost-tracking.md based on actual ratios.

Q: How do I get actual costs? A: Use /status after subagent completes, or check provider dashboard.

Why This Matters

Real story from r/LocalLLM (Jan 2026):

"Left my OpenClaw agent running overnight. Spawned 8 research subagents on Opus. Woke up to $340 API bill. This skill would've saved me."

Don't be that person.

---

Author: OpenClaw Community
License: MIT
Requires: OpenClaw with subagent support, notes/ directory