MCP tools reference

Generated from src/mcp/server.ts. Each registered tool has one row below. Availability depends on the calling agent, enabled targets and whether the caller is a delegated job. opencode prefixes tool names with bridge_.

The spawn tool requires agent to select a supported coding CLI. Delegated jobs receive a restricted tool set and explicit messaging grants. report_progress is for delegated jobs; hook_event is internal and must never be called by an agent.

Tool	Parameters	Behavior
`t3_capabilities`	`search?`	Validated T3 host binding and live provider/model/options catalog (experimental). search finds omitted/custom models. No native CLI fallback.
`t3_delegate`	`t3DelegateInput` (source schema)	Create an async T3-owned child task (stable clientRequestId required; default isolation: worktree). Pick provider/model/options via t3_capabilities. Permissions inherit; never creates a Bridge job. Use a fresh task and id per independent review. Completion wakes this thread - do not poll or add watchers.
`t3_task_status`	`taskId`	Read your T3 child task only if its result is needed mid-turn. workState/hasPendingChildRuns are not turn status. Reading a terminal result acknowledges T3 delivery; no Bridge receipt is created.
`t3_task_cancel`	`taskId`, `clientRequestId`, `reason?`	Cancel via T3, including later child turns (stable clientRequestId required). Never stops OS processes or Bridge jobs.
`t3_send`	`message`, `clientRequestId`, `mode?`, `taskId?`	Send into exactly this bound T3 thread, or a known owned child’s thread via taskId (default mode: queue; stable clientRequestId required). Unknown child bindings need an explicit t3_task_status first - send never reads/acknowledges a task result implicitly. Dispatch acceptance is not Bridge inbox consumption. No new-thread launch, no arbitrary target.
`health`	None	Broker health: round-trip and event-loop latency, history-import and backup phase/ETA, last verification time, recent error codes. No log or archive reads. If tools are slow, use health/peers, not live log files. Retry a timeout once; then report the exact error.
`ask_owner`	`askOwnerSchema` (source schema)	Ask the owner a decision for your own project, in “Waiting for you”. Check decisions first. Returns now; the answer arrives as a waking reply_to= message, also to the project main. Jobs ask their main. Use 2-4 options, one recommendation, brief context; link the concrete artifact for authorization. Never for secrets, status, peer questions, playable checks or routine approvals. Answers never bypass native approvals or accept an implementation. Same project+issue+topic merges; max 5 open/session; unanswered stay visible. Blocking destructive or authorization questions cannot default.
`withdraw_owner_question`	`id`, `status`, `reason`, `supersededBy?`	Dismiss your own open question (reason required). “superseded” needs supersededBy. Never answers or allows a tool.
`search_history`	None
`get_conversation`	None	Read a locally retained conversation by the id from search_history, in pages: exact raw bytes (base64) plus text chunks with source offsets. Pass returned next as after; concatenate chunks per source/generation to rebuild JSONL or a SQLite snapshot. No model calls, no network export.
`decide`	`approval_id?`, `decision?`, `reason?`, `topic?`, `text?`, `scope?`, `source_message_id?`	Two uses. (1) Answer a pending approval: approval_id + decision (allow/deny/escalate). (2) Record an owner decision you have researched: topic + text. A newer decision on a topic supersedes the previous revision across scopes; history is retained. In-scope sessions are notified once, without waking idle ones. Default scope: this project folder.
`decisions`	`query?`, `scope?`, `history?`	List current owner decisions, or search topic/text (case-insensitive substring). Default scope: this project, plus global and this session’s decisions. history=true adds superseded revisions, newest first.
`project_main`	`to`	Make a live local master this project’s main. Project addresses still reach all available live project sessions incl. secondaries; exact addresses stay direct.
`coordinator_availability`	`unavailable`	Yield this session’s project jobs to an available local master (e.g. before closing, at a usage limit); unavailable=false reverses it. The primary keeps its jobs until explicit handback; handed-off jobs are excluded.
`peers`	`native_child?`, `job?`, `agent?`, `project?`, `status?`, `name?`, `limit?`, `offset?`	List open sessions on this machine (claude, codex, opencode, antigravity, muse): name, agent, busy/idle, uptime, cwd, session id; plus your own name/settings, your subagents, and on request the latest unread file-transfer progress. Delegated jobs see parent and siblings (name, title, agent, status). Filter with agent/project/status/name and page with limit/offset; project as an absolute path matches that folder and below (physical path), other text matches a path substring.
`send`	`to`, `native_child?`, `message`, `reply_to?`, `conversation_id?`, `if_no_newer_than?`, `message_kind?`, `message_id?`, `mode?`	Send a message. to: a peer name from peers, a project address, an agent kind (only when exactly one is online), “” (everyone), or “jobs:” (only your running jobs). Delivery = queued in the inbox, not read; per-recipient results report queueing, not consumption - use wait_for_message(read_receipt_of=) for consumption. Project addresses include available live secondaries. Broadcasts wake live sessions per their settings and also reach recently seen offline local sessions/known project masters, connected paired-PC sessions and your running jobs; jobs:* reaches only your running jobs via existing links, even if authority RPCs are unavailable. Direct messages wake idle claude/codex/opencode sessions subject to wakeOnDirect and CLI transport; others read on their next turn. Auto-wake runs on the recipient PC (paired PCs included) and is never enabled by send. Offline recipients get the message when they return. Answer with new information via reply_to; send no pure acknowledgements and do not repeat a reply as a status note. Delegated jobs may send only to their parent, siblings, or exact local session/job names granted via send_to at spawn; broadcasts and other sessions are unavailable. A blocked/unsure job, or one before a consequential step, asks its parent with message_kind=“question” (question, options, recommendation, meanwhile). Sibling messages arrive live or next turn, with a quiet supervisor copy; sending to a finished sibling returns its final report at once - it will not answer, so do not wait for it or for its read receipt. peers shows grants and the sibling thread limit.
`send_status`	`message_id?`, `to?`	Look up your sent message by UUID in broker storage and archives (no wait for history indexing), or with to= list your latest stored sends to it (for a send interrupted before it returned an id). “stored” proves persistence only - not delivery or consumption. “pending”/“not_stored” describe this instant; an in-flight send may still store. Retry with the same message_id to avoid duplicates.
`native_child_grant`	`agent_id`, `send_to`	Parent only: replace a live native Claude child’s exact send_to grants (bridge jobs already have access). Empty send_to revokes external grants. Never registers a peer or assigns a main role.
`network_status`	None	List discovered LAN instances and paired broker links. Discovery is untrusted and never connects automatically; pair via the local CLI.
`resource_slots`	None	Show configured resource slots (config resourceSlots; e.g. one Unity editor): holder and waiters per slot, in queue order. Read-only; jobs acquire slots via the agent-bridge slot CLI.
`send_files`	`to`, `paths`, `destination?`	Deliver files/folders to an online peer’s inbox. Paired PCs: bounded chunks, SHA-256, restart resume; returns a transfer id at once. Progress is in the dashboard and inbox on request; only completed/failed/cancelled results arrive automatically. Limit: network.maxTransferBytes (default 8 GiB); older brokers and local delivery: 1 MiB / 128 entries. Symlinks/junctions rejected; received files are never executed.
`fetch_files`	`from`, `paths`	Pull files into this PC’s inbox over a paired encrypted link. The other PC must set network.fetchRoots (off by default); paths (absolute, or relative to the source session’s cwd) must stay under an allowed root. Returns a transfer id at once; progress in dashboard/inbox on request; only completed/failed/cancelled results arrive automatically.
`cancel_transfer`	`id`	Cancel a paired-PC transfer by id. Partial files stay unpublished; the cancellation is delivered when the peer reconnects. Completed transfers cannot be cancelled.
`inbox`	`include_quiet?`, `native_child?`, `mark_read?`, `limit?`, `id?`, `offset?`	Read unread messages. Quiet transfer progress, sibling copies and acknowledgements are excluded by default; include_quiet=true (or mark_read=false) shows retained copies. Messages are marked read unless mark_read=false; peeking produces no read receipt. A message too large for one result is listed by id and stays unread: read it via inbox(id=…, offset=…) in order; it is marked read only after all pages.
`wait_for_message`	`mode?`, `timeout_sec?`, `from?`, `reply_to?`, `conversation_id?`, `read_receipt_of?`, `resume_id?`	Default mode=“notify”: register a durable one-shot wait, return at once. Call once after asking, then keep working or end the turn; do not poll or re-wait. A matching unread message may return now (an active channel then owns delivery); otherwise it arrives via existing direct/auto-wake paths if supported, else on the next hook/inbox call. Auto-wake settings are unchanged. Notify waits survive /reload-plugins and session exit, have no timeout, and complete only when matching mail is consumed; mail stays queued if wake delivery fails or you are offline. mode=“block” waits and returns the message marked read; timeout_sec without mode, and read_receipt_of, default to block. One blocking call is capped at SINGLE_WAIT_SEC seconds; a message timeout then arms notify automatically. Claude Code may background calls after 120 seconds; background calls do not survive exit, and a stdio call cannot survive /reload-plugins - peers/SessionStart then show resume_id and filters. resume_id keeps saved filters/mode (mode=“notify” converts an interrupted block; mode=“cancel” archives without consuming mail). read_receipt_of is block-only and proves bridge consumption, not a reply or finished work. Nested child waits: block only.
`max_subagents`	`count`, `save?`	Set how many background subagents may run at once in this session, effective immediately (raising starts queued continuations; lowering stops none). save=true also writes the default for new sessions to ~/.agent-bridge/config.json. Only when your user asks.
`auto_wake`	`enabled`	Turn auto-wake on/off for this session: when on, a peer message arriving as you end a turn makes you continue and handle it (up to the configured hop limit agent-to-agent hops per conversation). Only when your user asks.
`spawn`	Delegation options	Start the selected agent as a background subagent; returns a job id at once. Keep working: the result arrives as a message from “-job-” (auto-injected, or wait_for_message from=). With wait=true, run in this server and return the final answer. Up to run in parallel.
`usage_limits`	`agent?`	Account usage per installed agent: Codex/Claude 5-hour and weekly windows with reset times; opencode today’s spend and free models. Check before large/parallel work to pick the agent with room, or to stop and save state. No model calls; takes a few seconds.
`list_models`	`agent`, `query?`	An agent’s access notes, defaults, and the models and effort levels it accepts for spawn. query filters models by name. No model calls.
`dashboard`	None	Open the agent-bridge dashboard (sessions, delegated runs, messages) in the user’s browser; returns its link. Only when the user asks.
`set_job_outcome`	`job`, `state`, `reason?`	Mark your finished job held (with reason) or discarded. Owning supervisor only. With jobCloseCleanup on, a discarded local worktree job pushes its commits and reaps only a proven-clean checkout; held jobs and local branches are kept.
`handoff_subagents`	`to`, `jobs?`, `note?`, `switch_project_main?`	Transfer your local jobs (running and finished, nested included) to an exact live local session, which becomes their supervisor and gets a waking inheritance message. Remote jobs and paired-PC targets are rejected; nothing is moved then.
`message_subagent`	`job`, `mode?`, `message?`, `title?`, `effort?`, `model?`, `access?`, `sandbox?`, `terminal_sandbox?`, `bypass_permissions?`, `native_subagents?`, `approvals_reviewer?`, `permission_mode?`, `auto_approve?`, `permission_profile?`	Message one of your spawn subagents (running or finished), like a native subagent - e.g. to answer its question promptly. It continues in its own session, full context, same folder/worktree. A running job receives it live at its next step (after the current tool call) and answers at once: ask its progress or redirect it. Answers arrive as job messages. A plain message never answers a pending approval - use decide or the dashboard. No message = “continue where you stopped” (recovers failed/interrupted jobs). If all slots are busy, a finished job’s continuation queues and auto-starts when one frees (cancel_subagent drops it).
`pause_subagent`	`job?`, `all?`, `reason?`	Pause one of your subagent jobs, or all of them, at a turn boundary. The same session and queued continuations are retained.
`resume_subagent`	`job?`, `all?`	Resume one paused job, or all paused jobs of this supervisor, in each job’s retained session.
`cancel_subagent`	`job`	Stop a spawn background job, or drop a queued continuation. Pass the job name (e.g. codex-job-1a2b3c4d).
`job_checklist`	`job`, `get?`, `add?`, `edit?`, `require?`, `unrequire?`, `close?`, `approve?`, `reject?`, `note?`	Read/change the checklist of one of your jobs (see checklist on spawn); no changes = read. Use it to answer a job’s checklist proposals (approve or reject - proposed until you do), react to a blocked item, or replan mid-run (add/edit/require/unrequire/close). A running Claude or Codex job is told at its next step (hook); other agents see the change when they next call checklist(). The job only ticks items (a required one only with a note) and proposes new ones; blocked items and proposals reach you like job questions. Required items open at finish mark the result incomplete. One call applies atomically; nothing is deleted (closed/rejected stay recorded). Supervisor only.
`project_checklist`	`get?`, `set?`, `add?`, `remove?`	Read/change this project’s checklist - the definition of done added to every job started here (unless checklist=“none” at spawn): steps every job must do, e.g. run focused tests, update the changelog. set replaces, add appends, remove removes (kept in the record). Its required items count like the supervisor’s: open at finish = incomplete result. Project = the one this session is registered with. Only the project main changes it (or the owner through the main); with project groups off for the project, the session registered in that project folder changes it. Anyone can read it. Running jobs keep their copy.
`checklist`	`update?`, `propose?`	Your bridge-kept to-do list for your supervisor’s task; no arguments shows it. Tick items as you work: update=[{ id, status, note }] (in_progress/done/blocked/skipped); a required item is skipped only with a note. Blocked notifies your supervisor; other ticks are quiet. Something missing? propose it: propose=[{ text, why }] - it joins only on supervisor approval; you cannot add, delete or un-require items. Required items still open at finish mark your result incomplete.
`report_progress`	`percent`, `eta_minutes?`, `note?`	Report progress to your supervisor: percent of the whole task done plus a few words on the current step. Call at start, at each milestone, and at least every few minutes; include eta_minutes when estimable and keep it updated. Does not interrupt your work.
`hook_event`	`event`, `session_id`, `stop_hook_active`, `cwd`, `agent_id`, `prompt`, `prompt_id`, `transcript_path`	Internal endpoint for agent-bridge’s own hooks. Do not call this tool.

