feat(llm): the per-phase request-side thinking policy — exposed, gated, recorded (#625)

[gadievron]

Fixes #625. Follow-ups named below (the echo-preservation design; thinking_tokens capture; the Bedrock knob) — recorded, not filed here.

What was wrong

Two gaps, one theme — the request-side instrument:

• No request-side thinking control while the SDK's messages.create accepts one — and the response's output_tokens includes thinking tokens, so the spend rode either way with no way to steer or explain it.
• The response translation dropped unsupported block kinds (thinking, refusal) with a once-per-kind stderr warning while forwarding their usage — the delivered content and the billed content could differ by an invisible amount, and a dropped refusal beside a benign stop_reason could read as an empty success (the file's own comment).

This is an enhancement with the hard constraint the issue itself names: the default stays byte-identical (the #242 instrument lesson — verdict behavior is evaluated separately, never mixed with a usage-accounting change).

The fix

• thinking on the config's phases (the SDK's own dict shapes — adaptive / enabled+budget / disabled; absent = no key sent, an explicit disabled is a distinct request that survives the round-trip). Parse-time validation rejects malformed shapes naming the config and phase; the enabled budget is bounded below the pipeline's smallest sub-call cap (4096 — the JSON-correction and stage-1-consistency requests ride the same binding at that cap, a larger budget would fail them mid-scan, and the consistency pass's exception handling would swallow it silently).
• Tool-calling phases are gated loudly (the platform requires thinking blocks echoed back with tool results; this pipeline's loops carry text and tool-use only): enhance/verify reject a policy at registry build before any adapter is built, and an adapter-level backstop covers every other tools= call site — including the threat-model repository exploration, which the build-time list cannot name (it drives both a single-turn path and a tool loop). One adapter per (provider, thinking) tuple.
• The policy is visible and identity-bound: recorded present-only in the step inputs and results.json; folded into the analyze/verify/llm-reachability checkpoint identities only-when-set — a resumed scan never adopts verdicts produced under a different policy (the fix(analyzer): recover reasoning-only empty-completion analyze responses #242 gen-params exclusion was conditional; a thinking policy changes ordinary successes, so the fold is the honesty mechanism). Default users' digests are unchanged — zero re-pay. The Go wizard now preserves hand-authored phase keys on re-runs.
• The dropped blocks are counted, per kind, and persisted: dropped_blocks on every result (per-kind by design — a routine thinking drop can never bury a dropped refusal) plus a run-cumulative per-kind counter that reaches the step reports' token_usage.dropped_blocks in both the success and the accounting-error branches. Present-only — clean runs' artifacts are byte-identical.

Evidence

• RED on base 6dde272 (final bytes, copies byte-identical): the two test files 26 RED / 1 GUARD (the reset-lifecycle row, green at base by design) — the default request's full-dict equality (no thinking key, no junk keys), the three shapes threading, the budget pre-flight (assert_not_called), the parse-time rejection matrix, the round-trip (None-vs-disabled), the tool gate naming the phase, the adapter backstop, the disabled-passes rows, the per-kind counts, the fingerprints' behavioral folds, the step surfaces, the Go merge.
• GREEN at head: 27/27 across the two files; the adjacent battery (the anthropic adapter, provider warnings, The Google adapter's requests carry no I/O deadline (genai's default is explicit timeout=None) — expose a per-adapter timeout knob and set HttpOptions.timeout #604's knob tests, config schema, backend identity, Backend fingerprint omits generation parameters, so changing max_tokens does not invalidate verify checkpoints #287, Cost accounting under-reports by ~15%, concentrated in the Claude Opus 5 phases #211, Silent accounting drops: the report-phase tracker hand-off and the step-report zero-snapshot swallow failures into complete-looking zero cost #605) all green.
• Full suite, matched conditions: head 4344 passed / 34 skipped / 2 failed (the pre-existing test_llm_sdk_contract_floor SDK-pin pair, reproduced identically on pristine master; CI's pinned env is authoritative); base 4288 / 34 / 28 — skipped 34=34, the passed delta exactly the RED rows flipping.
• SAST: ruff clean; Semgrep 0 new (the 1 hit is the pre-existing reset-loop import, untouched — the git-diff grep receipt); CodeQL (643 files) — 0 new (9 in-file hits all pre-existing or the intentional local-import convention; hunk-located in the receipt).
• The hunt loop to exhaustion: three fable rounds + the four-model panel. r1 caught the gate's own error message recommending app_context — which drives the threat-model tool loop (the phase the list cannot name; the adapter-level backstop adopted); and the budget pre-flight's per-call blindness (the consistency pass's bare except would swallow the mid-range-budget failure silently — the parse-time 4096 bound adopted). r2 caught the vacuous warning row and the untested step-report folds; r3 EXHAUSTED after the vacuous-row removal, the SUBCALL_BUDGET_CAP constant (the pin binds the shadow to the real constants), and the leaking-row finally.

The de-balancing check (the intent trace)

serves: I-ctx (the attacker-model instrument knob — visible and identity-bound), I-out (the delivered-vs-billed reconciliation persisted). de-balances-checked: the default request byte-identical (full-dict equality pinned); the artifacts present-only on the default path; validate() carries no policy (the 1-token probe cannot satisfy the budget constraint — documented at the site); the #211 usage_details channel untouched (dropped_blocks is a separate field); add_prior_usage untouched; the fingerprint folds only-when-set (zero re-pay); the Go merge preserves only hand-authored keys.

Notes for the reviewer

• Known residuals, scoped: the startup probe carries no thinking (a shape the server rejects for the model surfaces at the first real call, typed — the parse-time validation catches the client-side shapes first); the step-report dropped_blocks is run-cumulative (the Silent accounting drops: the report-phase tracker hand-off and the step-report zero-snapshot swallow failures into complete-looking zero cost #605 accepted trade — a reader summing across steps overcounts); thinking_tokens (the SDK ≥ 1.5.0 field that does split thinking from output) is deliberately a separate change; Bedrock does not consume the knob (warns once; its shared response translation does gain the counts).
• The echo-preservation design (an opaque provider-block round-trip through the loops) is the named follow-up that unlocks thinking on the tool phases.

---

CI anomaly (recorded, not laundered): the tests and gitleaks workflows did not dispatch for this PR — a repo-wide pull_request dispatch outage, not a failure: two pushes (incl. a retrigger) and a fresh PR number produced only the CodeQL workflows (gh api .../workflows/247980277/runs shows the last pull_request-triggered tests run was for another branch at 09:12Z; the workflow_dispatch API is unavailable for these workflows). The CodeQL matrix IS green (Python/Go/JS-TS/actions analysis + Mergeable — 16 checks, all SUCCESS). The full test suite + Go tests are green locally against the exact commit (the receipts above — python3 -m pytest tests/ -q: 4314 passed / 34 skipped / 2 pre-existing SDK-pin failures; go test ./internal/config/: ok). The merge should wait for the tests workflow to dispatch (or the human verifies via the local receipts).

[gadievron]

Conflict with master resolved on 5b920d0 — CHANGELOG-only, both release-note sections kept (2026-09-20 above 2026-09-19), nothing else changed in the resolution. The branch's tests + gitleaks workflows are dispatching on this head for the first time now that it is conflict-free.

@sounil — a code-owner review would be appreciated once the checks land: this change touches the LLM pipeline (phase config, registry, adapters, llm_client, step-report usage) and the llm-reachability checkpoint identities, so a second pair of eyes on the gating + accounting would be valuable.

[gadievron]

Disposition ruling needed — #625 is closed by #660; this PR needs a decision, not a conflict resolution.

#660 (46df6fd, merged 2026-09-21 17:24Z) closed #625. This branch (b58c2146) is now conflicting with master on 5 files (scanner.py, adapter.py, providers/anthropic.py, registry.py, llm_client.py — 15 hunks), and the two designs also collide semantically in the LLM config (a provider-entry thinking key vs this branch's phase-entry key). This comment lays out what each side has, verified at both trees, so the maintainer can pick a direction. Three options:

1. Close as superseded — the follow-ups below get filed as issues and re-implemented on the landed design.
2. Re-scope as a delta on the landed design — cherry-pick this branch's hardening; needs a granularity ruling first (phase-entry vs provider-entry thinking — provider aliases can express per-phase policies today, at config cost).
3. Revert feat(llm): request-side thinking control, effective-policy records, dropped-block diagnostic (#625) #660 — a maintainer action; I won't create or merge a revert PR.

Gaps on landed master today (independent of this branch's fate — each verified at abd1dcf):

• A rejected thinking policy fails per-unit, green. The guard lives inside the request path (providers/anthropic.py:206-225 — its comment says "build time" but it is per-request), and a thinking-named 400 reaches the per-unit catch-alls (core/analyzer.py:226, core/llm_reachability.py:744) → every unit errors while the CLI envelope reads success (exit 0 when no vulnerable/bypassable findings). This branch's ThinkingPolicyRejectedError makes the identical class fail closed (exit 2, zero downstream spend) — executed on both trees.
• dropped_block_kinds is computed but never persisted — zero production readers (utilities/llm/adapter.py:226, providers/anthropic.py:378-474 produce it; nothing consumes it). This branch persists per-kind counts as per-step deltas + a scan-level aggregate.
• anthropic[bedrock]>=0.40.0 predates the thinking parameter (it exists from 0.47.0) — the declared floor admits installs where every thinking call would TypeError. This branch floors at 0.47.0 with a capability test. (The requirements pin 1.7.0 masks this today.)
• No budget preflight — an enabled budget_tokens ≥ the call's max_tokens reaches the SDK (executed: budget 8000 @ cap 4096 forwarded on master; this branch refuses it pre-send with zero SDK calls).

What the landed design has that this branch lacks (keep in any successor): Bedrock thinking consumption; the central fingerprint_for_binding policy fold (core/backend_identity.py:197-229); the consistent per-step policy summaries; the standalone generate-context policy record.

Design-coupled deltas on this branch (valuable only if per-phase lands): phase-entry thinking with parse-time validation; the registry-build tool-phase gate; the Go wizard's phase-entry sibling-key preservation (provider entries are already preserved on master — internal/config/config.go:379-399 vs :408-415 — so this is not a live master bug); the distributed verify/llm-reach fingerprint folds with tests.

Debts either way: the behavioral regression test for the fatal-policy guard; the pre-existing auth-error green-scan class (401 on analyze → exit 0); the standalone-CLI policy-recording scope. The branch and all its receipts stay as-is pending the ruling.

Agent: PR-MERGE ses_f3e3e9b11ffetbZil76EvwfDum