> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# Workflows release notes

Curated overviews of recent Workflows prerelease package waves.

## Workflows 0.39

Workflows 0.39 ships as four packages: `@sanity/workflows`, `@sanity/workflows-ui`, `@sanity/workflows-cli`, and `@sanity/workflows-test`. `npx @sanity/workflows-cli codemod packages` moves a project to them. Every project needs to act, so read [Before you upgrade](https://www.sanity.io/docs/workflows/release-notes) first.

### Before you upgrade

- **Everyone:** the `@sanity/workflow-*` packages no longer publish. Run the codemod and install. If you use the generated runtime, regenerate and redeploy both stacks. Then typecheck. The codemod also renames ten UI exports. See [Move to the four Workflows packages](https://www.sanity.io/docs/workflows/upgrade).
- **Apps that list instances:** `useWorkflowInstances` and `useDocumentWorkflows` take a GROQ `filter` and `params`, and include completed instances. `InstancePreviewsFilter` is removed with no replacement. See [Pass a GROQ filter to instance list hooks](https://www.sanity.io/docs/workflows/upgrade).
- **Teams with workflow definitions:** deploy refuses reads that always return null, such as `$fields.lead.id` on an `assignee` field. Run `sanity-workflows deploy --check` with 0.39 and use the path it suggests. See [Fix condition and field reads that never hold a value](https://www.sanity.io/docs/workflows/upgrade).
- **Teams that redeploy definitions:** on instances of a definition version first deployed with 0.39, the engine refuses a key that a field’s `fields` or `of` doesn’t declare, and reads `$effects` and `$effectStatus` from the same effect run. A field without `fields` or `of` accepts any keys. Declare every key your definitions write before you redeploy. See [the reader model 13 step](https://www.sanity.io/docs/workflows/upgrade).
- **Teams adopting reader model 13 features:** start roles, effect reads, free-form fields, and `object` and `array` params need reader model 13. Upgrade every runtime first, then set `expectedMinReaderModel` to 13. See [Adopt start roles, effect reads, declared object keys, free-form fields, and object and array params](https://www.sanity.io/docs/workflows/upgrade).
- **Workflows stored in a Canvas or dashboard:** deploy refuses role gates and `$actor.roles` reads with `ResourceCapabilityError`. The engine refuses to start definitions that use them, and to fire actions on, edit, or tick their existing instances. See [Move role gates off Canvas and dashboard workflows](https://www.sanity.io/docs/workflows/upgrade).
- **Integrators:** a custom `clientFactory` receives `{resource, token?, apiHost?}`, as [Update a custom runtime client factory](https://www.sanity.io/docs/workflows/upgrade) shows. A custom engine client that reads revisions needs `getDataUrl`, and a hand-written `EnsureDocumentClient` needs `config()` and `createIfNotExists()`. Pass the instance document to `effectOutputsMap`, and handle `canvas` and `dashboard` in an exhaustive switch over `MemberResource['type']`.
- **Studio configs and CLI scripts:** `whoami --json` reports `resource` as `<type>:<id>`, and `nuke` asks for each target in that form. Replace `workflowDataset` with `workflowResource`, and `--media-library-id` with `--workflow-resource`. See [Name the workflow resource](https://www.sanity.io/docs/workflows/upgrade).
- **Teams using the generated runtime:** for a workflow that qualifies for [clock starts](https://www.sanity.io/docs/workflows/generate-functions), the redeployed heartbeat tries to start every admitted document without an instance, 20 per run, so check them first. A replaced Function loses its environment variables. See [Regenerate the Functions runtime](https://www.sanity.io/docs/workflows/upgrade).

### What’s new

- **Start roles.** `start: {roles: [...]}` limits who may start a fresh instance. Studio leaves the workflow out of Start for everyone else, unless an unfinished start on the document needs completing. See [Decide who may start an instance](https://www.sanity.io/docs/workflows/definitions-and-instances).
- **References into any resource type.** Without `resourceClients`, the engine derives a client for another dataset, Canvas, or dashboard from its own client with `withConfig`, so its token must reach that resource. See [Allowed target resources](https://www.sanity.io/docs/workflows/global-document-references).
- **Clock starts.** The generated heartbeat starts a Function-hosted autonomous workflow whose start filter reads `$now`, such as `embargoAt <= $now`, without a write to the document. See [Start documents on the clock](https://www.sanity.io/docs/workflows/generate-functions) for the filters that qualify.
- **Values.** An `object` without `fields` or `array` without `of` accepts any keys, and params can declare `object` and `array` shapes ([field types](https://www.sanity.io/docs/workflows/workflow-authoring-reference)). `editField` edits one list row by `_key` ([edit one row](https://www.sanity.io/docs/workflows/fields)), and `effectsRead` copies an effect’s result into a field ([return results](https://www.sanity.io/docs/workflows/effects-and-runtimes)).
- **Studio.** Object and list fields that declare sub-fields get inputs. A disabled action button says why with your requirement titles and guard names, and a blocked activity’s dialog adds requirement descriptions, so check that they read well. See [Complete a task, edit fields, and fire an action](https://www.sanity.io/docs/workflows/studio-user-guide).
- **Diagnostics.** An engine error whose kind has a docs page ends with a `Docs:` line that links to it. The generated heartbeat logs one `[heartbeat]` summary line per run. See [Check the result](https://www.sanity.io/docs/workflows/generate-functions).

### Fixes

- The start dialog submits a single assignee, keeps **Start** from submitting while a required assignee is empty, and lets you fill a required list field.
- The engine reads a single assignee record given for an `assignee` field at start, or for an `assignee` sub-field of an `object` or `array` action param, as a one-item list.
- When two people edit different rows of the same list of objects in Studio, the engine keeps both edits.

## Workflows 0.38

Workflows 0.38 makes engine calls in most workflows about three times faster, moves the generated heartbeat into its own organization stack, and checks definitions more strictly. Several changes need action, so read [Before you upgrade](https://www.sanity.io/docs/workflows/release-notes) first.

### Before you upgrade

- **Everyone:** upgrade every runtime that shares a workflow resource, such as Studio, Functions, and your own apps, to 0.38 together. See [the required references rollout](https://www.sanity.io/docs/workflows/upgrade).
- **Teams with workflow definitions:** a condition reference that can’t resolve now fails when the definition loads. Run [npx @sanity/workflow-cli deploy --check](https://www.sanity.io/docs/workflows/cli-reference) with 0.38 on a branch before you upgrade. See [condition variables](https://www.sanity.io/docs/workflows/workflow-authoring-reference).
- **Teams using the generated runtime:** regenerate, redeploy your existing stack, then deploy the new heartbeat stack in `workflows-heartbeat/` with an organization deploy token. Until you do, no heartbeat runs and nothing reports an error. See [deploy definitions and Functions](https://www.sanity.io/docs/workflows/generate-functions).
- **Code that forces a stage:** `setStage` and `sanity workflows set-stage` are removed. Fix what the transition reads and call `workflow.tick`. Otherwise, reset the failed activity with `sanity workflows reset-activity` or abort the instance. See [diagnose](https://www.sanity.io/docs/workflows/cli-reference).
- **Scripts and tests that query with GROQ right after an engine call:** pass `visibility: 'sync'` to that call. See [commit visibility](https://www.sanity.io/docs/workflows/engine).
- **Effect handlers:** a whole-document binding passes `{id, type, rev}` instead of the document, so read it with `context.getDocument(params.doc)`. A bare field name resolves from the queuing activity outward; pass `{scope: 'workflow', field}` to keep writing a workflow field. Upgrade every effect runtime before you deploy definitions with 0.38. See [handler context](https://www.sanity.io/docs/workflows/engine).
- **Agent hosts:** `@sanity/workflow-mcp` ships typed operations instead of an MCP server and tool definitions, so wrap each operation in your own tool. See [wrap an operation in a tool](https://www.sanity.io/docs/workflows/mcp).
- **Integrators:** a custom `WorkflowClient` needs `getDocuments`, and hand-built `ForMeTaskRow` rows need `overdueSince`. `grantsFromPath` has no effect, so `$can` reads the caller’s grants on the workflow resource; review `$can` conditions in hosts that never passed it. See [createEngine options](https://www.sanity.io/docs/workflows/engine). A `clientFactory` for `createRuntime` needs `withConfig` when a deployment binds a resource other than a dataset.

### What’s new

- **Faster engine calls.** Instance commits return without waiting for the query index. A per-call `visibility` option covers results you must query right away. See [commit visibility](https://www.sanity.io/docs/workflows/engine).
- **Two stacks for the generated runtime.** Document functions deploy with a project token; only the heartbeat needs an organization token. When a start watcher can evaluate the start filter, it starts a workflow only on the write that makes the filter true, and `blueprints generate` warns about filters it can’t evaluate. See [predict when generated triggers run](https://www.sanity.io/docs/workflows/generate-functions).
- **Stricter checks.** Misspelled variables and undeclared params fail at load time, and deploy warns when a transition reads `$effects`. See [return results and branch on them](https://www.sanity.io/docs/workflows/effects-and-runtimes).
- **More context for effect handlers.** Handlers receive `ctx.attempt` and `ctx.redelivered`, and can return a short `detail` note. See [effects and handler runtime contracts](https://www.sanity.io/docs/workflows/engine).
- **Studio.** Select a completed effect in the workflow history to see its outputs and note. Object and list values show as labeled grids. See [workflow history in Studio](https://www.sanity.io/docs/workflows/studio-user-guide).

### Performance

In our measurements on a staging project, compared with Workflows 0.36:

- In workflows that commit asynchronously, `fireAction` takes about 1.0 s (was about 3.7 s), `startInstance` about 1.1 s (was about 3.3 s), and a field edit about 0.6 s (was about 2.3 s).
- In Studio, the new stage shows about 1.5 s after you select **Approve** (was about 4.4 s). The runs table in the Workflows tool no longer re-renders every row when one instance changes.
- Workflows that always commit synchronously, such as those with a `singleSubject` start requirement, take about 3.4 s per action (was about 4.1 s).

### Fixes

- **Cancel workflow** shows only for editors the definition’s `abort` block admits.
- Finished work no longer shows as overdue. A done, failed, or skipped activity, and any task in a completed or aborted instance, shows its due date as a plain date.
- Picking a second person for a single-assignee field replaces the first instead of failing to save.
- Generated functions log routine lines, such as `ctx.log` output, at the info level instead of `ERROR`. Update any log alert that matches routine lines.
- Condition descriptions state what each condition requires, including negated conditions, and no longer show GROQ.

## Workflows 0.37

Workflows 0.37 renames the deployment `tag` to `partition`, lets a definition limit who may abort its instances, and replaces the generated runtime with one `createRuntime` factory. Studio shows one activity view across the Workflows tool and the document view, and the Workflows CLI validates definition files without a config, finds its config from any subdirectory, and reads any dataset you name.

> [!WARNING]
> The deployment tag is now partition
> The value that scopes a deployment's definitions and instances is now called `partition` in configuration, the Studio plugin, the engine and adapters, the test bench, MCP, and the CLI. The new name says what the value does: together with the workflow resource, it decides where a deployment's definitions and instances are stored. A deployment alone on its resource can now leave it out and use `default`.
> **Upgrade:** rename every `tag` to `partition` and keep the same value.

### Required migrations

Everyone with a Workflows config, engine code, Studio plugin, or MCP host: upgrade the Workflows packages together to 0.37.0, then rename each `tag` to `partition`, `--tag` to `--partition`, and `--all-tags` to `--all-partitions`, keeping the same values. Code that passes `tag` to `createEngine`, the adapter hooks, `createBench`, or an MCP tool throws a migration error before any read or write; read `engine.partition` and `bench.partition` instead. Configuration and CLI flags that still say `tag` keep working and print a warning. Rename the key rather than deleting it: a deployment with neither key moves to the `default` partition, where its existing workflows no longer appear, and `deploy` warns before writing there. Stored documents need no migration. See [deployment partitions](https://www.sanity.io/docs/workflows/deployments-and-resources).

Scripts that read CLI JSON: rows from `list` and `definitions list` carry `partition` instead of `tag`. When an instance ID or definition name exists in several deployments, a non-interactive read now fails and asks for `--deployment`. See the [CLI reference](https://www.sanity.io/docs/workflows/cli-reference).

MCP hosts: the discovery tool is `workflows_list_partitions` and returns `{partitions: [...]}`, and addressed tools take `partition`. Hosts that import the address constants switch to `LIST_WORKFLOW_PARTITIONS_TOOL_NAME`, `LIST_WORKFLOW_PARTITIONS_DESCRIPTION`, and `WORKFLOW_PARTITION_DESCRIPTION`. See [the workflow environment address](https://www.sanity.io/docs/workflows/mcp).

Teams that deploy raw stored JSON or use their own definition tooling: `deploy`, `deploy --check`, `definitions validate`, and the MCP validate tool reject a field operation whose `target` is not reachable from its activity, a manual `{type: 'field'}` target that is not document-valued, and a stage `editable` override for a field that is not editable in that stage. Before deploying with 0.37, run `npx @sanity/workflow-cli deploy --check` with the new version on a branch and fix what it reports; one failing definition blocks its whole deployment. Deployed definitions and running instances are unaffected. See [deploy](https://www.sanity.io/docs/workflows/deploy-definitions).

Teams using the generated runtime: regenerate with `npx @sanity/workflow-cli blueprints generate`, review your preserved effect handlers, then run `npx sanity@latest blueprints deploy`. Functions generated by an earlier release import removed names and fail to build until regenerated. Functions generated by 0.33.0 through 0.36.0 can also start a duplicate instance when the platform redelivers a write; regenerating and redeploying fixes that. Generated function names now derive from the deployment `name`; when a deployment's `name` differs from its partition, run `npx sanity@latest blueprints plan`, plan for the functions to be replaced, and remove the stale function directories that `blueprints generate` lists. Hand-written functions switch from `createRuntimeEngine` to `createRuntime`. See [the generated runtime](https://www.sanity.io/docs/workflows/generate-functions).

Custom effect runtimes: `drainEffects` no longer accepts `max`, and `isEntryUnheld` is no longer exported. `sweepStaleClaims` now also re-queues a pending effect that no drain has claimed by updating its `queuedAt`. See [drainers, claims, and leases](https://www.sanity.io/docs/workflows/effects-and-runtimes).

Custom integrations that read missing documents: the `DocumentAvailability` value `'deleted'` is now `'not-found'`. Replace every `'deleted'` comparison; unmigrated code no longer matches missing documents. See [handling missing content](https://www.sanity.io/docs/workflows/cookbook-handle-deleted-subject).

Code that handles every Workflows error kind or builds evaluations by hand: `WorkflowErrorKind` adds `abort-denied` and `operation-failed`, so an exhaustive `switch` or `Record<WorkflowErrorKind, ...>` must handle both to compile. `WorkflowEvaluation` has a new required `abort` field; add it to hand-built evaluations, such as test fixtures, for example `abort: {allowed: true}`. See [WorkflowEvaluation](https://www.sanity.io/docs/workflows/engine).

Apps that render assignee badges: the badge `vocabulary` is an `AssigneeVocabulary`, which includes `loading` and `error`; pass the full `useProjectMembers` state. The badges are named `ActorBadge` and `ActorBadges`, and `AssigneeBadge` and `AssigneeBadges` remain as deprecated aliases. See [assignment badges](https://www.sanity.io/docs/workflows/ui-components).

### New capabilities

- Limit who may abort an instance with `abort: {roles: [...]}` beside `start`. `abortInstance` refuses other callers with `AbortDeniedError`, Administrators included, and `WorkflowEvaluation.abort` tells a UI whether to show its abort control. See [who may abort](https://www.sanity.io/docs/workflows/definitions-and-instances). Requires reader model 11; see [Upgrade Workflows packages](https://www.sanity.io/docs/workflows/upgrade).
- Studio shows one activity view in the Workflows tool's For me panel, the Overview modal, and the document view: a header with the description, status, and target, then the fields, then a pinned footer with every action you can take. See [For me](https://www.sanity.io/docs/workflows/studio-user-guide).
- Validate definitions written as JSON files with `definitions validate <file...>`, without a config, a login, or network access. Agents and CI that do not use the MCP server get the same report as the MCP validate tool. See [definitions validate](https://www.sanity.io/docs/workflows/cli-reference).
- Run the Workflows CLI from any subdirectory: it finds the nearest `sanity.workflow.ts` in a parent directory, and `--path` names a config directly. See [find the config](https://www.sanity.io/docs/workflows/cli-reference).
- Inspect any dataset or media library with `list`, `show`, `tail`, `diagnose`, `definitions list`, and `definitions show` by passing `--project-id` and `--dataset`, or `--media-library-id`, without a config. See [read a resource without a config](https://www.sanity.io/docs/workflows/cli-reference).
- Start workflows whose content lives in another dataset or project from the CLI: `start` and the instance commands accept refs to any resource the deployment binds in `resourceAliases`. See [route foreign resources](https://www.sanity.io/docs/workflows/cross-resource-workflows).
- Studio names people, robot tokens, and automation instead of raw user IDs throughout the Workflows views, and run history reads as plain sentences. See [Workflows in Sanity Studio](https://www.sanity.io/docs/workflows/studio-user-guide).
- App SDK apps can name robot tokens too: `useProjectMembers` returns them in `robots` beside `members`. See [Edit project-member assignments](https://www.sanity.io/docs/workflows/ui-components).
- The Workflows tool's Overview shows applied filters in a filter bar, and its count line adds a one-click unassigned filter. See [Overview](https://www.sanity.io/docs/workflows/studio-user-guide).
- `deploy --dry-run` runs every check a real deploy runs before its first write, so it fails on any batch the deploy would reject. See [deploy](https://www.sanity.io/docs/workflows/cli-reference).
- `WorkflowDiagram` takes `initialView: 'actual-size'` to open at 1:1, centered on the current stage. See [the workflow diagram](https://www.sanity.io/docs/workflows/ui-components).
- `blueprints generate` works in projects that use TypeScript 6, TypeScript 7, or no TypeScript. See [the generated runtime](https://www.sanity.io/docs/workflows/generate-functions).
- The MCP server's `./stdio` entry loads from CommonJS. See [install the server](https://www.sanity.io/docs/workflows/mcp).

### Fixes

- Opening a document that belongs to a workflow no longer sends the Studio plugin into an update loop that kept the document form and Presentation from loading.
- `startInstance` refuses a start whose supplied subject or document reference points at a document that does not exist, instead of creating an instance that is immediately stuck. See [the Engine](https://www.sanity.io/docs/workflows/engine).
- `fireAction` re-checks the activity's `requirements` when it commits. An action whose requirements stopped being met after evaluation is rejected with `requirements-unmet`, and nothing is written.
- A mistyped standalone CLI command prints the error and the command's usage and exits `2`, instead of a stack trace.
- `nuke --instance` refuses an instance that is still in flight; abort it first.
- When a start requirement refuses an auto-started document, Studio says which requirement refused, and Try again checks it again. See [start a workflow automatically](https://www.sanity.io/docs/workflows/studio-plugin).
- The Studio document badge and the Workflows tool's run rows, release counts, and Release filter show only Content Release names, never `published` or `raw`. `perspectiveReleaseNames(perspective)` in `@sanity/workflow-engine` returns the same names for a custom interface. See [Overview](https://www.sanity.io/docs/workflows/studio-user-guide).
- When an undecidable transition holds a stage whose activities are all resolved, `diagnoseInstance` reports `stuck` with `transition-unevaluable`, or `document-missing` when the held transition reads a missing referenced document, even if a later transition is satisfied. CLI `diagnose`, MCP `workflows_diagnose`, and the Studio plugin show the same cause. See [diagnose](https://www.sanity.io/docs/workflows/cli-reference).

## September 30, 2026: Workflows 0.36

Workflows 0.36 narrows generated document triggers and adds recovery for queued effects. The Workflows CLI also checks that generated runtime files match your definitions before deployment. Definition validation now catches hidden clock and document reads.

### Required migrations

Teams using the generated runtime: upgrade your Workflows packages together to 0.36.0, regenerate with `npx @sanity/workflow-cli blueprint generate`, review your preserved effect handlers, deploy definitions, then redeploy Functions. When a generated Blueprint exists, file drift or missing handlers now stops definition deployment, including `--check` and `--dry-run`. The check covers the whole config even when deploying one definition or deployment. See [generated runtime rollout](https://www.sanity.io/docs/workflows/generate-functions).

Authors with effect budgets: `runtime.memory` is now whole GB from 1 through 10, and `runtime.timeout` is whole seconds from 1 through 900. Replace megabyte-style values such as `memory: 512` with a supported allocation such as `memory: 1`, then regenerate and redeploy Functions. Values outside these ranges fail validation. See [runtime settings](https://www.sanity.io/docs/workflows/deployments-and-resources).

Authors using clock functions in conditions, predicates, spawn expressions, or start rules: replace `now()` with `$now` and `dateTime::now()` with `dateTime($now)` before your next definition validation or deployment. Query-based initial values remain exempt. Existing stored definitions are not rewritten. See [condition evaluation](https://www.sanity.io/docs/workflows/conditions).

Authors with implicit document reads in start rules: a `start.filter` that reads the root document requires a subject field, and a GROQ start requirement cannot read a root document. Validation now also detects projection escapes and implicit reads through `references()`, `sanity::versionOf()`, and `sanity::partOfRelease()`. Rewrite affected requirements against supplied variables; `$fields` contains raw inputs, not hydrated documents. See [start conditions](https://www.sanity.io/docs/workflows/conditions).

Teams using reserved document types as subjects: discovery now excludes the `sanity.` and `system.` namespaces when a subject has no `types`, including when reading older definitions. Explicitly list the reserved type and, in Studio, add a mapping row. Listing an engine-owned instance, definition, or guard type now fails `defineWorkflow` and deploy validation. Remove those type names and use `spawn` to coordinate workflow instances. See [subject fields](https://www.sanity.io/docs/workflows/workflow-authoring-reference) and [Studio configuration](https://www.sanity.io/docs/workflows/studio-plugin).

Teams relying on autonomous starts for existing documents: generated workflows with no start filter, or a filter that reads nothing beyond `_type`, now use creates-only watchers. Filters that read `$now`, other documents, or dynamic paths still observe every update. Regeneration does not backfill existing documents. Start their workflow instances explicitly where needed. See [generated document triggers](https://www.sanity.io/docs/workflows/generate-functions).

Custom telemetry consumers: event names now identify the package, such as `Workflows Engine Instance Started`, `Workflows CLI Definition Shared`, and `Workflows React Session Started`. Update logger filters and include both old and new names when querying historical data. CLI trace version 2 replaces payload fields `command` and `flags` with context fields `commandArguments` and `extraArguments`, alongside `coreOptions`; `groupOrCommand` is always `workflows`, and `success` remains the result. `extraArguments` now includes flag values such as `--tag=prod`, except redacted and undeclared inputs. Review your collection policy before upgrading.

### New capabilities

Generated start watchers can respond only to updates of fields their start filter reads, and effect drains respond to pending-effect changes. This reduces Function invocations caused by unrelated edits. Dynamic or whole-document reads keep the broader update trigger. See [generated document triggers](https://www.sanity.io/docs/workflows/generate-functions).

The generated heartbeat periodically reevaluates function-hosted parent workflows and recovers function-hosted effects whose trigger was missed or whose lease expired. Recovery also covers effects on completed instances and workflows hosted elsewhere, and respects declared effect budgets. Recovery shares a bounded Function invocation, so it does not guarantee a completion deadline. See [heartbeat recovery](https://www.sanity.io/docs/workflows/generate-functions).

This release does not change stored document shapes or raise the reader-model floor. Generated runtimes remain experimental and are not ready for production use.

## September 23, 2026: Workflows 0.35

Workflows 0.35 fixes a CLI compatibility issue that prevented `sanity.workflow.ts` from loading in TypeScript 7 projects. Blueprint generation and its `--check` mode support TypeScript 6, TypeScript 7, and projects without TypeScript installed. Upgrade the Workflows packages you use together to 0.35.0; no configuration changes are required. See [Configure and deploy workflow definitions](https://www.sanity.io/docs/workflows/deploy-definitions).

## September 21, 2026: Workflows 0.34

Workflows 0.34 fixes compatibility with Sanity UI 4 for the Studio plugin and shared UI components.

### Required migrations

For the Studio plugin, upgrade Sanity Studio to 6.15 or later in the 6.x line. Upgrade every `@sanity/workflow-*` package in your application to 0.34.0 together, reinstall dependencies, and commit the updated lockfile. Mixing Workflows releases can fail the studio build. See [the upgrade instructions](https://www.sanity.io/docs/workflows/upgrade).

If you use `@sanity/workflow-components` or `@sanity/workflow-diagram` outside Studio, provide `styled-components ^6.4.2`. Both packages install Sanity UI 4. Use `@sanity/ui ^4.2.1` for the theme provider around these Workflows components. See [UI component installation](https://www.sanity.io/docs/workflows/ui-components).

Upgrading from 0.33 requires no changes to workflow definitions or stored workflow data. Keep your existing `expectedMinReaderModel` value.

## September 18, 2026: Workflows 0.33

Workflows 0.33 adds retry policies for external work and explains when a deleted document blocks an active workflow. The Workflows tool now marks overdue tasks individually.

### Required migrations

#### Upgrade the runtimes that share workflow data

If a document referenced by a required field is deleted while the workflow is active, normal actions and transitions stop. Abort and permitted direct field edits remain available.

Upgrade every studio, CLI, MCP server, Sanity Function, worker, and application sharing the workflow resource to Workflows 0.33.0. After verifying the rollout, set `expectedMinReaderModel: 10` before deploying definitions with required content references or effect retry policies.

Existing workflow instances need no reset or backfill. Older runtimes can still advance some instances without the new checks, so upgrade every shared runtime before relying on them. Follow the [model-10 rollout](https://www.sanity.io/docs/workflows/upgrade).

#### Upgrade App SDK integrations

Studio and App SDK integrations require `@sanity/sdk` 3.1 or later in the 3.x line, with matching `@sanity/sdk-react` when used. Before reinstalling, configure SDK 3 to resolve `@sanity/mutate` 0.18.2; version 0.18.1 can leave document reads pending. Follow the [installation instructions](https://www.sanity.io/docs/workflows/app-sdk).

Custom implementations of Workflows client interfaces must read request targets from `url` instead of `uri`. The [compatibility guidance](https://www.sanity.io/docs/workflows/upgrade) names the affected interfaces.

### New capabilities

#### Declare retries for effects

An effect is external work queued by a workflow, such as sending a notification. Its `retry` policy can set the attempt count, fixed or exponential waits, and a window for starting another attempt. Retries run within one invocation, so the policy must fit its runtime. See [bounded effect retries](https://www.sanity.io/docs/workflows/engine).

#### Identify deleted documents and overdue tasks

When a referenced document is deleted while a workflow is active, Sanity Studio identifies the affected field. A required reference blocks progress until you restore the document or select a readable replacement in an editable field. In the Workflows tool’s **Overview** and **Board**, an overdue dot identifies each late task. See [Workflows in Sanity Studio](https://www.sanity.io/docs/workflows/studio-user-guide).

#### Try experimental runtime generation

The Workflows CLI can generate Sanity Functions from your workflow definitions with `npx @sanity/workflow-cli blueprint generate`. This command is **experimental and not ready for production use**. Its flags and generated output may change. See [CLI command reference](https://www.sanity.io/docs/workflows/cli-reference) for options and current limitations.

## September 8, 2026: Workflows 0.32

Workflows 0.32 separates team responsibility from personal task ownership. A task can retain its project-role assignments while one person holds it. Sanity Studio distinguishes personal and role-routed work, with new controls for moving between tasks. Custom runtimes can discover when a workflow next needs a time-based check.

This is a breaking package release. Existing installations need coordinated runtime upgrades; claim declarations and custom effect configuration need code changes. Stored workflows need no reset or backfill.

### Required migrations

#### Upgrade the runtimes that share workflow data

Singular assignments now store a member list. Guards combining operations such as draft edits and publishing also need different document handling. Both require reader model 9, a stored-data compatibility level that older runtimes cannot handle.

Before allowing affected writes:

1. Upgrade every studio, command-line tool, agent server, Sanity Function, worker, and application sharing the workflow data to runtime packages **0.32.0**.
2. After verifying every reader, set the deployment's reviewed `expectedMinReaderModel` to `9`.
3. Deploy revised definitions and verify their model. An unchanged redeployment can reuse the old definition.

An existing workflow instance, meaning one started workflow, keeps its original definition and assignment representation. The new lists apply to future instances started from a model-9 definition.

Existing instances with affected guards can require model 9 on their first new-engine commit, without redeployment. Older runtimes then refuse them; **downgrading is not a rollback**. The [rollout guide](https://www.sanity.io/docs/workflows/upgrade) identifies affected definitions. Others retain their existing reader requirement.

#### Replace claim shortcuts with explicit fields and actions

The `claim` shortcut for taking and releasing work is removed. Definitions containing `type: 'claim'` now fail validation.

Use ordinary fields and explicit actions. Preserve who can take, release, and act on the work. `$assigned` also matches an eligible role pool before anyone takes the task; it does not require a personal holder.

The [assignment example](https://www.sanity.io/docs/workflows/claim-assignment) shows routed work. The [editorial review recipe](https://www.sanity.io/docs/workflows/cookbook-editorial-review) preserves actor-based ownership instead.

#### Group custom effect settings when constructing an engine

Effects are queued work your application handles, such as sending email. Engine construction now groups their settings under `effects`:

- `effectHandlers` becomes `effects.handlers`.
- `effectLeaseMs` becomes `effects.leaseMs`.
- `missingHandler` becomes `effects.missingHandler`.

Use the same group in `useWorkflowEngine` and keep it stable between renders. The Studio plugin's own `effectHandlers` setting is unchanged.

Old TypeScript calls fail to compile. Old JavaScript settings are ignored, so draining can throw `MissingHandlerError`. Queued effects need no rewrite. See the [handler configuration example](https://www.sanity.io/docs/workflows/effects-and-runtimes).

### New capabilities

#### Separate personal assignments from role-routed work

Taking a task retains its role routes; releasing the person can return it to the role pool. In Sanity Studio, **For me** separates **Tasks assigned to you** from **Tasks sent to your roles**. See [personal and role-routed tasks](https://www.sanity.io/docs/workflows/studio-user-guide).

#### Move between tasks and board stages

Expand a task's fields and actions without losing its selection. Previous/next controls and keyboard navigation move through the current list. A board navigator helps you reach stages on a wide board. See [task and board navigation](https://www.sanity.io/docs/workflows/studio-user-guide).

#### Schedule the next time-based workflow check

Custom runtimes can use `nextEvaluationAt` to schedule another tick, even when the last tick changed nothing. Your runtime still owns the timer and handles data changes. Some time conditions report no boundary, so a missing timestamp does not mean an active instance needs no further checks. See the [scheduling example](https://www.sanity.io/docs/workflows/sanity-functions).

### Custom integration changes

Instance lists gain viewer-assignment filters and counts in the [CLI reference](https://www.sanity.io/docs/workflows/cli-reference) and [MCP operations](https://www.sanity.io/docs/workflows/mcp-tools-reference).

Custom integrations also have migration details for [guard contracts](https://www.sanity.io/docs/workflows/workflow-authoring-reference), [test-bench changes](https://www.sanity.io/docs/workflows/testing), and [engine errors](https://www.sanity.io/docs/workflows/engine).

## August 28, 2026: Workflows 0.31

Workflows 0.31 makes Studio runs easier to scan and corrects MCP rollout guidance for role-constrained assignments. It also publishes Blueprint provider groundwork, but Blueprint deployment is not generally available yet.

### Required migrations

#### Update Blueprint lifecycle configuration

Users of `@sanity/workflow-blueprint` must remove `ownershipAction` and unknown lifecycle keys. Lifecycle supports only `deletionPolicy` with `retain` or `protect`, plus `dependsOn` references that begin with `$.resources.`. Omit lifecycle to use the default retain policy. Code that constructs `WorkflowsResource` values directly must include `lifecycle: {deletionPolicy: 'retain'}` (or `protect`) or switch to `defineWorkflows`. Unsupported configuration now fails validation. Continue using `sanity workflows deploy` until the [Blueprint integration is available](https://www.sanity.io/docs/workflows/prerelease).

#### Upgrade MCP before deploying role-constrained assignments

MCP 0.30 reported reader model 6 for role-constrained assignment fields even though the engine requires model 8. Upgrade `@sanity/workflow-mcp` to 0.31, upgrade every reader sharing the workflow resource, then pass `expectedMinReaderModel: 8` to `workflows_deploy_definition`. The stale guidance causes deployment rejection before any write. Definitions without assignment `roles` remain on reader model 4. Follow the [role-constrained assignment rollout](https://www.sanity.io/docs/workflows/upgrade).

### New capabilities

#### See tasks and blockers at a glance in Studio

The Studio [Overview](https://www.sanity.io/docs/workflows/studio-user-guide) groups the current stage’s human work by task in the Tasks column and on board cards, so separate assignments and unassigned work stay visible. Overdue marks show how late work is or how many tasks are overdue. Blocked marks name the task or automation that failed or did not finish. Applied filters now stay beside Add filter while the workflow and run-scope controls remain on the left. No Studio upgrade action is required beyond installing the 0.31 package stack.

## August 26, 2026: Workflows 0.30

Workflows 0.30 makes large sets of workflow instances easier to manage. A workflow instance is one started workflow. Studio brings all instances into one filterable view, custom interfaces gain paged live previews, and workflow authors can limit assignments to people or collective roles with specific project roles.

### Required migrations

#### Handle workflow instances after deleting their subject

A workflow instance’s subject is the document it follows. Studio no longer offers bulk cleanup for active instances left behind when that document is deleted. Applications that delete subject documents must handle those instances explicitly. Use the [deleted-subject Function](https://www.sanity.io/docs/workflows/cookbook-handle-deleted-subject) to apply your lifecycle policy; otherwise the instances remain active. No action is needed if your application keeps subject documents.

### New capabilities

#### Limit assignments to qualified project roles

Add `roles` to an `assignee` or `assignees` field to control who can be assigned. Workflows accepts people who hold a listed project role and collective roles that match a listed role. Existing values remain removable and reorderable even when they no longer qualify. See [Assignments and role eligibility](https://www.sanity.io/docs/workflows/claim-assignment) for the definition example and matching rules.

Fields without `roles` keep their current behavior. To enable role constraints, upgrade every runtime sharing the workflow resource, confirm access to the project member directory, then set `expectedMinReaderModel: 8` and redeploy. Follow the [model-8 rollout](https://www.sanity.io/docs/workflows/upgrade) for the required order.

#### See every workflow instance in one Studio view

Overview brings workflow instances from every definition into one table or board, with filters, Open and Closed views, and a docked detail panel. The list continues loading until every matching instance is available instead of stopping at 200. For me isolates the current user’s open work, while Definitions contains the deployed workflow catalog and setup details. See the [Workflows tool](https://www.sanity.io/docs/workflows/studio-user-guide).

#### Build complete workflow instance lists in custom interfaces

`instancePreviewsQuery` returns lightweight, cursor-paged instance summaries, while `instanceChangesQuery` keeps the list current. React applications can use `useInstancePreviews`, while Studio integrations can use `useWorkflowInstancePreviews`. These APIs replace full instance reads and integration-specific paging. See [Read instance previews](https://www.sanity.io/docs/workflows/definitions-and-instances) and [List instance previews](https://www.sanity.io/docs/workflows/custom-reactive-adapters).

## August 20, 2026: Workflows 0.29

0.29 adds advisory node semantics, field arithmetic, Enterprise caller attributes, and clearer stuck-work signals in Studio.

### Required migrations

#### Update exhaustive semantic mappings

`ActionSemantic` now includes `signal.*` and `custom.*` values as well as decisions. Update exhaustive maps, or narrow their input to `DecisionSemantic`. See [action semantics](https://www.sanity.io/docs/workflows/workflow-authoring-reference).

#### Rename an attributes predicate

`attributes` is now reserved by the synthetic `$attributes`. Definitions deployed under model 6 or earlier with `predicates.attributes` must rename it and redeploy; otherwise references resolve to the caller attribute bag. See [named predicates](https://www.sanity.io/docs/workflows/conditions).

### New capabilities

#### Add advisory node semantics

Workflows, stages, and activities accept `Semantic[]`; actions accept `ActionSemantic[]`. Integrations can render these labels without changing execution. See [definition properties](https://www.sanity.io/docs/workflows/workflow-authoring-reference).

#### Count and initialize fields

`field.inc`, `field.dec`, and `field.setIfMissing` are available from actions and effect completion. Upgrade every runtime before using them, then follow the [bounded retry pattern](https://www.sanity.io/docs/workflows/workflow-authoring-reference).

#### Gate caller actions with User Attributes

`$attributes` brings Enterprise User Attributes into caller-bound soft gates. Missing attributes fail closed, and values are not persisted. See [context-specific variables](https://www.sanity.io/docs/workflows/workflow-authoring-reference).

#### Find stuck work in Studio

Landing and workflow pages now surface active, overdue, and snapshot-detectable stuck work. Workflow details adds transition-aware diagnosis and recovery guidance. See the [Workflows tool](https://www.sanity.io/docs/workflows/studio-user-guide).

Use these notes to upgrade Workflows safely. Each release lists required migrations before new capabilities. Package changelogs remain the exhaustive API record.

## August 14, 2026: Workflows 0.28

This release tightens deployment authoring, adds project role catalogs to assignment controls, and clarifies role-assigned work.

### Required migrations

#### Use authored deployment input types

Authored configs now require `WorkflowDeploymentInput` with the current literal `expectedMinReaderModel: 4`. Reuse the authored object across config and Blueprint entry points; a parsed `WorkflowDeployment` is not an authoring input. Missing this migration produces TypeScript errors. See [Reader-model rollout](https://www.sanity.io/docs/workflows/prerelease).

#### Update assignment component inputs

Add `roles` to `ProjectMembersState`, add roles to hand-built StudioProjectUsersState values, pass `RoleVocabulary` to role resolvers, and replace `AssigneeBadge(s).members` with `vocabulary`. Use `roles: []` to retain member-derived role choices. See [Reusable UI components](https://www.sanity.io/docs/workflows/ui-components).

#### Name direct RoleAvatar instances

Direct RoleAvatar hosts must provide their own tooltip and accessible name. AssigneeStack users need no change.

#### Update embedded CLI command IDs

Standalone `sanity-workflows` users need no action. Embedded oclif hosts must replace `editorial-workflows:*` and removed root aliases with `workflows:*` topic IDs. Otherwise a command can fail or resolve a host-owned command. The official `sanity workflows` mount is not shipped yet. See [Configure and deploy workflow definitions](https://www.sanity.io/docs/workflows/deploy-definitions).

### New capabilities

#### Project role catalogs drive assignment

Pickers can offer project roles with no current holders. An empty or unavailable catalog falls back to member-held roles, and an already-stored unknown role stays visible and removable.

#### For me explains role-assigned work

The document view and Workflows tool show a notice when visible work is included through a role the current editor holds. Role aliases do not add work to this queue.

#### Revision conflicts are easier to classify

The engine now exports `isRevisionConflict(error)` for a known revision-guarded write. Do not use it to classify a whole cascade or every 409. The Studio plugin also avoids a false warning when another client completes the same start. See [isRevisionConflict](https://reference.sanity.io/_sanity/workflow-engine/index/isRevisionConflict/).

## August 11, 2026: Workflows 0.27

Workflows 0.27 makes agent tools easier to discover, makes project roles legible throughout assignment controls, and moves document-editor workflow controls onto self-contained instance cards. Custom reactive integrations can now distinguish an evaluation failure from loading.

### Required migrations

#### Rename MCP tool calls

Every MCP wire name now uses the plural `resource_verb` form. Update prompts, approval lists, scripts, literal `tools/call` requests, telemetry queries, and embedded registrations that hard-code a name before upgrading. Calls made with an old name fail as unknown tools. Parameters and response shapes are unchanged.

##### Workflows MCP tool renames in 0.27

| Previous name | New name |
| --- | --- |
| `list_workflow_tags` | `workflows_list_tags` |
| `list_workflow_definitions` | `workflows_list_definitions` |
| `list_workflow_instances` | `workflows_list_instances` |
| `get_workflow_state` | `workflows_get_state` |
| `diagnose_workflow` | `workflows_diagnose` |
| `start_workflow` | `workflows_start` |
| `fire_workflow_action` | `workflows_fire_action` |
| `get_workflow_definition` | `workflows_get_definition` |
| `get_workflow_authoring_guide` | `workflows_get_authoring_guide` |
| `validate_workflow_definition` | `workflows_validate_definition` |
| `deploy_workflow_definition` | `workflows_deploy_definition` |

See [the MCP tool reference](https://www.sanity.io/docs/workflows/mcp-tools-reference).

#### Read role records from ProjectMember.roles

`ProjectMember.roles` is now `readonly {name: string; title?: string}[]` instead of `readonly string[]`. Read `role.name` wherever an integration previously read a role string. Adapters such as `useProjectMembers` return the new shape automatically, but downstream readers must migrate or TypeScript fails. Stored assignee values still use the machine role name, so no stored-data migration is required.

See [Supply project members](https://www.sanity.io/docs/workflows/ui-components).

#### Update WorkflowSession test doubles

`WorkflowSession` adds the required `evaluationError` field. Hook consumers receive it automatically. Tests or adapters that construct a complete session object must add `evaluationError: undefined` or supply the current evaluation failure.

See [Render every session state](https://www.sanity.io/docs/workflows/custom-reactive-adapters).

### New capabilities

#### Work from instance cards in Studio

The document editor's Workflows view now gives each run its own card. The header shows the run, stage, and status while collapsed; one click expands it. The card's overflow menu opens workflow history or aborts an in-flight run with a required reason.

See [See where your work stands](https://www.sanity.io/docs/workflows/studio-user-guide).

#### Assign roles with clearer member context

Every Studio assignee control accepts people and project roles. Roles use square avatars and their project titles for display while stored assignments retain machine names. Shared pickers sort members by display name, search names, email addresses, and roles, and show account details on hover. Pickers present choices; they do not infer assignment eligibility.

See [Reusable UI components](https://www.sanity.io/docs/workflows/ui-components).

#### Render evaluation failures explicitly

`useWorkflowSession` now exposes `evaluationError`. It identifies a failed evaluation attempt that would otherwise look like indefinite loading before the first successful evaluation. A later successful attempt or an instance change clears it; `ready` is unaffected.

See [The reactive session](https://www.sanity.io/docs/workflows/custom-reactive-adapters).

## August 10, 2026: Workflows 0.26

Workflows 0.26 gives MCP embedding hosts a supported way to construct engine clients and keep model-facing behavior aligned with the bundled server.

### Required migrations

No upgrade action required. All new exports are additive, and the bundled `workflow-mcp` stdio server keeps its existing behavior. Hosts that hand-built client configuration or engine construction can adopt the shared seams on their own schedule.

### New capabilities

#### Embed MCP tools with shared engine policy

`workflowClientConfig` layers the engine's API version, request-tag family, published perspective, and resource address over a host's client configuration. `createWorkflowEngine` binds that client to one workflow environment, while `workflowErrorText` and the exported tag-description constants keep custom wrappers aligned with the bundled server.

See [Embed the tools in another MCP server](https://www.sanity.io/docs/workflows/mcp).

## August 6, 2026: Workflows 0.25

Workflows 0.25 reshapes the Studio tool around each workflow, lets agents discover deployed environment tags, and makes MCP tool definitions host-neutral.

### Required migrations

#### Update MCP clients and embedding hosts

The action tool is now `fire_workflow_action`. Replace `fire_action` in calls, prompts, allowlists, and telemetry filters. The old wire name is not registered.

Embedding hosts that consume raw `WorkflowToolDef` values must read `requiresAddress` and merge their own environment fields when it is true. A tool's `inputSchema` now contains only tool-owned parameters. Add `requiresAddress` to custom definitions.

Tool schemas use zod v3 through `zod/v3`. Build merged fields with the same major. `zod` and `@modelcontextprotocol/sdk` are peer dependencies. npm 7+ and pnpm install peers automatically; strict installers must add them explicitly.

See [Connect an agent over MCP](https://www.sanity.io/docs/workflows/mcp).

#### Update Workflows tool links

The top-level tabs are Workflows at `/workflows/overview`, All documents at `/workflows/all-documents`, and For me at `/workflows/for-me`. A workflow's Documents and Definition pages now live below `/workflows/overview/<name>`. Update bookmarks and links. A bare `/workflows` address and the retired `/workflows/documents` and `/workflows/tasks` pages return to the landing page. The old `/workflows/documents/<name>` and `/workflows/definition/<name>` deep links no longer match.

#### Preserve required inputs and activity deadlines

The Studio start dialog now gates only input fields declared `required: true`. Add that declaration to `subject` or any other input that every run must supply.

Activity rows now show an inline calendar only for `dueDate` and `dueDatetime`. If a plain `date` or `datetime` was intended to be the row's deadline, change its kind. Other date fields remain available in activity detail and the Date filter.

Engine 0.25 retains data model 5 and reader floor 4. Keep `expectedMinReaderModel: 4`. No stored-data migration is required.

### New capabilities

#### Discover deployed workflow environments

The bundled MCP server adds `list_workflow_tags`, which takes a workflow resource and returns the sorted tags that currently contain deployed definitions. The engine also exports `deployedTagsGroq()` and `definitionTagsGroq()` for custom hosts. Discovery reports observed environments; confirm the tag instead of choosing one automatically.

See [the MCP server](https://www.sanity.io/docs/workflows/mcp) and [Reference](https://www.sanity.io/docs/workflows/reference).

#### Work workflow by workflow in Studio

The Workflows landing presents deployed workflows as cards. Each workflow has its own Documents board and Definition page. Selecting a run opens a resizable Workflow details panel with its document, stages, management controls, and recent history.

See [Add Workflows to Sanity Studio](https://www.sanity.io/docs/workflows/studio-plugin).

### Improvements

Actor resolution now bridges project-scoped sessions, including SAML SSO sessions, through the project's user directory before persisting the account-global user ID. Standard sessions require no upgrade action.

## August 3, 2026: Workflows 0.24

Workflows 0.24 adds explicit deadline fields, a document board in Studio, focused instance cleanup, and clearer workflow diagrams.

### Required migrations

#### Update WorkflowDiagram integrations

WorkflowDiagram no longer accepts guardCount, selectedStage, or onSelectStage. Remove those props. Stage pills no longer provide host-defined selection behavior.

WS_CARD_TOKENS removes --ws-red and --ws-font. Replace --ws-positive with --ws-path. A custom wrapper that relies on explicit diagram typography must provide --ws-font and --ws-font-weight separately.

See [Reusable UI components](https://www.sanity.io/docs/workflows/ui-components).

#### Upgrade readers before using deadline fields

Engine 0.24 writes model 5 documents and retains reader floor 4. Keep expectedMinReaderModel: 4. No stored-data migration is required.

Before deploying a definition that uses dueDate or dueDatetime, upgrade every Studio, CLI, MCP server, Function, server, and application that reads the workflow resource. Older engines reject those field kinds.

See [How early access works](https://www.sanity.io/docs/workflows/prerelease).

### New capabilities

#### Declare a workflow deadline

Use dueDate or dueDatetime to identify the single top-level deadline for a workflow, stage, or activity scope. Both kinds use the same values, validation, options, and Studio controls as date and datetime.

See [Fields](https://www.sanity.io/docs/workflows/fields).

#### Browse workflow documents by stage

Use the Studio Documents tab to group the newest 200 runs of one selected workflow by stage, switch between horizontal columns and a stacked list, and share the selected workflow through the URL.

See [Workflows tool](https://www.sanity.io/docs/workflows/studio-user-guide).

#### Manage active work in Studio

Abort an in-flight workflow from instance detail with a recorded reason. Owners of editable to-do lists can remove rows immediately; assignment-only and read-only views cannot.

See [Add Workflows to Sanity Studio](https://www.sanity.io/docs/workflows/studio-plugin).

#### Delete one terminal instance

sanity-workflows nuke --instance removes one terminal instance and its guards without resetting the deployment. It refuses in-flight instances and non-workflow documents.

See [the nuke command reference](https://www.sanity.io/docs/workflows/cli-reference).

#### Fill a diagram container

Set fill to keep the diagram canvas at the parent’s full width while respecting the supplied height. The graph remains centered and is never enlarged beyond 1:1.

See [Render the workflow diagram](https://www.sanity.io/docs/workflows/ui-components).

### Studio and diagram improvements

The Workflows tool now opens on Definitions and orders its tabs as Definitions, Documents, Tasks, and For me. Definition detail shows its deploy time, active-instance count, trigger, configuration issues, and a full-width stage diagram.

Required start inputs left by a valid mapping are collected in the start dialog instead of making the workflow unavailable. Mapping diagnostics remain on developer-facing definition surfaces.

Completed workflow stages now use a neutral face. Diagram paths distinguish the current stage, completed stages, traversed transitions, untraversed transitions, and branches the run can no longer reach. Hovering a dashed transition shows its direction, with animation disabled for reduced motion.

Studio feedback now distinguishes engine refusals, failed writes, and successful commits whose follow-up effects remain incomplete. Task lists wait briefly for document titles before appearing, unresolved document links show a loading face, and project-member controls remain loading until the directory settles.

## July 24, 2026: Workflows 0.23

The 0.23 release expands the Workflows tool with definition and history views, makes stage overrides easier from an interactive terminal, and restores Studio workflow actions and assignments.

### Required migrations

None. Engine 0.23 keeps data model 4 and reader floor 4. Keep expectedMinReaderModel: 4; no stored workflow data or Studio configuration migration is required.

### New capabilities

#### Browse definitions and instance history in Studio

The Workflows tool adds a Definitions tab with deployed definition details and stage diagrams. Instance detail now carries the document-oriented workflow snapshot, an inline newest-first history feed, and pending-effect controls. The document view links to this detail instead of opening a separate debug event log.

See [Workflows tool](https://www.sanity.io/docs/workflows/studio-user-guide).

#### Use native document previews

Reference fields, array items, and other Studio document previews no longer add workflow-stage decorations. Current stage remains visible in the form strip, document badge, and Workflows tool.

#### Fire actions and assign users in Studio

Studio can again fire workflow actions and save user assignees when its Sanity client is explicitly bound to a project API host. The fix restores account-global identity resolution for these Studio operations.

## July 24, 2026: Workflows 0.22

The 0.22 release makes CLI reads easier to automate, removes resource-selection friction for instance commands, and makes deployment targets clearer.

### Required migrations

None. Engine 0.22 still writes model 4 documents and keeps the reader floor at 4. Keep `expectedMinReaderModel: 4`; no stored workflow data migration is required.

A stale numeric acknowledgement now reaches the runtime compatibility check, which rejects it with readers-first rollout guidance. The check still accepts only 4.

[Review Reader-model rollout.](https://www.sanity.io/docs/workflows/prerelease)

### New capabilities

#### Automate CLI reads

Use --json with list, show, definition list, and definition show. Show commands return stored documents; list commands return structured row data with resource provenance and a truncated flag. Multi-resource JSON reads fail instead of returning partial results.

[See Read the output as JSON.](https://www.sanity.io/docs/workflows/cli-reference)

#### Locate instances across resources

diagnose, fire-action, abort, and reset-activity now find an instance across every configured workflow resource from its ID alone. --deployment and --tag remain optional narrowers.

[See Select a deployment, a tag, or an instance.](https://www.sanity.io/docs/workflows/cli-reference)

#### See where deploy writes

Deploy progress and completion lines now name the deployment, tag, and workflow resource.

[See Deploy.](https://www.sanity.io/docs/workflows/deploy-definitions)

## July 23, 2026: Workflows 0.21

The 0.21 release changes the persisted reader floor, workflow readiness, identity storage, recovery, and integration APIs.

### Required migrations

#### Upgrade every reader before deploying

Engine 0.21 writes model 4 definitions and instances. Upgrade Studio, applications, Functions, servers, CLI processes, and MCP servers first. Then change every deployment acknowledgement to expectedMinReaderModel: 4.

```typescript
// sanity.workflow.ts
{
  expectedMinReaderModel: 4,
  // workflowResource, definitions, ...
}
```

Follow [Reader-model rollout](https://www.sanity.io/docs/workflows/prerelease).

#### Replace start and activity readiness syntax

Replace start.allowed with ordered start.requirements. Replace activity requirement records with ordered GROQ requirement arrays. Use singleSubject for one unfinished run of the same definition per subject.

```typescript
start: {
  requirements: [
    {type: 'singleSubject', name: 'one-open-run'},
    {type: 'groq', name: 'ready', query: '$fields.ready == true'},
  ],
}
```

See [Start conditions](https://www.sanity.io/docs/workflows/conditions).

#### Use one user identity across resources

`$actor.id`, user assignees, and `$assigned` now use the account-global `sanityUserId`. The same user therefore matches across projects, datasets, Canvas, and Media Library.

On project datasets, guard predicates compare the project-local value returned by `identity()`. The engine localizes projected actor and assignee metadata automatically, so guard authors do not translate IDs.

Existing live identity values resolve through the project directory and converge on their next engine commit. Audit history remains unchanged.

#### Upgrade Sanity Studio

The Studio plugin now requires Sanity 6.3 or later.

See [Install the packages](https://www.sanity.io/docs/workflows/studio-plugin).

#### Follow MCP instance-list cursors

list_workflow_instances now returns one page with has_more and next_cursor. Keep the same filters and continue until has_more is false.

See [The tools](https://www.sanity.io/docs/workflows/mcp-tools-reference).

### New capabilities

#### Load project members in App SDK

useProjectMembers(projectId) returns the ProjectMembersState used by the shared member and assignee controls. AssigneePicker is controlled through onChange(nextValue).

See [Edit project-member assignments](https://www.sanity.io/docs/workflows/ui-components).

#### Recover terminal activities

resetActivity reruns or skips a terminal activity in the current stage, then continues the cascade. The CLI exposes the same operation as reset-activity.

See [Recover a terminal activity](https://www.sanity.io/docs/workflows/activities-and-actions).

#### Clean up deleted Studio subjects

The Workflows tool can confirm a local subject is still deleted before aborting its orphaned workflow instances.

See [Workflows tool](https://www.sanity.io/docs/workflows/studio-user-guide).

#### Settle spawned cohorts together

A parent now reacts after every child created by one spawn commit has settled, rather than observing a partially settled cohort.

## July 22, 2026: Workflows 0.20

The 0.20 release aligns the public Workflows packages as one runtime stack and updates Studio integration.

### Required migrations

#### Matching package versions

Install every @sanity/workflow-* package used by one application at the same version. Shared runtime packages are now exact-version peer dependencies, so dependencies previously installed transitively must be installed explicitly.

**npm**

```shell
npm install @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0
```

**pnpm**

```shell
pnpm add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0
```

**yarn**

```shell
yarn add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0
```

**bun**

```shell
bun add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0
```

See [Versions and breaking changes](https://www.sanity.io/docs/workflows/prerelease).

#### Document view registration

Call `workflowDefaultDocumentNode()` without mapping arguments.

See [Add the plugin to your config](https://www.sanity.io/docs/workflows/studio-plugin).

#### Auto-start configuration

Move `autoStart` onto each applicable mapping row.

See [Start a workflow automatically](https://www.sanity.io/docs/workflows/studio-plugin).

#### Optional mappings

Remove mappings used only for workflow discovery. Keep a mapping when it customizes a discovered workflow or binds a definition that uses `doc.ref` instead of a subject field.

See [Discover workflows from subjects](https://www.sanity.io/docs/workflows/studio-plugin).

#### Preview setup

Remove `WorkflowStagePreview` and the `_id` projection added solely for workflow badges.

See [See where your work stands](https://www.sanity.io/docs/workflows/studio-user-guide).

### New capabilities

#### Automatic workflow discovery

The Studio plugin discovers deployed workflows whose caller-provided subject accepts a document type in the current Studio schema. Multiple workflows may target the same document type.

See [Add the plugin to your config](https://www.sanity.io/docs/workflows/studio-plugin).

#### Workflow status in previews

Documents with active workflows display their current stage in supported Studio previews.

#### Interactive CLI selection

Interactive commands ask which deployment to use when configuration is ambiguous. Non-interactive commands still require `--deployment` or `--tag`.

See [Select a deployment, a tag, or an instance](https://www.sanity.io/docs/workflows/cli-reference).

## July 22, 2026: Workflows 0.19

Engine 0.19 adds new runtime capabilities.

### Required migrations

Deployment `name` is now the unique CLI identity. Rename any deployment whose name is duplicated or contains anything other than lowercase letters, digits, or dashes.

A `tag` may group deployments across resources. Each `(workflowResource, tag)` pair remains unique. Use `--deployment <name>` for one deployment. Use `--tag <tag>` for a tag group. See [A deployment has two identities](https://www.sanity.io/docs/workflows/deployments-and-resources).

**npm**

```shell
# Target one deployment by name
npx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
npx sanity-workflows deploy --tag prod
```

**pnpm**

```shell
# Target one deployment by name
pnpm dlx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
pnpm dlx sanity-workflows deploy --tag prod
```

**yarn**

```shell
# Target one deployment by name
yarn dlx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
yarn dlx sanity-workflows deploy --tag prod
```

**bun**

```shell
# Target one deployment by name
bunx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
bunx sanity-workflows deploy --tag prod
```

The new `progress` field requires engine 0.19 readers. Follow [Reader-model acknowledgement](https://www.sanity.io/docs/workflows/engine) before deploying it. Existing workflow data needs no migration. Keep `expectedMinReaderModel: 2`.

```typescript
// sanity.workflow.ts
{
  name: 'production',
  expectedMinReaderModel: 2,
  // workflowResource, definitions, ...
}

// Direct engine deployment
await engine.deployDefinitions({
  expectedMinReaderModel: 2,
  definitions,
})
```

### New capabilities

#### Progress fields

Use a `progress` field to store completion from 0 to 100.

See [Fields](https://www.sanity.io/docs/workflows/fields).

#### Live progress reporting

Call `ctx.setProgress(...)` to update a progress field while an effect handler runs.

See the [working handler example](https://www.sanity.io/docs/workflows/engine).

#### Live field operations

Call `ctx.commitOps(...)` to commit field operations while an effect handler runs.

See the [working handler example](https://www.sanity.io/docs/workflows/engine).

#### Action-flow previews

Action evaluation can preview whether an action exits the current stage.

The preview identifies the selected transition.

See [Activities and actions](https://www.sanity.io/docs/workflows/activities-and-actions).

## July 21, 2026: Workflows 0.18

### Required migrations

Upgrade every reader before deploying definitions with this release. Readers include Studio, applications, Functions, MCP servers, and CLI processes. Then add `expectedMinReaderModel: 2` to every workflow deployment configuration and every direct `deployDefinitions()` call. Keep the value literal. Follow the [reader-first rollout](https://www.sanity.io/docs/workflows/prerelease) before changing it.

```typescript
// sanity.workflow.ts
{
  name: 'production',
  expectedMinReaderModel: 2,
  // workflowResource, definitions, ...
}

// Direct engine deployment
await engine.deployDefinitions({
  expectedMinReaderModel: 2,
  definitions,
})
```

`subject` is now a field kind. Replace the former required `doc.ref` subject convention with one workflow-scoped `subject` field. Without this migration, an existing definition can still run but no longer appears in document pickers or satisfies subject-based start rules when redeployed. See [Fields](https://www.sanity.io/docs/workflows/fields).

Audit start inputs and spawn mappings. Unknown, wrong-kind, non-input, self-filled, and duplicate initial fields now fail instead of being silently discarded.

### New capabilities

Studio can automatically start configured workflows when an editor opens a fresh document. Configure `autoStart` by document type; see [Turn on auto-start for fresh documents](https://www.sanity.io/docs/workflows/studio-plugin).

Definitions can use first-class subject fields, typed scalar choice lists, inclusive string/text/number validation bounds, and decision semantics on actions. Effect handlers preserve concrete Sanity client APIs, including Agent Actions. Studio v6, reusable workflow controls, shared project-user resolution, and the redesigned Workflows tool are also included.

## July 15, 2026: Workflows 0.17

### Required migrations

Move permission expressions from `start.filter` to `start.allowed`. `filter` now controls browse-time visibility and cannot read `$fields`; `allowed` is enforced when an instance starts.

Treat a caller-supplied `instanceId` as the idempotency key. Retrying the same start resumes it; do not reuse the ID for a different definition or version.

Fix newly rejected definition traps before redeploying, including invalid workflow or guard names, unbound $row reads, out-of-scope spawn reads, and invalid static field paths.

### New capabilities

Programmatic starts gain an enforced allowed gate and resumable retries. The dedicated Workflows tool, causal autonomy analysis, runtime persisted-document validation, resource-surface checks for supplied references, and the tag-scoped CLI nuke command are included.

## July 14, 2026: Workflows 0.16

### Required migrations

Move every operation, effect, and spawn payload onto an action. Triggered actions are now the only payload mechanism; remove payloads attached directly to transitions or other structure.

Definitions that can be started directly must use the start block. Review start filters against the new start context before redeploying.

### New capabilities

Definitions gain explicit start configuration and triggered actions. CLI, MCP, and condition descriptions use one filter vocabulary, while the test bench more closely mirrors guarded engine behavior.

> [!NOTE]
> Visiting agent?
> Workflows has MCP tools that let an agent inspect, operate, author, validate, and deploy workflows. An agent host embeds these tools. Ask the person you work for whether your host [includes the Workflows tools](https://www.sanity.io/docs/workflows/mcp).





## Related changelog entries

Entries are listed newest first; each link points to the full entry as markdown. Follow one when you need to know what changed, when, or why — for example, to summarize recent updates, explain behavior that differs from older documentation, or check whether a fix has shipped.

- [Workflows v0.39.0: Four packages, start roles, and stricter checks](https://www.sanity.io/docs/changelog/workflows-MC4zOS4w.md) — November 16, 2026
- [Workflows v0.38.0: Faster engine calls and two runtime stacks](https://www.sanity.io/docs/changelog/workflows-MC4zOC4w.md) — November 10, 2026