Skip to content

fix(mcp): name the field a caller can set in an unpriced-cap refusal (#1196) - #1199

Merged
Birfy merged 2 commits into
mainfrom
agent/1196-mcp-usd-hint
Nov 21, 2026
Merged

Birfy merged 2 commits into
mainfrom
agent/1196-mcp-usd-hint

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 20, 2026

Copy link
Copy Markdown
Collaborator

Fixes #1196.

What changed

An unpriced max_usd was refused with build_call_limit's CLI sentence on
every surface, so the MCP plan / start tools and a Python
runstore.launch / execute caller were told to pass --usd-per-call — a flag
neither of them can pass.

  • evolvespec.build_call_limit grows a keyword usd_hint whose default is a
    new surface-neutral NEUTRAL_CAP_HINT (set usd_per_call beside it); the
    reason text and the point of refusal are unchanged.
  • CLI_CAP_HINT (pass --usd-per-call on the command line) stays a named
    constant and is now passed by cli.py at the evolve run-options call site,
    so the CLI sentence is byte-identical through cli.main.
  • mcp._call_limit_payload passes usd_per_call in the same tool call, so a
    host reads the argument it can actually send in that call.
  • runstore.py is not touched (zero diff): it inherits the neutral default,
    which is what a keyword caller needs, and it cannot drift back because it
    passes no hint.
  • Both docstrings that claimed the refusal "reads the same wherever the number
    was typed" now say the reason is shared and the actionable hint is per
    surface.

The refusal still happens before create / launch: a refused start leaves
runs == [].

Diffstat: 6 files +126/−34 — agentdescent/cli.py 8,
agentdescent/evolvespec.py 23, agentdescent/mcp.py 14,
changelog.d/1196-unpriced-cap-hint.md 6, tests/test_max_usd_refusal_hint.py
86, tests/test_mcp_call_limit.py 23; agentdescent/runstore.py zero.

Verification at the tip

Base: 8d75685aecdecb9a93056d8abee661b827a83c28
Tip SHA: 22c717dabc9abd8189b1c74336410e27ff98b85c

Ran:

  • Red first, re-taken after the rebase at base 8d75685a, clean worktree,
    only this branch's two changed test files:
    PYTHONPATH=$PWD pytest -o addopts='' -p no:cacheprovider -q tests/test_max_usd_refusal_hint.py tests/test_mcp_call_limit.py
    → 3 failed, 12 passed in 9.03s:
    test_a_tool_refusal_names_the_argument_it_can_pass,
    test_a_python_caller_is_told_to_set_the_field_not_a_flag,
    test_the_default_hint_names_no_surface. The CLI row passes at base by
    design (it pins today's CLI text).
  • Cap / run-store surfaces at the tip:
    PYTHONPATH=$PWD pytest -o addopts='' -p no:cacheprovider -q tests/test_max_usd_refusal_hint.py tests/test_mcp_call_limit.py tests/test_budget_guard.py tests/test_operator_run_cap.py
    → 38 passed.
  • MCP / plan / run-store CLI / changelog set at the tip:
    PYTHONPATH=$PWD pytest -o addopts='' -p no:cacheprovider -q tests/test_mcp*.py tests/test_changelog_fragments.py tests/test_plan_text_output.py tests/test_plan_headroom_shape.py tests/test_runstore_cli.py tests/test_budget_guard.py tests/test_operator_run_cap.py
    → 292 passed.
  • PYTHONPATH=$PWD pytest -q tests/test_changelog_fragments.py → 45 passed.
  • PYTHONPATH=$PWD python -m tools.gen_api_docs --check → docs/api.md is up to date.
  • PYTHONPATH=$PWD python -m tools.changelog_fragments check → 9 changelog fragment(s) OK.
  • Full suite measured before the rebase: at 9db1a14e (that tip tree minus
    only the fragment paragraph) 21 failed, 7929 passed, 51 skipped, 10 errors in 2008.20s; in a clean clone at 050235a4 21 failed, 7924 passed, 53 skipped, 10 errors in 1861.11s. comm on the failed/error ids
    both ways: 31 ids each, 0 tip-only / 0 main-only (docker sandbox,
    era_srbench and env-class OSError/MemoryError only). The skip delta is
    the checkout shape: the baseline ran in a linked worktree, where .git is
    a file, so the two tests/test_repo_hygiene.py rows skip there — the only
    reason for 51 vs 53, and 7924 + 4 + 2 − 1 = 7929.
  • Rebase delta is disjoint: git diff --name-only 050235a4..8d75685a is
    AGENTS.md, .github/scripts/controller.py,
    .github/workflows/controller.yml,
    tests/test_process_controller.py, tests/test_process_controller_draft.py,
    changelog.d/1187-controller-pr-trigger.md,
    changelog.d/1192-draft-skip.md; this branch's six files are
    agentdescent/cli.py, agentdescent/evolvespec.py, agentdescent/mcp.py,
    changelog.d/1196-unpriced-cap-hint.md,
    tests/test_max_usd_refusal_hint.py, tests/test_mcp_call_limit.py — the
    intersection is empty, so the measured suite pair still stands.

Not run:

  • mkdocs build --strict — docstrings only; neither symbol is in
    docs/api.md, and gen_api_docs --check reports it up to date; CI runs
    strict.

@github-actions github-actions Bot added risk:T2 Risk tier T2 (package code or an unnamed path), set by the controller from the diff agent-pr Pull request opened by an agent labels Nov 20, 2026
@HugoXK HugoXK added area:plugins Host plugins and installers: Claude Code, Codex, DSH, OpenCode, MCP server bug Something isn't working labels Nov 20, 2026
…1196)

The row that pinned the tool's sentence by comparing it with the helper's
default proved uniformity, not either surface's text. Every surface now gets a
literal: the CLI flag sentence through cli.main, the tool's argument sentence
(whole), and the field alone for a Python caller.
…1196)