Delegation options

agent is required: claude, codex, opencode, antigravity or muse.

Peer names default to <agent>-<project folder> (for example codex-showcase), or <agent>-session until the folder is known. An agent-kind address such as codex selects that local peer when unambiguous. Set AGENT_BRIDGE_NAME or name in the configuration to choose a peer name.

wait defaults to false; true runs in this server and returns the answer.
session_id continues an earlier run; cwd selects its working folder.
host runs on a paired PC with separate remote-job permission.
native_subagents sets the Codex child-thread budget (default 6, range 0–32; 0 disables). This differs from bridge delegation depth and concurrency.
send_to grants messaging to exact local sessions or jobs outside the default sibling scope.
timeout_sec defaults to 60 minutes with wait: true; background jobs default to the 24-hour ceiling. A timeout reports the session ID so a caller can continue retained context.
Target options include Codex sandbox and approvals_reviewer, Claude permission_mode, opencode auto_approve, and Antigravity terminal_sandbox and bypass_permissions. Codex defaults to auto_review; user forwards eligible requests.

Pass a prompt and a short title for a new job. Set access deliberately and use worktree: true for edits. host requires an absolute remote cwd; send_to grants are local-only. A continuation preserves saved settings unless explicitly overridden. See delegation, access and approval forwarding and remote jobs.

