dispatch-workflow: per-workflow tool schema never exposes the ref parameter added in #49408

[blozano-tt]

Summary

#49408 (fixing #49400) added a ref field to DispatchWorkflowOutput
in schemas/agent-output.json and updated dispatch_workflow.cjs's ref
resolution priority to check message.ref first. That part works — I verified it
with unit-level testing against a compiled workflow.

But the per-workflow MCP tool the agent actually calls to request a dispatch
never got updated to expose ref as a parameter. The agent has no way to
supply it, so message.ref is always absent in practice, and every dispatch
silently falls through the priority chain to GITHUB_REF/context.ref — the
dispatching workflow's own trigger ref, not anything the agent intended.

Where the gap is (confirmed against v0.84.2 and current main)

pkg/workflow/safe_outputs_dispatch.go, generateDispatchWorkflowTool:

func generateDispatchWorkflowTool(workflowName string, workflowInputs map[string]any) map[string]any {
	...
	tool := generateWorkflowToolDefinition(workflowToolDefinitionOptions{
		workflowName:      workflowName,
		workflowInputs:    workflowInputs,
		descriptionFormat: "Dispatch the '%s' workflow with workflow_dispatch trigger. ...",
		metadataKey:       "_workflow_name",
	})
	...
}

Neither this function nor generateWorkflowToolDefinition (in
pkg/workflow/safe_outputs_workflow_helpers.go) references ref or
allowed-refs anywhere — I grepped both files at v0.84.2 and at current
main; zero hits either version. The generated tool's inputSchema.properties
only ever contains the target workflow's own workflow_dispatch inputs (e.g.
model, build-type, platform) — there is no generic ref/branch property
added regardless of whether the workflow's dispatch-workflow config sets
allowed-refs.

Compare to dispatch_workflow.cjs (the runtime handler), which does look for
message.ref and does have allowed-refs matching logic — that side of
#49408 is real and works. It's just unreachable, because nothing ever puts
ref in the agent's hands.

Live evidence

tenstorrent/tt-metal, workflow "Silencer", run
https://github.com/tenstorrent/tt-metal/actions/runs/30729757440 (job agent).
The workflow's dispatch-workflow config has allowed-refs: ["silencer/*"]
configured correctly. The agent's own reasoning trace noticed the gap live:

I'm noticing the t3000_unit_tests dispatch tool doesn't have a ref or branch
parameter in its schema—just build-type, model, and platform—so it might not
target my specific branch automatically.

And the raw safe-output it was forced to emit, with no ref field to fill in:

{"inputs":{"model":"all"},"workflow_name":"t3000-unit-tests","type":"dispatch_workflow"}

Consequence: this dispatched a full T3000 hardware test run against main
instead of the PR branch it was meant to validate — the workflow has an
allowed-refs allowlist specifically to scope dispatches to its own
silencer/* branches, and that allowlist is currently unreachable dead
configuration.

Suggested fix

Add a ref (string) property to the tool's inputSchema.properties in
generateDispatchWorkflowTool (or generateWorkflowToolDefinition, gated on
whether allowed-refs is configured for that workflow, mirroring how
dispatch_workflow.cjs already gates acceptance of message.ref on
allowed-refs being present) so the agent can actually see and fill in the
field the backend has been ready to accept since #49408. Ideally also update
the tool's descriptionFormat to mention that ref is required/validated
against the configured glob when present, so the agent understands the
contract instead of discovering the missing field by trial and error (as it
did here).

Related

• dispatch-workflow: let the agent specify the target ref/branch per call #49400 / dispatch_workflow: support per-call ref override for runtime branch targeting #49408 — added backend support for message.ref; this issue is the
  remaining half needed for it to actually be usable.
• dispatch-workflow / call-workflow: findWorkflowFile never checks the .yaml extension #49178 / fix: findWorkflowFile checks .yaml extension in addition to .yml #49230 — the earlier .yaml findWorkflowFile fix, unrelated to
  this gap but part of the same overall effort to get dispatch-workflow
  working for tenstorrent/tt-metal's silencer workflow.