build_call_limit's hint default is now surface-neutral, because runstore.launch
and execute reach it from Python where neither a flag nor a tool argument is
actionable. The CLI passes CLI_CAP_HINT and the MCP tools pass theirs; the two
docstrings say that the reason is shared and the hint is per surface.
@HugoXK

HugoXK commented Nov 21, 2026

Copy link
Copy Markdown
Collaborator Author

Advisory QA read — #1199 at 22c717dabc9abd8189b1c74336410e27ff98b85c

Read live at that head (draft: false, mergeable_state: clean, 0 comments before this one); base 8d75685aecdecb9a93056d8abee661b827a83c28, main 4b46761a6bb69985d86a9495b4eb8e397b3f2a92 — the single commit above the base is #1198 (AGENTS.md + a test docstring). Body Tip SHA: equals the head. 6 files +126/−34 = 160 changed lines → T2 by path (agentdescent/**), under the 250-line / 12-file cap; labels bug + area:plugins + risk:T2 match.

Ran (fresh clone, fetched refs/pull/1199/head):

  • Full offline suite at the tip, one command, -n 8 -o addopts="": 21 failed / 7924 passed / 63 skipped / 10 errors, 275.83s. The same command at base 8d75685a: 21 failed / 7921 passed / 63 skipped / 10 errors, 285.54s. The 31 red ids are the same set id for id (junit both ways, comm empty): 0 new, 0 vanished. The +3 passed is this branch's net test delta (+4 rows, −1 replaced).
  • Red at base, only this branch's two changed test files in a clean 8d75685a worktree: 3 failed, 12 passed in 6.25s — exactly the body's row and the same three ids (test_a_tool_refusal_names_the_argument_it_can_pass, test_a_python_caller_is_told_to_set_the_field_not_a_flag, test_the_default_hint_names_no_surface).
  • Focused set at the tip (test_max_usd_refusal_hint, test_mcp_call_limit, test_budget_guard, test_operator_run_cap, test_evolvespec): 108 passed.
  • python -m tools.gen_api_docs --check → docs/api.md is up to date; python -m tools.changelog_fragments check → 9 fragments OK.

