[BUG] Workflow tool hard-rejects run_in_background with a bare 'unexpected parameter' error instead of stating the tool is background-only

What's Wrong?

The Workflow tool hard-rejects the run_in_background parameter with a bare InputValidationError that gives no hint the tool is background-only.

The Agent tool (single-subagent dispatch) accepts run_in_background to choose foreground vs. background execution. Workflow is conceptually the same kind of "spawn agent work and get a result" tool — just for multi-agent scripts instead of one agent — so a model naturally assumes the same parameter exists there. It doesn't, and passing it produces a hard validation failure:

Workflow({ scriptPath: ".claude/workflows/my-workflow.mjs", args: {...}, run_in_background: false })

→

InputValidationError: Workflow failed due to the following issue:
An unexpected parameter `run_in_background` was provided

The Workflow tool's prose description does say "Workflows run in the background — this tool returns immediately with a task ID" up front, so the parameter is redundant by design (Workflow is ALWAYS background, unlike Agent which can run foreground). But nothing in the schema or in the validation error states that explicitly — the error is a generic "unexpected parameter" with no pointer to "Workflow is background-only; there is no foreground mode." The model has to infer the design intent from the prose description after the failure, costing a wasted round-trip re-issuing the identical call without the parameter.

The two orchestration entry points (Agent and Workflow) have divergent capability surfaces (one can run foreground, the other can't) without the divergence being called out at the point of failure.

What Should Happen?

Either of:

1. Accept run_in_background on Workflow as a validation-only/no-op field. Since the tool is background-only, true is always correct, and false could warn-and-ignore (or error with a specific message, see 2) rather than generic-hard-fail.
2. Keep rejecting it, but make the error message self-explanatory for this known-adjacent parameter, e.g.: Workflow always runs in the background; there is no foreground mode and no run_in_background parameter. Use the Agent tool's run_in_background if you need a foreground subagent.

Option 2 generalizes: when strict schema validation rejects a parameter that IS valid on a sibling tool the model plausibly confused it with, the error message is the cheapest place to teach the distinction — a one-line hint there saves a model round-trip every time.

Error Messages/Logs

InputValidationError: Workflow failed due to the following issue:
An unexpected parameter `run_in_background` was provided

Steps to Reproduce

1. In a Claude Code session (with any workflow script available, e.g. .claude/workflows/my-workflow.mjs), have the model issue a Workflow tool call that includes run_in_background:

``
Workflow({ scriptPath: ".claude/workflows/my-workflow.mjs", args: {}, run_in_background: false })
``

1. The call fails with the bare InputValidationError above; re-issuing the identical call without run_in_background succeeds.

Schema-level confirmation (from the v2.1.212 CLI bundle):

• The Agent tool's input schema includes run_in_background: boolean().optional().
• The Workflow tool's input schema (script/name/scriptPath/args/resumeFromRunId/remote/…) has no run_in_background key, and unknown keys hard-fail through the generic strict-validation path (`An unexpected parameter ${param} was provided`) with no tool-specific messaging.

Claude Model

Not sure / Multiple models (observed with Opus-tier orchestrators; the confusion is model-independent — any model that has used Agent's run_in_background can make it)

Is this a regression?

No, this never worked

Claude Code Version

2.1.212 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Non-interactive/CI environment

Additional Information

Observed in an autonomous multi-agent orchestration setup where the same orchestrator session routinely uses both Agent (with run_in_background both ways) and Workflow. The parameter-surface divergence between the two dispatch tools is invisible until the validation error, and the error text doesn't resolve it.