fix(agents): persist pending_action for gated tool calls

[w7-mgfcode]

Root cause

The experiment agent can call an approval-gated mutation tool (save_scenario, create_alias, archive_run). Those tools returned {"status":"approval_required", ...} to the model, but never wrote a machine-readable pending_action to session/deps state. service.chat() / stream_chat() decide approval by inspecting final_result.pending_action / final_result.approval_required — fields that the agent's structured output (ExperimentReport) does not define. So a gated call left the session active, persisted no pending_action, and emitted no approval_required event — the Chat UI received only the assistant's prose and showed no Approve/Reject card. (Investigation: session e4fe2f76… logged tool_save_scenario requires_approval=true, yet agent_session.pending_action stayed null and status stayed active.)

Fix

Deterministic, deps-based propagation (does not depend on the model echoing the request into its output):

• AgentDeps gains a pending_action: dict | None slot + set_pending_action(action_type, arguments, description).
• The three gated tools call ctx.deps.set_pending_action(...) when approval is required, before returning the approval dict. The save_scenario arguments are exactly what _execute_pending_action replays on approval.
• service.chat() and service.stream_chat() check deps.pending_action first (new shared _record_pending_action helper), persisting session.pending_action, flipping the session to awaiting_approval, and emitting the approval_required event. The legacy final_result.pending_action / approval_required checks remain as fallbacks.
• ExperimentReport is intentionally left unchanged (the model-dependent alternative was the fragile path).

Tests

Three new regression tests in app/features/agents/tests/test_service.py:

• test_set_pending_action_records_request — AgentDeps.set_pending_action records the request.
• test_chat_persists_pending_action_from_deps — chat() persists pending_action + sets awaiting_approval when the output has no approval field.
• test_stream_chat_emits_approval_required_from_deps — stream_chat() emits the approval_required event from deps.pending_action.

Covers the full chain: gated tool → deps.pending_action → awaiting_approval → approval_required.

Validation

• ruff check ✅
• ruff format --check ✅
• mypy app/ ✅ — only pre-existing xgboost optional-dep import-not-found errors in untouched files (forecasting/, registry/)
• pyright app/features/agents/ ✅ 0 errors
• pytest -m "not integration" ✅ 1650 passed, 12 skipped (agents slice 139, scenarios 53)

Notes

• The live Gemini HITL round-trip was not re-tested because the Google free-tier quota was exhausted (see fix(config): reject doubled provider prefixes in agent model ids #334 / quota); the new unit tests cover the deterministic backend logic.
• Companion issues from the same investigation: fix(config): reject doubled provider prefixes in agent model ids #334 (doubled provider prefix), fix(agents): surface fallback model failures with actionable details #335 (surface fallback model failures).

Closes #336

[sourcery-ai]

Sorry @w7-mgfcode, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b9b1b621-9be2-4acf-9180-3a17742c33b8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/agents-persist-pending-action

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}