grok-build-upstream-mirror/crates/codegen/xai-grok-tools-api/proto/grok-tools.proto

syntax = "proto3";

package xai.grok.tools.v1;

// ============================================================================
// MAIN SERVICE
// ============================================================================

/// GrokToolsService provides a gRPC interface to the Grok tools runtime.
/// It supports tool execution, discovery, configuration, and lifecycle management.
service GrokToolsService {
  // ========== TOOL EXECUTION ==========

  /// Execute a single tool call
  rpc ExecuteTool(ExecuteToolRequest) returns (ExecuteToolResponse);

  /// Execute a tool with streaming output.
  ///
  /// Currently operates as "chunked unary" — the tool executes to completion,
  /// then the result is streamed in byte-level chunks. True incremental
  /// streaming (partial output during execution) is planned.
  rpc ExecuteToolStream(ExecuteToolRequest) returns (stream ToolStreamChunk);

  // ========== TOOL DISCOVERY ==========

  /// List all available tools with their schemas and capabilities
  rpc ListTools(ListToolsRequest) returns (ListToolsResponse);

  /// Get detailed information about a specific tool
  rpc GetToolInfo(GetToolInfoRequest) returns (ToolInfo);

  /// Used to finalize the tool configuration, after this call
  /// tools are safe to call
  rpc FinalizeToolConfigRequest(FinalizeToolServerConfigRequest)
      returns (FinalizeToolServerConfigResponse);

  // ========== TOOL STATE ==========

  /// Get the current tool state (serialized Resources).
  ///
  /// Flushes any in-flight persistence writes and waits for any active
  /// tool execution to complete before serializing, so the returned
  /// snapshot is always consistent.
  ///
  /// The returned JSON has the shape:
  /// ```json
  /// {
  ///   "params": { "<tool_id>": { ... }, ... },
  ///   "state":  { "<tool_id>": { ... }, ... }
  /// }
  /// ```
  rpc GetToolState(GetToolStateRequest) returns (GetToolStateResponse);

  // ========== DYNAMIC TOOL MANAGEMENT ==========

  /// Enable a tool (make it available for execution)
  rpc EnableTool(EnableToolRequest) returns (EnableToolResponse) {
    option deprecated = true;
  }

  /// Disable a tool (prevent execution, keep registered)
  rpc DisableTool(DisableToolRequest) returns (DisableToolResponse) {
    option deprecated = true;
  }

  // ========== TOOL OPTIONS ==========

  /// Set tool-specific options (merged with defaults)
  rpc SetToolOptions(SetToolOptionsRequest) returns (SetToolOptionsResponse) {
    option deprecated = true;
  }

  /// Get current tool options (effective options after merging)
  rpc GetToolOptions(GetToolOptionsRequest) returns (GetToolOptionsResponse) {
    option deprecated = true;
  }

  /// Reset tool options to defaults
  rpc ResetToolOptions(ResetToolOptionsRequest)
      returns (ResetToolOptionsResponse) {
    option deprecated = true;
  }

  // ========== TOOL NAME OVERRIDES ==========

  /// Set name overrides for a single tool (display name and/or parameter names).
  /// Call once per tool that needs overrides. Tools without overrides use
  /// canonical names. Overrides affect runtime error messages and schema
  /// property names returned to the model.
  rpc SetToolOverride(SetToolOverrideRequest)
      returns (SetToolOverrideResponse) {
    option deprecated = true;
  }

  /// Clear all name overrides for a tool, reverting to canonical names.
  rpc ClearToolOverride(ClearToolOverrideRequest)
      returns (ClearToolOverrideResponse) {
    option deprecated = true;
  }

  // ========== SYSTEM REMINDERS ==========

  /// Enable or disable system reminders globally.
  /// When disabled, both per-tool reminders and TodoNudge are suppressed.
  rpc SetSystemReminders(SetSystemRemindersRequest)
      returns (SetSystemRemindersResponse) {
    option deprecated = true;
  }

  /// Get the current state of the system reminders toggle.
  rpc GetSystemReminders(GetSystemRemindersRequest)
      returns (GetSystemRemindersResponse) {
    option deprecated = true;
  }

  // ========== TRUNCATION CONFIG ==========

  /// Set output truncation configuration for the session.
  /// Controls how much tool output is kept before truncation.
  /// Call once at session setup; applies to all subsequent tool executions.
  rpc SetTruncationConfig(SetTruncationConfigRequest)
      returns (SetTruncationConfigResponse) {
    option deprecated = true;
  }

  /// Get the current truncation configuration.
  rpc GetTruncationConfig(GetTruncationConfigRequest)
      returns (GetTruncationConfigResponse) {
    option deprecated = true;
  }

  // ========== AGENT ==========

  /// Get the agent's rendered system prompt.
  /// Returns empty string if the server was constructed without an agent.
  rpc GetSystemPrompt(GetSystemPromptRequest)
      returns (GetSystemPromptResponse) {
    option deprecated = true;
  }

  /// Get the agent definition metadata.
  /// Returns empty/default if the server was constructed without an agent.
  rpc GetAgentInfo(GetAgentInfoRequest) returns (GetAgentInfoResponse) {
    option deprecated = true;
  }

  /// Check whether the completion requirement has been satisfied
  /// for the current turn. Only meaningful if the agent has a
  /// completionRequirement set.
  rpc GetCompletionState(GetCompletionStateRequest)
      returns (GetCompletionStateResponse) {
    option deprecated = true;
  }

  /// Reset per-turn completion tracking. Call at the start of each
  /// new model turn so the harness gets a fresh "completed" signal.
  rpc ResetCompletionState(ResetCompletionStateRequest)
      returns (ResetCompletionStateResponse) {
    option deprecated = true;
  }

  /// Finalize the agent after all tool name/param overrides have been
  /// applied via SetToolOverride. Renders the system prompt with the
  /// current override state. After this call, SetToolOverride is
  /// rejected with an error.
  ///
  /// Not needed if the server was constructed with from_definition_file()
  /// — finalization happens automatically at build time.
  rpc FinalizeAgent(FinalizeAgentRequest) returns (FinalizeAgentResponse) {
    option deprecated = true;
  }
}

