agent-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/docker/docker-agent/blob/main/agent-schema.json",
  "title": "Docker Agent Configuration",
  "description": "Configuration schema for Docker Agent v8",
  "type": "object",
  "properties": {
    "version": {
      "type": "string",
      "description": "Configuration version",
      "enum": [
        "0",
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8"
      ],
      "examples": [
        "0",
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8"
      ]
    },
    "providers": {
      "type": "object",
      "description": "Map of custom provider configurations. Providers define reusable defaults (base_url, token_key, api_type) that models can reference.",
      "additionalProperties": {
        "$ref": "#/definitions/ProviderConfig"
      }
    },
    "agents": {
      "type": "object",
      "description": "Map of agent configurations",
      "additionalProperties": {
        "$ref": "#/definitions/AgentConfig"
      }
    },
    "models": {
      "type": "object",
      "description": "Map of model configurations",
      "additionalProperties": {
        "$ref": "#/definitions/ModelConfig"
      }
    },
    "mcps": {
      "type": "object",
      "description": "Map of reusable MCP server definitions. Define MCP servers here and reference them by name from agent toolsets to avoid duplication.",
      "additionalProperties": {
        "$ref": "#/definitions/MCPToolset"
      }
    },
    "rag": {
      "type": "object",
      "description": "Map of reusable RAG source definitions. Define RAG sources here and reference them by name from agent toolsets to avoid duplication.",
      "additionalProperties": {
        "$ref": "#/definitions/RAGToolset"
      }
    },
    "metadata": {
      "$ref": "#/definitions/Metadata",
      "description": "Configuration metadata"
    },
    "permissions": {
      "$ref": "#/definitions/PermissionsConfig",
      "description": "Tool permission configuration for controlling tool approval behavior"
    }
  },
  "additionalProperties": false,
  "definitions": {
    "ProviderConfig": {
      "type": "object",
      "description": "Configuration for a model provider. Defines reusable defaults that models can inherit by referencing the provider name. Supports any provider type (openai, anthropic, google, amazon-bedrock, etc.).",
      "properties": {
        "provider": {
          "type": "string",
          "description": "The underlying provider type. Defaults to \"openai\" when not set. Supported values: openai, anthropic, google, amazon-bedrock, dmr, and any built-in alias (requesty, azure, xai, ollama, mistral, etc.).",
          "examples": [
            "openai",
            "anthropic",
            "google",
            "amazon-bedrock"
          ]
        },
        "api_type": {
          "type": "string",
          "description": "The API schema type to use. Only applicable for OpenAI-compatible providers.",
          "enum": [
            "openai_chatcompletions",
            "openai_responses"
          ],
          "default": "openai_chatcompletions",
          "examples": [
            "openai_chatcompletions",
            "openai_responses"
          ]
        },
        "base_url": {
          "type": "string",
          "description": "Base URL for the provider's API endpoint. Required for OpenAI-compatible providers, optional for native providers.",
          "format": "uri",
          "examples": [
            "https://router.example.com/v1"
          ]
        },
        "token_key": {
          "type": "string",
          "description": "Environment variable name containing the API token. If not set, requests will use the default token for the provider type.",
          "examples": [
            "CUSTOM_PROVIDER_API_KEY",
            "ANTHROPIC_API_KEY"
          ]
        },
        "temperature": {
          "type": "number",
          "description": "Default sampling temperature for models using this provider.",
          "minimum": 0,
          "maximum": 2
        },
        "max_tokens": {
          "type": "integer",
          "description": "Default maximum number of tokens for models using this provider."
        },
        "top_p": {
          "type": "number",
          "description": "Default top-p (nucleus) sampling parameter.",
          "minimum": 0,
          "maximum": 1
        },
        "frequency_penalty": {
          "type": "number",
          "description": "Default frequency penalty.",
          "minimum": -2,
          "maximum": 2
        },
        "presence_penalty": {
          "type": "number",
          "description": "Default presence penalty.",
          "minimum": -2,
          "maximum": 2
        },
        "parallel_tool_calls": {
          "type": "boolean",
          "description": "Whether to enable parallel tool calls by default."
        },
        "provider_opts": {
          "type": "object",
          "description": "Provider-specific options passed through to the underlying client.",
          "additionalProperties": true
        },
        "track_usage": {
          "type": "boolean",
          "description": "Whether to track token usage by default."
        },
        "thinking_budget": {
          "description": "Default reasoning effort/budget for models using this provider. Can be an integer token count or a string effort level.",
          "oneOf": [
            {
              "type": "integer",
              "description": "Token budget for reasoning"
            },
            {
              "type": "string",
              "description": "Effort level (e.g., \"low\", \"medium\", \"high\", \"none\", \"adaptive\")"
            }
          ]
        },
        "task_budget": {
          "description": "Default total-token budget for an agentic task (forwarded to Anthropic as `output_config.task_budget`, with the required `task-budgets-2026-03-13` beta header attached automatically). Configurable on any Claude model — docker-agent does not gate by model name — but at the time of writing only Claude Opus 4.7 honors it. Accepts an integer token count or an object {type: tokens, total: N}.",
          "oneOf": [
            {
              "type": "integer",
              "minimum": 0,
              "description": "Token budget for the full task (combined thinking, tool calls, and output)."
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": ["tokens"],
                  "description": "Budget kind. Only \"tokens\" is supported today."
                },
                "total": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Total budget value."
                }
              },
              "required": ["total"],
              "additionalProperties": false
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "AgentConfig": {
      "type": "object",
      "description": "Configuration for a single agent",
      "properties": {
        "model": {
          "type": "string",
          "description": "Model to use for this agent (can be just model name or provider/model format)",
          "examples": [
            "gpt-4",
            "openai/gpt-4o",
            "anthropic/claude-sonnet-4-0",
            "anthropic/claude-sonnet-4-5",
            "claude"
          ]
        },
        "fallback": {
          "$ref": "#/definitions/FallbackConfig",
          "description": "Fallback model configuration for automatic failover and retry behavior"
        },
        "description": {
          "type": "string",
          "description": "Description of the agent"
        },
        "welcome_message": {
          "type": "string",
          "description": "Optional welcome message to display when the agent starts"
        },
        "toolsets": {
          "type": "array",
          "description": "List of toolsets available to the agent",
          "items": {
            "$ref": "#/definitions/Toolset"
          }
        },
        "instruction": {
          "type": "string",
          "description": "Instructions for the agent"
        },
        "code_mode_tools": {
          "type": "boolean",
          "description": "Enable Code Mode for tools"
        },
        "sub_agents": {
          "type": "array",
          "description": "List of sub-agents. Can be names of agents defined in this config, external references (OCI images like 'namespace/repo' or URLs), or named external references using 'name:reference' syntax (e.g. 'reviewer:agentcatalog/review-pr'). External agents without an explicit name are named after their last path segment.",
          "items": {
            "type": "string"
          }
        },
        "handoffs": {
          "type": "array",
          "description": "List of agents this agent can hand off the conversation to. Can be names of agents defined in this config, external references (OCI images like 'namespace/repo' or URLs), or named external references using 'name:reference' syntax (e.g. 'reviewer:agentcatalog/review-pr'). External agents without an explicit name are named after their last path segment.",
          "items": {
            "type": "string"
          }
        },
        "add_date": {
          "type": "boolean",
          "description": "Whether to add date information"
        },
        "add_environment_info": {
          "type": "boolean",
          "description": "Whether to add environment information"
        },
        "max_iterations": {
          "type": "integer",
          "description": "Maximum number of iterations",
          "minimum": 0
        },
        "max_consecutive_tool_calls": {
          "type": "integer",
          "description": "Maximum consecutive identical tool calls before the agent is terminated. Prevents degenerate loops. 0 uses the default of 5.",
          "minimum": 0
        },
        "max_old_tool_call_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to keep from old tool call arguments and results. Older tool calls beyond this budget will have their content replaced with a placeholder. Tokens are approximated as len/4. Set to -1 to disable truncation (unlimited tool content). Default: 40000.",
          "minimum": -1
        },
        "num_history_items": {
          "type": "integer",
          "description": "Number of history items to keep",
          "minimum": 0
        },
        "add_prompt_files": {
          "type": "array",
          "description": "List of prompt files to add",
          "items": {
            "type": "string"
          }
        },
        "commands": {
          "description": "Named prompts for /commands. Supports simple string format or advanced object format with description and instruction.",
          "oneOf": [
            {
              "type": "object",
              "additionalProperties": {
                "oneOf": [
                  {
                    "type": "string",
                    "description": "Simple command format: the string becomes the instruction"
                  },
                  {
                    "$ref": "#/definitions/CommandConfig"
                  }
                ]
              }
            },
            {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "oneOf": [
                    {
                      "type": "string",
                      "description": "Simple command format: the string becomes the instruction"
                    },
                    {
                      "$ref": "#/definitions/CommandConfig"
                    }
                  ]
                }
              }
            }
          ]
        },
        "structured_output": {
          "type": "object",
          "description": "Structured output configuration for constraining model responses to a specific JSON schema. Supported by OpenAI (native) and Google Gemini (native). Anthropic requires prompt engineering or tool-based approaches.",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the response format schema"
            },
            "description": {
              "type": "string",
              "description": "Optional description of what the schema represents"
            },
            "strict": {
              "type": "boolean",
              "description": "Enable strict schema adherence (OpenAI only). When true, all properties must be in required array.",
              "default": false
            },
            "schema": {
              "type": "object",
              "description": "JSON Schema object defining the structure of the response. Must include type, properties, and required fields.",
              "required": [
                "type",
                "properties"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "object"
                  ],
                  "description": "Schema type, must be 'object' for structured outputs"
                },
                "properties": {
                  "type": "object",
                  "description": "Object properties with their schemas",
                  "additionalProperties": true
                },
                "required": {
                  "type": "array",
                  "description": "List of required property names",
                  "items": {
                    "type": "string"
                  }
                },
                "additionalProperties": {
                  "type": "boolean",
                  "description": "Whether additional properties are allowed",
                  "default": false
                }
              },
              "additionalProperties": true
            }
          },
          "required": [
            "name",
            "schema"
          ],
          "additionalProperties": false
        },
        "add_description_parameter": {
          "type": "boolean",
          "description": "Whether to add a 'description' parameter to tool calls, allowing the LLM to provide context about why it is calling a tool"
        },
        "hooks": {
          "$ref": "#/definitions/HooksConfig",
          "description": "Lifecycle hooks for executing shell commands at various points in the agent's execution"
        },
        "cache": {
          "$ref": "#/definitions/CacheConfig",
          "description": "Optional response cache: when the same user question is asked again, replay the previous answer instead of calling the model."
        },
        "skills": {
          "description": "Enable skills discovery for this agent. Set to true to load all discovered skills from local filesystem sources; false disables skills. A list can mix sources (\"local\" or an HTTP/HTTPS URL) and/or skill names to include. If only names are given, local sources are loaded and filtered to just those skills.",
          "oneOf": [
            {
              "type": "boolean",
              "description": "When true, loads all discovered local skills. When false, skills are disabled."
            },
            {
              "type": "array",
              "description": "List combining skill sources and/or skill names to include. Items equal to \"local\" or starting with http:// or https:// are treated as sources; any other string is treated as a skill name filter.",
              "items": {
                "type": "string"
              },
              "examples": [
                ["local"],
                ["local", "https://skills.example.com"],
                ["git", "docker"],
                ["local", "docker-build"]
              ]
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "CommandConfig": {
      "type": "object",
      "description": "Advanced command configuration with description and instruction",
      "properties": {
        "description": {
          "type": "string",
          "description": "Description shown in completion dialogs and help text"
        },
        "instruction": {
          "type": "string",
          "description": "The prompt sent to the agent. Supports bang commands (!`command`) and positional arguments ($1, $2, etc.)"
        }
      },
      "additionalProperties": false
    },
    "FallbackConfig": {
      "type": "object",
      "description": "Configuration for fallback model behavior when the primary model fails",
      "properties": {
        "models": {
          "type": "array",
          "description": "List of fallback models to try in order if the primary model fails. Each entry can be a model name from the models section or an inline provider/model format (e.g., 'openai/gpt-4o').",
          "items": {
            "type": "string"
          },
          "examples": [
            [
              "anthropic/claude-sonnet-4-0",
              "openai/gpt-4o"
            ],
            [
              "backup_model",
              "openai/gpt-5-mini"
            ]
          ]
        },
        "retries": {
          "type": "integer",
          "description": "Number of retries per model with exponential backoff for retryable errors (5xx, timeouts). Use 0 or omit for default (2 retries = 3 total attempts per model). Use -1 to disable retries entirely (try each model only once).",
          "minimum": -1,
          "default": 2
        },
        "cooldown": {
          "type": "string",
          "description": "Duration to stick with a successful fallback model before retrying the primary. Only applies after a non-retryable error (e.g., 429 rate limit). Use Go duration format (e.g., '1m', '30s', '2m30s'). Default is '1m'.",
          "pattern": "^([0-9]+(ns|us|\u00b5s|ms|s|m|h))+$",
          "default": "1m",
          "examples": [
            "1m",
            "30s",
            "2m30s",
            "5m"
          ]
        }
      },
      "additionalProperties": false
    },
    "CacheConfig": {
      "type": "object",
      "description": "Configuration for the agent's response cache. When enabled, the assistant response produced for a given user question is stored and replayed verbatim the next time the same question is asked, skipping the model entirely. Two normalization options control what 'same question' means: case_sensitive (default false) toggles case-insensitive matching, and trim_spaces (default false) strips leading/trailing whitespace before comparison. Set 'path' to persist entries to a JSON file (relative paths resolve against the agent config directory); leave it empty to keep entries in memory only.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Set to true to enable the cache. When false (or when the cache section is omitted), no caching is performed.",
          "default": false
        },
        "case_sensitive": {
          "type": "boolean",
          "description": "When true, questions must match exactly (including case) to hit the cache. Default: false (case-insensitive matching).",
          "default": false
        },
        "trim_spaces": {
          "type": "boolean",
          "description": "When true, leading and trailing whitespace is stripped from questions before they are compared. Default: false.",
          "default": false
        },
        "path": {
          "type": "string",
          "description": "Path to a JSON file used to persist cache entries across runs. Relative paths are resolved against the agent's config directory. When empty, the cache lives only in memory."
        }
      },
      "additionalProperties": false
    },
    "HooksConfig": {
      "type": "object",
      "description": "Lifecycle hooks configuration for an agent. Hooks allow running shell commands at various points in the agent's execution lifecycle.",
      "properties": {
        "pre_tool_use": {
          "type": "array",
          "description": "Hooks that run before a tool is executed. Can allow/deny/modify tool calls.",
          "items": {
            "$ref": "#/definitions/HookMatcherConfig"
          }
        },
        "post_tool_use": {
          "type": "array",
          "description": "Hooks that run after a tool completes (both success and failure). The result is delivered in tool_response (failed calls carry an is_error flag and any error text). Returning decision=block or exit code 2 stops the run loop after the current tool batch — useful for circuit-breaker patterns.",
          "items": {
            "$ref": "#/definitions/HookMatcherConfig"
          }
        },
        "permission_request": {
          "type": "array",
          "description": "Hooks that run just before the runtime prompts the user to approve a tool call (i.e. when --yolo and permission rules did not short-circuit the decision). Hooks may auto-allow or auto-deny via hook_specific_output.permission_decision; otherwise control falls through to the interactive confirmation. Tool-matched, like pre_tool_use.",
          "items": {
            "$ref": "#/definitions/HookMatcherConfig"
          }
        },
        "session_start": {
          "type": "array",
          "description": "Hooks that run when a session begins. Can load context or setup environment.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "user_prompt_submit": {
          "type": "array",
          "description": "Hooks that run once per user message, after the user has submitted their prompt and before the first model call of the turn. The submitted text is passed in the prompt field. Hooks can block submission (decision=block / continue=false / exit code 2) or contribute additional_context that is spliced into the conversation as a transient system message for that turn only. Sub-sessions (transferred tasks, background agents) do NOT fire this event because their kick-off message is synthesised by the runtime.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "turn_start": {
          "type": "array",
          "description": "Hooks that run at the start of every agent turn (each model call). Their AdditionalContext is appended as transient system messages for that turn only — it is NOT persisted to the session, so per-turn signals (date, prompt files) are recomputed every turn instead of bloating message history on every resume.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "before_llm_call": {
          "type": "array",
          "description": "Hooks that run just before each model call (after turn_start has assembled the messages). Use for observability, cost guardrails, or auditing without contributing system messages — turn_start is the right event for the latter.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "after_llm_call": {
          "type": "array",
          "description": "Hooks that run just after each successful model call, before the response is recorded into the session and tool calls are dispatched. Receives the assistant text content in stop_response. Failed calls fire on_error instead.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "session_end": {
          "type": "array",
          "description": "Hooks that run when a session ends. Can perform cleanup or logging.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "pre_compact": {
          "type": "array",
          "description": "Hooks that run just before the runtime compacts the session transcript into a summary. The trigger is reported in source: 'manual' (user-initiated /compact), 'auto' (proactive threshold), 'overflow' (context-overflow recovery), or 'tool_overflow' (proactive after tool results pushed past the threshold). Hooks may block compaction (decision=block / continue=false / exit code 2) or contribute additional_context that is appended to the compaction prompt — useful for steering the summary without modifying the agent's instruction.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "subagent_stop": {
          "type": "array",
          "description": "Hooks that run when a sub-agent (transferred task, background agent, skill sub-session) finishes. Fires against the parent agent's executor so handlers configured on the orchestrator see every child completion. The sub-agent's name is in agent_name and its final assistant message in stop_response.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "on_user_input": {
          "type": "array",
          "description": "Hooks that run when the agent needs user input. Can send notifications or log events.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "stop": {
          "type": "array",
          "description": "Hooks that run when the model finishes responding and is about to hand control back to the user. Can perform post-response validation or logging.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "notification": {
          "type": "array",
          "description": "Hooks that run when the agent sends a notification (error, warning) to the user. Can send external notifications or log events.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "on_error": {
          "type": "array",
          "description": "Hooks that run when the runtime hits an error during a turn (model failures, repetitive tool-call loops). Fires alongside notification (level=error); use this for structured error-only handlers without parsing notification_level.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "on_max_iterations": {
          "type": "array",
          "description": "Hooks that run when the runtime reaches its configured max_iterations limit. Fires alongside notification (level=warning); use this for structured handlers (e.g. log to a metrics pipeline) without parsing notification_message.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "on_agent_switch": {
          "type": "array",
          "description": "Hooks that run whenever the runtime moves the active agent to a new one (transfer_task, handoff, or the return after a transferred task completes). Receives from_agent, to_agent, and agent_switch_kind in the input. Observational; useful for audit, transcript, and metrics pipelines that track which agent ran which tools.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "on_session_resume": {
          "type": "array",
          "description": "Hooks that run when the user explicitly approves the runtime to continue past its configured max_iterations limit. Receives previous_max_iterations and new_max_iterations in the input. Observational; useful for alerting on extended-runtime sessions or for billing/quota pipelines that meter resumes.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "on_tool_approval_decision": {
          "type": "array",
          "description": "Hooks that run after the runtime's tool approval chain (yolo / permissions / readonly / ask) resolves a verdict for a tool call, before the call is executed (allow) or its error response is recorded (deny / canceled). Receives approval_decision (\"allow\" | \"deny\" | \"canceled\") and approval_source (a stable classifier of which step decided). Observational; gives audit pipelines a single \"who approved what\" record without re-implementing the chain.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "before_compaction": {
          "type": "array",
          "description": "Hooks that run immediately before a session compaction. The Input carries input_tokens, output_tokens, context_limit, and compaction_reason ('threshold', 'overflow', 'manual'). A hook may veto compaction by setting decision='block' (or exiting with code 2), or supply a custom summary via hookSpecificOutput.summary, in which case the runtime applies that summary verbatim and skips the LLM-based summarization. Be cautious about denying when compaction_reason='overflow': the runtime is recovering from a context-overflow error and a denial there will leave the session unable to make progress.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        },
        "after_compaction": {
          "type": "array",
          "description": "Hooks that run after a successful compaction (a summary was applied to the session). Receives the final summary text in Input.summary alongside input_tokens, output_tokens, context_limit and compaction_reason. Purely observational — hook output is ignored.",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        }
      },
      "additionalProperties": false
    },
    "HookMatcherConfig": {
      "type": "object",
      "description": "Configuration for matching tools and their associated hooks",
      "properties": {
        "matcher": {
          "type": "string",
          "description": "Regex pattern to match tool names (e.g., 'shell|edit_file'). Use '*' to match all tools. Case-sensitive.",
          "examples": [
            "*",
            "shell",
            "shell|edit_file|write_file",
            "mcp__.*"
          ]
        },
        "hooks": {
          "type": "array",
          "description": "Hooks to execute when the matcher matches",
          "items": {
            "$ref": "#/definitions/HookDefinition"
          }
        }
      },
      "required": [
        "hooks"
      ],
      "additionalProperties": false
    },
    "HookDefinition": {
      "type": "object",
      "description": "Definition of a single hook command",
      "properties": {
        "name": {
          "type": "string",
          "description": "Optional friendly hook name used in logs and runtime hook events."
        },
        "type": {
          "type": "string",
          "description": "Type of hook. 'command' executes a shell command; 'builtin' invokes a named in-process Go function registered by the runtime; 'model' asks an LLM and translates its reply into the hook's native output (used for LLM-as-a-judge pre_tool_use, summarizers, etc., with no Go code). The docker-agent runtime ships these builtins: 'add_date' (turn_start: today's date), 'add_environment_info' (session_start: cwd, git, OS, arch), 'add_prompt_files' (turn_start: contents of named files looked up in the workdir hierarchy and the home directory), 'add_git_status' (turn_start: `git status --short --branch`), 'add_git_diff' (turn_start: `git diff --stat`, or full diff with args=['full']), 'add_directory_listing' (session_start: top-level entries of cwd), 'add_user_info' (session_start: current OS user and hostname), 'add_recent_commits' (session_start: `git log --oneline -n N`, default N=10, override via args=['<N>']), 'max_iterations' (before_llm_call: hard stop after N model calls; args=['<N>'] required).",
          "enum": [
            "command",
            "builtin",
            "model"
          ]
        },
        "command": {
          "type": "string",
          "description": "Shell command (type=command) or builtin name (type=builtin) to invoke. Command hooks receive JSON input via stdin with tool/session information. Ignored when type=model."
        },
        "args": {
          "type": "array",
          "description": "Arbitrary string arguments passed to the hook handler. Builtin handlers receive them as a typed parameter; e.g. 'add_prompt_files' takes the list of prompt files to load, 'add_recent_commits' optionally takes a positive integer commit limit, 'add_git_diff' accepts 'full' to emit the full unified diff, and 'max_iterations' takes a positive integer call limit.",
          "items": {
            "type": "string"
          }
        },
        "timeout": {
          "type": "integer",
          "description": "Execution timeout in seconds (default: 60)",
          "minimum": 1,
          "default": 60
        },
        "env": {
          "type": "object",
          "description": "Environment variables to add or override for this hook only.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "working_dir": {
          "type": "string",
          "description": "Working directory for this hook. Relative paths are resolved from the agent working directory."
        },
        "on_error": {
          "type": "string",
          "description": "How non-fail-closed hook failures are handled. 'warn' logs and continues (default), 'ignore' continues silently, and 'block' denies the event.",
          "enum": [
            "warn",
            "ignore",
            "block"
          ],
          "default": "warn"
        },
        "model": {
          "type": "string",
          "description": "Model spec ('provider/model', e.g. 'openai/gpt-4o-mini') invoked by type=model hooks. Required for that type, ignored otherwise."
        },
        "prompt": {
          "type": "string",
          "description": "User-message template rendered for each invocation of a type=model hook. Parsed as a Go text/template with the hook Input as the data context: {{ .ToolName }}, {{ .ToolInput }}, {{ .StopResponse }}, etc. Required for type=model."
        },
        "schema": {
          "type": "string",
          "description": "Well-known response interpretation for type=model hooks. Empty: return the model's reply as additional_context. 'pre_tool_use_decision': ask the model for {decision, reason} JSON and produce a permission_decision verdict (allow|ask|deny)."
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false,
      "allOf": [
        {
          "if": {"properties": {"type": {"const": "command"}}, "required": ["type"]},
          "then": {"required": ["command"]}
        },
        {
          "if": {"properties": {"type": {"const": "builtin"}}, "required": ["type"]},
          "then": {"required": ["command"]}
        },
        {
          "if": {"properties": {"type": {"const": "model"}}, "required": ["type"]},
          "then": {"required": ["model", "prompt"]}
        }
      ]
    },
    "ModelConfig": {
      "type": "object",
      "description": "Configuration for a model",
      "properties": {
        "provider": {
          "type": "string",
          "description": "Model provider (e.g., openai, anthropic, dmr)",
          "examples": [
            "openai",
            "anthropic",
            "dmr",
            "ollama",
            "github-copilot"
          ]
        },
        "model": {
          "type": "string",
          "description": "Model name"
        },
        "temperature": {
          "type": "number",
          "description": "Sampling temperature",
          "minimum": 0,
          "maximum": 2
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens",
          "minimum": 1
        },
        "top_p": {
          "type": "number",
          "description": "Top-p sampling parameter",
          "minimum": 0,
          "maximum": 1
        },
        "frequency_penalty": {
          "type": "number",
          "description": "Frequency penalty",
          "minimum": -2,
          "maximum": 2
        },
        "presence_penalty": {
          "type": "number",
          "description": "Presence penalty",
          "minimum": -2,
          "maximum": 2
        },
        "base_url": {
          "type": "string",
          "description": "Base URL for the model API",
          "format": "uri"
        },
        "parallel_tool_calls": {
          "type": "boolean",
          "description": "Whether to enable parallel tool calls"
        },
        "token_key": {
          "type": "string",
          "description": "Token key for authentication"
        },
        "provider_opts": {
          "type": "object",
          "description": "Provider-specific options. Sampling parameters: top_k (integer, supported by anthropic, google, amazon-bedrock, and custom OpenAI-compatible providers like vLLM/Ollama), repetition_penalty (float, forwarded to custom OpenAI-compatible providers), min_p (float, forwarded to custom providers), seed (integer, forwarded to OpenAI). Infrastructure options: http_headers (map of string to string, adds custom HTTP headers to every request; used for OpenAI-compatible providers like github-copilot which requires Copilot-Integration-Id). dmr: runtime_flags. anthropic/amazon-bedrock (Claude): interleaved_thinking (boolean, default true), thinking_display ('summarized', 'omitted', or 'display') controls whether thinking blocks are returned in responses when thinking is enabled. Claude Opus 4.7 hides thinking by default ('omitted'); set thinking_display: summarized (or thinking_display: display) to receive thinking blocks. openai: transport ('sse' or 'websocket') to choose between SSE and WebSocket streaming for the Responses API. openai/anthropic/google: rerank_prompt (string) to fully override the system prompt used for RAG reranking (advanced - prefer using results.reranking.criteria for domain-specific guidance). Google: google_search (boolean) enables Google Search grounding, google_maps (boolean) enables Google Maps grounding, code_execution (boolean) enables server-side code execution.",
          "additionalProperties": true
        },
        "track_usage": {
          "type": "boolean",
          "description": "Whether to track usage"
        },
        "thinking_budget": {
          "description": "Controls reasoning effort/budget. Use 'none' or 0 to disable thinking. OpenAI: string levels ('minimal','low','medium','high','xhigh'). Anthropic: integer token budget (1024-32768), 'adaptive' (adaptive thinking with high effort by default), 'adaptive/<effort>' where effort is low/medium/high/xhigh/max ('xhigh' is supported by Claude Opus 4.7+), or effort levels ('low','medium','high','xhigh','max') which use adaptive thinking with the given effort. Amazon Bedrock (Claude): integer token budget or effort levels ('low','medium','high') mapped to token budgets. Google Gemini 2.5: integer token budget (-1 for dynamic, 0 to disable, 24576 max). Google Gemini 3: string levels ('minimal' Flash only,'low','medium','high'). Thinking is only enabled when explicitly configured.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "^(none|minimal|low|medium|high|xhigh|max|adaptive(/low|/medium|/high|/xhigh|/max)?)$",
              "description": "Reasoning effort level. 'adaptive' uses adaptive thinking with high effort (default). 'adaptive/<effort>' specifies the effort level (low/medium/high/xhigh/max). 'adaptive/xhigh' requires Claude Opus 4.7+. Use 'none' to disable thinking."
            },
            {
              "type": "integer",
              "minimum": -1,
              "maximum": 32768,
              "description": "Token budget for extended thinking (Anthropic, Bedrock Claude, Gemini 2.5). Use 0 to disable thinking."
            }
          ],
          "examples": [
            "none",
            0,
            "minimal",
            "low",
            "medium",
            "high",
            "xhigh",
            "max",
            "adaptive",
            "adaptive/low",
            "adaptive/medium",
            "adaptive/high",
            "adaptive/xhigh",
            "adaptive/max",
            -1,
            1024,
            8192,
            32768
          ]
        },
        "task_budget": {
          "description": "Total-token budget for a full agentic task (forwarded to Anthropic as `output_config.task_budget`, with the required `task-budgets-2026-03-13` beta header attached automatically). Limits the combined tokens spent on thinking, tool calls, and output across the whole task. Configurable on any Claude model — docker-agent does not gate by model name — but at the time of writing only Claude Opus 4.7 honors it. Accepts an integer token count or an object {type: tokens, total: N}.",
          "oneOf": [
            {
              "type": "integer",
              "minimum": 0,
              "description": "Total token budget for the task (e.g., 128000)."
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": ["tokens"],
                  "description": "Budget kind. Only \"tokens\" is supported today."
                },
                "total": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Total budget value."
                }
              },
              "required": ["total"],
              "additionalProperties": false
            }
          ],
          "examples": [
            64000,
            128000,
            { "type": "tokens", "total": 128000 }
          ]
        },
        "routing": {
          "type": "array",
          "description": "Routing rules for request-based model selection. When configured, this model becomes a router that selects the best model based on the user's input. The model's provider/model fields define the fallback model.",
          "items": {
            "$ref": "#/definitions/RoutingRule"
          }
        }
      },
      "additionalProperties": false
    },
    "RoutingRule": {
      "type": "object",
      "description": "A single routing rule that maps example phrases to a target model",
      "properties": {
        "model": {
          "type": "string",
          "description": "Model reference (another model name in the models section or inline spec like 'openai/gpt-4o')"
        },
        "examples": {
          "type": "array",
          "description": "Example phrases that should trigger routing to this model",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "model",
        "examples"
      ],
      "additionalProperties": false
    },
    "Metadata": {
      "type": "object",
      "description": "Configuration metadata",
      "properties": {
        "author": {
          "type": "string",
          "description": "Author of the configuration"
        },
        "license": {
          "type": "string",
          "description": "License for the configuration"
        },
        "readme": {
          "type": "string",
          "description": "README or description"
        },
        "description": {
          "type": "string",
          "description": "Description of the agent configuration"
        },
        "version": {
          "type": "string",
          "description": "Version of the agent configuration (used for OCI registry publishing)"
        }
      },
      "additionalProperties": false
    },
    "PermissionsConfig": {
      "type": "object",
      "description": "Tool permission configuration. Controls tool call approval behavior with optional argument matching.",
      "properties": {
        "allow": {
          "type": "array",
          "description": "Tool patterns that are auto-approved without user confirmation. Supports tool names with glob patterns (e.g., 'read_*') and argument matching (e.g., 'shell:cmd=ls*' to allow shell commands starting with 'ls'). MCP tools can use qualified names (e.g., 'mcp:github:*').",
          "items": {
            "type": "string"
          },
          "examples": [
            [
              "shell:cmd=ls*",
              "shell:cmd=git status*",
              "shell:cmd=go test*"
            ],
            [
              "mcp:github:get_*",
              "mcp:github:list_*"
            ],
            [
              "think",
              "create_todo*",
              "list_todos"
            ]
          ]
        },
        "ask": {
          "type": "array",
          "description": "Tool patterns that always require user confirmation, even for tools that are normally auto-approved (e.g. read-only tools). Supports the same pattern syntax as allow: tool names with globs and argument matching (e.g., 'fetch' to always ask before fetching URLs).",
          "items": {
            "type": "string"
          },
          "examples": [
            [
              "fetch"
            ],
            [
              "mcp:github:get_*"
            ]
          ]
        },
        "deny": {
          "type": "array",
          "description": "Tool patterns that are always rejected. Takes priority over allow patterns. Supports the same pattern syntax as allow: tool names with globs and argument matching (e.g., 'shell:cmd=rm -rf*' to block dangerous rm commands).",
          "items": {
            "type": "string"
          },
          "examples": [
            [
              "shell:cmd=rm -rf*",
              "shell:cmd=sudo*"
            ],
            [
              "shell:cmd=git push --force*",
              "shell:cmd=git reset --hard*"
            ],
            [
              "mcp:github:delete_*"
            ]
          ]
        }
      },
      "additionalProperties": false
    },
    "MCPToolset": {
      "type": "object",
      "description": "Reusable MCP server definition. Define once at the top level and reference by name from agent toolsets.",
      "properties": {
        "command": {
          "type": "string",
          "description": "Command to run the MCP server (stdio transport)"
        },
        "args": {
          "type": "array",
          "description": "Arguments to pass to the command",
          "items": {
            "type": "string"
          }
        },
        "ref": {
          "type": "string",
          "description": "Docker MCP reference (e.g., 'docker:context7')",
          "pattern": "^docker:"
        },
        "remote": {
          "$ref": "#/definitions/Remote",
          "description": "Remote MCP server configuration (SSE/streamable-http transport)"
        },
        "config": {
          "description": "MCP server configuration (for docker refs)"
        },
        "version": {
          "type": "string",
          "description": "Version/package reference for auto-installation"
        },
        "env": {
          "type": "object",
          "description": "Environment variables for the MCP server",
          "additionalProperties": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "description": "Optional list of tools to expose from the MCP server",
          "items": {
            "type": "string"
          }
        },
        "instruction": {
          "type": "string",
          "description": "Custom instruction for this MCP server's tools. By default, setting this field replaces the toolset's built-in instructions entirely. To enrich (rather than replace) the original instructions, include the placeholder {ORIGINAL_INSTRUCTIONS} in your text \u2014 it will be substituted with the toolset's built-in instructions at runtime. For example: '{ORIGINAL_INSTRUCTIONS}\nAlways prefer JSON output.' will prepend the original instructions and append your extra guidance."
        },
        "name": {
          "type": "string",
          "description": "Optional display name override for the MCP server"
        },
        "defer": {
          "description": "Deferred loading configuration for tools from this MCP server",
          "oneOf": [
            {
              "type": "boolean",
              "description": "Set to true to defer all tools"
            },
            {
              "type": "array",
              "description": "Array of tool names to defer",
              "items": {
                "type": "string"
              }
            }
          ]
        },
        "working_dir": {
          "type": "string",
          "description": "Optional working directory for the MCP server process. Relative paths are resolved relative to the agent's working directory. Only valid for subprocess-based MCP types (command or ref); not supported for remote MCP toolsets."
        }
      },
      "anyOf": [
        {
          "required": [
            "command"
          ]
        },
        {
          "required": [
            "remote"
          ]
        },
        {
          "required": [
            "ref"
          ]
        }
      ],
      "additionalProperties": false
    },
    "RAGToolset": {
      "type": "object",
      "description": "Reusable RAG source definition. Define once at the top level and reference by name from agent toolsets. RAG config fields (tool, docs, strategies, results, respect_vcs) are specified directly alongside toolset fields.",
      "allOf": [
        {
          "$ref": "#/definitions/RAGConfig"
        },
        {
          "type": "object",
          "properties": {
            "instruction": {
              "type": "string",
              "description": "Custom instruction for this RAG source"
            },
            "tools": {
              "type": "array",
              "description": "Optional list of tools to expose",
              "items": {
                "type": "string"
              }
            },
            "name": {
              "type": "string",
              "description": "Optional display name override for the RAG tool"
            },
            "defer": {
              "description": "Deferred loading configuration",
              "oneOf": [
                {
                  "type": "boolean",
                  "description": "Set to true to defer all tools"
                },
                {
                  "type": "array",
                  "description": "Array of tool names to defer",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            }
          }
        }
      ]
    },
    "Toolset": {
      "type": "object",
      "description": "Tool configuration",
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of tool",
          "enum": [
            "mcp",
            "script",
            "think",
            "memory",
            "filesystem",
            "shell",
            "tasks",
            "todo",
            "fetch",
            "api",
            "a2a",
            "lsp",
            "user_prompt",
            "openapi",
            "model_picker",
            "background_agents",
            "rag"
          ]
        },
        "instruction": {
          "type": "string",
          "description": "Custom instruction for this toolset. By default, setting this field replaces the toolset's built-in instructions entirely. To enrich (rather than replace) the original instructions, include the placeholder {ORIGINAL_INSTRUCTIONS} in your text \u2014 it will be substituted with the toolset's built-in instructions at runtime. For example: '{ORIGINAL_INSTRUCTIONS}\nAlways prefer JSON output.' will prepend the original instructions and append your extra guidance."
        },
        "toon": {
          "type": "string",
          "description": "A comma-delimited list of regular expressions of tools to toonify"
        },
        "model": {
          "type": "string",
          "description": "Model to use for the LLM turn that processes tool results from this toolset. Enables per-tool model routing: cheaper/faster models handle simple tool results (e.g. knowledge-base lookups, file reads) while the agent's primary model handles complex reasoning. Value can be a model name from the models section or an inline provider/model format (e.g. 'openai/gpt-4o-mini')."
        },
        "ref": {
          "type": "string",
          "description": "Reference to a Docker MCP tool (e.g., 'docker:context7') or a named MCP definition from the top-level 'mcps' section"
        },
        "config": {
          "description": "Tool-specific configuration"
        },
        "command": {
          "type": "string",
          "description": "Command to execute for MCP tools"
        },
        "remote": {
          "$ref": "#/definitions/Remote",
          "description": "Remote tool configuration"
        },
        "args": {
          "type": "array",
          "description": "Arguments for the tool",
          "items": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "description": "List of tools to include",
          "items": {
            "type": "string"
          }
        },
        "env": {
          "type": "object",
          "description": "Environment variables",
          "additionalProperties": {
            "type": "string"
          }
        },
        "shared": {
          "type": "boolean",
          "description": "Whether the tool is shared (for think tool)"
        },
        "path": {
          "type": "string",
          "description": "Path for memory tool"
        },
        "shell": {
          "type": "object",
          "description": "Shell script configurations (for script tool)",
          "patternProperties": {
            "^[A-Za-z_][A-Za-z0-9_\\-]*$": {
              "$ref": "#/definitions/ScriptShellToolConfig"
            }
          },
          "additionalProperties": false
        },
        "post_edit": {
          "type": "array",
          "description": "Post-edit commands for filesystem tool",
          "items": {
            "$ref": "#/definitions/PostEditConfig"
          }
        },
        "api_config": {
          "$ref": "#/definitions/ApiConfig",
          "description": "API tool configuration"
        },
        "rag_config": {
          "$ref": "#/definitions/RAGConfig",
          "description": "RAG configuration for type: rag toolsets"
        },
        "ignore_vcs": {
          "type": "boolean",
          "description": "Whether to ignore VCS files (.git directories and .gitignore patterns) in filesystem operations. Default: true",
          "default": true
        },
        "defer": {
          "description": "Enable deferred loading for tools in this toolset. Set to true to defer all tools, or an array of tool names to defer only those tools. Deferred tools are not loaded into the agent's context immediately, but can be discovered and loaded on-demand using search_tool and add_tool.",
          "oneOf": [
            {
              "type": "boolean",
              "description": "Set to true to defer all tools"
            },
            {
              "type": "array",
              "description": "Array of tool names to defer",
              "items": {
                "type": "string"
              }
            }
          ],
          "examples": [
            true,
            [
              "read_file",
              "write_file"
            ]
          ]
        },
        "timeout": {
          "type": "integer",
          "description": "Timeout in seconds for the fetch tool",
          "minimum": 1
        },
        "url": {
          "type": "string",
          "description": "URL for the a2a or openapi tool",
          "format": "uri"
        },
        "headers": {
          "type": "object",
          "description": "HTTP headers for API requests (supports ${env.VAR} interpolation)",
          "additionalProperties": {
            "type": "string"
          }
        },
        "name": {
          "type": "string",
          "description": "Name for the a2a tool"
        },
        "file_types": {
          "type": "array",
          "description": "File extensions this LSP server handles (e.g., [\".go\", \".mod\"]). Only for lsp toolsets.",
          "items": {
            "type": "string"
          }
        },
        "models": {
          "type": "array",
          "description": "List of allowed models for the model_picker tool.",
          "items": {
            "type": "string"
          }
        },
        "version": {
          "type": "string",
          "description": "Package reference for auto-installation of MCP/LSP tool binaries. Format: 'owner/repo' or 'owner/repo@version'. Set to 'false' to disable auto-install for this toolset."
        },
        "working_dir": {
          "type": "string",
          "description": "Optional working directory for MCP/LSP toolset processes. Relative paths are resolved relative to the agent's working directory. Only valid for type 'mcp' or 'lsp', and not supported for remote MCP toolsets (no local subprocess)."
        }
      },
      "additionalProperties": false,
      "anyOf": [
        {
          "allOf": [
            {
              "properties": {
                "type": {
                  "const": "mcp"
                }
              }
            },
            {
              "anyOf": [
                {
                  "required": [
                    "command"
                  ]
                },
                {
                  "required": [
                    "remote"
                  ]
                },
                {
                  "required": [
                    "ref"
                  ]
                }
              ]
            }
          ]
        },
        {
          "properties": {
            "type": {
              "enum": [
                "mcp",
                "script",
                "think",
                "memory",
                "filesystem",
                "shell",
                "tasks",
                "todo",
                "fetch",
                "api",
                "a2a",
                "lsp",
                "user_prompt",
                "model_picker",
                "background_agents"
              ]
            }
          }
        },
        {
          "allOf": [
            {
              "properties": {
                "type": {
                  "const": "lsp"
                }
              }
            },
            {
              "required": [
                "command"
              ]
            }
          ]
        },
        {
          "allOf": [
            {
              "properties": {
                "type": {
                  "const": "api"
                }
              }
            },
            {
              "required": [
                "api_config"
              ]
            }
          ]
        },
        {
          "allOf": [
            {
              "properties": {
                "type": {
                  "const": "a2a"
                }
              }
            },
            {
              "required": [
                "url"
              ]
            }
          ]
        },
        {
          "allOf": [
            {
              "properties": {
                "type": {
                  "const": "openapi"
                }
              }
            },
            {
              "required": [
                "url"
              ]
            }
          ]
        },
        {
          "allOf": [
            {
              "properties": {
                "type": {
                  "const": "model_picker"
                }
              }
            },
            {
              "required": [
                "models"
              ]
            }
          ]
        },
        {
          "properties": {
            "type": {
              "const": "background_agents"
            }
          }
        },
        {
          "properties": {
            "type": {
              "const": "rag"
            }
          }
        }
      ]
    },
    "Remote": {
      "type": "object",
      "description": "Remote tool configuration",
      "properties": {
        "url": {
          "type": "string",
          "description": "URL for the remote tool",
          "format": "uri"
        },
        "transport_type": {
          "type": "string",
          "description": "Transport type for the remote connection"
        },
        "headers": {
          "type": "object",
          "description": "HTTP headers for remote requests",
          "additionalProperties": {
            "type": "string"
          }
        },
        "oauth": {
          "$ref": "#/definitions/RemoteOAuthConfig",
          "description": "Explicit OAuth credentials for servers that do not support Dynamic Client Registration"
        }
      },
      "required": [
        "url"
      ],
      "additionalProperties": false
    },
    "ScriptShellToolConfig": {
      "type": "object",
      "description": "Configuration for custom shell tool",
      "properties": {
        "cmd": {
          "type": "string",
          "description": "Command to execute"
        },
        "description": {
          "type": "string",
          "description": "Description of the shell tool"
        },
        "args": {
          "type": "object",
          "description": "Arguments schema (passed as properties in JSON schema)",
          "additionalProperties": true
        },
        "required": {
          "type": "array",
          "description": "Required arguments",
          "items": {
            "type": "string"
          }
        },
        "env": {
          "type": "object",
          "description": "Environment variables for the command",
          "additionalProperties": {
            "type": "string"
          }
        },
        "working_dir": {
          "type": "string",
          "description": "Working directory for the command"
        }
      },
      "additionalProperties": false
    },
    "PostEditConfig": {
      "type": "object",
      "description": "Post-edit command configuration",
      "properties": {
        "path": {
          "type": "string",
          "description": "Path pattern for files to apply post-edit command"
        },
        "cmd": {
          "type": "string",
          "description": "Command to execute after edit"
        }
      },
      "required": [
        "path",
        "cmd"
      ],
      "additionalProperties": false
    },
    "ApiConfig": {
      "type": "object",
      "description": "API tool configuration for making HTTP requests to external APIs",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the API tool"
        },
        "instruction": {
          "type": "string",
          "description": "Instructions for using the API tool"
        },
        "endpoint": {
          "type": "string",
          "description": "API endpoint URL",
          "format": "uri"
        },
        "method": {
          "type": "string",
          "description": "HTTP method",
          "enum": [
            "GET",
            "POST",
            "PUT",
            "PATCH",
            "DELETE"
          ]
        },
        "headers": {
          "type": "object",
          "description": "HTTP headers for the request",
          "additionalProperties": {
            "type": "string"
          }
        },
        "args": {
          "type": "object",
          "description": "Arguments schema for the API call",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "Argument type"
              },
              "description": {
                "type": "string",
                "description": "Argument description"
              }
            }
          }
        },
        "required": {
          "type": "array",
          "description": "Required argument names",
          "items": {
            "type": "string"
          }
        },
        "output_schema": {
          "type": "object",
          "description": "JSON Schema describing the API tool's output. Used by MCP/Code Mode; tool responses are still returned as strings at runtime.",
          "additionalProperties": true
        }
      },
      "required": [
        "name",
        "endpoint",
        "method"
      ],
      "additionalProperties": false
    },
    "RAGConfig": {
      "type": "object",
      "description": "RAG (Retrieval-Augmented Generation) configuration for document search and retrieval with pluggable strategies. Multiple strategies enable hybrid retrieval and reranking.",
      "properties": {
        "tool": {
          "type": "object",
          "description": "Tool configuration for the RAG source",
          "properties": {
            "name": {
              "type": "string",
              "description": "Custom name for the tool (defaults to RAG source name if not specified)"
            },
            "description": {
              "type": "string",
              "description": "Description of what the tool does (shown to the LLM when selecting tools)"
            },
            "instruction": {
              "type": "string",
              "description": "Instruction on how the RAG tool should be used effectively (shown in system prompt)"
            }
          },
          "additionalProperties": false
        },
        "docs": {
          "type": "array",
          "description": "Shared document paths or directories indexed by all strategies",
          "items": {
            "type": "string"
          }
        },
        "respect_vcs": {
          "type": "boolean",
          "description": "Whether to respect VCS ignore files (e.g., .gitignore) when collecting documents for indexing. When true (default), files matching ignore patterns will be excluded. Can be overridden per-strategy.",
          "default": true
        },
        "strategies": {
          "type": "array",
          "description": "Array of retrieval strategy configurations. Each strategy can have different parameters based on its type.",
          "minItems": 1,
          "items": {
            "type": "object",
            "description": "Retrieval strategy configuration with type-specific parameters. Structured fields are limited; additional parameters are passed through as-is for strategy-specific use.",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "Retrieval strategy type",
                "enum": [
                  "bm25",
                  "chunked-embeddings",
                  "semantic-embeddings"
                ]
              },
              "embedding_model": {
                "type": "string",
                "description": "Embedding model reference for chunked-embeddings and semantic-embeddings strategies (looked up in models map, or 'auto' for automatic selection)",
                "examples": [
                  "openai/text-embedding-3-small",
                  "dmr/embeddinggemma",
                  "auto"
                ]
              },
              "docs": {
                "type": "array",
                "description": "Additional documents for this strategy only (augments shared docs)",
                "items": {
                  "type": "string"
                }
              },
              "database": {
                "type": "string",
                "description": "Database path or connection string. Currently only simple string values are supported (e.g., './vector.db', './bm25.db')."
              },
              "similarity_metric": {
                "type": "string",
                "description": "Similarity metric (chunked-embeddings only). Currently only 'cosine_similarity' is implemented.",
                "enum": [
                  "cosine_similarity"
                ]
              },
              "vector_dimensions": {
                "type": "integer",
                "description": "Vector dimensions for embeddings (chunked-embeddings only). Must match your embedding model's output dimensions and is required for chunked-embeddings strategies.",
                "minimum": 1,
                "examples": [
                  1536,
                  3072,
                  1024,
                  768
                ]
              },
              "k1": {
                "type": "number",
                "description": "BM25 term frequency saturation (bm25 only, typically 1.2-2.0)",
                "minimum": 0
              },
              "b": {
                "type": "number",
                "description": "BM25 length normalization (bm25 only, 0-1, typically 0.75)",
                "minimum": 0,
                "maximum": 1
              },
              "threshold": {
                "type": "number",
                "description": "Minimum score threshold (0-1 for chunked-embeddings, unbounded for bm25)",
                "minimum": 0
              },
              "limit": {
                "type": "integer",
                "description": "Max results from this strategy (candidates for fusion). If unset, defaults to 5 in the implementation.",
                "minimum": 1
              },
              "chunking": {
                "type": "object",
                "description": "Text chunking configuration",
                "properties": {
                  "size": {
                    "type": "integer",
                    "description": "Chunk size in characters. If unset, defaults to 1000 in the implementation.",
                    "minimum": 1
                  },
                  "overlap": {
                    "type": "integer",
                    "description": "Overlap between chunks in characters. If unset, defaults to 75 in the implementation.",
                    "minimum": 0
                  },
                  "respect_word_boundaries": {
                    "type": "boolean",
                    "description": "When true, chunks will split on the nearest whitespace boundary instead of at the exact character limit, preventing words from being truncated."
                  },
                  "code_aware": {
                    "type": "boolean",
                    "description": "Enable code-aware chunking for source files. When true, the chunking strategy will prefer AST-based or language-aware processors when available (tree-sitter based), and fall back to plain text chunking for unsupported languages."
                  }
                },
                "additionalProperties": false
              },
              "embedding_batch_size": {
                "type": "integer",
                "description": "Number of text chunks to send to the embedding API in a single request (chunked-embeddings/semantic-embeddings only)",
                "minimum": 1,
                "default": 50
              },
              "max_embedding_concurrency": {
                "type": "integer",
                "description": "Maximum concurrent embedding batch API requests. For semantic-embeddings, also controls parallel LLM calls for generating chunk summaries.",
                "minimum": 1,
                "default": 3
              },
              "max_indexing_concurrency": {
                "type": "integer",
                "description": "Maximum number of files to index in parallel during initialization",
                "minimum": 1,
                "default": 3
              },
              "respect_vcs": {
                "type": "boolean",
                "description": "Override the RAG-level respect_vcs setting for this strategy only."
              },
              "chat_model": {
                "type": "string",
                "description": "Chat model used to generate semantic representations for each chunk (semantic-embeddings only, required)",
                "examples": [
                  "anthropic/claude-sonnet-4-5",
                  "openai/gpt-4o-mini"
                ]
              },
              "semantic_prompt": {
                "type": "string",
                "description": "Custom prompt template for semantic LLM. Uses JavaScript template literal syntax with the following placeholders: ${path} (full source file path), ${basename} (base name of file), ${chunk_index} (numeric chunk index), ${content} (raw chunk content), ${ast_context} (AST metadata when ast_context is enabled). Only applicable to semantic-embeddings strategy."
              },
              "ast_context": {
                "type": "boolean",
                "description": "Include TreeSitter-derived AST metadata in the semantic prompt (semantic-embeddings only, requires chunking.code_aware for best results)",
                "default": false
              }
            },
            "additionalProperties": true
          }
        },
        "results": {
          "type": "object",
          "description": "Result post-processing configuration (fusion, deduplication, limiting). If omitted, sensible defaults are applied in code.",
          "properties": {
            "limit": {
              "type": "integer",
              "description": "Maximum number of results to return (top K)",
              "minimum": 1,
              "default": 15
            },
            "fusion": {
              "type": "object",
              "description": "Configuration for combining results from multiple strategies. If omitted and multiple strategies are configured, Reciprocal Rank Fusion (rrf) with k=60 is used.",
              "properties": {
                "strategy": {
                  "type": "string",
                  "description": "Fusion strategy to use",
                  "enum": [
                    "rrf",
                    "reciprocal_rank_fusion",
                    "weighted",
                    "max"
                  ],
                  "default": "rrf",
                  "examples": [
                    "rrf",
                    "weighted"
                  ]
                },
                "k": {
                  "type": "integer",
                  "description": "RRF smoothing parameter k (only for RRF strategy)",
                  "minimum": 1,
                  "default": 60
                },
                "weights": {
                  "type": "object",
                  "description": "Strategy weights for weighted fusion (strategy name -> weight)",
                  "additionalProperties": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "examples": [
                    {
                      "chunked-embeddings": 0.7,
                      "bm25": 0.3
                    }
                  ]
                }
              },
              "additionalProperties": false
            },
            "reranking": {
              "type": "object",
              "description": "Configuration for reranking results using a specialized reranking model. Reranking re-scores the retrieved results to improve relevance accuracy.",
              "properties": {
                "model": {
                  "type": "string",
                  "description": "Model reference for reranking (can be inline like 'dmr/model-name' or a reference to a defined model)",
                  "examples": [
                    "dmr/hf.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF",
                    "reranker_model"
                  ]
                },
                "top_k": {
                  "type": "integer",
                  "description": "Optional: only rerank top K results for efficiency. When unset or 0, defaults to the global results.limit (which itself defaults to 15).",
                  "minimum": 0,
                  "default": 0
                },
                "threshold": {
                  "type": "number",
                  "description": "Optional: minimum score threshold after reranking (filter results below this score)",
                  "minimum": 0,
                  "maximum": 1,
                  "default": 0.5
                },
                "criteria": {
                  "type": "string",
                  "description": "Optional: domain-specific relevance criteria to guide scoring. This text is appended to the base reranking prompt to customize what 'relevance' means for your use case. Supported by OpenAI, Anthropic, and Gemini providers (not DMR native reranking).",
                  "examples": [
                    "Prioritize recent information and practical examples over historical context",
                    "When scoring relevance, focus on code examples and implementation details"
                  ]
                }
              },
              "required": [
                "model"
              ],
              "additionalProperties": false
            },
            "deduplicate": {
              "type": "boolean",
              "description": "Remove duplicate documents across strategies",
              "default": true
            },
            "include_score": {
              "type": "boolean",
              "description": "Include relevance scores in results",
              "default": false
            },
            "return_full_content": {
              "type": "boolean",
              "description": "Return full document content instead of just the matched chunk. The full document is read directly from the file system.",
              "default": false
            }
          },
          "additionalProperties": false
        }
      },
      "required": [
        "strategies"
      ],
      "additionalProperties": false
    },
    "RemoteOAuthConfig": {
      "type": "object",
      "description": "OAuth configuration for remote MCP servers that do not support Dynamic Client Registration (RFC 7591)",
      "properties": {
        "clientId": {
          "type": "string",
          "description": "OAuth client ID"
        },
        "clientSecret": {
          "type": "string",
          "description": "OAuth client secret"
        },
        "callbackPort": {
          "type": "integer",
          "description": "Fixed port for the OAuth callback server (default: random available port)",
          "minimum": 1,
          "maximum": 65535
        },
        "scopes": {
          "type": "array",
          "description": "OAuth scopes to request",
          "items": {
            "type": "string"
          }
        },
        "callbackRedirectURL": {
          "type": "string",
          "description": "Optional OAuth redirect URI used in place of http://127.0.0.1:{callbackPort}/callback. The literal placeholder ${callbackPort} is replaced with the actual local callback port at runtime. The external URL is expected to redirect the browser back to the local callback server."
        }
      },
      "required": [
        "clientId"
      ]
    }
  }
}