dispatch_async
Run long tasks asynchronously beyond MCP timeouts by spawning a background job and returning a job_id for polling or webhook notification.
Instructions
Spawn a dispatch in the background, return a job_id immediately.
Use this for anything that may exceed the MCP transport's per-call
ceiling (~60s in Cowork) — persona runs, refactors, anything in a
busy project. The subprocess is spawned with its own session
(start_new_session=True) and its stdout/stderr go to files on
disk, so the work survives transport timeouts and bridge restarts.
Then poll with wait_dispatch(job_id) in a loop until
status != 'running'.
Args mirror dispatch. Empty prompts return a structured error
synchronously without creating a job.
Optional webhook notification (notify_url):
The bridge POSTs a JSON payload to notify_url when the job
reaches a terminal state matching notify_on. notify_on
values: done, error, cancelled, abandoned.
Default ["done"]. Delivery is fire-and-log — failures are
recorded in the event log as webhook_failed but don't affect
the job. Add auth via notify_headers.
Payload shape (truncated to 4KB on result_preview)::
{"event": "done", "job_id": "...", "channel": "...",
"status": "done", "ok": true, "started_at": ...,
"finished_at": ..., "result_preview": "...", "error": null}Returns:
Success: {ok: true, job_id, channel}.
Validation failure: {ok: false, error}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| channel | No | default | |
| timeout_seconds | No | ||
| permission_mode | No | ||
| cwd | No | ||
| notify_url | No | ||
| notify_on | No | ||
| notify_headers | No |