// ============================================================================
// CLIENT CALLBACK SERVICE
// ============================================================================

/// GrokToolsCallbackService is implemented by the client/host process and
/// dialed by grok-tools-server during finalize when callback fields are set.
///
/// The contract is deliberately minimal — the server owns all subagent
/// knowledge (type registry, prompts, toolset resolution, and lifecycle state
/// in the shared coordinator actor); the host only does genuinely host-side work:
///
/// - `SpawnSubagent`: execute one resolved child request to completion.
///   The RPC spans the whole request; cancellation is the call's cancellation.
/// - `SendNotification`: fire-and-forget push of serde-tagged notification
///   JSON (e.g. `SubagentCompleted`) into the host's conversation stream.
service GrokToolsCallbackService {
  /// Rust sends one tool notification to the host process.
  rpc SendNotification(ToolNotificationMsg) returns (NotificationAck);

  /// Execute one resolved child request and return its final result.
  rpc SpawnSubagent(SpawnSubagentRequest) returns (SubagentResultMsg);
}

// ============================================================================
// TOOL SERVER CONFIG MESSAGES (finalize-time configuration)
// ============================================================================

/// Request to finalize the tool server configuration.
/// After this call, the toolset is locked and tools are safe to call.
/// This replaces the old enable/disable/SetToolOptions pattern —
/// all tool selection and configuration happens in a single call.
message FinalizeToolServerConfigRequest {
  /// The tools to enable and their configuration.
  /// Only tools listed here will be available after finalization.
  repeated ToolConfigEntry tools = 1;

  /// Optional truncation configuration for the session.
  optional TruncationConfig truncation = 2;

  /// Whether system reminders should be enabled (default: false).
  bool system_reminders_enabled = 3;

  /// Optional: pre-load tool state from a previous session.
  ///
  /// JSON shape must match GetToolStateResponse.state_json:
  ///   { "params": { ... }, "state": { ... } }
  ///
  /// Applied AFTER the toolset loads any existing state from disk,
  /// so values provided here override on-disk state. Missing keys
  /// are left at their defaults (merge semantics, not replace).
  ///
  /// Typical use: pass the output of a previous GetToolState call
  /// to warm-start a new session with the same FileReadTracker,
  /// TodoState, etc.
  optional string initial_tool_state_json = 4;

  /// Behavior preset name (e.g. "current", "legacy-0.4.10").
  /// Applied to all version-managed tools. Defaults to "current" when empty.
  optional string behavior_preset = 5;

  /// Optional host callback address. When set, grok-tools-server dials this
  /// client-hosted gRPC endpoint during finalize and injects callback-backed
  /// resource views for notifications and subagents. The server accepts bare
  /// "host:port" addresses and assumes "http://".
  optional string client_callback_addr = 6;

  /// Logical session identifier used for callback correlation and resource
  /// scoping (SessionIdResource / OwnerSessionId). If omitted while a callback
  /// address is present, the server uses its generated process session id.
  optional string session_id = 7;

  /// Per-session bearer secret required by the client-hosted callback service.
  /// Only used when client_callback_addr is set.
  optional string client_callback_secret = 8;

  reserved 9;
}