schema = {
      agent: z.enum(CODING_AGENTS).describe(remoteOnly
        ? "Agent to run on the paired machine; model and effort as its provider supports."
        : "Agent to run. Before first using an agent, call list_models(agent) for its access notes, models, efforts and defaults."),
      host: (remoteOnly ? remoteHost : remoteHost.optional()).describe("Paired instance to run on; requires absolute cwd there and its remoteJobs allowlist"),
      prompt: z.string().min(1).describe("Complete, self-contained instructions"),
      model: z
        .string()
        .regex(MODEL_NAME_PATTERN)
        .optional()
        .describe(`Model ID for the selected agent${remoteOnly ? " on that paired machine" : "; see list_models"}.`),
      effort: z
        .string()
        .regex(/^[A-Za-z0-9_-]{1,20}$/)
        .optional()
        .describe(`Thinking level for the selected agent${remoteOnly ? "" : "; see list_models"}.`),
      session_id: z.string().optional().describe("Continue a previous delegated session"),
      cwd: z
        .string()
        .optional()
        .describe(`Working directory; with worktree=true, the repo the worktree is made from. Default: ${ctx.cwd()}; pass it when the work is elsewhere.`),
      timeout_sec: z
        .number()
        .int()
        .min(10)
        .max(MAX_JOB_TIMEOUT_SEC)
        .optional()
        .describe(`Default ${DEFAULT_DELEGATE_TIMEOUT_SEC} with wait=true, none (${MAX_JOB_TIMEOUT_SEC}) for background spawn`),
      access: z
        .enum(ACCESS_LEVELS as [Access, ...Access[]])
        .optional()
        .describe(
          '"read" (default): look only. "ask": look; changes/commands are asked of the user in this session (opencode; Codex with trusted hook). "edit": may change files. For parallel/risky work combine edit with worktree=true.',
        ),
      worktree: z
        .boolean()
        .optional()
        .describe(
          "Run in a new git worktree on its own branch (implies access=edit); your working copy is untouched. The result says how to review, merge or discard.",
        ),
      base: z.string().min(1).max(4096).optional().describe("Worktree base ref/commit. Default: compare HEAD with its fetched upstream (else the remote default): advance only if purely behind; equal/ahead/diverged keeps HEAD. Offline: cached reference, else HEAD with a warning. Local-only repos: HEAD. The choice is reported at job start."),
      title: z
        .string()
        .min(1)
        .max(MAX_TITLE_CHARS)
        .describe('Short title, 3-7 words, e.g. "Fix castle gate alignment". Required; shown in peers/dashboard.'),
      allow_tools: z
        .array(z.string().min(1).max(200))
        .max(50)
        .optional()
        .describe(
          'MCP tools the job may call without asking, as "server.tool" patterns with *: e.g. ["pair-desk.get_*", "pair-desk.list_*"] (reads), "pair-desk:worker" (reads, comments, progress, plans, steps, issue edits, review locations - not issue creation, status, builds or handoff), or "server" (all its tools). Add "pair-desk.create_issue"/"pair-desk.set_build" separately for those. ' +
          `Default: ${defaultAllowText(cfg)} (config jobs.defaultAllowTools); a passed list replaces it (re-include "pair-desk:worker" to keep it); [] = none.`,
        ),
      send_to: z.array(z.string().refine(isJobSendTarget, "Use an exact local session or job name, not an agent kind, broadcast, wildcard or remote address"))
        .max(MAX_JOB_SEND_TARGETS).optional()
        .describe("Allow this job to send to these exact local session/job names, including replies to mail its supervisor received. Default: closed; no other external recipients. Cross-session jobs need a reciprocal grant to answer; hop limits and quiet copies to both owners remain. Kept across continuations."),
      notes: z.enum(["none", "milestones", "blockers"]).optional().describe("Reporting cadence; default none (final report only). Routine notes stay in dashboard/history; questions, final results and approvals can still request attention."),
      checklist: z.union([z.literal("none"), z.array(checklistItemSchema).max(CHECKLIST_LIMITS.items)]).optional().describe(remoteOnly ? CHECKLIST_REMOTE : CHECKLIST_ARG_DESCRIPTION),
      // Validate these at dispatch so options for another target remain ignored, as before.
      ...Object.fromEntries(CODING_AGENTS.flatMap(target => Object.entries(DELEGATION_TARGETS[target].schema)
        .map(([key, field]) => [key, z.unknown().optional().describe(`${target} only: ${field.description ?? key}`)]))),
    }

