Pass the spend threshold exactly and persist it in model_call traces

Two defects found by the commit gate while integrating #241:

- claude_code formatted the threshold with `.4f`, moving the boundary:
  0.00001 became "0.0000" (no threshold) and 0.12345 became "0.1235" (a higher
  one). budget_arg() now emits the float's shortest round-trip decimal in plain
  notation, rejects non-positive/non-finite values, and is tested on tiny
  thresholds.
- runtime.trace_recorder dropped max_budget_usd (and cost_usd), so production
  traces never persisted them. They now land in the model_call record's
  result (null when unset/unknown), including transport-failure records;
  tested through the real recorder and TraceStore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: tzhouam

doc/architecture/SPEC/kb_service.md

@@ -306,3 +306,5 @@ diff 时保留原摘录（证据不会因此变得更"好过"）。只扩展带
 x 必须为正。因阈值停下的调用（`stop_reason="max_budget"`）→ `ModelUnavailable`，并作为失败记录（不会成为训练样本）。
 `ModelReply.cost_usd` 取自 `usage["cost_usd"]`（未知为 None），trace 记录同时写入 `cost_usd` 与 `max_budget_usd`。
 不传上限的现有调用方行为不变：该参数根本不会发给 transport。
+`runtime.trace_recorder` 把阈值与花费持久化到 `model_call` 记录的 `result.max_budget_usd` / `result.cost_usd`
+（未设或未知为 null），包括 transport 抛错的失败记录。

doc/architecture/SPEC/providers/claude_code.md

@@ -48,3 +48,5 @@ stdlib + `.base` + `..agent_loop.AgentOutcome` + `..llm` 的类型。
 `stops_at_spend = True`：`complete(max_budget_usd=x)` 把 `--max-budget-usd x` 传给 CLI（仅 print 模式有效，`_run` 正是 print 模式），
 x 必须为正。CLI 在每个 API 请求完成**之后**检查预算：它阻止下一个请求，不能截断当前请求，所以花费可超出 x 一个请求。CLI 因预算停下（`subtype` 含 budget）时返回 `stop_reason="max_budget"` 且无文本 —— 被截断的回答永远不可用。
 `total_cost_usd` 以 `usage["cost_usd"]` 返回。
+阈值参数由 `budget_arg()` 精确生成：浮点数的最短往返十进制、普通（非科学）记数法；非正、非有限值 → `ValueError`。
+固定精度格式会移动边界（`.4f` 把 0.00001 变成 "0.0000" 即没有阈值，把 0.12345 变成 "0.1235" 即更高的阈值），所以不允许。

src/infermatrix_copilot/kb_service/models.py

@@ -129,6 +129,7 @@ def call_json(self, role: ModelRole, *, system: str, prompt: str,
         except Exception as exc:  # the transport's own failure modes
             if self._recorder is not None:
                 self._recorder({**identity, "served_model": "", "stop_reason": "", "usage": {},
+                                "cost_usd": None, "max_budget_usd": max_budget_usd,
                                 "seconds": round(time.time() - started, 3), "system": system,
                                 "prompt": prompt, "reply": "", "error": str(exc)[:2000]})
             raise ModelUnavailable(f"{role.label()} failed: {exc}") from exc

src/infermatrix_copilot/kb_service/runtime.py

@@ -128,7 +128,12 @@ def record(entry: dict) -> None:
                 outputs={"reply": entry["reply"]},
                 model={k: entry.get(k, "") for k in ("role", "provider", "model", "effort", "served_model")},
                 usage=entry.get("usage") or {}, seconds=entry.get("seconds"),
-                result={"stop_reason": entry.get("stop_reason", "")}, error=entry.get("error", ""))
+                # spend: the requested stop threshold and the reported cost
+                # (None when unset/unknown), on failures too
+                result={"stop_reason": entry.get("stop_reason", ""),
+                        "max_budget_usd": entry.get("max_budget_usd"),
+                        "cost_usd": entry.get("cost_usd")},
+                error=entry.get("error", ""))
         except Exception:  # noqa: BLE001 - tracing never breaks a model call
             pass
 

src/infermatrix_copilot/providers/claude_code.py

@@ -22,8 +22,10 @@
 from __future__ import annotations
 
 import json
+import math
 import subprocess
 import sys
+from decimal import Decimal
 from pathlib import Path
 
 from ..agent_loop import AgentOutcome
@@ -43,6 +45,17 @@
 _BRIDGE_SERVER = "infermatrix-tools"
 
 
