Task Cost

Agent Task Cost

Measure the task; do not estimate from prose or wall time alone.

This skill currently reads the OpenAI Codex CLI's local session state (rollout files under ~/.codex/sessions and the local authenticated app server). The pattern of explicit start/finish snapshots, subagent registration, and concurrency adjustment generalizes to any agent runtime that logs per-session token counts.

All commands below run scripts/task_cost.py from this skill's folder.

Start the meter

Run this before substantive task work:

python3 scripts/task_cost.py start \
  --label "<short task label>" \
  --planned-subagent "<model>:<reasoning-effort>:<count>"

The script detects the parent session, model, and reasoning effort from the current rollout. If detection is missing or wrong, pass --model, --reasoning-effort, or --service-tier explicitly. Preserve the returned task ID.

The start record must contain:

• local and UTC start time;
• parent model, reasoning effort, and service tier when known;
• planned subagent model, effort, and count;
• parent token baseline;
• live account-usage percentages and reset boundaries.

Register every subagent

Immediately after spawning a subagent, register its session ID and actual configuration:

python3 scripts/task_cost.py add-subagent \
  --task-id <task-id> \
  --session-id <subagent-session-id> \
  --model <model> \
  --reasoning-effort medium \
  --baseline zero

Use --baseline zero for a newly created subagent whose whole session belongs to this task. Use --baseline current only when continuing a pre-existing session. Unregistered subagents are conservatively treated as concurrent outside work, so registration matters.

Finish the meter

Run this as the final tool action, after substantive work and verification:

python3 scripts/task_cost.py finish --task-id <task-id>

Report:

• elapsed wall time;
• parent and subagent configurations;
• exact observed token deltas for parent, every registered subagent, and total task;
• input, cached input, uncached input, output, reasoning output, and total tokens without double-counting cached or reasoning tokens;
• raw account-percentage change for every comparable pool/window;
• other active session count and observed token delta during the interval;
• best-guess task-attributable percentage change and confidence;
• all measurement limitations.

Treat total_tokens as token cost. Do not invent a dollar cost. If a dollar estimate is requested, obtain a current authoritative rate card and state that subscription usage percentages are an unreliable billing ledger.

Concurrency adjustment

Account usage is shared and backend-rounded. Other running tasks can move the same percentage meter. The script scans locally observed rollouts active during the interval, excludes the parent and registered subagents, and estimates:

task-attributable percentage = raw percentage change x task token share of observed concurrent tokens

Treat the result as a best-guess estimate; exact allocation is impossible from a shared meter. Model, reasoning, cache, tool, and service-tier differences can make equal token counts consume unequal capacity. State the detected concurrent-session count, token share, and confidence. A raw 0-point change with nonzero tokens means the task fell below the meter's rounding resolution while still consuming usage.

Measurement boundaries

• Token deltas are exact between local rollout snapshots, provided all task subagents were registered.
• The final natural-language answer generated after finish is necessarily outside the ending snapshot; say so.
• If a usage window resets between snapshots, mark its percentage delta non-comparable.
• If the live usage query fails after one retry, still report tokens and elapsed time, but mark percentage measurement unavailable.
• Never expose authentication tokens or app-server credentials.