schema: {
      terminal_sandbox: z.boolean().optional().describe("Enable agy's terminal sandbox (separate from tool permissions)"),
      bypass_permissions: z.boolean().optional().describe("Antigravity override: true bypasses native approvals, false keeps native policy. Overrides read/ask access; handoff restrictions remain."),
    }

schema: {
      native_subagents: nativeSubagentsSchema,
      sandbox: z.enum(CODEX_SANDBOXES as [string, ...string[]]).optional().describe("Overrides access with an exact Codex sandbox mode"),
      approvals_reviewer: z.enum(CODEX_APPROVALS_REVIEWERS).optional().describe("Reviewer: auto_review (approve for me; default) or user (forward approvals). Sandbox unchanged."),
    }

schema: { permission_mode: z.enum(CLAUDE_PERMISSION_MODES as [string, ...string[]]).optional().describe("Overrides access with an exact Claude permission mode") }

schema: {
      permission_profile: z.string().min(1).max(80).optional().describe("Muse permission profile name (--permission-profile)"),
    }

schema: { auto_approve: z.boolean().optional().describe("Overrides access: auto-approve all opencode permissions (opencode run --auto)") }

Parameter schemas

The following source excerpts preserve bounds and defaults. A question mark in the table means the schema uses .optional(). Named shared schemas are defined in the product source.

t3_capabilities

search: z.string().min(1).max(512).optional()

t3_task_status

taskId: z.string().min(1).max(512)

t3_task_cancel

taskId: z.string().min(1).max(512)
clientRequestId: t3RequestId
reason: z.string().max(1000).optional()

t3_send

message: z.string().min(1).max(64_000)
clientRequestId: t3RequestId
mode: t3Mode.optional()
taskId: z.string().min(1).max(512).optional()

withdraw_owner_question

id: z.uuid()
status: z.enum(["cancelled","superseded"])
reason: z.string().trim().min(1).max(1000)
supersededBy: z.uuid().optional()

decide

approval_id: z.uuid().optional().describe("Pending approval id from the job question or dashboard")
decision: z.enum(["allow", "deny", "escalate"]).optional()
reason: z.string().max(4000).optional()
topic: z.string().trim().min(1).max(MAX_DECISION_TOPIC_CHARS).optional().describe("Stable topic; trimmed and case-insensitive")
text: z.string().trim().min(1).max(MAX_DECISION_TEXT_CHARS).optional().describe("The owner's decision text")
scope: decisionScopeSchema.optional().describe('"all", {project: folder}, or {sessions: [peer names/ids/session ids]}')
source_message_id: z.string().optional().describe("Optional existing bridge message id recording the owner's choice")

