Workflows is a deterministic multi-agent orchestration mechanism — a background task type that coordinates multiple Claude subagents running in parallel or in sequence. It is registered in getAllTasks() next to LocalAgentTask, LocalShellTask, and friends, but only when the WORKFLOW_SCRIPTS feature flag is on (claude-code/src/tasks.ts:9). Its task-type identifier is 'local_workflow' (claude-code/src/Task.ts:11) and its task-ID prefix is 'w' (claude-code/src/Task.ts:84). The invocation surface is WorkflowTool, itself lazily loaded behind the same flag — and the act of loading it first calls initBundledWorkflows() to register the bundled workflow scripts (claude-code/src/tools.ts:129, claude-code/src/tools.ts:131).

The word "deterministic" here is narrow and worth pinning down at the outset: it means the agent identities and assignment plan are reproducible, not that the agents' outputs are. Agent IDs are derived from role + context — formatAgentId(TEAM_LEAD_NAME, finalTeamName) mints a stable ID for a lead from its name and team (claude-code/src/tools/TeamCreateTool/TeamCreateTool.ts:146) — so the same orchestration can reconstitute the same addressable agents. Each agent still calls a non-deterministic model, so the content varies run to run. The steward's roster is fixed; the flavor in the pot is not.

(Two of the core types are empty stubs in the leaked source — LocalWorkflowTaskState (claude-code/src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts:2) and SdkWorkflowProgress (claude-code/src/types/tools.ts:7) — because the orchestrator body is ant-only and not fully present. This page therefore reads the visible seams: registration, gating, transcript routing, progress, and controls.)

How it works

Invoking WorkflowTool registers a background task of type 'local_workflow' (claude-code/src/Task.ts:11), tracked in AppState alongside every other task the harness manages (claude-code/src/tasks.ts:9).

That task spawns multiple subagents through the standard agent path, with one extra parameter. Each subagent's transcript is routed into a grouping subdirectory — workflows/<runId> — via the transcriptSubdir argument (claude-code/src/tools/AgentTool/runAgent.ts:322), applied by setAgentTranscriptSubdir(agentId, transcriptSubdir) (claude-code/src/tools/AgentTool/runAgent.ts:351). This is the "one basket per group, one record per basket" rule: every agent's history is filed separately under the run.

The controllers for those agents live on LocalWorkflowTaskState as a Map, not a Record — deliberately. The source spells out why next to the identical session-hooks pattern: with a Record + spread, each of N parallel spawns would cost O(N) to copy the growing container (O(N²) total) and fire every store listener; with a Map, .set() is O(1) and returning prev unchanged lets the store's Object.is(next, prev) check skip listener notification entirely (claude-code/src/utils/hooks/sessionHooks.ts:48, claude-code/src/utils/hooks/sessionHooks.ts:54, claude-code/src/utils/hooks/sessionHooks.ts:60). This is what keeps high-concurrency fan-out cheap.

Progress flows back through emitTaskProgress() (claude-code/src/utils/task/sdkProgress.ts:10), which carries an optional workflowProgress: SdkWorkflowProgress[] payload (claude-code/src/utils/task/sdkProgress.ts:19) onto a task_progress SDK event as workflow_progress (claude-code/src/utils/task/sdkProgress.ts:34).

The operator gets per-agent surgical control. The background tasks dialog wires up killWorkflowTask, skipWorkflowAgent, and retryWorkflowAgent from the workflow task module (claude-code/src/components/tasks/BackgroundTasksDialog.tsx:111, claude-code/src/components/tasks/BackgroundTasksDialog.tsx:112, claude-code/src/components/tasks/BackgroundTasksDialog.tsx:113) — skip a step, retry a botched one, or kill the whole run, each independent of the other agents. The status pill reads "1 background workflow" / "N background workflows" so the run is visible at a glance (claude-code/src/tasks/pillLabel.ts:57, claude-code/src/tasks/pillLabel.ts:58).

Two guardrails bound the mechanism. First, no recursion: WORKFLOW_TOOL_NAME is in ALL_AGENT_DISALLOWED_TOOLS, with the comment "Prevent recursive workflow execution inside subagents," so a spawned agent cannot itself launch a workflow (claude-code/src/constants/tools.ts:44, claude-code/src/constants/tools.ts:45) — the group leader may not crown himself steward. Second, permission integrity: WorkflowTool is allowlisted in the auto-mode classifier as safe, precisely because "subagents go through canUseTool individually" — the orchestrator is trusted only because each agent it spawns is still permission-checked on its own (claude-code/src/utils/permissions/classifierDecision.ts:84, claude-code/src/utils/permissions/classifierDecision.ts:85).

Why it matters

Reproducibility without false determinism. Because agent IDs are derived from role + team rather than randomly assigned (claude-code/src/tools/TeamCreateTool/TeamCreateTool.ts:146), the same orchestration plan reconstitutes the same addressable agents — they can be resumed, targeted, and debugged by name — even though the model's content differs each run. That is the honest meaning of "deterministic" here: the 台账 (ledger) is fixed; the output is alive.

Isolation that survives parallelism. Routing each agent into its own workflows/<runId> transcript subdir (claude-code/src/tools/AgentTool/runAgent.ts:322, claude-code/src/tools/AgentTool/runAgent.ts:351) means parallel agents never trample each other's history, and any one agent's run can be read back afterward.

Concurrency-safe bookkeeping. The Map-based controller store (claude-code/src/utils/hooks/sessionHooks.ts:48) is what makes spawning many agents in a single synchronous tick affordable instead of quadratic.

Bounded blast radius and surgical control. The recursion ban (claude-code/src/constants/tools.ts:45) prevents a workflows-spawning-workflows fan-out explosion, while per-agent skip/retry/kill (claude-code/src/components/tasks/BackgroundTasksDialog.tsx:111) gives the operator a scalpel instead of an all-or-nothing switch. And because every subagent is still individually permission-gated (claude-code/src/utils/permissions/classifierDecision.ts:85), "allowing the orchestrator" never means "allowing whatever the orchestrator decides to do."

Read the source

Start at the registry: getAllTasks() in claude-code/src/tasks.ts:9 shows LocalWorkflowTask gated on WORKFLOW_SCRIPTS. The task identity lives in claude-code/src/Task.ts:11 (type) and claude-code/src/Task.ts:84 (ID prefix 'w'). The invocation tool and its bundled-workflow init: claude-code/src/tools.ts:129 and claude-code/src/tools.ts:131. The spawn-time transcript grouping: claude-code/src/tools/AgentTool/runAgent.ts:322 and claude-code/src/tools/AgentTool/runAgent.ts:351. Determinism of IDs: claude-code/src/tools/TeamCreateTool/TeamCreateTool.ts:145. The Map-vs-Record concurrency rationale: claude-code/src/utils/hooks/sessionHooks.ts:48. Progress emission: claude-code/src/utils/task/sdkProgress.ts:10. UI controls: claude-code/src/components/tasks/BackgroundTasksDialog.tsx:111. Recursion guard: claude-code/src/constants/tools.ts:44. Permission allowlisting: claude-code/src/utils/permissions/classifierDecision.ts:84. The pill label: claude-code/src/tasks/pillLabel.ts:57. Finally, note the empty stubs — claude-code/src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts:2 and claude-code/src/types/tools.ts:7 — which mark where the ant-only core was elided from the leak.