Complete the plugin wire contracts: rename provider to model, add hook/event surfaces, finish category protocols

[scrothers]

What & why

Completes the wire contracts in api/ against docs/specifications/ before anything is released. A full proto-vs-spec review found spec-mandated behaviors with no wire path, missing RPCs, and naming debt; no v* tag exists yet, so this PR is the last free window for wire-breaking changes. Spec-first throughout: every proto change lands with its owning spec updated fix-forward in the same commit.

Commits are one-per-phase and reviewable independently:

1. ci: buf breaking now compares against the latest v* release tag and skips when none exists — the check previously diffed against the PR base branch, which contradicts proto.md's stated wire-compat policy and would fail every intentional pre-release change (starting with this PR).
2. Rename provider → model: package provider.v1 merges into model.v1 (ModelService, ModelError, CATEGORY_MODEL, top-level Usage); docs/specifications/provider/ → model/; every cross-reference, rule file, and hand-written Go reference updated; pkg/provider deleted, stubs regenerated.
3. hook/v1 + shared foundations: the previously-unwired hook-dispatch surface (HookSubscriberService.DispatchHook, typed per-point payloads, observe/transform/veto semantics, fail-closed veto, HookError taxonomy, EVENT_KIND_HOOK_ERROR); HookPoint homed in common.v1 to stay cycle-free; CallContext; ApplyResult in plan.v1; ContextSection/Stability relocated to content.v1; ConfigAttribute nested object schema + defaults; RunSessionResult aggregate cost/usage.
4. Category protocol completion: model (assembled context handoff, cache breakpoints, GenerationParams, input-size-tiered pricing, reasoning tokens, REFUSAL/STOP_SEQUENCE, DocumentBlock, Message identity/attribution, per-model CountTokens), tool (CallContext with cwd, side-effect-free Preview for the plan gate, default_timeout/idempotent), context/memory (turn_id standardization, compactor pressure stats, ListRecords/GetRecord, record provenance, relevance score, INVALID_SCOPE), frontend/widget/plan/session (connection-scoped multiplexed Attach with full session lifecycle — create/attach/resume/detach/list, deletion deliberately withheld from all plugins; supersedes-replay backfill; aggregate slash-command registry; usage and own-status events; PlanDecisionScope; content-block UserMessage; PlanItem kind/risk/description/preview snapshots; WidgetError; SessionInfo). Every category gains Describe (live ProducerRef identity, closing the dev_overrides gap) and supported_hook_points.
5. event/v1: one payload message per EventKind — schema_version "1" of each kind, normative for the emitting owner while staying opaque to the kernel at write time.

Checklist