decisions

query: z.string().max(MAX_DECISION_TEXT_CHARS).optional()
scope: decisionScopeSchema.optional().describe('"all", {project: folder}, or {sessions: [names/ids]}; project/session scopes include global decisions')
history: z.boolean().optional()

project_main

to: z.string().min(1).max(64)

coordinator_availability

unavailable: z.boolean()

peers

native_child: z.string().optional().describe("Native Claude agent_id from its start hook; scopes the call to that child")
job: z.string().optional().describe("Exact job name: its stored report + receipt (own jobs only)")
agent: z.enum(CODING_AGENTS as unknown as [string, ...string[]]).optional()
project: z.string().max(256).optional().describe("Project folder substring")
status: z.string().max(64).optional().describe("Peer activity or job status")
name: z.string().max(256).optional().describe("Case-insensitive name or title substring")
limit: z.number().int().min(1).max(500).optional()
offset: z.number().int().nonnegative().optional()

send

to: z.string().min(1).describe('Peer name, project address, agent kind, "*" (sessions and your running jobs), or "jobs:*" (only your running jobs)')
native_child: z.string().optional().describe("Your scoped native Claude agent_id from SubagentStart; send as that child")
message: z.string().min(1).max(MAX_BODY_CHARS).describe("Message text (Markdown is fine)")
reply_to: z.string().optional().describe("Id of the message you are answering")
conversation_id: z.string().optional().describe("Continue an existing conversation")
if_no_newer_than: z.string().optional().describe("Refuse if newer unread conversation or recipient mail exists after this message id")
message_kind: z.enum(["note", "question"]).optional().describe("note: FYI/status kept in history; never wakes or enters context. question: needs supervisor attention (job blocked, or before a risky step)")
message_id: z.uuid().optional().describe("Stable UUID for idempotent send/recovery retry; reuse only with identical content. Needs an updated broker.")
mode: z.enum(["auto", "queue", "steer", "restart"]).optional().describe("Omitted/auto retains existing delivery. Queue is one-shot only to a current authenticated Claude native child, rejects message_id and proves stored mail only. Session/job queue, steer and restart refuse; unknown outcomes never retry or fall back.")

send_status

message_id: z.uuid().optional()
to: z.string().min(1).max(256).optional().describe("Instead of message_id: list your latest stored sends to this address among recent mail (for a send that was interrupted before it returned an id)")

native_child_grant

agent_id: z.string()
send_to: z.array(z.string()).max(20)

send_files

to: z.string().min(1).describe("Peer name, including host/peer for a paired instance")
paths: z.array(z.string().min(1)).min(1).max(MAX_STREAM_ENTRIES).describe("Files/folders: absolute, or relative to this session's cwd")
destination: z.enum(["downloads"]).optional().describe("Paired PC only: also place the received files in that PC's Downloads folder (new names, never overwriting; the inbox copy stays). On by default; a PC turns it off with network.transferDestinations: {}. Both sides are told where the files went")

fetch_files

from: z.string().min(1).describe("Paired host/peer to fetch from")
paths: z.array(z.string().min(1)).min(1).max(MAX_STREAM_ENTRIES)

cancel_transfer

id: z.uuid()

inbox

include_quiet: z.boolean().optional().describe("Include historical quiet coordination copies (default false)")
native_child: z.string().optional().describe("Your scoped native Claude agent_id; read only that child's inbox")
mark_read: z.boolean().optional().describe("Mark returned messages read (default true); false peeks, including retained quiet copies")
limit: z.number().int().min(1).max(100).optional()
id: z.string().min(1).max(256).optional().describe("Read this one unread message in pages (when too large for one result)")
offset: z.number().int().nonnegative().optional().describe("With id: the body character to start the page at (default 0)")

wait_for_message

mode: z.enum(["notify", "block", "cancel"]).optional().describe("Default notify; block for a bounded synchronous result; cancel a saved wait with resume_id")
timeout_sec: z.number().int().min(1).max(MAX_WAIT_SEC).optional().describe(`Block only: default and single-call cap ${SINGLE_WAIT_SEC}; without mode selects legacy block. Ignored in notify`)
from: z.string().optional().describe("Only accept messages from this peer name or agent kind")
reply_to: z.string().optional().describe("Only accept replies to this message id")
conversation_id: z.string().optional()
read_receipt_of: z.uuid().optional().describe("Wait until all recipients consumed this sent message")
resume_id: z.uuid().optional().describe("Saved wait id shown by peers or SessionStart after a reload")

max_subagents

count: z.number().int().min(1).max(MAX_JOBS_LIMIT)
save: z.boolean().optional()

auto_wake

enabled: z.boolean()

spawn

wait: z.boolean().optional().describe("Wait for the answer and return it instead of running in the background; default false.")
title: schema.title.optional().describe("Short title, 3-7 words. Optional for background runs: derived from the prompt's first non-empty line if omitted (noted in the result).")

usage_limits

agent: z.enum(CODING_AGENTS as unknown as [string, ...string[]]).optional().describe("Only this agent (default: all installed)")

list_models

agent: z.enum(targets as [CodingAgent, ...CodingAgent[]]).describe("The subagent agent")
query: z.string().max(80).optional().describe('Filter, e.g. "sonnet" or "openai/"')

set_job_outcome

job: z.string().min(1)
state: z.enum(["held", "discarded"])
reason: z.string().max(MAX_HOLD_REASON_CHARS).optional()

handoff_subagents

to: z.string().min(1).max(64).describe("Exact live local session name from peers")
jobs: z.union([z.literal("all"), z.array(z.string().min(1).max(80)).min(1).max(1000)]).optional().describe("Exact job names, or all (default)")
note: z.string().max(4000).optional().describe("Context for the new supervisor")
switch_project_main: z.boolean().optional().describe("With all jobs, also make the same-project target the main session")

message_subagent