/// Per-tool configuration entry.
/// Maps to `ToolConfig` in the tools library.
message ToolConfigEntry {
  /// Fully qualified tool ID: colon-separated `Namespace:tool`
  /// (e.g., "GrokBuild:bash", "GrokBuild:read_file").
  ///
  /// The whole selection path keys on this format: the default
  /// client-facing name is the segment after the FIRST colon (see
  /// `default_client_name` in the xai-grok-tools-api crate).
  string id = 1;

  /// Tool-specific parameters as JSON string.
  /// Merged with the tool's default params. Optional.
  optional string params_json = 2;

  /// Client-facing tool name override.
  /// If empty, the tool's default ID is used.
  optional string name_override = 3;

  /// Parameter name overrides (canonical param → client-facing param).
  /// Only include params that need overriding.
  map<string, string> params_name_overrides = 4;

  /// Per-tool behavior version override (e.g. "legacy-0.4.10").
  /// Wins over FinalizeToolServerConfigRequest.behavior_preset.
  /// Only valid for version-managed tools.
  optional string behavior_version = 5;

  /// Client-facing tool description override.
  /// When set, replaces the tool's built-in description entirely.
  /// The override string is still rendered through TemplateRenderer,
  /// so ${{ tools.by_kind.* }} variables resolve correctly.
  optional string description_override = 6;
}

/// Structured validation details returned when finalize rejects a tool config.
message FinalizeConfigValidationDetails {
  repeated FinalizeConfigViolation violations = 1;
}

/// One validation violation in FinalizeToolServerConfigRequest.
message FinalizeConfigViolation {
  /// Zero-based index into FinalizeToolServerConfigRequest.tools.
  optional uint32 entry_index = 1;
  /// Fully-qualified tool ID or synthetic scope like "(global)".
  string tool_id = 2;
  /// Request/config field path such as "tools[0].params_json" or "params.enabled_background".
  optional string field_path = 3;
  /// Human-readable reason for the violation.
  string message = 4;
  /// Expected type/constraint when known.
  optional string expected = 5;
  /// Preview of the rejected value as JSON/text when safe to include.
  optional string bad_value_json = 6;
  /// Machine-friendly category (e.g. "params_type", "params_json_parse").
  string category = 7;
}

/// Structured deprecation/lifecycle warning for a specific tool version
/// or bundle. Informational only — does not affect control flow.
message VersionWarning {
  /// Fully-qualified tool ID (e.g. "GrokBuild:run_terminal_cmd").
  /// Empty for bundle-level warnings.
  string fq_tool_id = 1;
  /// The deprecated version (e.g. "legacy-0.4.10").
  string deprecated_version = 2;
  /// Suggested replacement version (e.g. "current").
  string replacement = 3;
  /// Human-readable deprecation message.
  string message = 4;
}

/// Status of the optional callback connection established during finalize.
message CallbackStatus {
  bool connected = 1;
  repeated string active_surfaces = 2;
  optional string message = 3;
}

/// Response from finalizing the tool server configuration.
message FinalizeToolServerConfigResponse {
  bool success = 1;
  string message = 2;

  /// The finalized tool definitions (name, description, schema).
  /// Clients can use these to build tool schemas for the model.
  repeated ToolInfo tools = 3;

  /// Deprecation/lifecycle warnings for resolved versions.
  /// Empty when all versions are Active.
  repeated VersionWarning version_warnings = 4;

  /// Optional status for the finalize-time callback dial.
  optional CallbackStatus callback_status = 5;
}

