Return a structured guide to every tool, recommended workflow, and common gotcha. Call this once when you start using the bridge, or whenever you're unsure which tool fits a situation.

The shape:

• tools: name → {group, summary, when_to_use, when_not_to_use}

• workflows: list of named multi-step patterns with example invocations.

• concepts: short definitions of channel, session pinning, permission_mode, cwd, the stop sentinel, and the durability model.

• gotchas: things that have actually bitten users.

Run a prompt against Claude Code in this devcontainer; return the result.

Use for short prompts (under ~60s round trip). For anything longer use dispatch_async so the MCP transport's per-call ceiling doesn't abort your tool call before claude finishes.

Args: prompt: The natural-language task for Claude Code. channel: Logical conversation thread. Same channel = shared session (subsequent calls --resume it). Default "default" — pick a stable channel name per logical thread (e.g. "feature-auth"). timeout_seconds: Wall-clock seconds before the call is aborted. Default 300. permission_mode: default | acceptEdits | plan | bypassPermissions. Defaults to CLAUDE_BRIDGE_DEFAULT_PERMISSION_MODE. cwd: Per-call working directory override. Use it to retarget at a specific project (e.g. /workspace) while keeping the bridge anchored in a clean directory for fast cold starts.

Returns: Success: {ok: true, channel, duration_ms, result, session_id, raw, stderr}. Failure: {ok: false, channel, duration_ms, error, exit_code?}. Failures never raise — the MCP layer always sees a result.

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}.

Non-blocking read of a job's current state.

status values:

• running — work in flight; elapsed_ms included for progress.

• done — full sync-style result keys.

• cancelled — user called cancel_dispatch.

• abandoned — runtime cancel (transport timeout, FastMCP shutdown). Subprocess kept running; watcher will transition this to done or error shortly. Poll again.

• error — dispatcher-internal error or unparseable output.

• orphaned — subprocess and output both lost on a restart.

Unknown job_id returns {ok: false, error: ...}. Works for both live jobs and ones loaded from disk after a bridge restart.

Long-poll a job for up to max_wait_seconds.

Default 50s is intentionally below the typical MCP transport ceiling (~60s) — call this in a loop and break when status != 'running'. The underlying job is shielded from cancellation, so if your MCP call is aborted at the ceiling the work keeps running and you can re-enter with the same job_id.

User-cancel a running job. SIGTERMs the subprocess by PID, then cancels the asyncio task. Status becomes cancelled (vs the abandoned state for runtime/transport-induced cancellations).

Returns {cancelled: true} if the cancel was actionable, or {cancelled: false, reason} for jobs that have already finished or have no live task.

All tracked jobs (running and finished). raw is stripped from done-state summaries to keep the response cheap; use get_dispatch(job_id) for the full payload.

Recurring dispatch: fire prompt on channel every interval_seconds, until a deadline or until the prompt emits the literal stop sentinel [BRIDGE_STOP_SCHEDULE] in its result.

Each tick is an independent dispatch_async job — ticks are short individually, but the schedule can run for hours. The bridge owns the loop, persists schedules to disk, and resumes them after a restart (without burst-firing missed ticks).

Args: prompt: The text fired at each tick. channel: Channel for every tick. Same-session continuity across ticks (each tick --resumes the prior). interval_seconds: Seconds between ticks. Minimum 10. until: Absolute end time, ISO 8601. Prefer including a timezone (e.g. "2026-04-27T20:00:00Z"); naive datetimes without a timezone are interpreted as UTC, not local time, so the same string yields the same instant regardless of which container the bridge runs in. Mutually exclusive with until_seconds. until_seconds: Relative end time in seconds from now (e.g. 14400 = 4 hours). timeout_seconds: Per-tick timeout. Default 300. permission_mode: Same as dispatch. cwd: Same as dispatch. after_schedule_id: Chain this schedule to start only after the named predecessor terminates (completed, cancelled, or error). Useful for pipelines: "after wave A merges, run hygiene check wave B." This schedule starts in waiting status and transitions to active automatically. Cycles are detected and rejected. notify_url: HTTPS endpoint to POST event payloads to. Optional. Bridge fires fire-and-log POSTs; the destination is the user's relay (Slack/Pushover/email/etc.) — bridge does not retry. notify_on: List of event names to push. Values: tick (every tick fired — chatty), tick_with_sentinel (the tick that triggered self-cancel), tick_error (a tick failed to spawn), schedule_end (any terminal transition: completed, cancelled, error). Default ["schedule_end"]. notify_headers: Extra request headers (e.g. auth). Sent on every webhook POST.