job: z.string().min(1).describe('Job name, e.g. "codex-job-1a2b3c4d" or "opencode-ask-9f8e7d6c" (see peers)')
mode: z.enum(["auto", "queue", "steer", "restart"]).optional().describe("Omitted/auto preserves existing continuation behavior. Explicit queue/steer/restart refuse before title, settings or continuation; job emission cannot prove durable acceptance.")
message: z.string().optional().describe("Follow-up text. Default: continue where you stopped, finish the task.")
title: z.string().min(1).max(MAX_TITLE_CHARS).optional().describe("New short title (3-7 words), e.g. for an untitled job")
effort: z .string() .regex(/^[A-Za-z0-9_-]{1,20}$/) .optional() .describe("Effort for this continuation and later turns. A running turn keeps its level; cancel_subagent + message_subagent applies it now.")
model: z.string().regex(MODEL_NAME_PATTERN).optional().describe("Model for this and later turns; a running turn keeps its model")
access: z.enum(ACCESS_LEVELS as [Access, ...Access[]]).optional().describe("Next-turn access: read/ask/edit. Replaces earlier exact permission overrides")
sandbox: z.enum(CODEX_SANDBOXES as [string, ...string[]]).optional().describe("Codex sandbox for the next turn. A running turn keeps its sandbox.")
terminal_sandbox: z.boolean().optional().describe("Antigravity terminal sandbox for the next turn.")
bypass_permissions: z.boolean().optional().describe("Antigravity next turn: true bypasses native approvals, false keeps native policy")
native_subagents: nativeSubagentsSchema
approvals_reviewer: z.enum(CODEX_APPROVALS_REVIEWERS).optional().describe("Codex reviewer next turn: auto_review or user (running turn unchanged)")
permission_mode: z.enum(CLAUDE_PERMISSION_MODES as [string, ...string[]]).optional().describe("Claude permission mode for the next turn.")
auto_approve: z.boolean().optional().describe("opencode auto-approval for the next turn.")
permission_profile: z.string().trim().min(1).max(80).optional().describe("Muse permission profile next turn; replaces earlier access")

pause_subagent

job: z.string().min(1).optional().describe("One job name")
all: z.boolean().optional().describe("True to pause all jobs of this supervisor")
reason: z.string().max(500).optional()

resume_subagent

job: z.string().min(1).optional()
all: z.boolean().optional()

cancel_subagent

job: z.string().min(1)

job_checklist

job: z.string().min(1).max(80).describe('Job name, e.g. "codex-job-1a2b3c4d" (see peers)')
get: z.boolean().optional().describe("Return the list (the default when nothing changes)")
add: z.array(checklistItemSchema).min(1).max(CHECKLIST_LIMITS.items).optional().describe("New items; required unless required=false")
edit: z.array(z.object({ id: z.string().regex(/^c\d{1,4}$/), text: z.string().min(1).max(CHECKLIST_LIMITS.text).optional(), required: z.boolean().optional() })) .min(1).max(CHECKLIST_LIMITS.batch).optional().describe("Change an item's text or required flag")
require: itemIds.optional().describe("Item ids to make required")
unrequire: itemIds.optional().describe("Item ids to make optional")
close: itemIds.optional().describe("Item ids that no longer apply; they stop counting")
approve: itemIds.optional().describe("Proposed ids to accept (optional until required)")
reject: itemIds.optional().describe("Proposed item ids to turn down")
note: z.string().max(CHECKLIST_LIMITS.note).optional().describe("Why, stored with closed, approved or rejected items")

project_checklist

get: z.boolean().optional().describe("Return the list (the default when nothing changes)")
set: z.array(checklistItemSchema).max(CHECKLIST_LIMITS.projectItems).optional().describe("Replace the whole list; [] empties it")
add: z.array(checklistItemSchema).min(1).max(CHECKLIST_LIMITS.projectItems).optional().describe("Items to append; required unless required=false")
remove: z.array(z.string().regex(/^p\d{1,4}$/)).min(1).max(CHECKLIST_LIMITS.projectItems).optional().describe("Item ids to remove")

checklist

update: z.array(z.object({ id: z.string().regex(/^c\d{1,4}$/), status: z.enum(JOB_ITEM_STATUSES), note: z.string().max(CHECKLIST_LIMITS.note).optional().describe("What you did, why you skipped it, or what blocks it") })) .max(CHECKLIST_LIMITS.batch).optional()
propose: z.array(z.object({ text: z.string().min(1).max(CHECKLIST_LIMITS.text), why: z.string().max(CHECKLIST_LIMITS.note).optional() })) .max(CHECKLIST_LIMITS.proposals).optional()

report_progress

percent: z.number().min(0).max(100).describe("Percent of the whole task done, 0-100")
eta_minutes: z.number().min(0).max(1440).optional().describe("Minutes until done (0-1440); update as the estimate changes")
note: z.string().max(200).optional().describe('Current step in a few words, e.g. "tests pass, updating docs"')

hook_event

event: z.string()
session_id: z.string().nullish()
stop_hook_active: z.union([z.boolean(), z.string()]).nullish()
cwd: z.string().nullish()
agent_id: z.string().nullish()
prompt: z.string().nullish()
prompt_id: z.string().nullish()
transcript_path: z.string().nullish()