// ============================================================================
// CALLBACK MESSAGES
// ============================================================================

message ToolNotificationMsg {
  string session_id = 1;
  /// serde(tag = "type") JSON for xai_grok_tools::notification::ToolNotification.
  string notification_json = 2;
  /// Monotonically increasing sequence number for observability.
  uint64 sequence = 3;
}

message NotificationAck {}

/// Execute one resolved child request.
///
/// The server resolves everything from its own registry and finalized
/// toolset before dialing: `system_prompt` is the complete production
/// subagent base template + definition body rendered with the child's actual
/// (possibly randomized) tool names, and `tool_names` is selected from the
/// canonical production AgentDefinition. The host executes the request with
/// the supplied tool names and working directory.
///
/// Lifecycle (backgrounding, foreground budget, query/cancel, completion
/// surfacing) is owned by the server-side coordinator actor; the host keeps
/// no lifecycle state. Cancellation = the gRPC call's cancellation.
message SpawnSubagentRequest {
  string id = 1;
  string prompt = 2;
  string description = 3;
  string subagent_type = 4;
  string parent_session_id = 5;
  optional string parent_prompt_id = 6;
  /// Resume a previously completed child: the server validates source identity
  /// and workspace; the host replays non-system turns, installs the freshly
  /// rendered `system_prompt`, and appends `prompt`.
  optional string resume_from = 7;
  optional string cwd = 8;
  reserved 9, 10, 11, 12, 13;
  /// Complete rendered production system prompt for the child.
  optional string system_prompt = 14;
  /// Client-facing names of the tools the child may use.
  repeated string tool_names = 15;
  /// Optional user message prepended before the task prompt.
  optional string initial_user_message = 16;
}

message SubagentResultMsg {
  bool success = 1;
  string output = 2;
  optional string error = 3;
  bool cancelled = 4;
  /// Deprecated: identity is stamped by the server.
  string subagent_id = 5;
  /// Deprecated: identity is stamped by the server.
  string child_session_id = 6;
  uint32 tool_calls = 7;
  uint32 turns = 8;
  uint64 duration_ms = 9;
  /// Legacy total/context usage fallback.
  uint64 tokens_used = 10;
  /// Deprecated: workspace is stamped by the server.
  optional string worktree_path = 11;
  /// Deprecated: delivery state is owned by the server.
  bool backgrounded = 12;
  optional uint64 output_tokens_used = 13;
  optional uint64 total_tokens_used = 14;
}

// ============================================================================
// TOOL EXECUTION MESSAGES
// ============================================================================

message ExecuteToolRequest {
  /// Name of the tool to execute (e.g., "read_file", "grep", "run_terminal_cmd")
  string tool_name = 1;

  /// Tool input parameters as JSON string
  string input_json = 2;

  /// Reserved for future session support
  reserved 3;

  /// Execution options (global)
  ExecutionOptions options = 4;

  /// Unique call ID for tracing (optional, generated if not provided)
  optional string call_id = 5;

  // Field 6 reserved: was tool_options_json, removed.
  // Use ToolConfigEntry.params_json in FinalizeToolServerConfigRequest instead.
  reserved 6;
}

message ExecutionOptions {
  /// Timeout in milliseconds
  optional uint64 timeout_ms = 1;

  /// Whether to run in background (for bash)
  bool background = 2;

  /// Base output format preference
  OutputFormat output_format = 3;

  /// Working directory override (for file operations)
  optional string working_directory = 4;

  /// Specific fields to include in output_json (e.g., ["path", "lines", "line_count"])
  /// If empty, includes all fields based on output_format.
  /// Field names are tool-specific; check tool's output schema for available fields.
  repeated string include_fields = 5;

  /// Fields to exclude from output_json (e.g., ["raw_bytes", "metadata"])
  /// Applied after include_fields filtering.
  /// Useful for removing large/unnecessary fields to save tokens.
  repeated string exclude_fields = 6;

  /// Maximum size of each streaming data chunk in bytes.
  /// Default: 1 MiB (1048576). Must not exceed 4 MiB (4194304).
  /// Only used by ExecuteToolStream; ignored by ExecuteTool.
  optional uint32 stream_chunk_size = 7;
}

