Skip to content

feat(run): stop a worker run on max_calls / max_usd with a named stop reason #1166

Closed

Description

@HugoXK

Slice of #963 (the other three parts are already delivered: nested refusal #1080, MCP write confinement #985, CLI write dirs #1087). This is the budget half, narrowed to what a run can actually enforce offline.

Problem

A host worker (dsh-superagent Executor Session, Claude Code, Codex, DSH) can start an evolution run that spawns many workers/calls. Today the budget knobs are partly there — max_seconds exists, and budget_usd only produces an overshoot warning between rounds (evolvespec.budget_round_overshoot_warning) — but nothing stops a run that keeps calling. Measured on main: max_calls, max_usd and max_tokens appear 0 times in runners.py and 0 times as enforced knobs in evolvespec.py. So "the run spends without a cap" is still true.

Scope (one slice)

  • Accept max_calls and max_usd as run-level limits (spec/knob + CLI flag), validated: non-negative numbers, 0 meaning "no calls/spend at all", a bad value refused with one readable message.
  • Enforce both inside the run: the runner counts calls and accumulates usd per call; when either limit would be exceeded the next call is not made, the round winds down normally (no traceback, no half-written artifact) and the run records stop_reason naming the limit that fired (budget), plus which one and the observed value.
  • Surface it where a reader looks first: the run's status.json and agentdescent status output carry the stop reason; a capped run is not reported as a success.
  • max_concurrency is not in this slice; it stays in feat(mcp): host-worker guard — nested-run refusal, write-dir confinement, per-Ticket budget #963.

Acceptance criteria

  • With max_calls: 1 against a fake worker that would call 5 times: exactly 1 call happens, the run ends, status.json has stop_reason = the budget reason, and agentdescent status prints it. No traceback, exit code documented in the help text.
  • With max_usd below the cost of a second call: the second call does not happen, same record shape.
  • A run that finishes under both limits keeps stop_reason as it is today (no behaviour change when unset).
  • A negative or non-numeric value is refused at spec validation with a message naming the field and the value.
  • Offline tests, deterministic, no new dependency, no network, no sandbox.

Non-goals

  • No per-Ticket accounting store across runs, no controller/claim interaction, no change to how a run is merged or reviewed.

Partial: #963

Activity

  1. HugoXK commented on Nov 19, 2026

    @HugoXK
    CollaboratorAuthor

    Claim: agent/1166-budget-guard -> one PR against main, maintainer_can_modify: true. Owner on the board: AgentDescent Dev-1.

    Scope is the two limits in the body (max_calls, max_usd) enforced inside the run with a named stop_reason; max_concurrency and any cross-run accounting stay in #963. Acceptance is checked row by row at the named tip, and the PR carries Partial: #963 so the parent is not closed by this slice.

  2. added
    enhancementNew feature or request
    area:evolveThe evolve loop: evolution, async_evolve, aggregator, population, policies, strategies
    area:runstoreRun store, ledger, checkpoint, resume and replay
    area:cliThe agentdescent command line (cli.py, doctor, plan/evolve/status/apply)
    on Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:cliThe agentdescent command line (cli.py, doctor, plan/evolve/status/apply)area:evolveThe evolve loop: evolution, async_evolve, aggregator, population, policies, strategiesarea:runstoreRun store, ledger, checkpoint, resume and replayenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions