Browse documentation

Technical documentation / Reference

Client-provided local-agent tools

magi-code serve --stdio can advertise client-provided tools to the existing agent runner. This optional version-1 extension supplements built-ins; it never replaces their execution, permissions or safeguards. The spawning client executes only its registered tools and owns any approval UI. Registration does not certify that approval occurred.

Negotiate once

Require client.tools and supply client_tools in initialize.params. The field is required when negotiated and forbidden otherwise; null is invalid, an empty array is valid. Example params (not a complete frame):

{
  "required_capabilities": ["client.tools", "session.create", "turn.start"],
  "client_tools": [{
    "name": "client__lookup_record",
    "description": "Look up a record by identifier.",
    "input_schema": {
      "type": "object",
      "properties": {"record_id": {"type": "string"}},
      "required": ["record_id"],
      "additionalProperties": false
    },
    "timeout_ms": 30000
  }]
}

Descriptors accept exactly name, description, input_schema and optional timeout_ms; unknown or duplicate descriptor fields fail. Names must be unique. The entire registry is validated before startup effects; invalid registration returns invalid_params. Corrected preflight requests need fresh request IDs. Once initialization is admitted, restart the child to change registration. There is no registration/update/unregister method.

Only negotiated clients receive client.tools in capabilities, client_tools: {"tools":[names],"limits":{...}}, and extensions["client.tools"]. Names retain registration order. The extension descriptor has schema_version:1, registration:"startup_only", the same names and limits. Up to 18 required-capability entries are allowed when requesting this extension; without it, the existing maximum remains 16. tool.cards negotiates independently.

Bounds and schemas

Limit keyValue / meaning
tools32 descriptors per child
name_bytes64 ASCII bytes: client__ plus 1–56 letters, digits or underscores; case-sensitive
description_bytes2048 UTF-8 bytes; nonblank; no controls except LF/tab
registry_bytes32768 compact serialized bytes of the effective descriptor array, including defaulted timeouts
schema_bytes8192 compact serialized bytes per input schema
schema_depth16 containers, root counts as one
arguments_bytes16384 compact serialized bytes; arguments must be an object
result_bytes32768: UTF-8 text bytes plus compact structured JSON bytes if present
pending_calls16 across root, all subagents and Code Mode
default_timeout_ms30000
min_timeout_ms / max_timeout_ms1000 / 300000 inclusive

The schema root must explicitly have "type":"object". Backend validates a bounded inline subset, not instances against JSON Schema. Supported schema keywords:

Nested schemas may be booleans. Schema containers and keyword value types are checked; unknown keywords, including $schema and schema references, fail rather than being ignored. Literal enum, const, default and examples values remain data. No resolution, network/file access, regex compilation or full schema evaluation occurs. Providers may reject unsupported schemas; backend does not replace them with an unconstrained schema. Client must validate actual arguments and return an error on mismatch.

All bounds apply together with the base protocol: input frame 65536 bytes excluding LF, output frame 65536 including LF, JSON depth 32, 4096 lifetime request IDs, bounded output queues/deadlines. Escaping and envelopes count toward wire bounds. No argument/schema/result truncation to fit. An outgoing call exceeding wire bounds fails locally with client_tool_payload_limit; within-frame invalid result fields return invalid_params; oversized input frames retain base close behavior.

Execute and reply

client.tool.call is a critical event, independent of cards. Its data contains exactly:

{
  "session_id": "root-session",
  "run_id": "root-run",
  "call_id": "fresh-UUID",
  "task_id": null,
  "subagent_id": null,
  "name": "client__lookup_record",
  "arguments": {"record_id": "example"},
  "timeout_ms": 30000
}

Envelope instance_id identifies the child. Session/run stay root-scoped. Root calls have null task/subagent IDs; delegated calls use backend task and activity identities, not model labels. Nested calls identify the executing subagent. Call UUIDs are separate from provider call IDs and request IDs; never reuse them or replay uncertain execution.

Reply with ordinary method client.tool.result, a fresh request ID, and exactly these params:

{
  "instance_id": "child-instance",
  "session_id": "root-session",
  "run_id": "root-run",
  "call_id": "fresh-UUID",
  "task_id": null,
  "subagent_id": null,
  "status": "success",
  "text": "Record found.",
  "structured": {"found": true}
}

All fields except structured are required. Copy the complete identity from the call/envelope. Status is success or error; text may be empty. Structured output accepts any JSON, including explicit null, distinct from omission. Both statuses may include it. No streaming, attachments, images or chunks.

{"accepted":true} acknowledges first valid broker acceptance, not durable history. Protected text and structured JSON reach ordinary tool-result handling; strings and credential-like fields are sanitized/redacted, including structured keys. Redaction collisions or excessive expanded output are rejected, never silently dropped. Error status is untrusted tool output, not a backend diagnosis. Existing required history appends and run.finished remain authoritative.

Without negotiation the method returns unsupported_method. With negotiation, normal readiness errors apply. Unknown, completed, expired, cancelled, wrong-instance or mismatched-scope calls return stale_client_tool_call. Invalid payload returns invalid_params without consuming a pending call; correct it with a fresh request ID before deadline. Duplicate request IDs retain duplicate_id; a repeated result under a fresh ID is stale. Results consume the existing request quota; reserve headroom for replies, cancellation and shutdown.

Cancellation and permissions

The absolute monotonic timeout begins before publishing the call and includes delivery, approval and execution. It is not restarted on receipt or invalid replies. Calls may finish out of order; match complete identities, not arrival order. A seventeenth pending call fails promptly with client_tool_busy, without another execution queue.

client.tool.cancel repeats session/run/call/task/subagent identity and adds reason: cancelled, timeout, run_finished or shutdown. It carries no arguments/results and requires no acknowledgement. Cancellation/expiry compete with completion; late replies are rejected. Stop client work when notified. No rollback guarantee and no automatic broker retries. Disconnect may prevent notice delivery; client must stop outstanding work on transport loss. Existing two-second output/cleanup bounds still apply.

Tools pass through normal pre/post hooks, protected results, cancellation and persistence. Argument shape/size is rechecked after pre-call hook transformation. Direct full/compact catalogs and Code Mode discovery/calls expose only permitted tools; existing MCP compact visibility is unchanged. Direct and Code Mode exclusions remain independent. Client tools cannot claim built-in/MCP names, bypass their approvals or serve as fallback execution for them.

Noninspection subagents inherit the registry within profile, task and per-surface restrictions. Inspection tasks cannot call any client tool, including tools described as read-only. Saved delegated permissions capture explicit names and SHA-256 effective-descriptor fingerprints (default timeout included, object keys sorted, array order retained). Resume intersects current registry and saved/current restrictions. New, removed or changed tools are unavailable; missing legacy client permissions deny all client tools. Legacy delegated sessions without a saved scope also receive none. Top-level reopened sessions use the current startup registry. Registration itself is not persisted or reconstructed from tool history.

Generic tool cards may display names/status when negotiated; execution does not depend on cards. Raw arguments/results are not added to presentation history. Transport success, client execution, protected-result acceptance and durable recording remain separate outcomes.

Edit this page on GitHub ↗