/// Client-configurable truncation settings.
/// All fields are optional — omitted fields mean "use the tool's built-in default".
message TruncationConfig {
  /// Max total output bytes for any tool. Default: 40KB.
  /// Overrides the built-in per-tool defaults.
  optional uint32 default_max_output_bytes = 1;

  /// Per-tool max output byte overrides.
  /// Keys are canonical tool names (e.g., "run_terminal_cmd", "grep").
  map<string, uint32> per_tool_max_output_bytes = 2;

  /// Deprecated and ignored: read_file no longer clips lines (clipping
  /// silently corrupts single-line files; the whole-read token cap bounds
  /// output instead). Field number kept for wire compatibility.
  optional uint32 max_chars_per_line = 3 [deprecated = true];

  /// Max lines to read for read_file. Default: 1000.
  optional uint32 max_lines_read = 4;
}

/// Output format preference - affects output_json structure.
/// Only DEFAULT and CONCISE are supported; other values are treated as DEFAULT.
enum OutputFormat {
  OUTPUT_FORMAT_UNSPECIFIED = 0;
  /// Standard output with typical detail level
  OUTPUT_FORMAT_DEFAULT = 1;
  /// Minimal output with only essential fields (saves tokens)
  OUTPUT_FORMAT_CONCISE = 2;
  // Fields 3-4 removed (RAW, STRUCTURED were never implemented).
  reserved 3, 4;
}

message ExecuteToolResponse {
  /// Unique call ID for tracing
  string call_id = 1;

  /// Tool execution result
  oneof result {
    ToolSuccess success = 2;
    ToolError error = 3;
  }

  /// Execution metadata
  ExecutionMetadata metadata = 4;
}

message ToolSuccess {
  // Field 1 removed: output_schema_json moved to ToolInfo.output_schema_json.
  reserved 1;

  /// Structured output as JSON (conforms to the tool's output schema)
  string output_json = 2;

  /// Human-readable summary for prompt injection
  string prompt_text = 3;

  // Field 4 removed: was follow_up_messages, the tool follow-up mechanism.
  reserved 4;
  reserved "follow_up_messages";
}

message ToolError {
  /// Error code for machine processing
  ErrorCode code = 1;

  /// Human-readable error message
  string message = 2;

  /// Detailed error context as JSON
  optional string details_json = 3;

  /// Whether this error is retryable
  bool retryable = 4;

  /// Suggested fix or next action (for LLM consumption)
  optional string suggestion = 5;

  /// Related file path (if applicable)
  optional string file_path = 6;

  /// Line number (if applicable)
  optional int32 line_number = 7;
}

enum ErrorCode {
  ERROR_CODE_UNSPECIFIED = 0;

  // Input/validation errors (4xx-like)
  ERROR_CODE_INVALID_INPUT = 100;
  ERROR_CODE_MISSING_REQUIRED_FIELD = 101;
  ERROR_CODE_INVALID_TOOL_NAME = 102;
  ERROR_CODE_TOOL_DISABLED = 103;
  ERROR_CODE_TOOL_NOT_FOUND = 104;
  reserved 106;  // was TASK_NOT_FOUND, now handled by tool layer

  // File operation errors
  ERROR_CODE_FILE_NOT_FOUND = 200;
  ERROR_CODE_FILE_NOT_READ = 201;
  ERROR_CODE_FILE_EXTERNALLY_MODIFIED = 202;
  ERROR_CODE_FILE_ALREADY_EXISTS = 203;
  ERROR_CODE_PERMISSION_DENIED = 204;
  ERROR_CODE_MULTIPLE_MATCHES = 205;
  ERROR_CODE_NO_MATCHES = 206;

  // Execution errors (5xx-like)
  ERROR_CODE_EXECUTION_FAILED = 300;
  ERROR_CODE_TIMEOUT = 301;
  ERROR_CODE_CANCELLED = 302;
  ERROR_CODE_RATE_LIMITED = 303;

  // Internal errors
  ERROR_CODE_INTERNAL = 500;
  ERROR_CODE_NOT_IMPLEMENTED = 501;
}

message ExecutionMetadata {
  /// Time taken to execute in milliseconds
  uint64 duration_ms = 1;

  /// Tokens estimated in output (for LLM context management)
  int32 estimated_tokens = 2;

  /// Whether output was truncated
  bool truncated = 3;

  /// Tool version that executed
  string tool_version = 4;

  /// Resolved behavior contract version for the tool that executed
  /// (e.g. "current", "legacy-0.4.10"). Empty for unmanaged tools.
  string contract_version = 5;
}

