fix(582): preflight warns when kind:tool UDF may not always emit a required schema field

[Muizzkolapo]

Summary

Post-568 (flat schema fields required-by-default), a kind: tool action's UDF can declare a field required in the compiled output schema but only emit it inside a conditional branch. The runtime crashes mid-pipeline (_validate_udf_output → 'X' is a required property) whenever the guard misses. The qanalabs reconstruct_options action hit this at 39/52 records: source_quote was required, but apply_edited_distractors only writes result['source_quote'] = flat['source_quote'] inside if 'source_quote' in flat.

This PR adds a static-AST preflight warning that names action + field before the run starts. Warning-only; agac inspect exit stays 0, consistent with the 566/567/569 preflight family.

Design

agent_actions/validation/udf_required_field_validator.py:

• Bounded intra-function AST scan — never imports or executes the UDF; source only, via inspect.getsource(function).
• Recognises unconditional emit shapes: return {"k": ...}, initial result = {"k": ...} dict-literal assignment, top-level result["k"] = ..., top-level result.update({"k": ...}).
• Errs toward silence — any shape it does not fully recognise (helper-call init, **spread, list return, mid-function reassignment) yields None and no warning. This preserves "0 false positives on tools that unconditionally emit their required fields" (spec's Verification bullet).
• Tail-return search stops at nested FunctionDef/AsyncFunctionDef/Lambda boundaries so a helper defined below the outer's return cannot shadow it.

agent_actions/services/preflight_service.py adds _collect_tool_required_field_inputs + _warn_tool_conditional_required_field_risks, wired as step 8 after the sibling passthrough check. Reads json_output_schema.required (the tool path always compiles via the openai dialect → dict shape).

Deviations from the spec: the spec listed PreflightService.validate() and/or ValidateUDFsCommand as wire points. ValidateUDFsCommand operates on raw config that has not yet been through schema compilation (no json_output_schema.required to compare against), so wiring landed only in PreflightService. agac inspect and agac run both go through PreflightService, matching the spec's Success metric.

Verification story

• Harness gates: gate.sh red recorded a genuine assertion failure at the PreflightService.validate() wire point (no ImportError-based fake-RED). gate.sh green re-runs the RED test hash-checked against tampering, then full pytest (8136 passed), ruff format --check, ruff check, mypy agent_actions.
• HIGH-tier review: 3/3 YES from correctness / blast-radius / tests-anti-gaming blind reviewers. Correctness reviewer flagged a nested-function edge case (a helper defined below the outer's tail return would be picked as the tail via ast.walk); fixed in the follow-up commit with a dedicated regression test (test_nested_helper_return_does_not_shadow_outer_tail).
• Smoke: skipped — risk.sh reports smoke_required=no; the diff is preflight-only (new validator + wiring), touches no runtime/config-load surface or smoke-registry paths.
• Real-project verification: prototype detector run against every @udf_tool function in the qanalabs tools/qanalabs-quiz-gen/ tree during development. On apply_edited_distractors the unconditional set is exactly {options, answer, answer_text} (matching the initial dict literal); every other required field is correctly flagged. On tools that emit unconditionally via a full dict literal (e.g. assemble_question), the emitted set covers every required field and no warning fires.

Test plan

• Assertion-level wire-point RED (tests/validation/test_udf_required_field_wiring.py) proves the warning behavior at the public PreflightService.validate() API without importing the new symbol.
• Unit suite (tests/validation/test_udf_required_field_validator.py) — 17 cases covering: qanalabs reproducer, unconditional dict literal / via-name / top-level subscript / .update({...}), conditional-only, helper init, **spread, early guard return, list return, subscript-inside-if, additionalProperties: true does not suppress the check, no-required-fields no-op, missing source ignored, syntactically-invalid source ignored, multi-action correctness, nested-helper-does-not-shadow-outer-tail.
• Full pytest green (8136 passed). mypy agent_actions clean. ruff clean.

🤖 Generated with Claude Code