feat: configurable retry policy as a top-level retry: root

[uipreliga]

Summary

Split out of #34, addressing @akshaylive's review on that PR:

The weight 0 fix LGTM. The configurable retry policy should ideally be a separate PR. Additionally the retry policy configuration shouldn't be in "run_limits" (retry policy is not really a limit, so a separate top level field is better). I haven't looked too deep into the impl but would this clear the working directory between retries?

All three points are taken:

Comment	Resolution
Should be a separate PR	This PR. #34 is now the weight-0 fix alone.
Shouldn't live under run_limits	Moved to a top-level retry: block and its own -D root — see below.
Does it clear the working directory between retries?	No. Answered in detail below and documented in the guide.

Stacked on fix/weight-zero-gating-and-retry-policy (#34) — retarget to main once that merges.

Configurable retry policy

• New RetryPolicy (models/retry.py): max_retries / initial_delay / backoff_multiplier, all optional.
• It lives at the task's top level (retry:), not under run_limits. Per review: run_limits holds caps that abort a run, whereas a retry policy is how hard the run tries to survive a transient error.
• retry is a first-class 4th -D root alongside agent/run_limits/sandbox: -D retry.max_retries=0 to fail fast while debugging. It merges through the same resolve_root engine at every layer (experiment defaults → task → variant → CLI), so the unification invariant holds — two new tests/test_merge_unification.py cases pin it.
• All retry decisions resolve through one seam, errors/retry.py::resolve_retry_config. A category that is non-retryable in the built-in table (auth/billing) is never made retryable by a per-run override — retryability is a property of the error, not the run.
• Persisted error_details.is_retryable / retry_delay_seconds in task.json now reflect the run's actual policy instead of the built-in defaults.

Review question: does this clear the working directory between retries?

No — and the guide now says so explicitly. A retried communicate() re-sends the prompt into the same sandbox and the same agent session; the working directory is not reset, so files the failed attempt already wrote survive into the retry. The crashed attempt's partial turn is also preserved on the result (deliberate, for crash forensics), which means trajectory-observing criteria (command_executed, commands_efficiency, skill_triggered) see both attempts.

I chose to document this rather than add a reset seam: resetting mid-task would discard work the agent already did and budget already spent. retry.max_retries: 0 is the escape hatch when you need a clean single-attempt trajectory. Happy to add the reset if reviewers prefer it.

Test plan

• make verify green — 3450 passed, 2 skipped, ruff + pyright + custom CE lint clean.
• New tests: retry-policy resolution + fail-fast, error_details policy fidelity, -D retry.* override + field-merge + did-you-mean on an unknown key, and merge-unification parity for the new root.

🤖 Generated with Claude Code

[github-actions]

Claude finished @uipreliga's task in 1m 25s —— View job

---

Code Review in Progress

Review Tasks:

• Read .github/code_review.md for review standards
• Read CLAUDE.md for project conventions
• Run git diff to see full changes
• Review all 16 changed files with full context
• Check cross-file consistency
• Analyze "what's missing"
• Provide design-level feedback
• Complete final review summary

Starting review now...

---