[karthickmk2001]

Closes #32

What does this change, and why?

#32 asked for two things to make cost ceilings usable as a CI guard:

1. Pre-flight prompt-size cap for the api agent (this PR). The api agent pastes the brief plus the target's source into one prompt, so a large target produces a large prompt whose cost is only known after the call. --max-cost is checked after the runs finish, so it can't prevent that.
2. A distinct exit code when --max-cost is exceeded. This already shipped in Use a distinct exit code (3) when a run stops at --max-cost #64 (exit 3). This PR also fixes secfoo run --help, which still said --max-cost exits 2.

How the cap works:

• New secfoo run --max-input-tokens <n>, falling back to [agents.api].max_input_tokens in ~/.secfoo/config.toml.
• After the api agent assembles the prompt (including incremental Memory Bank scans), it estimates the size with LiteLLM's token_counter for the selected model. When LiteLLM can't count for that model, it uses ~4 characters per token, so the cap doesn't silently switch off.
• If the prompt is over the limit, the run fails before litellm.completion() is called, so nothing is sent or billed. The error names the size and the limit, for example: "Prompt is about 10,012 input tokens, over the max_input_tokens limit of 1,000 (--max-input-tokens or [agents.api].max_input_tokens). Nothing was sent to the model. Narrow the target with --exclude, or raise the limit."
• CLI agents (claude, codex, …) read the target's files themselves, so secfoo can't measure their prompt up front. They warn and ignore the setting rather than pretend to cap it.
• The setting is plumbed like --model from Support per-agent model selection and run overrides #60: CLI → execute_runs(max_input_tokens=…) → adapter.configure_max_input_tokens().

Docs: docs/REFERENCE.md (CI gates table and config example) and config.example.toml.

Testing

• pytest tests passes. 1027 passed locally. The only 4 failures are existing Windows-only POSIX permission and symlink tests that fail on main too; Linux CI is unaffected.
• ruff check . adds no new findings in the changed files (same count as main).
• Added tests:
  • tests/test_agents/test_api.py: over the limit fails with no model call; under the limit runs; no limit means no counting; LiteLLM's tokenizer is used for the selected model; the 4-chars-per-token fallback; invalid limits are rejected.
  • tests/test_agents/test_base.py: CLI agents warn and ignore the setting.
  • tests/test_settings.py: config parsing and validation.
  • tests/test_cli.py: the flag overrides config, rejects 0, and --help says exit 3.

🤖 Generated with Claude Code

[github-actions]

Leaderboard update

• Closed api agent: pre-flight prompt-size cap, and a distinct exit code when --max-cost is exceeded #32 (difficulty: low): +3 points

karthickmk2001 now has 3 points (rank #3). 22 more to reach Bronze.

Full leaderboard