• Local gate passes: go mod tidy is a no-op, go build ./..., go vet ./..., gofmt -l -s . prints nothing, go test -race -covermode=atomic ./..., golangci-lint run
• Observable behavior changes update the matching docs/specifications/ document in this same PR
• No hand edits under pkg/*/proto/v1/ — .proto changes made in api/ and regenerated with buf generate
• Doc cross-references are path + heading anchor (never section numbers); renamed headings were grepped for inbound anchors
• New internal/ packages include README.md + CLAUDE.md in the same commit (n/a — no new internal/ packages)
• No compiled artifacts outside bin/

Notes for reviewers

• This PR is the last free pass for wire-breaking proto changes. Once the first v* tag ships, the re-scoped buf breaking check activates and every released package's contract becomes permanent.
• The buf breaking step intentionally reports nothing on this PR (no release tag exists); gosec/govulncheck/mkdocs build --strict were also run locally and are clean.
• Spec sections deserving close reading: agent-loop/hook-dispatch.md (new wire contract + per-point transform-mutability table; the veto trust-model open question is resolved as "any plugin declared in agent.hcl"), frontend/frontend-protocol.md (Attach reframed as connection-scoped with per-session subscription; session deletion is deliberately not exposed to any plugin), state-backend.md (kind→event.v1 mapping and the normative-for-owner/opaque-to-kernel distinction).
• FRONTEND_ERROR_CATEGORY_SESSION_BUSY is defined but currently untriggerable (deletion was withheld); kept reserved with an open-question note in frontend/conformance.md.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

This PR completes and aligns the project’s gRPC/protobuf “wire contracts” and specs prior to the first release by renaming the model-provider category (provider → model), adding missing protocol surfaces (notably Describe, hook dispatch, and tool Preview), and updating documentation/specs to match.

Changes:

• Renames the model-provider category across protos, generated stubs, kernel code, and specs (provider → model).
• Adds/extends protocol surfaces across categories (e.g., Describe RPCs, tool Preview, hook dispatch service, widget error taxonomy, expanded plan/session shapes).
• Updates specifications and documentation to reflect the revised contracts and behaviors, plus CI buf breaking policy to compare against the latest v* tag (skipping when none exists).

Reviewed changes

Copilot reviewed 118 out of 121 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/widget/proto/v1/widget_grpc.pb.go	Adds generated Describe RPC plumbing for WidgetService.
pkg/tool/proto/v1/tool_grpc.pb.go	Adds generated Preview + Describe RPC plumbing for ToolService; updates model ref text.
pkg/slashcommand/proto/v1/slashcommand.pb.go	Updates spec references from provider → model.
pkg/schema/proto/v1/schema.pb.go	Updates schema package comments to reference model spec instead of provider.
pkg/render/proto/v1/render.pb.go	Adds ActionNode.provider field to rendered action payloads.
pkg/hook/proto/v1/hook_grpc.pb.go	Introduces generated gRPC stubs for HookSubscriberService dispatch.
pkg/context/proto/v1/context_grpc.pb.go	Adds generated Describe RPC plumbing for ContextService.
pkg/config/proto/v1/config.pb.go	Extends config schema types with nested object attributes + default JSON support.
pkg/common/plugin.go	Updates PluginKey mapping for CATEGORY_MODEL.
pkg/common/plugin_test.go	Updates PluginKey test to expect model category key.
mkdocs.yml	Renames docs nav paths from specifications/provider → specifications/model.
internal/telemetry/span_test.go	Updates ProducerRef category constant to CATEGORY_MODEL.
internal/statebackend/event.go	Adds hook-error kind mapping; updates producer category text to model.
internal/statebackend/event_test.go	Adds test for hook-error event kind encoding; updates category usage.
internal/statebackend/doc.go	Updates doc references and category vocabulary to model.
internal/pluginruntime/README.md	Updates example client type names from provider → model.
internal/pluginruntime/launch.go	Updates comments/examples to refer to model client.
internal/pluginruntime/doc.go	Updates package docs to refer to model client.
internal/pluginruntime/adapter.go	Switches category client construction from provider to model.
internal/pluginruntime/adapter_test.go	Updates tests for CATEGORY_MODEL and model client types.
internal/kernelcallback/server_test.go	Updates spoofed ProducerRef category constant to CATEGORY_MODEL.
internal/agentprofile/types.go	Updates comment to point at pkg/model proto types.
internal/agentprofile/tools.go	Updates spec cross-reference from provider → model.
internal/agentprofile/model.go	Switches imports/types from provider v1 to model v1; updates spec refs.
internal/agentprofile/model_test.go	Updates tests to use model v1 proto types.
internal/agentprofile/doc.go	Updates spec cross-reference from provider → model.
docs/specifications/tool/README.md	Updates tool protocol overview for model rename + new RPC surfaces.
docs/specifications/tool/examples.md	Updates tool examples for Preview/Describe and CallContext fields.
docs/specifications/tool/data-types.md	Documents ToolCall.call_context and updated model references.
docs/specifications/tool/conformance.md	Updates conformance taxonomy references and adds new requirements (Describe, call_context, idempotent/default_timeout, Preview).
docs/specifications/README.md	Updates top-level reading order to use model/ directory.
docs/specifications/model/README.md	Updates model provider overview and RPC list (provider → model).
docs/specifications/model/examples.md	Updates model service name and expands request/usage examples (ids, context, caching, refusal/stop-sequence).
docs/specifications/model/conformance.md	Updates taxonomy naming and adds new capability requirements (Describe, documents, cache breakpoints, tool-choice modes, supported_hook_points, reasoning tokens).
docs/specifications/memory/README.md	Expands memory protocol surface (ListRecords/GetRecord/Describe) and updates model references.
docs/specifications/memory/protocol.md	Adds enumeration/audit path semantics and updates hook trigger semantics and model references.
docs/specifications/memory/examples.md	Expands memory service example with ListRecords/GetRecord/Describe and adds new record fields (relevance/provenance).
docs/specifications/memory/data-types.md	Adds supported_hook_points, turn_id ULID, provenance, relevance_score, list/get record shapes, invalid_scope.
docs/specifications/memory/conformance.md	Updates conformance matrix for new RPCs/fields and invalid_scope mapping.
docs/specifications/kernel-callbacks.md	Updates CountTokens references to model; documents Emit payload schema_version and hook-error semantics.
docs/specifications/glossary.md	Updates category directory reference and adds event schema/backfill terms.
docs/specifications/frontend/widget-protocol.md	Adds Describe, supported_hook_points, WidgetError taxonomy, and clarifies widget attach scope.
docs/specifications/frontend/render-tree.md	Adds ActionNode.provider and defines RenderRequest schema_version semantics.
docs/specifications/frontend/README.md	Updates frontend/widget overview for connection-scoped Attach, Describe, lifecycle/backfill, and registry semantics.
docs/specifications/frontend/examples.md	Updates frontend/widget service excerpts and worked attach/backfill example (including decision scoping).
docs/specifications/frontend/conformance.md	Updates frontend/widget conformance requirements for schema_version, Describe, lifecycle/backfill, provider disambiguation, and WidgetError taxonomy.
docs/specifications/conventions.md	Updates cross-reference examples and directory shape to model/.
docs/specifications/context/README.md	Adds Describe to context provider surface and updates model references.
docs/specifications/context/protocol.md	Adds supported_hook_points and Describe; standardizes turn_id and compactor timing signals; adds Render schema_version note.
docs/specifications/context/examples.md	Updates context protocol excerpt for turn_id/history signals and Describe.
docs/specifications/context/data-types.md	Moves ContextSection/Stability to content.v1, standardizes turn_id, adds compactor timing signals, updates model references.
docs/specifications/context/conformance.md	Adds Describe and history-token signal requirements; updates model taxonomy reference.
docs/specifications/configuration/settings-and-global.md	Updates retry policy reference from provider conformance → model conformance.
docs/specifications/configuration/README.md	Updates configuration overview references to model/.
docs/specifications/configuration/lock-file.md	Documents dev_overrides identity resolution via Describe RPC.
docs/specifications/configuration/blocks-reference.md	Documents nested object config attributes and default_json semantics.
docs/specifications/configuration/agent-profiles.md	Updates model routing references to model/ README.
docs/specifications/architecture.md	Updates model provider references; formalizes hook wire surface and veto trust model text.
docs/specifications/agent-loop/turn-algorithm.md	Updates cost accounting references to model pricing/spec.
docs/specifications/agent-loop/subagents.md	Adds RunSessionResult aggregate usage fields and updates cancellation reference to model streaming.
docs/specifications/agent-loop/README.md	Updates docs to model directory and reframes hook-dispatch section.
docs/specifications/agent-loop/plan-apply-gate.md	Adds plan snapshot fields and Preview flow; introduces PlanDecisionScope semantics.
docs/specifications/agent-loop/error-recovery.md	Updates model error recovery references and naming.
docs/specifications/agent-loop/conformance.md	Adds third-party veto subscription as MAY and removes superseded open question.
docs/index.md	Updates model provider link to specifications/model.
docs/first-party/tools/mcp-client.md	Updates schema subset reference from provider → model.
docs/first-party/tools/image-vision.md	Updates model spec references for vision/canonical message schema.
docs/first-party/providers/xai.md	Updates model provider spec references from provider → model.
docs/first-party/providers/README.md	Updates authoritative spec location from specifications/provider → specifications/model.
docs/first-party/providers/openai.md	Updates all model-provider spec references from provider → model.
docs/first-party/providers/google.md	Updates all model-provider spec references from provider → model.
CONTRIBUTING.md	Updates CI/buf breaking policy description to compare against latest v* tag.
CLAUDE.md	Updates repo map to reflect model/ directory naming.
api/pluggableharness/agent/widget/v1/widget.proto	Adds Describe RPC, supported_hook_points, and WidgetError taxonomy.
api/pluggableharness/agent/tool/v1/tool.proto	Adds Preview + Describe RPCs, call_context, default_timeout, idempotent, and RenderRequest.schema_version.
api/pluggableharness/agent/slashcommand/v1/slashcommand.proto	Updates capability reference from provider → model.
api/pluggableharness/agent/session/v1/session.proto	Adds SessionInfo message (timestamps + optional cost).
api/pluggableharness/agent/schema/v1/schema.proto	Updates schema doc comments from provider → model.
api/pluggableharness/agent/render/v1/render.proto	Adds ActionNode.provider to disambiguate tool provider.
api/pluggableharness/agent/plan/v1/plan.proto	Adds plan snapshot fields + optional preview; introduces ApplyResult and apply outcomes.
api/pluggableharness/agent/kernel/v1/kernel.proto	Extends RunSessionResult with aggregate cost/tokens; adds EVENT_KIND_HOOK_ERROR; updates CountTokens comment refs.
api/pluggableharness/agent/config/v1/config.proto	Adds nested object_attributes and optional default_json to ConfigAttribute.
api/pluggableharness/agent/common/v1/common.proto	Renames CATEGORY_PROVIDER → CATEGORY_MODEL; adds HookPoint enum and CallContext message.
.github/workflows/ci.yml	Updates buf breaking to compare against latest v* tag and skip when none exists.
.claude/rules/proto.md	Updates proto packaging/versioning guidance from provider → model.
.claude/rules/grpc.md	Updates grpc shape table and error mapping refs from provider → model.
.claude/rules/go-layout.md	Updates Go layout doc to reflect pkg/model.
.claude/rules/determinism.md	Updates determinism doc reference from provider → model cost computation.

Comments suppressed due to low confidence (2)

docs/specifications/model/README.md:3

• This sentence says "the other five" but then lists four protocol directories. Since widget is documented under frontend/, consider wording this as either “the other five categories” (explicitly listing widget) or “the other four protocol directories”.
  docs/specifications/model/README.md:19
• This bullet calls out “the six RPCs” and includes Render, but earlier this README frames Render as optional and counts five required RPCs. Consider avoiding a hard count here and explicitly marking Render as optional to keep the transport summary and the category-structure list consistent.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.