Batch Work in Parallel (parallelmap)

The CLI's own names for this feature keep the word swarm: the tool is parallel_map, the gate answers swarm_authorization_required, and the variables start with POSTSALE_SWARM_. The pages call it a parallel batch; the codes call this a swarm.

When many orders or shipments need the same multi-step treatment, the agent can fan out with parallel_map. Each item gets a subagent. The parent receives an aggregated result: per-item outcomes plus a failed[] list. Because a batch can move money many times over, parallel batch has a stricter safety model than a single --yes.

In this article, we will explain when parallel batch helps, cover hard caps, authorize batches correctly, avoid keyword false positives on read-only work, and read stream events and failures.

Real-World Example

We have fifty ready orders that each need rates, a shipment, and a label. Doing that as fifty separate parent turns is slow. Parallel batches fans the work out with concurrency limits and shared idempotency keys.

Before We Begin

This article assumes that:

• You understand Safety: parent --yes is not batch approval
• You have practiced a single order path first (Ship one order)
• For unattended money-moving batches, your organization has already decided how POSTSALE_SWARM_AUTOAUTH is used

When to use it

Use parallel batch when you have a list of independent items (typically N ≥ 3) and the same multi-step template applies to each. The parent agent usually finds the list, then calls parallel_map.

Size limits

Batch authorization is separate from --yes

If the batch would run money-moving tools, or if the template text looks money-related:

1. You must authorize the batch before any subagent starts.
2. Parent --yes only covers the parent loop.
3. Subagents refuse money-moving without a batch auth token.

Read-only batches and keyword false positives

The gate scans template text for money-adjacent words (including ship, label, shipment, purchase, void, and related terms). A fully read-only batch can still trip the gate.

Setting money_moving: false in options does not turn off the scan.

Destructive tools never fan out

Subagents cannot run destructive tools (permanent deletes or the end-of-day manifest close) at all. Those tools are removed from the subagent tool set, and the executor refuses them as a second layer. There is no batch authorization path for destructive work: a delete must happen in the parent loop, where the normal confirmation gate applies. Batch authorization covers money-moving tools only.

Idempotency

Subagent tool calls use deterministic idempotency keys derived from the batch id, subagent index, tool, and input. Re-running the same fan-out after a crash reuses the same keys, which lets the backend recognize and skip already-purchased labels. Known idempotency edge cases are tracked in Limits and Honesty, so verify with a search after a crash recovery.

Try a careful read batch

Here's how:

postsale run "Look up ord_a, ord_b and ord_c; report id, number and status only"

Success looks like per-item results without a money batch prompt when the template stays free of trigger words.

Money batches at an interactive terminal

postsale run "ship today's pending orders with the cheapest carrier" --yes

Expect a batch authorization step before subagents run, even though --yes is present.

Streaming

With --stream you may see subagent_start, subagent_end, and subagent_draining (SIGINT while money work is in flight).

Dry-run still needs batch authorization

Money tools can be simulated inside subagents under dry-run, but batch authorization still applies.

Good to Know

When reporting how many things were created, prefer durable confirmed_effects over optimistic prose.

Subagents treat buyer-controlled fields (order notes, item names, customer names, addresses) as untrusted data: instructions found inside them are never followed. This protection is built into every subagent prompt.

Additional Reading

• Safety model
• Dry-run
• Batches and Unattended Runs
• Recipe: [read-only-parallel batch](../recipes/read-only-parallel batch.md)