gc_dispatch
Dispatch agents on demand with task assignments, inspect available targets, providers, and models, preview dispatch resolution, and track job status and output through a unified management interface.
Instructions
On-demand agent dispatch. Spawn an agent with a task, inspect dispatchable targets, inspect provider/model availability, preview dispatch resolution, check job status, retrieve output. Actions: dispatch (spawn agent), list_agents (local markdown agents only), list_providers (show valid provider overrides and availability), list_models (show provider model inventories with authoritative vs hint provenance), resolve_dispatch (preview what provider/model/mode GC would use for one target), list_targets (all dispatchable targets, optionally filtered by kind), status (check job), output (get result), list (query jobs), dismiss (hide noisy job), delete (remove one), prune (bulk cleanup), repair_stale (reconcile ghost running jobs after crashes/redeploys). Default is fire-and-forget (returns job_id immediately). Set wait=true to block until done.
Use gc_dispatch for assignments and runnable work. If you want an ongoing dialogue with an external A2A peer (for example Pluto), use gc_peer_conversation instead — that path preserves session/thread semantics and avoids creating one job per turn. Do not inspect past sessions to guess provider/model defaults. Use list_agents, list_providers, list_models, and especially resolve_dispatch instead.
Semantics:
provider = GC dispatch route, not upstream vendor and not CLI binary name
model = real provider-native model id only
resolve_dispatch shows provider_type, binary, model_source, and model_resolution so you can see exactly what GC will do
Provider selection (dispatch backend / route):
Default: omit provider and let the daemon resolve from the agent's declared provider/model fields plus configured fallback order
provider: "native" — explicit in-process/native dispatch route
provider: "native:" — explicit native backend pin, for example provider: "native:zai"
provider: "claude" | "droid" | "pi" — explicit built-in CLI route override
provider: "kimi" — explicit dynamic CLI route override when kimi is installed
provider: "" — any other installed CLI route label or alias accepted by the daemon
action=list_providers — inspect the currently valid native + CLI route strings before choosing one
Model selection:
For CLI providers with model_resolution=provider_runtime, omit model unless you know a valid provider-native model id
Never pass transport labels such as "kimi-cli" or "claude-code-cli" as model values
action=list_models shows exact live inventories where GC can verify them, and clearly labeled hints otherwise
Claude-specific permission controls:
permission_mode: default|auto|dontAsk|acceptEdits|plan|bypassPermissions
dangerously_skip_permissions: true adds --dangerously-skip-permissions
allow_dangerously_skip_permissions: true adds --allow-dangerously-skip-permissions
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory (optional, defaults to project default) | |
| kind | No | Target filter for list_targets (default: all) | |
| task | No | Task text (required for dispatch) | |
| wait | No | If true, block until agent completes (default: false) | |
| agent | No | Agent name to dispatch (required for dispatch) | |
| force | No | Force deletion of running job (for delete) | |
| issue | No | Bee issue ID to link (optional) | |
| limit | No | Max rows to return/delete (list/prune) | |
| model | No | Explicit real model id override, or a model hint for list_providers/resolve_dispatch (e.g. "claude-sonnet-4-6", "claude-opus-4-6", "gpt-5.2-codex"). Do not pass CLI labels such as "kimi-cli" or "claude-code-cli". Default: agent-defined, GC default, or provider runtime default depending on resolve_dispatch. | |
| action | Yes | Action to perform | |
| job_id | No | Job ID (for status/output actions) | |
| reason | No | Dismiss reason (for dismiss) | |
| status | No | Filter by status (for list/prune) | |
| add_dir | No | Claude only: additional directory to allow tool access to | |
| dry_run | No | Preview repair_stale without mutating | |
| timeout | No | Max lifetime of the dispatched CLI subprocess. Integer seconds (default: 1800 / 30 min), or "infinite"/"infinity"/"none" to disable the wrapper kill entirely. Accepts string-of-int ("600") so LLM stringification is safe. | |
| provider | No | Explicit GC dispatch route override, or route hint/filter for list_providers, list_models, or resolve_dispatch. This is not the upstream vendor and not the CLI binary name. Accepts dynamic CLI route labels such as "claude", "droid", "pi", "kimi", plus "native" or "native:<backend>" such as "native:zai". | |
| scheduled | No | Filter scheduled jobs only (for list) | |
| on_complete | No | Terminal hook for dispatch. Currently supports "notify" to emit a mailbox event when the job finishes. | |
| since_hours | No | Only jobs newer than N hours (for list) | |
| allowed_tools | No | Claude only: comma-separated allowed tools | |
| include_hidden | No | Include hidden jobs (list/prune; default false) | |
| permission_mode | No | Claude permission mode override (passed as --permission-mode) | |
| disallowed_tools | No | Claude only: comma-separated disallowed tools | |
| older_than_hours | No | Minimum age in hours for prune (default 24) | |
| older_than_minutes | No | Minimum age in minutes for repair_stale (default 30) | |
| dangerously_skip_permissions | No | Claude only: pass --dangerously-skip-permissions | |
| allow_dangerously_skip_permissions | No | Claude only: pass --allow-dangerously-skip-permissions |