/// Streaming output chunk
message ToolStreamChunk {
  string call_id = 1;

  oneof chunk {
    /// Incremental data chunk (prompt_text or output_json fragment)
    StreamDataChunk data = 2;

    /// Final result (always the last chunk — metadata only, no payload)
    StreamFinalResult final_result = 3;
  }
}

/// What kind of data this chunk carries.
enum StreamDataKind {
  STREAM_DATA_KIND_UNSPECIFIED = 0;
  /// Fragment of the human-readable prompt_text string.
  STREAM_DATA_KIND_PROMPT_TEXT = 1;
  /// Fragment of the structured output_json string.
  STREAM_DATA_KIND_OUTPUT_JSON = 2;
}

/// A single chunk of streamed data (either prompt_text or output_json).
message StreamDataChunk {
  /// Which field this chunk belongs to.
  StreamDataKind kind = 1;

  /// Raw bytes of the chunk (UTF-8 encoded string fragment).
  bytes data = 2;

  /// Byte offset of this chunk within the complete field.
  /// First chunk starts at 0. Subsequent chunks continue from
  /// previous offset + len(data).
  uint64 offset = 3;
}

/// Final result sent as the last streaming chunk.
/// Contains only metadata and error information — the actual payload
/// (prompt_text, output_json) has already been streamed via StreamDataChunk.
message StreamFinalResult {
  /// Execution metadata (timing, token estimates, truncation).
  ExecutionMetadata metadata = 1;

  /// If the tool execution failed, this contains the error.
  /// When present, any previously streamed data chunks should be discarded.
  optional ToolError error = 2;

  /// Total size in bytes of all prompt_text chunks combined.
  uint64 prompt_text_size = 3;

  /// Total size in bytes of all output_json chunks combined.
  uint64 output_json_size = 4;

  // Field 5 removed: was follow_up_messages, the tool follow-up mechanism.
  reserved 5;
  reserved "follow_up_messages";
}

// ============================================================================
// TOOL DISCOVERY MESSAGES
// ============================================================================

message ListToolsRequest {
  /// Filter by tool category
  optional ToolCategory category = 1;

  /// Include disabled tools
  bool include_disabled = 2;

  /// Include full schemas (can be large)
  bool include_schemas = 3;
}

enum ToolCategory {
  TOOL_CATEGORY_UNSPECIFIED = 0;
  TOOL_CATEGORY_FILE = 1;
  TOOL_CATEGORY_SEARCH = 2;
  TOOL_CATEGORY_SHELL = 3;
  TOOL_CATEGORY_WORKFLOW = 4;
  TOOL_CATEGORY_EXTERNAL = 5;
  TOOL_CATEGORY_CUSTOM = 6;
}

message ListToolsResponse {
  repeated ToolInfo tools = 1;
  int32 total_count = 2;
  int32 enabled_count = 3;
}

message GetToolInfoRequest {
  string tool_name = 1;
}

message ToolInfo {
  /// Unique tool identifier
  string name = 1;

  /// Tool display name
  string display_name = 2;

  /// Full description (for LLM system prompt)
  string description = 3;

  /// Short description (for UI)
  optional string short_description = 4;

  /// Tool category
  ToolCategory category = 5;

  /// JSON Schema for input parameters (as JSON string)
  string input_schema_json = 6;

  /// Current state
  bool enabled = 7;

  /// Tool capabilities/features
  ToolCapabilities capabilities = 8;

  /// Version info
  string version = 9;

  /// Whether this is a built-in or custom tool
  ToolSource source = 10;

  /// Reserved for removed config_schema_json
  reserved 11;

  /// Tool-specific options schema (JSON Schema as JSON string)
  /// Defines what options this tool accepts
  optional string options_schema_json = 12;

  /// Default values for tool options (as JSON string)
  optional string default_options_json = 13;

  /// Current effective options (defaults merged with configured, as JSON string)
  optional string current_options_json = 14;

  /// Supported output formats and what each includes.
  /// Each OutputFormat value should appear at most once.
  /// Server will reject duplicates during tool registration.
  repeated OutputFormatSpec output_formats = 15;

  /// All available output fields with descriptions.
  /// Each field name should be unique.
  /// Server will reject duplicates during tool registration.
  repeated OutputFieldSpec output_fields = 16;

  /// JSON Schema describing the structure of output_json returned by ExecuteTool.
  /// Generated from the tool's output types via schemars.
  string output_schema_json = 17;

  /// Resolved behavior contract version for this tool (e.g. "current",
  /// "legacy-0.4.10"). Empty for unmanaged tools.
  string contract_version = 18;

  /// Tool namespace (e.g. "GrokBuild", "Codex", "OpenCode").
  /// Populated by ListTools pre-finalization from the fully-qualified
  /// registry key (e.g. "GrokBuild:grep" → namespace="GrokBuild").
  string namespace = 19;

  // 20-21 were `allowed_capability_modes` / `tool_kind`, exposed so remote
  // clients could filter child subagent toolsets themselves. The server now
  // resolves child toolsets from its own registry and sends the result in
  // SpawnSubagentRequest, so nothing consumes them. No released pin ever
  // read them.
  reserved 20, 21;
}

