cost-tracker

Cost Tracker

Aggregates and reports token cost per user story. Does NOT enforce ceilings — that is budget-monitor's responsibility. Runs at session end, after all other skills complete.

Parameters (passed by adapter)

• userStoryId — from config or prompt
• sessionTokensUsed — total tokens (input + output) consumed in this session
• modelRateKey — key into defaults/budget-defaults.md rate table (e.g., claude-sonnet-4-6)

Config Keys

• organization.userStoryId (fallback if not passed as parameter)
• audit.db.connectionString — pyodbc connection string for SQL Server dual-write (optional)
• audit.db.schema (default: guardrails) — schema owning CostLog
• audit.db.tablePrefix (default: "") — optional prefix for table name

Process

1. Compute session cost

Look up blended rate from defaults/budget-defaults.md using modelRateKey. If modelRateKey not found in table: use claude-sonnet-4-6 blended rate as fallback.

sessionCostUSD = (sessionTokensUsed / 1_000_000) × blendedRate

Note: rates in defaults/budget-defaults.md are expressed as USD per 1,000,000 tokens (e.g., claude-sonnet-4-6 blended = $9.00 per 1M tokens).

2. Read existing rollup

If audit.db.connectionString is set (DB path):

Query SQL Server with a 3-second connection timeout:

SELECT ISNULL(SUM(SessionCostUSD), 0)
FROM   [{audit.db.schema}].[{audit.db.tablePrefix}CostLog]
WHERE  UserStoryId = ?

Use the result as priorCost. If the query fails, fall back to the JSONL path below and emit P2 WARN "DB cost rollup read failed: {error}".

Fallback / no DB (JSONL path):

Read .guardrails-costs.jsonl and find all records with matching userStoryId. Sum their sessionCostUSD values to get priorCost.

accumulatedCost = priorCost + sessionCostUSD

3. Append session record

Always write to .guardrails-costs.jsonl:

{
  "timestamp": "2026-03-17T10:30:00Z",
  "userStoryId": "PROJ-142",
  "sessionId": "backend-coding-agent-20260317T102300Z",
  "sessionTokensUsed": 12400,
  "modelRateKey": "claude-sonnet-4-6",
  "sessionCostUSD": 0.112,
  "accumulatedCostUSD": 1.45,
  "maxCostUSD": 5.0
}

DB write (SQL Server): If audit.db.connectionString is set, also INSERT the record into [{audit.db.schema}].[{audit.db.tablePrefix}CostLog] using pyodbc (3-second connection timeout). Columns match the JSON fields above (camelCase → PascalCase). If the INSERT fails: emit P2 WARN "DB cost write failed: {error}" but do NOT block.

4. Emit alerts

• Expose accumulatedCost to budget-monitor for P1 ceiling check at 100%. The 80% advisory alert is emitted by budget-monitor (Check 4), which is the single owner of all budget threshold notifications.

If .guardrails-costs.jsonl is not writable: P2 WARN but do not block. DB and JSONL failures are both non-blocking.

Hook-Level Cost Logging

The run-guardrails-hook script writes a cost record at the hook layer during the stop phase:

• Reads CLAUDE_SESSION_TOKENS_USED and CLAUDE_MODEL_RATE_KEY from Claude Code environment variables
• Computes session cost using the blended rate table (same rates as above)
• Reads prior accumulated cost from DB (fallback: JSONL) for the userStoryId
• Writes to both .guardrails-costs.jsonl and [{schema}].[{prefix}CostLog] (if DB configured)

Hook-level cost records complement the skill-layer records. The skill layer has full context (e.g., exact input/output token split); the hook provides a fallback record using blended rates in case the skill layer does not execute (e.g., early session termination).