control-token-spend

<objective>

Durable local consumption evidence and advisory budget signals from bounded, deterministic transcript processing, with inspectable scheduled-worker state.

</objective>

<dependencies>

• Python 3.13 or 3.14; standard library only. Check the interpreter before running.
• Readable Claude Code transcripts; the default source is ~/.claude/projects.
• macOS launchd for managed scheduling. Other platforms return unsupported.
• Optional investigation supports aise 1.0.0-rc.4 with an explicitly selected existing database. Accounting works without it. Never install dependencies, start TraceRoost, rebuild an index, or invoke a model for these operations.

</dependencies>

<testing>

Release verification uses captured native assistant and tool-result records, generated streaming usage and monetary boundaries, real SQLite partial-row and timestamp-boundary imports, linked report formats, durable alert deduplication, retention and overlap checks. Copied assets run with site packages disabled and an empty executable search path. Recording command collaborators exercise managed job restart and permission failure without changing shared launch agents.

</testing>

<input_output>

Read $ARGUMENTS as the requested operation and its options. Empty arguments select report, covering the preceding hour. Translate natural-language intent into individual CLI arguments; quote each value and never evaluate supplied text as shell syntax. Use --help for the bundled command's exact option grammar.

Pass each configuration value as its option on the granted command, for example python3 -B "${CLAUDE_SKILL_DIR}/scripts/usage_control.py" report --reset-at 2026-10-09T00:00:00Z. An option overrides the matching SPX_USAGE_* environment variable — SPX_USAGE_RESET_AT, SPX_USAGE_ALERT_USD, SPX_USAGE_WEEKLY_BUDGET_USD, SPX_USAGE_PRICE_FILE, SPX_USAGE_LAUNCHD_NAMESPACE — and the saved installation configuration.

Input	Contract
--reset-at	Required explicit UTC timestamp anchoring seven-day periods; reuse saved installation configuration when available. Ask for an absent anchor.
--alert-usd	Positive estimated API-equivalent threshold for the rolling fifteen-minute detector; default 20.
--weekly-budget-usd	Optional positive weekly API-equivalent target; no default. Its absence disables weekly budget and pace signals.
--price-file	Optional path to a JSON price-override file whose prices object keys a model identifier to its five rates in USD per million tokens.
--launchd-namespace	Optional launchd label namespace of the managed jobs, saved with the installation; one or more dot-separated segments of ASCII letters, digits, hyphens and underscores, none empty; default engineering.outcome.usage-control. status, stop and restart act only on jobs under the namespace the installation record names; a reinstall under another namespace records the new namespace, replaces only that namespace's jobs and leaves the four most recent earlier namespaces; older ones are stopped and their launch-agent files removed, the plan names those files in retention_removals, and a changed launch agent is left in place and reported as a retention gap.
--root	Stable operator-owned state root; default ~/Library/Application Support/Outcome Engineering/usage-control.
--projects	Read-only transcript root, disjoint from the state root.
--start, --end	Inclusive start and exclusive end, timezone-aware ISO timestamps. Freeze these when comparing reports.
--aise, --aise-database	Both required when optional investigation is selected; an absent or incompatible tool records a gap.

The runtime persists incremental offsets, reconciled requests and bounded evidence in SQLite. A report directory contains report.html, measurements.json, sessions.csv, and linked evidence.html excerpts with original-source references. latest-report.json identifies the latest report. Detector evidence lives under alerts/; worker-status.json and retention-status.json expose operational state.

</input_output>

<available_scripts>

Run python3 -B "${CLAUDE_SKILL_DIR}/scripts/usage_control.py" with the selected operation and validated options. Its sibling usage_accounting.py, usage_reports.py, and usage_schedule.py supply accounting, rendering and scheduling; invoke the entrypoint rather than the sibling modules.

Operation	Observable result
collect	One bounded import page and explicit coverage gaps.
report	Frozen HTML, JSON and CSV evidence, with an equally sized previous interval.
detect	Rolling fifteen-minute and configured weekly advisory signals, with durable identities.
hourly	Report for the preceding completed UTC hour.
install	Reviewable plan; --activate explicitly writes stable assets and activates quarter-hour detection and hourly reporting.
status	Actual managed-job observations and the last worker result.
stop, restart	Managed-job operations with checked outcomes; restart reuses durable state.

</available_scripts>

<workflow>

<step name="validate">

Resolve the operation, state root, source root, reset anchor and any supplied budget from the request or saved configuration. Ask only for choices that remain missing. Before an invocation writes to a state root the request does not name, present that absolute state root through {{! tool('ask_user') !}} and run only after the operator confirms it; an empty-argument report follows the same rule. Reject unsupported interpreter versions before execution. Keep invalid amounts, timestamp order and incomplete investigation options outside the mutation path.

</step>

<step name="execute">

Run one finite invocation of the bundled entrypoint. Collection reads at most 32 MiB across 128 files per invocation, with bounded directory discovery and a 120-second worker deadline. Incomplete coverage resumes through saved offsets; report that limitation and avoid an unattended whole-history loop. A busy worker returns overlap_skipped immediately.

For scheduling, first obtain the install plan and inspect its exact asset root, interpreter, job paths, source and effective configuration, and the absolute path of every launch agent in retention_removals, which activation stops and deletes. Present those paths through {{! tool('ask_user') !}} and activate only when the operator has authorized scheduling at the job paths and the removal of those launch agents. Confirm with status. Preserve unrelated launch agents and original transcripts.

</step>

<step name="interpret">

Read the generated measurement and selected linked excerpts. Reconcile all four usage fields, request and native child shares, pricing gaps, context growth and cache creation before drawing conclusions. Large tool results and repeated arguments establish inspection candidates; they establish no waste or exact tool-cost attribution on their own.

Treat API-equivalent cost as a priced estimate. The bundled model-prices.json prices each model; a listed model in the price-override file replaces its price. Keep subscription-allowance observations separate. Compare equally covered windows and qualify late imports, unknown pricing and missing evidence. Attribute verified delivered output only from Applied store state, default-branch merge evidence, or current passing pinned verification. Preserve required gates and resource ceilings in every recommendation.

</step>

<step name="return_evidence">

Return the exact UTC interval, coverage, principal measured drivers and clickable artifact paths. State the actual installation and worker status when scheduling was requested. Agent-driven feedback, automatic mail delivery and model-routing changes require their own authorized workflow.

</step>

</workflow>

<error_handling>

Observation	Action
Invalid configuration	Name the rejected field and correct it before execution.
Partial import	Report measured totals as partial and preserve offsets for the next finite invocation.
Unknown model or cache duration	Preserve token counts; report unavailable pricing or the documented lower-bound assumption.
Optional investigation failure	Preserve deterministic accounting and name the missing investigation evidence.
Changed or unowned installed assets or jobs	Preserve them, report the exact path, and reconcile ownership before replacement.
Worker or launchd failure	Inspect the saved diagnostics and actual job observations; use restart after correcting the cause.

The runtime owns atomic-write temporary files and retention of recognized artifacts. Run no shell deletion command. A nonzero exit or unknown job state supplies no successful-installation claim.

</error_handling>

<success_criteria>

• The selected operation returns an inspectable result with exact bounds and gaps.
• Reports reconcile their shared frozen measurement and link bounded transcript evidence.
• Signals retain effective configuration and never predict subscription percentages.
• Requested scheduling is verified through actual job observations; failures remain visible.
• Original transcripts, unrelated jobs, required gates and resource ceilings remain preserved.

</success_criteria>