/// Describes an output format supported by a tool
message OutputFormatSpec {
  /// Which format this describes
  OutputFormat format = 1;

  /// Human-readable description of this format
  string description = 2;

  /// Field names included by default in this format
  repeated string default_fields = 3;
}

/// Describes an available output field
message OutputFieldSpec {
  /// Field name (used in include_fields/exclude_fields)
  string name = 1;

  /// Human-readable description
  string description = 2;

  /// JSON type: "string", "number", "boolean", "array", "object"
  string json_type = 3;

  /// Example value (as JSON string)
  optional string example_json = 4;

  /// Which formats include this field by default
  repeated OutputFormat included_in = 5;

  /// If true, this field can be large (useful for token management)
  bool potentially_large = 6;
}

message ToolCapabilities {
  /// Can run in background
  bool supports_background = 1;

  /// Can stream output
  bool supports_streaming = 2;

  /// Reserved for future session support
  reserved 3;

  /// Has side effects (modifies files/system)
  bool has_side_effects = 4;

  /// Can be cancelled mid-execution
  bool supports_cancellation = 5;

  /// Supports timeout configuration
  bool supports_timeout = 6;

  /// Custom capability flags
  repeated string custom_capabilities = 10;
}

enum ToolSource {
  TOOL_SOURCE_UNSPECIFIED = 0;
  TOOL_SOURCE_BUILTIN = 1;
  TOOL_SOURCE_MCP = 2;
  TOOL_SOURCE_CUSTOM = 3;
  TOOL_SOURCE_SKILL = 4;
}

// ============================================================================
// DYNAMIC TOOL MANAGEMENT MESSAGES
// ============================================================================

message EnableToolRequest {
  string tool_name = 1;
}

message EnableToolResponse {
  bool success = 1;
  string message = 2;
}

message DisableToolRequest {
  string tool_name = 1;
}

message DisableToolResponse {
  bool success = 1;
  string message = 2;
}

// ============================================================================
// TOOL OPTIONS MESSAGES
// ============================================================================

message SetToolOptionsRequest {
  string tool_name = 1;

  /// Options to set (as JSON string)
  /// These are merged with existing options unless replace=true
  string options_json = 2;

  /// If true, replace all options instead of merging
  bool replace = 3;
}

message SetToolOptionsResponse {
  bool success = 1;
  string message = 2;

  /// The effective options after setting (as JSON string)
  string effective_options_json = 3;
}

message GetToolOptionsRequest {
  string tool_name = 1;

  /// If true, include the options schema in the response
  bool include_schema = 2;
}

message GetToolOptionsResponse {
  string tool_name = 1;

  /// Current effective options (defaults + configured, as JSON string)
  string effective_options_json = 2;

  /// Default options for this tool (as JSON string)
  string default_options_json = 3;

  /// User-configured options that override defaults (as JSON string)
  string configured_options_json = 4;

  /// JSON Schema for options (if include_schema was true)
  optional string options_schema_json = 5;
}

message ResetToolOptionsRequest {
  string tool_name = 1;

  /// If provided, only reset these specific option keys
  /// If empty, reset all options to defaults
  repeated string keys_to_reset = 2;
}

