feat(eval): add --agent and AGENTOPS_AGENT override for the eval target

[Paulo Lacerda (placerda)]

What this is

An override seam for the eval target, not a fix for #388. The first push on this
branch claimed to fix stale-version evaluation. It does not, and the reasons are
worth writing down so nobody rediscovers them.

agentops eval run now accepts --agent, falling back to the AGENTOPS_AGENT
environment variable. A bare number (--agent 12) replaces just the version
segment of the configured target; a full agent reference replaces it outright.
Unset means unchanged.

RunOptions.agent_override already existed at orchestrator.py:56 and was
already consumed by all three execution backends via
classify_agent(options.agent_override or config.agent, ...). A repo-wide grep
for agent_override returned exactly four lines: the field and the three
consumers. Nothing ever set it. This connects the CLI to that seam.

#388 stays open. No Fixes / Closes here.

Why this does not fix #388

Nothing produces AGENTOPS_AGENT. A grep across src/ and templates/
finds the constant, the CLI consumer, the six injection sites, and nothing else.
On GitHub Actions ${{ env.AGENTOPS_AGENT || vars.AGENTOPS_AGENT }} resolves to
an empty string. On Azure DevOps $(AGENTOPS_AGENT) arrives verbatim and the
unexpanded-token guard strips it. Both paths fall back to the pin, so a user on
this build reproducing #388 sees behavior identical to 0.8.4.

A producer cannot be bolted on without restructuring the templates. Two
reasons, either of which is sufficient:

1. The eval gate is structurally pre-deploy in every generated template. Real
   job order is eval -> build -> deploy for placeholder mode and
   provision -> eval -> deploy for azd mode, not the provision -> deploy -> eval the issue describes. If the deploy step is what publishes the new
   Foundry version, then no value of AGENTOPS_AGENT can be correct at the time
   eval runs, because that version does not exist yet.
2. The injected expressions read same-job env scope, which cannot receive a
   value from a prior job or stage. Producing one requires declared
   jobs.<id>.outputs plus needs.<job>.outputs.* on GitHub Actions, or
   explicit stageDependencies mapping on Azure DevOps. Those six expressions
   would have to be rewritten, not just fed.

Which azd verb creates the new agent version

Not determinable from this repository, and that is a real answer rather than a
dodge: this repo does not own the file that decides.

Evidence checked:

• No azure.yaml is shipped anywhere under src/. The generated azd workflows
  invoke a user-authored azure.yaml and fail with "No azure.yaml found"
  when it is absent.
• The template header states it directly: "AgentOps only gates quality; azd owns
  provision, deployment packaging, and any hooks declared in azure.yaml"
  (agentops-deploy-dev-azd.yml).
• azd ai agent appears only as eval subcommands (eval init, eval generate, eval run, eval show) across azd_runner.py, azd_eval_init.py,
  orchestrator.py, and docs. There is no azd ai agent create / publish /
  deploy anywhere in the repo.
• docs/ci-github-actions.md:260 describes azd provision as creating the ARM
  deployment from infra/main.bicep. Nothing describes either verb publishing a
  Foundry agent version.
• No Foundry SDK call in the azd path creates a version. The only
  client.agents.create_version call is in prompt_deploy.py:496, which is
  prompt-agent mode, not azd mode.

So the answer depends on the user's own azure.yaml. An agent declared as an
ARM/Bicep resource under infra/ lands during azd provision. An agent
published by a postdeploy hook or a service definition lands during azd deploy. Whoever fixes #388 needs to determine this per-project, or pick a
mechanism that does not depend on the answer (for example, having eval resolve
"latest" at run time, or moving the gate after deploy with an explicit rollback).

Prompt-agent mode is the one case the repo does answer, and it is already
immune: prompt_deploy.stage_prompt_agent_candidate writes
.agentops/deployments/agentops.candidate.yaml with a fresh agent value, and
cicd.py:906 points the prompt-agent eval step at it.

workflow analyze

The previous push added a warning that fired on every correctly-pinned hosted
project, including eval-only repos with no deploy pipeline, and told users to
export AGENTOPS_AGENT "with the version the deploy step resolved" when nothing
produces that. Unactionable advice at scale is worse than silence.

The warning is gone. The signal now fires only when the repo also has a generated
deploy pipeline, which is the only place a deploy step could move the target
underneath the gate, and its text describes the limitation and points at #388
rather than instructing an impossible action.

Known limitations of this seam

• OFFICIAL_EVAL_RUNNER ignores the override entirely. That branch
  (cicd.py:523-590) routes through official_eval.py, which calls
  classify_agent(config.agent, ...) with no override parameter. --agent has
  zero effect there.
• Governance gates would diverge. The ASSERT and Red Team gates run
  --config {config_path} with no override. Once eval can follow a deployed
  version, those gates would score a different artifact than eval did.
• No validation of override values. apply_agent_version_override returns a
  non-numeric override verbatim, so malformed input (12abc, a truncated
  endpoint URL) surfaces as a confusing classify_agent failure rather than a
  clear message. Noted in the helper docstring; worth tightening when a producer
  lands and starts generating these programmatically.

An empty AGENTOPS_AGENT is deliberately not a hard failure. Every pipeline
this tool generates today passes exactly that, so failing closed would break all
of them.

Tests

tests/unit/test_eval_agent_override.py covers precedence (--agent beats the
env var), the unexpanded-$(NAME) guard, verbatim full references, and a loud
failure when the configured target has no version slot. These were verified
failing-first by stashing the source changes.

Two tests exist specifically to prevent this PR from reading as more than it is:

• test_no_generated_workflow_produces_a_value_for_the_override asserts that no
  generated workflow declares job outputs or assigns AGENTOPS_AGENT. It fails
  the moment a producer lands, which is when the Generated workflows evaluate a stale agent version: agentops.yaml pins versions/N and deploy never rewrites it #388 notes need updating.
• test_generated_ci_today_evaluates_the_pin_because_nothing_sets_the_override
  pins the real runtime behavior: empty, whitespace, and unexpanded CI tokens all
  fall back to the configured agent.

The three render assertions in test_cicd.py now carry docstrings stating that
they check plumbing only and pass against a non-functional pipeline.

Unit suite: 1145 passed, 5 skipped (baseline 1116/5).

Relationship to #391

No semantic conflict. The two changes touch disjoint constructs inside the same
string literals, #391's stricter assertions hold under these changes, and neither
change is silently dropped. Only CHANGELOG.md conflicts, mechanically. Merge
order does not matter.