api agent: pre-flight prompt-size cap, and a distinct exit code when --max-cost is exceeded #32

Two suggestions from a reader (Peter) on the DEV.to cost-per-run article, which I said I would write up here.

1. Pre-flight prompt-size cap for the api agent

The api agent sends the brief plus target content to the model. A large target can produce a very large prompt, and the cost is only known after the call.

Proposal: estimate the prompt size before sending and refuse (or warn) if it exceeds a configurable limit, for example a --max-input-tokens flag or a config value. The failure message should say how large the prompt was and which limit applied.

2. Distinct exit code when the budget is exceeded

--max-cost and --fail-on both feed CI exit codes. A CI job cannot currently tell "the scan ran and found issues" apart from "the scan was stopped because the cost ceiling was hit".

Proposal: use a dedicated exit code for budget exceeded, separate from the findings code and the generic error code, and document it next to --max-cost.

Why it matters

Both changes make cost ceilings usable as a real guard in CI, which is the main reason to track cost per run.

Happy to work on a PR for either if the approach sounds right.