message ResetToolOptionsResponse {
  bool success = 1;
  string message = 2;

  /// The effective options after reset (as JSON string)
  string effective_options_json = 3;
}

// ============================================================================
// TOOL NAME OVERRIDE MESSAGES
// ============================================================================

message SetToolOverrideRequest {
  /// The canonical tool name to set overrides for.
  string tool_name = 1;

  /// The model-facing tool name. If empty, the canonical name is used
  /// (clears any existing tool name override for this tool).
  string tool_name_for_model = 2;

  /// Parameter name overrides (canonical param → model-facing param).
  /// Only include params that need overriding — unlisted params keep
  /// their canonical names. Empty map clears param overrides.
  map<string, string> param_name_overrides_for_model = 3;
}

message SetToolOverrideResponse {
  bool success = 1;
  string message = 2;
}

message ClearToolOverrideRequest {
  /// The canonical tool name to clear all overrides for.
  string tool_name = 1;
}

message ClearToolOverrideResponse {
  bool success = 1;
  string message = 2;
}

// ============================================================================
// SYSTEM REMINDERS MESSAGES
// ============================================================================

message SetSystemRemindersRequest {
  /// Whether system reminders should be enabled.
  bool enabled = 1;
}

message SetSystemRemindersResponse {
  bool success = 1;
  string message = 2;
  /// The effective state after the change.
  bool enabled = 3;
}

message GetSystemRemindersRequest {}

message GetSystemRemindersResponse {
  /// Whether system reminders are currently enabled.
  bool enabled = 1;
}

// ============================================================================
// TRUNCATION CONFIG MESSAGES
// ============================================================================

message SetTruncationConfigRequest {
  /// The truncation configuration to apply for the session.
  TruncationConfig config = 1;
}

message SetTruncationConfigResponse {}

message GetTruncationConfigRequest {}

message GetTruncationConfigResponse {
  /// The current effective truncation configuration.
  TruncationConfig config = 1;
}

// ============================================================================
// AGENT MESSAGES
// ============================================================================

message GetSystemPromptRequest {
  /// "full" or "compact". Defaults to "full" if empty.
  string variant = 1;
}

message GetSystemPromptResponse {
  /// The rendered system prompt.
  string system_prompt = 1;
  /// "extend" or "full" — the prompt mode used.
  string prompt_mode = 2;
}

message GetAgentInfoRequest {}

message GetAgentInfoResponse {
  string name = 1;
  string description = 2;
  repeated string tools = 3;
  repeated string disallowed_tools = 4;
  string permission_mode = 5;
  string output_format = 6;
  /// Completion requirement (if set).
  AgentCompletionRequirement completion_requirement = 7;
  /// Per-tool execution config.
  map<string, AgentToolExecConfig> tool_config = 8;
}

/// Completion requirement from the agent definition.
message AgentCompletionRequirement {
  string tool = 1;
  string reminder = 2;
}

/// Per-tool execution config from the agent definition.
message AgentToolExecConfig {
  AgentToolRetryConfig retry = 1;
}

/// Retry config for a single tool.
message AgentToolRetryConfig {
  uint32 max_retries = 1;
  uint64 base_delay_ms = 2;
  uint64 max_delay_ms = 3;
}

message GetCompletionStateRequest {}

message GetCompletionStateResponse {
  /// Whether a completion requirement exists for this agent.
  bool has_requirement = 1;
  /// The tool that must be called.
  string required_tool = 2;
  /// Whether the tool was called this turn.
  bool completed = 3;
}

message ResetCompletionStateRequest {}
message ResetCompletionStateResponse {}

message FinalizeAgentRequest {}

message FinalizeAgentResponse {
  bool success = 1;
  /// The finalized system prompt (same as GetSystemPrompt would return).
  string system_prompt = 2;
}

// ============================================================================
// TOOL STATE MESSAGES
// ============================================================================

message GetToolStateRequest {}

message GetToolStateResponse {
  /// The serialized tool state as a JSON string.
  ///
  /// Shape: `{ "params": { ... }, "state": { ... } }`.
  /// Contains all registered (serializable) Resources — file read tracker,
  /// todo state, todo nudge counters, per-tool params, etc.
  /// Ephemeral resources (cwd, terminal, notification handle) are excluded.
  string state_json = 1;
}