+def budget_arg(value: float) -> str:
+    """The threshold as the CLI argument, EXACTLY: the float's shortest
+    round-trip decimal in plain (never scientific) notation. Fixed-precision
+    formatting would move the boundary: `.4f` turned 0.00001 into "0.0000"
+    (no threshold at all) and 0.12345 into "0.1235" (a higher one)."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)) \
+            or not math.isfinite(value) or not value > 0:
+        raise ValueError(f"max_budget_usd must be a positive finite number, got {value!r}")
+    return format(Decimal(repr(float(value))), "f")
+
+
 class ClaudeCodeTransport(HarnessTransport):
     """claude CLI (headless) as a Strict backend."""
 
@@ -69,9 +82,7 @@ def _run(self, prompt_text: str, *, system: str, cwd: str,
         if selected:
             cmd += ["--model", selected]
         if max_budget_usd is not None:
-            if not max_budget_usd > 0:
-                raise ValueError(f"max_budget_usd must be positive, got {max_budget_usd!r}")
-            cmd += ["--max-budget-usd", f"{max_budget_usd:.4f}"]
+            cmd += ["--max-budget-usd", budget_arg(max_budget_usd)]
         if mcp_config is not None:
             cmd += ["--mcp-config", str(mcp_config), "--strict-mcp-config",
                     "--allowedTools", f"mcp__{_BRIDGE_SERVER}"]

test/test_kb_spend_cap.py

@@ -57,7 +57,7 @@ def test_claude_passes_the_cap_only_when_given(tmp_path):
 
     reply = transport.complete(system="S", messages=MESSAGES, max_budget_usd=0.5)
     argv = _argv(tmp_path)
-    assert argv[argv.index("--max-budget-usd") + 1] == "0.5000"
+    assert argv[argv.index("--max-budget-usd") + 1] == "0.5"
     assert reply.usage["cost_usd"] == pytest.approx(0.07)
     assert reply.stop_reason == "end_turn"
 
@@ -152,3 +152,78 @@ def test_gateway_treats_a_call_stopped_at_its_cap_as_unavailable():
 def test_gateway_rejects_a_non_positive_cap():
     with pytest.raises(ModelUnavailable, match="positive"):
         _gateway(_Transport(capped=True)).call_json(ROLE, system="S", prompt="P", max_budget_usd=-1)
+
+
+# -- exact threshold argument ----------------------------------------------------
+
+@pytest.mark.parametrize("value, expected", [
+    (0.00001, "0.00001"),        # `.4f` made this "0.0000": no threshold at all
+    (0.12345, "0.12345"),        # `.4f` made this "0.1235": a HIGHER threshold
+    (1e-9, "0.000000001"),       # never scientific notation
+    (0.5, "0.5"),
+    (3, "3.0"),
+    (1234.5678, "1234.5678"),
+])
+def test_budget_arg_is_exact(value, expected):
+    from decimal import Decimal
+
+    from infermatrix_copilot.providers.claude_code import budget_arg
+
+    arg = budget_arg(value)
+    assert arg == expected
+    assert Decimal(arg) > 0 and float(arg) == float(value)  # never rounded to 0, never moved
+
+
+@pytest.mark.parametrize("bad", [0, -0.1, float("nan"), float("inf"), True, "0.5"])
+def test_budget_arg_rejects_non_positive_or_non_finite(bad):
+    from infermatrix_copilot.providers.claude_code import budget_arg
+
+    with pytest.raises(ValueError):
+        budget_arg(bad)
+
+
+def test_claude_passes_a_tiny_threshold_unrounded(tmp_path):
+    _claude(tmp_path).complete(system="S", messages=MESSAGES, max_budget_usd=0.00001)
+    argv = _argv(tmp_path)
+    assert argv[argv.index("--max-budget-usd") + 1] == "0.00001"
+
+
+# -- persisted through the REAL recorder -------------------------------------------
+
+def _store_gateway(tmp_path, transport):
+    from infermatrix_copilot.kb_service.runtime import trace_recorder
+    from infermatrix_copilot.trace_store import TraceStore
+
+    store = TraceStore(tmp_path / "traces", environ={})
+    return store, ModelGateway(None, transport_factory=lambda provider: transport,
+                               recorder=trace_recorder(store))
+
+
+def test_trace_persists_threshold_and_cost(tmp_path):
+    store, gateway = _store_gateway(tmp_path, _Transport(capped=True))
+    gateway.call_json(ROLE, system="S", prompt="P", max_budget_usd=0.00001)
+    (record,) = store.query(kind="model_call")
+    assert record["result"]["max_budget_usd"] == 0.00001
+    assert record["result"]["cost_usd"] == pytest.approx(0.12)
+
+
+def test_trace_persists_threshold_on_transport_failure(tmp_path):
+    class Exploding(_Transport):
+        def complete(self, **kwargs):
+            raise RuntimeError("cli crashed")
+
+    store, gateway = _store_gateway(tmp_path, Exploding(capped=True))
+    with pytest.raises(ModelUnavailable):
+        gateway.call_json(ROLE, system="S", prompt="P", max_budget_usd=0.25)
+    (record,) = store.query(kind="model_call")
+    assert record["error"]
+    assert record["result"]["max_budget_usd"] == 0.25
+    assert record["result"]["cost_usd"] is None
+
+
+def test_trace_without_a_threshold_records_none(tmp_path):
+    store, gateway = _store_gateway(tmp_path, _Transport(capped=False, usage={}))
+    gateway.call_json(ROLE, system="S", prompt="P")
+    (record,) = store.query(kind="model_call")
+    assert record["result"]["max_budget_usd"] is None
+    assert record["result"]["cost_usd"] is None