Probes at the tip, one per surface (the point of the change):

  • build_call_limit(max_usd=1.0) → … (set usd_per_call beside it), and no -- anywhere in the message.
  • MCP Tools.plan / Tools.start with max_usd=1.0 → … (usd_per_call in the same tool call); status()["runs"] == [] after both refusals.
  • Python runstore.launch(store, max_usd=1.0) → neutral wording, no --, and the store directory was never created.
  • CLI evolve <spec> --max-usd 1 → rc 2, and its JSON error string is byte-identical to 8d75685a (diff of the two strings empty); compose's evolve.usd_per_call sentence from fix(evolvespec): name the spec field an unpriced dollar cap needs #1185 is unchanged.
  • Call-site grep: cli.py has exactly one build_call_limit (the evolve verb, passing CLI_CAP_HINT), and the internal run worker is pre-validated there; runstore passes no hint by design. No public CLI verb is left with the neutral wording.

Not run: docker sandboxes (no daemon on this box — the same 10 errors at both ends), wheel smoke (no packaging path), real-model / USD probe (offline box, the cap is arithmetic), risk_gate.py (no gh; the tier is computed from .github/agent/risk-rules.json), mkdocs build --strict (no docs/** or mkdocs.yml change; the generated page is reported current).

Findings: none.

No UI surface: refusal wording on the CLI, the MCP tools and the Python API; nothing is rendered.

No merge action from QA: this report is advisory, the merge gate is the repo's review decision on the head sha, and the merge itself is executed by the repo's merge process.

@Birfy

Birfy commented Nov 21, 2026

Copy link
Copy Markdown
Collaborator

Review (Birfy)

Tip SHA: 22c717d
Ran:

  • .github/scripts/risk_gate.py --repo ThinkFlowLab/agentdescent --pr 1199 → T2 (160 lines / 6 files)
  • pytest -o addopts="" -p no:cacheprovider -q tests/test_max_usd_refusal_hint.py tests/test_mcp_call_limit.py tests/test_budget_guard.py tests/test_operator_run_cap.py at this tip → 38 passed
  • python -m tools.changelog_fragments check → 9 fragments OK
  • python -m tools.gen_api_docs --check → docs/api.md is up to date
  • Required CI at this tip → green (build, test (3.9)–test (3.13), otel-wire; deploy skipped; risk tier / reviewed tip report-only)
    Not run:
  • Full offline suite locally — the CI test matrix is the line
  • mkdocs build --strict — docstring-only change; gen_api_docs --check is clean and CI already ran strict
    Findings:
  • No actionable defects. build_call_limit now takes a keyword-only usd_hint whose default (NEUTRAL_CAP_HINT) names the field and no surface, which is what runstore.launch / execute inherit. The CLI passes CLI_CAP_HINT so its sentence stays byte-identical; MCP plan / start name usd_per_call in the same tool call. compose still has its own earlier evolve.usd_per_call refusal, so a spec cap does not pick up a CLI flag. A refused cap still happens before create / launch.
    Verdict: PASS

@Birfy
Birfy merged commit 4337e62 into main Nov 21, 2026
12 checks passed
@Birfy
Birfy deleted the agent/1196-mcp-usd-hint branch November 21, 2026 04:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-pr Pull request opened by an agent area:plugins Host plugins and installers: Claude Code, Codex, DSH, OpenCode, MCP server bug Something isn't working risk:T2 Risk tier T2 (package code or an unnamed path), set by the controller from the diff

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(mcp): the tool surface refuses an unpriced max_usd by naming a CLI flag its caller cannot pass

2 participants