Skip to content

Tool provider protocol#

Covers the tool provider category — file I/O, shell execution, search, web access, task tracking, sub-agent spawning, and similar operations (Claude Code's "tools," Terraform's closest analog would be a provider's resources and data sources combined). Sibling to model/ (model provider) in this system's Terraform-derived vocabulary; the other plugin categories (context/, memory/, frontend/) follow the same shape this and model/ establish.

Tool sets converge strongly across agentic coding harnesses on a common core of operations. Where that convergence exists, this category treats it as evidence for what belongs in the reference catalog (reference-catalog.md). Where genuine divergence exists (edit mechanisms, risk/approval models, concurrency handling), this category calls that out explicitly rather than picking one approach and presenting it as settled.

This category depends directly on model/: the common JSON-Schema subset tool authors write input_schema/output_schema within is the same one model/data-types.md#tool-schema defines for model tool-calling declarations (one wire type, pluggableharness.schema.v1.Schema, shared by both categories), and Invoke's server-streaming-plus-cancellation shape reuses model/README.md's StreamCompletion pattern verbatim. See architecture.md for the surrounding system (plan/apply gate, hook dispatch, Emit→Render→Paint, state backend) — this directory only covers the tool-provider RPC surface, data types, and reference catalog in detail.

Transport & lifecycle#

Subprocess + gRPC via hashicorp/go-plugin, per architecture.md. Standard handshake (magic cookie, protocol version negotiation) applies uniformly across all seven provider categories and isn't repeated per category.

A tool provider plugin exposes four RPCs: GetSchema, Configure, Invoke, Describe. It MAY additionally implement Render (see protocol.md#render) and Preview (see protocol.md#preview).

Invoke is server-streaming, the same shape model/README.md specifies for StreamCompletion and for the identical reason: a tool like exec needs to stream live stdout/stderr rather than blocking until completion, and none of the underlying primitives (process exec, HTTP fetch, file I/O) need mid-call client input on the same call. Cancellation follows the model-provider pattern exactly: the kernel cancels/closes the gRPC stream; it is not a distinct RPC or a sentinel event the plugin must invent. Plugin authors MUST treat stream cancellation as a normal, expected event — kill the child process, release file handles/sockets, discard buffers — never as an error condition. A tool provider and a model provider are both "long-running, streaming, cancellable" from the kernel's point of view, and giving them different cancellation mechanics would be an unforced inconsistency.

Category structure#

  • protocol.md — the RPCs: GetSchema (including the kind: interactive sub-classification), Configure, Invoke, Describe, Render, Preview.
  • data-types.md — ToolSchema, RiskClass, the ToolCall/ToolEvent/ToolResult shapes, and ConcurrencySpec.
  • reference-catalog.md — the first-party reference tool set this protocol defines, and the genuinely ambiguous classification calls (bash, web_fetch) worth calling out by name.
  • examples.md — a worked agent.hcl provider block, the real proto wire definitions, and a full Invoke event sequence.
  • conformance.md — the error taxonomy and the MUST/SHOULD/MAY summary matrix, plus genuinely open questions.