Returns: {ok: true, schedule_id, schedule} or {ok: false, error}.

Self-cancellation: if any tick's result text contains [BRIDGE_STOP_SCHEDULE], the schedule cancels after that tick. Use this in your prompt for "watch X until Y" patterns:

"Check open PRs. If all merged, end your reply with
[BRIDGE_STOP_SCHEDULE]. Otherwise summarize."

Webhook payload shape (result_preview truncated to 4KB)::

{"event": "schedule_end", "schedule_id": "...",
 "channel": "...", "tick_count": 17, "status": "cancelled",
 "last_tick_at": ..., "last_tick_result": "...",
 "last_job_id": "...", "error": null}

Every schedule the bridge knows about — active, completed, cancelled, error.

Detail view of one schedule. Includes last_job_id so you can follow up with get_dispatch or list_completions.

Stop a schedule from firing further ticks. In-flight ticks are not cancelled — use cancel_dispatch(last_job_id) for that.

Jobs whose finished_at > since, oldest first.

Use since=0 for "everything that ever finished". For ongoing polling, track the largest finished_at you've seen and pass it as the next since. Cheap and non-blocking — safe to call at the start of every turn / iteration to surface "anything new?".

Returns {completions: [<get_dispatch shape>, ...]} with finished_at present on each entry. raw is omitted; fetch full payloads via get_dispatch(job_id).

Long-poll up to max_wait_seconds for any new completion since the cursor. Returns immediately if any are already available; otherwise waits.

Default 50s is below the MCP transport ceiling so you can re-enter in a loop. Useful when watching schedule ticks land without polling each tick's job_id separately.

Return bridge events whose ts > since, oldest first.

The event log records dispatch starts/ends, schedule ticks, sentinel hits, schedule completions, webhook outcomes, and recovery actions. The buffer is bounded (default 1000 events) and persisted across bridge restarts.

Two read modes:

• Debug mode (notable_only=False, the default): every event. Good for forensic post-mortem of a workflow.

• Surfacing mode (notable_only=True): only state transitions worth reporting to a human — terminal dispatch states, schedule completions / cancellations / errors, webhook failures, recovery actions. Skips dispatch_start, schedule_tick, schedule_created, webhook_sent, and bridge_init_subprocess_alive. This is what an orchestrator wants for "what should I tell the user about?".

Cursor pattern: pass since=0 for everything, then on each subsequent call pass the largest ts you saw.

types is an explicit allow-list — composes with notable_only (intersection).

Common types:

• Dispatch lifecycle: dispatch_start, dispatch_end, dispatch_cancelled, dispatch_abandoned, dispatch_error, dispatch_orphan_finalized.

• Schedule lifecycle: schedule_created, schedule_tick, schedule_activated, schedule_self_cancelled, schedule_cancelled, schedule_completed, schedule_tick_error.

• Webhook outcomes: webhook_sent, webhook_failed.

• Recovery: bridge_init_recovery, bridge_init_subprocess_alive.

Each event has ts (epoch seconds), event (type), plus type-specific fields (job_id, schedule_id, channel, ok, duration_ms, etc.).

Note: events generated before this feature shipped are gone — the in-memory buffer only captures from the current bridge process onward. Anything you persisted before then lives in the optional CLAUDE_BRIDGE_LOG JSONL file (if you enabled it).

channel → pinned session_id. Doesn't tell you whether work is in flight on a channel — use list_jobs for that.

Drop a channel's pinned session so the next dispatch starts a fresh Claude Code session. Useful when a project MCP server has wedged inside the channel's session and you want a clean reconnect.

Does not cancel running work — use cancel_dispatch for that.