[DOCS] Workflow script parse error contract is undocumented: errors now identify the offending line instead of always pointing at TypeScript

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/workflows

Section/Topic

The "How a workflow runs" and "Behavior and limits" sections on the Workflows guide, plus the WorkflowOutput error field description in the Agent SDK TypeScript reference.

Current Documentation

From the Workflows guide, the script-shape and runtime sections are silent on what happens when the script fails to parse:

"The body is plain JavaScript with top-level await. agent() spawns one subagent and pipeline() runs one per item in a list." "The workflow runtime executes the script in an isolated environment, separate from your conversation. Intermediate results stay in script variables instead of landing in Claude's context."

The runtime constraint table (Behavior and limits) does not mention parse failure at all.

From the Agent SDK TypeScript reference (https://code.claude.com/docs/en/agent-sdk/typescript), the WorkflowOutput shape and prose around it say:

```typescript theme={null}
type WorkflowOutput = {
status: "async_launched";
taskId: string;
runId?: string;
summary?: string;
transcriptDir?: string;
scriptPath?: string;
error?: string;
};

> "Returns immediately after the tool accepts the invocation. The final result arrives later as a task completion. Check `error` before treating the run as started: a script that fails its syntax check returns `status: \"async_launched\"` with `error` set, and never runs."

| Field           | Type               | Description                                                                                                                     |
| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `error`         | `string`           | Set when the script fails its syntax check. When present, the run did not start despite the `async_launched` status             |

Neither page documents that the parse failure path now reports a specific offending line, nor that prior versions always blamed TypeScript for any script-level error, nor that strings containing Unicode quote characters (for example curly quotes or non-ASCII typographic quotes embedded in agent prompts) are now preserved correctly through the parser instead of being mangled before parse.

### What's Wrong or Missing?

### A. Workflows guide omits the script-parse failure mode entirely

The Workflows guide describes the script shape, the runtime, and the behavior and limits, but it does not tell readers what they will see when the script Claude wrote does not parse, or where to look for the cause. After the v2.1.202 fix, a script-level failure surfaces a specific line in the user's script — a meaningful improvement that the guide does not mention, so authors editing `scriptPath` files by hand have no documented contract for the error they will receive.

### B. The `WorkflowOutput.error` description is too generic to be actionable

The Agent SDK reference says only that `error` is "set when the script fails its syntax check." It does not state that v2.1.202 changed the contents of that string to include the offending line, nor that prior versions would surface the error as if it were a TypeScript problem regardless of the actual cause. SDK callers parsing `error` cannot rely on a stable shape without a doc note.

### C. The Unicode-quote fix is undocumented

Workflow scripts whose string literals contain Unicode quote characters (for example curly quotes from copy-pasted prose, or non-ASCII quotation marks in agent prompts) used to be corrupted by the parser before the script ever ran. The v2.1.202 fix preserves these strings. This is invisible to anyone reading the current docs: nothing warns authors that non-ASCII quotes are now safe to use inside `agent(\`...\`)` arguments, and nothing warns SDK integrators that the historical failure mode for those inputs has changed.

### Suggested Improvement

### Option A: Document the parse-error contract in the Workflows guide

Add a short subsection under "How a workflow runs" (or under "Behavior and limits") titled something like "Script parse failures". State:

* When the script fails to parse or has a syntax error, the run never starts and the error message names the offending line in the script the runtime wrote.
* Unicode quote characters (curly quotes, typographic quotes) inside string literals are now preserved correctly; pre-v2.1.202 scripts that contained them would have been corrupted before parse and are no longer affected.
* Before v2.1.202, parse errors were reported as TypeScript errors regardless of the actual cause; v2.1.202 changed the reporting so the script-level cause is named.

Pointers to the persisted script at `scriptPath` should be reinforced so users can open the file the runtime is actually running and read the line the error names.

### Option B: Tighten the `WorkflowOutput.error` description

Update the Agent SDK TypeScript reference for `WorkflowOutput.error` to state:

* v2.1.202+: the string identifies the offending line in the persisted script at `scriptPath`.
* Pre-v2.1.202: any parse failure was reported as a TypeScript error even when the script was plain JavaScript; SDK callers who log `error` should expect the post-fix format to differ from historical runs.

If a future Python Agent SDK reference adds the same `WorkflowOutput` result shape, mirror the note there as well.

### Impact

Medium - Makes feature difficult to understand

### Additional Context

Changelog entry (v2.1.202):

> "Fixed workflow scripts with unicode quote escapes in strings being corrupted before parsing; workflow parse errors now show the offending line instead of always blaming TypeScript"

**Affected Pages:**

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/workflows | Primary user-facing guide; runtime and behavior-and-limits sections are silent on parse failure |
| https://code.claude.com/docs/en/agent-sdk/typescript | `WorkflowOutput.error` description and the surrounding prose say only "fails its syntax check" without naming the line or the pre-fix TypeScript blame |
**Total scope:** 2 pages affected (Workflows guide plus the TypeScript Agent SDK reference).

Cross-references:

* https://code.claude.com/docs/en/changelog — v2.1.202 entry is the source of truth for the behavior change.
* https://code.claude.com/docs/en/agent-sdk/typescript — `WorkflowOutput` type and field descriptions.