[guamiao]

Closes #2149.

Rationale for this change

The agent tool recovery evaluation (#2067 / #2146) found four failed PowerContext tool results that did not tell the agent what to change: three Server 422 responses omitted the rejected field, and the Codex plugin reported an authorization denial as a Scope-binding failure. Agents guessed, retried with changed arguments, or told the user the wrong cause.

What changes are included in this PR?

• Dream evidence selection (create_dream_run): an empty artifacts selection reports loc=["artifacts"] with type evidence_selection_required; more than 20 Artifacts reports artifacts with evidence_limit_exceeded; more than 32 references counting Sources reports sources with evidence_limit_exceeded. Messages state the bounds for the selected operation: revise_tags has a combined limit of 32 references and no separate 20-Artifact limit.
• Candidate validation (propose_experience): InvalidCandidateError details map the internal artifacts field to the public artifact_refs field with a stable reason (target_not_in_artifact_refs), and name target for family/target failures. Internal-only fields and reasons shared by several public fields keep details: null; no exception text is echoed.
• Working-note expiry (capture_working_note): a past expiry returns {"field": "expires_at", "reason": "not_in_future"}, and the runtime separates working-note-expiry-timezone from working-note-expiry-past. Replay of an existing note is unchanged.
• Codex plugin: the PreToolUse hook now classifies 401 as an authentication failure and 403 as an authorization denial, keeps transport and unresolved-binding failures on the existing reason, and catches protocol-level http.client errors so the hook denies instead of crashing.
• Tests: field-level validation tests for the Dream bounds, mapping tests for candidate errors, HTTP-level assertions for the 422 bodies (including the revise_tags boundary), and direct runtime tests for both expiry reasons.

Status codes and outer error codes are unchanged. No OpenAPI or generated model changes were required (scripts/generate_api.py --check passes).

Are there any user-facing changes?

Error details now carry a field name and a stable reason so an agent can correct the request. No endpoints or request fields change. Known limits:

• Candidate errors with no unique public field (evidence, basis, audit, family) and the approve-only lineage sources error keep details: null.
• A naive expires_at is rejected by the transport model as timezone_aware; the field/reason shape applies to the past-expiry path and to direct runtime calls.
• A pre-existing admission/execution mismatch remains for revise_tags: the runtime appends tag_target.basis_ref to the resolved Artifacts, so a 32-reference selection is only valid end to end when that basis Artifact is already part of the selection. This PR only corrects the admission message; the counting mismatch should be handled separately.

How was this change tested?

• pytest tests/builtin/dream tests/builtin/review tests/e2e/test_builtin_runtime.py tests/e2e/test_runtime_server.py tests/e2e/test_artifact_dreaming.py tests/e2e/test_candidate_review.py tests/test_api_contract.py tests/test_error_details.py tests/e2e/test_request_error_details.py -q → 194 passed, 82 skipped (before the review follow-up).
• pytest tests/builtin/dream tests/e2e/test_request_error_details.py -q → 11 passed (after the review follow-up).
• pytest tests/codex_plugin/test_scope_binding.py -q → 84 passed.
• ruff check, ruff format --check, and ty check on the changed files pass.
• python scripts/generate_api.py --check passes.
• Known unrelated Windows failure: tests/builtin/runtime/test_extraction_diagnostics.py::test_extraction_diagnostics_observes_spawned_worker_failure_and_stopped_supervisor[_worker_crash-...] also fails on a clean upstream/master checkout.

AI usage statement

AI-assisted: Claude Code (Anthropic, Claude Sonnet 4.6) was used to implement the change and write the tests. The resulting diff was reviewed by two independent agent reviewers, and the reviewer P3 finding was addressed in commits 3835fbda and 641469f8.

[hidb4ai]

One non-blocking P3 issue in the evidence-limit diagnostic.

[hidb4ai]

LGTM