netclaw-config.v1.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.netclaw.local/config/v1",
  "title": "Netclaw Config v1",
  "type": "object",
  "required": ["configVersion"],
  "properties": {
    "configVersion": {
      "type": "integer",
      "const": 1
    },
    "Slack": {
      "type": "object",
      "properties": {
        "Enabled": { "type": "boolean" },
        "SocketMode": { "type": "boolean" },
        "DefaultChannelId": { "type": ["string", "null"] },
        "DefaultChannelName": { "type": ["string", "null"] },
        "MentionOnly": { "type": "boolean" },
        "AllowDirectMessages": { "type": "boolean" },
        "MentionRequiredInDm": { "type": "boolean" },
        "AllowedChannelIds": {
          "type": "array",
          "items": { "type": "string" }
        },
        "AllowedUserIds": {
          "type": "array",
          "items": { "type": "string" }
        },
        "ChannelAudiences": {
          "type": "object",
          "description": "Per-channel audience overrides. Keys are channel IDs or 'dm'. Values are 'personal', 'team', or 'public'.",
          "additionalProperties": {
            "type": "string",
            "enum": ["personal", "team", "public"]
          }
        }
      },
      "additionalProperties": false
    },
    "Discord": {
      "type": "object",
      "properties": {
        "Enabled": { "type": "boolean" },
        "DefaultChannelId": { "type": ["string", "null"] },
        "AllowDirectMessages": { "type": "boolean" },
        "MentionOnly": { "type": "boolean", "default": true },
        "MentionRequiredInDm": { "type": "boolean", "default": false },
        "AllowedChannelIds": {
          "type": "array",
          "items": { "type": "string" }
        },
        "AllowedUserIds": {
          "type": "array",
          "items": { "type": "string" }
        },
        "ChannelAudiences": {
          "type": "object",
          "description": "Per-channel audience overrides. Keys are channel IDs or 'dm'. Values are 'personal', 'team', or 'public'.",
          "additionalProperties": {
            "type": "string",
            "enum": ["personal", "team", "public"]
          }
        }
      },
      "additionalProperties": false
    },
    "Mattermost": {
      "type": "object",
      "properties": {
        "Enabled": { "type": "boolean" },
        "ServerUrl": { "type": ["string", "null"], "format": "uri", "description": "Base URL of the Mattermost server (e.g. https://mm.example.com)." },
        "CallbackUrl": { "type": ["string", "null"], "format": "uri", "description": "URL that Mattermost can reach for interactive button callbacks (e.g. http://netclaw-host:5199/api/mattermost/actions). When unset, approvals use the text-reply fallback." },
        "DefaultChannelId": { "type": ["string", "null"] },
        "AllowDirectMessages": { "type": "boolean" },
        "MentionOnly": { "type": "boolean", "default": true },
        "MentionRequiredInDm": { "type": "boolean", "default": false },
        "AllowedChannelIds": {
          "type": "array",
          "items": { "type": "string" }
        },
        "AllowedUserIds": {
          "type": "array",
          "items": { "type": "string" }
        },
        "ChannelAudiences": {
          "type": "object",
          "description": "Per-channel audience overrides. Keys are channel IDs or 'dm'. Values are 'personal', 'team', or 'public'.",
          "additionalProperties": {
            "type": "string",
            "enum": ["personal", "team", "public"]
          }
        }
      },
      "additionalProperties": false
    },
    "Logging": {
      "type": "object",
      "properties": {
        "LogLevel": {
          "type": "object",
          "properties": {
            "Default": {
              "type": "string",
              "enum": ["Trace", "Debug", "Information", "Warning", "Error", "Critical", "None"]
            }
          },
          "additionalProperties": true
        },
        "Console": {
          "type": "object",
          "properties": {
            "Enabled": { "type": "boolean" }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": true
    },
    "Telemetry": {
      "type": "object",
      "properties": {
        "Enabled": { "type": "boolean" },
        "Otlp": {
          "type": "object",
          "properties": {
            "Endpoint": { "type": "string", "format": "uri" }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "Persistence": {
      "type": "object",
      "additionalProperties": true
    },
    "Session": {
      "type": "object",
      "description": "Operator-facing session configuration.",
      "properties": {
        "MaxToolIterationsPerTurn": {
          "type": "integer",
          "minimum": 1,
          "maximum": 500,
          "default": 60,
          "description": "Maximum LLM-to-tools-to-LLM iterations allowed per turn. One LLM response with any number of parallel tool calls counts as exactly one iteration."
        },
        "MemoryObserverIdleSeconds": {
          "type": "integer",
          "minimum": 10,
          "description": "Idle seconds before memory observer triggers distillation."
        },
        "IdleTimeout": {
          "type": "string",
          "description": "Session idle timeout in HH:mm:ss format. Set to 00:00:00 to disable."
        },
        "TurnLlmTimeoutSeconds": {
          "type": "integer",
          "minimum": 1,
          "description": "Timeout in seconds for the primary per-turn LLM streaming call."
        },
        "ToolExecutionTimeoutSeconds": {
          "type": "integer",
          "minimum": 1,
          "description": "Per-tool-call inactivity budget in seconds: a tool call must produce its first result (or stream item) within this time, and each later item resets it."
        },
        "SidecarLlmTimeoutSeconds": {
          "type": "integer",
          "minimum": 1,
          "description": "Timeout in seconds for sidecar LLM calls (title, memory, compaction)."
        },
        "FirstTokenTimeoutSeconds": {
          "type": "integer",
          "minimum": 10,
          "maximum": 1800,
          "default": 600,
          "description": "Maximum silence in seconds between consecutive LLM streaming deltas. After the first delta arrives, the watchdog uses this as the inter-delta timeout (timer resets on each delta)."
        },
        "PrefillTimeoutSeconds": {
          "type": "integer",
          "minimum": 60,
          "maximum": 7200,
          "default": 1800,
          "description": "Maximum time in seconds to wait for the first streaming delta from the LLM. Covers queue wait and prompt prefill on self-hosted backends. After the first delta, the watchdog switches to FirstTokenTimeoutSeconds."
        },
        "NoProgressTimeoutSeconds": {
          "type": "integer",
          "minimum": 60,
          "maximum": 7200,
          "default": 1200,
          "description": "Hard ceiling in seconds on time without substantive output. Reset only by real streaming tokens — content-free keepalives never extend it — so a backend that heartbeats forever without producing a token is killed once this elapses. Catches a wedged stream the prefill/first-token liveness watchdog cannot, because keepalives refresh those."
        },
        "CompactionThreshold": {
          "type": "number",
          "minimum": 0.1,
          "maximum": 1.0,
          "description": "Legacy root-level alias for Session.Tuning.CompactionThreshold."
        },
        "SnapshotInterval": {
          "type": "integer",
          "minimum": 1,
          "description": "Legacy root-level alias for Session.Tuning.SnapshotInterval."
        },
        "KeepRecentToolResults": {
          "type": "integer",
          "minimum": 0,
          "description": "Legacy root-level alias for Session.Tuning.KeepRecentToolResults."
        },
        "MaxInlineToolResultChars": {
          "type": "integer",
          "minimum": 100,
          "description": "Legacy root-level alias for Session.Tuning.MaxInlineToolResultChars."
        },
        "DiscoveredToolRetentionTurns": {
          "type": "integer",
          "minimum": 0,
          "description": "Legacy root-level alias for Session.Tuning.DiscoveredToolRetentionTurns."
        },
        "DiscoveredToolMaxCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Legacy root-level alias for Session.Tuning.DiscoveredToolMaxCount."
        },
        "KeepRecentMessages": {
          "type": "integer",
          "minimum": 1,
          "description": "Legacy root-level alias for Session.Tuning.KeepRecentMessages."
        },
        "TitleGenerationInterval": {
          "type": "integer",
          "minimum": 0,
          "description": "Legacy root-level alias for Session.Tuning.TitleGenerationInterval."
        },
        "DeterministicRetrievalEnabled": {
          "type": "boolean",
          "description": "Legacy root-level alias for Session.Tuning.DeterministicRetrievalEnabled."
        },
        "Tuning": {
          "type": "object",
          "description": "Internal tuning constants. Not part of the documented operator surface.",
          "properties": {
            "CompactionThreshold": { "type": "number", "minimum": 0.1, "maximum": 1.0 },
            "SnapshotInterval": { "type": "integer", "minimum": 1 },
            "KeepRecentToolResults": { "type": "integer", "minimum": 0 },
            "MaxInlineToolResultChars": { "type": "integer", "minimum": 100 },
            "DiscoveredToolRetentionTurns": { "type": "integer", "minimum": 0 },
            "DiscoveredToolMaxCount": { "type": "integer", "minimum": 0 },
            "KeepRecentMessages": { "type": "integer", "minimum": 1 },
            "TitleGenerationInterval": { "type": "integer", "minimum": 0 },
            "DeterministicRetrievalEnabled": { "type": "boolean" },
            "MemoryDistillationTurnInterval": { "type": "integer", "minimum": 0 },
            "MinimumRecallCompositeScore": {
              "type": ["number", "null"],
              "minimum": 0,
              "description": "Optional override for the minimum composite score a memory must reach to be injected via automatic recall. When omitted, the coordinator uses a built-in default. Power-user knob; set to 0 to effectively disable the floor."
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "Security": {
      "type": "object",
      "description": "Trust-context security policy defaults.",
      "properties": {
        "DeploymentPosture": {
          "type": ["string", "null"],
          "enum": ["Public", "Team", "Personal", null]
        },
        "ShellExecutionMode": {
          "type": ["string", "null"],
          "enum": ["Off", "SandboxOnly", "HostAllowed", null]
        },
        "StrictDefaults": {
          "type": "boolean",
          "default": true
        }
      },
      "additionalProperties": false
    },
    "Tools": {
      "type": "object",
      "properties": {
        "ShellMode": {
          "type": ["string", "null"],
          "enum": ["Off", "SandboxOnly", "HostAllowed", null]
        },
        "ShellTimeoutSeconds": {
          "type": "integer",
          "minimum": 1,
          "default": 60
        },
        "MaxOutputChars": {
          "type": "integer",
          "minimum": 1,
          "default": 256000,
          "description": "Capture ceiling for tool output: the maximum characters captured in bounded memory to become the full-output spill file written under the session directory when a result exceeds the inline budget. This is NOT what the model sees inline — that is Session.Tuning.MaxInlineToolResultChars (plus any per-tool override). Output beyond this ceiling is discarded while the source keeps draining (so a live child process never deadlocks), and the spill is a head+tail view."
        },
        "AudienceProfiles": {
          "$ref": "#/$defs/ToolAudienceProfiles"
        },
        "WebFetch": {
          "type": "object",
          "properties": {
            "RequireHttps": {
              "type": "boolean",
              "default": true,
              "description": "When true, web_fetch rejects plain HTTP URLs unless the host is in HttpAllowList."
            },
            "HttpAllowList": {
              "type": "array",
              "items": { "type": "string" },
              "default": ["localhost", "127.0.0.1", "::1", "[::1]"],
              "description": "Hosts allowed to use plain HTTP when RequireHttps is true. Default includes loopback addresses."
            }
          },
          "additionalProperties": false
        },
        "HardDenyPatterns": {
          "type": "array",
          "items": { "type": "string" },
          "default": [],
          "description": "Additional shell command patterns to add to the hard deny list. Verb-chain prefixes that are categorically blocked and cannot be approved."
        },
        "MaxToolTimeoutSeconds": {
          "type": "integer",
          "minimum": 1,
          "default": 600,
          "description": "Maximum per-call timeout in seconds that the LLM can request via _timeout_seconds meta field. Values above this ceiling are clamped."
        }
      },
      "additionalProperties": false
    },
    "Providers": {
      "type": "object",
      "additionalProperties": true
    },
    "Models": {
      "type": "object",
      "description": "Model selection by role (Main, Fallback, Compaction).",
      "properties": {
        "Main": { "$ref": "#/$defs/ModelReference" },
        "Fallback": { "$ref": "#/$defs/ModelReference" },
        "Compaction": { "$ref": "#/$defs/ModelReference" }
      },
      "additionalProperties": false
    },
    "Memory": {
      "type": "object",
      "description": "Cross-session memory configuration.",
      "properties": {
        "Enabled": {
          "type": "boolean",
          "default": true,
          "description": "When false, the entire cross-session memory subsystem is disabled."
        },
        "RecallTimeoutMs": {
          "type": "integer",
          "minimum": 50,
          "maximum": 10000,
          "default": 300,
          "description": "Automatic recall timeout budget in milliseconds."
        },
        "AutoRecallMaxItems": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "default": 3,
          "description": "Maximum number of memory items auto-injected per turn."
        }
      },
      "additionalProperties": false
    },
    "Search": {
      "type": "object",
      "description": "Web search backend configuration.",
      "properties": {
        "Enabled": {
          "type": "boolean",
          "default": true,
          "description": "When false, the web search subsystem is disabled."
        },
        "Backend": {
          "type": "string",
          "enum": ["duckduckgo", "brave", "searxng"],
          "default": "duckduckgo",
          "description": "Search backend identifier."
        },
        "BraveApiKey": {
          "type": ["string", "null"],
          "description": "Brave Search API key. Required when Backend is Brave. Stored in secrets.json."
        },
        "SearXngEndpoint": {
          "type": ["string", "null"],
          "description": "SearXNG instance base URL. Required when Backend is SearXng."
        }
      },
      "additionalProperties": false
    },
    "SkillSync": {
      "type": "object",
      "description": "Startup synchronization behavior for system skills.",
      "properties": {
        "Enabled": {
          "type": "boolean",
          "default": true,
          "description": "When false, the skill sync subsystem is disabled entirely."
        },
        "DisableSystemSkillSync": {
          "type": "boolean",
          "default": false,
          "description": "When true, skip feed sync at startup and use local built-in/on-disk system skills only."
        }
      },
      "additionalProperties": false
    },
    "ExternalSkills": {
      "type": "object",
      "description": "External skill directory sources (Claude Code, Open Code, custom paths).",
      "properties": {
        "Sources": {
          "type": "array",
          "description": "Ordered list of external skill sources. Precedence follows list order; native Netclaw skills always win.",
          "items": {
            "type": "object",
            "properties": {
              "Name": {
                "type": "string",
                "description": "Unique identifier for this source (e.g., 'claude-code', 'team-skills')."
              },
              "Path": {
                "type": ["string", "null"],
                "description": "Absolute path to the skill directory. Mutually exclusive with WellKnown."
              },
              "WellKnown": {
                "type": ["string", "null"],
                "enum": ["claude-code", "open-code", null],
                "description": "Well-known source alias. Resolves to a standard path automatically."
              },
              "Enabled": {
                "type": "boolean",
                "default": true,
                "description": "Whether this source is active."
              },
              "AllowSymlinks": {
                "type": "boolean",
                "default": false,
                "description": "Whether to follow symlinks in this directory. Resolved paths are still validated to stay within the source root."
              }
            },
            "required": ["Name"],
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "SkillFeeds": {
      "type": "object",
      "description": "Private skill server feeds. Skills are synced from these servers at startup and periodically.",
      "properties": {
        "SyncIntervalMinutes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 1440,
          "default": 60,
          "description": "How often (in minutes) to re-check feeds for updated skills. 0 disables periodic sync."
        },
        "Feeds": {
          "type": "array",
          "description": "Ordered list of skill server feeds. Earlier feeds win on name collisions.",
          "items": {
            "type": "object",
            "properties": {
              "Name": {
                "type": "string",
                "description": "Unique feed identifier (used as directory name). Lowercase alphanumeric and hyphens."
              },
              "Url": {
                "type": "string",
                "format": "uri",
                "description": "Skill server base URL (e.g., https://skills.corp.com)."
              },
              "ApiKey": {
                "type": ["string", "null"],
                "description": "Optional Bearer token for authenticated access. Supports ENC: prefix."
              },
              "Enabled": {
                "type": "boolean",
                "default": true,
                "description": "Whether this feed is active."
              },
              "TimeoutSeconds": {
                "type": "integer",
                "minimum": 1,
                "maximum": 300,
                "default": 30,
                "description": "HTTP timeout in seconds for requests to this feed."
              }
            },
            "required": ["Name", "Url"],
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "SubAgents": {
      "type": "object",
      "description": "Timeout configuration for subagent execution (seconds).",
      "properties": {
        "Enabled": {
          "type": "boolean",
          "default": true,
          "description": "When false, the subagent subsystem is disabled."
        },
        "PrefillTimeoutSeconds": {
          "type": "integer",
          "minimum": 5,
          "maximum": 3600,
          "default": 1800,
          "description": "Generous wait-for-first-delta budget (seconds) covering queue wait and cold prefill for sub-agent LLM calls, mirroring Session.PrefillTimeoutSeconds. Content-free prompt_progress keepalives refresh it; after the first substantive delta the per-agent inter-delta budget applies. A per-agent definition may override via prefillTimeoutSeconds frontmatter."
        },
        "NoProgressTimeoutSeconds": {
          "type": "integer",
          "minimum": 60,
          "maximum": 7200,
          "default": 1200,
          "description": "Hard ceiling (seconds) on time without substantive output for sub-agent LLM calls, mirroring Session.NoProgressTimeoutSeconds. Reset only by real streaming tokens — content-free keepalives never extend it — so a backend that heartbeats forever without producing a token is killed once this elapses."
        }
      },
      "additionalProperties": false
    },
    "Notifications": {
      "type": "object",
      "description": "Operational alert notification configuration.",
      "properties": {
        "Webhooks": {
          "type": "array",
          "description": "Webhook targets for operational notifications. Empty = logging only.",
          "items": {
            "type": "object",
            "properties": {
              "Url": { "type": "string", "format": "uri" },
              "Name": { "type": ["string", "null"] },
              "Headers": {
                "type": ["object", "null"],
                "additionalProperties": { "type": "string" }
              },
              "Format": {
                "type": "string",
                "enum": ["Generic", "Slack"],
                "default": "Generic",
                "description": "Payload format for this webhook target. Generic = JSON envelope; Slack = Block Kit format."
              }
            },
            "required": ["Url"],
            "additionalProperties": false
          }
        },
        "DeduplicationWindowSeconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3600,
          "default": 300,
          "description": "Minimum interval in seconds between duplicate alerts of the same type."
        },
        "MaxRetries": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10,
          "default": 2,
          "description": "Number of delivery retries per webhook target before giving up."
        },
        "TimeoutSeconds": {
          "type": "integer",
          "minimum": 1,
          "maximum": 60,
          "default": 10,
          "description": "HTTP timeout in seconds for each webhook POST attempt."
        }
      },
      "additionalProperties": false
    },
    "Webhooks": {
      "type": "object",
      "description": "Inbound webhook feature settings. Individual route definitions live under ~/.netclaw/config/webhooks/*.json.",
      "properties": {
        "Enabled": {
          "type": "boolean",
          "default": false
        },
        "ExecutionTimeoutSeconds": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3600,
          "default": 300
        }
      },
      "additionalProperties": false
    },
    "Scheduling": {
      "type": "object",
      "description": "Scheduling and reminders subsystem configuration.",
      "properties": {
        "Enabled": {
          "type": "boolean",
          "default": true,
          "description": "When false, the scheduling subsystem is disabled. Reminder and scheduling tools are not registered."
        }
      },
      "additionalProperties": false
    },
    "Daemon": {
      "type": "object",
      "description": "Daemon network and exposure configuration.",
      "properties": {
        "Host": {
          "type": "string",
          "default": "127.0.0.1",
          "description": "IP address the daemon binds to. Defaults to loopback (127.0.0.1)."
        },
        "Port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535,
          "default": 5199,
          "description": "TCP port the daemon listens on. Defaults to 5199."
        },
        "ExposureMode": {
          "type": "string",
          "enum": ["local", "reverse-proxy", "tailscale-serve", "tailscale-funnel", "cloudflare-tunnel"],
          "default": "local",
          "description": "Tunnel infrastructure in front of the daemon. Defaults to local (loopback only, no tunnel)."
        },
        "TrustedProxies": {
          "type": "array",
          "default": [],
          "description": "Explicitly trusted reverse-proxy source IPs or CIDR ranges. Required for reverse-proxy mode.",
          "items": {
            "type": "string",
            "pattern": "^(?:(?:\\d{1,3}\\.){3}\\d{1,3}(?:\\/(?:[0-9]|[12][0-9]|3[0-2]))?|(?:[0-9A-Fa-f:]+:+)+[0-9A-Fa-f]+(?:\\/(?:[0-9]|[1-9][0-9]|1[01][0-9]|12[0-8]))?)$"
          }
        },
        "SkipTunnelProcessCheck": {
          "type": "boolean",
          "default": false,
          "description": "When true, skips the local tunnel-process prerequisite check for tunnel-backed exposure modes. Use only for sidecar or host-managed tunnel topologies."
        },
        "DisableSelfUpdate": {
          "type": "boolean",
          "default": false,
          "description": "When true, in-place binary self-update via 'netclaw update' is blocked. Update availability checks still run. Intended for container deployments where the image tag is the version."
        },
        "UpdateChannel": {
          "type": "string",
          "enum": [
            "stable",
            "beta"
          ],
          "default": "stable",
          "description": "Release channel the update check follows. 'stable' (default) only sees stable releases; 'beta' opts into prereleases and rolls onto a stable release once it supersedes a beta. Stable clients are never offered a prerelease."
        }
      },
      "additionalProperties": false
    },
    "Workspaces": {
      "type": "object",
      "description": "Project workspace configuration.",
      "properties": {
        "Directory": {
          "type": "string",
          "description": "Root directory for project workspaces. Projects are git repos with an AGENTS.md, potentially nested at any depth. Defaults to ~/.netclaw/workspaces."
        }
      },
      "additionalProperties": false
    },
    "McpServers": {
      "type": "object",
      "description": "MCP server profiles keyed by name.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "Transport": {
            "type": "string",
            "enum": ["stdio", "sse", "http"],
            "default": "stdio"
          },
          "Command": { "type": ["string", "null"] },
          "Arguments": {
            "type": ["array", "null"],
            "items": { "type": "string" }
          },
          "Url": { "type": ["string", "null"], "format": "uri" },
          "EnvironmentVariables": {
            "type": ["object", "null"],
            "additionalProperties": { "type": "string" }
          },
          "Headers": {
            "type": ["object", "null"],
            "additionalProperties": { "type": "string" }
          },
          "Enabled": { "type": "boolean", "default": true },
          "GrantCategory": { "type": ["string", "null"] },
          "OAuthClientId": { "type": ["string", "null"] },
          "OAuthScope": { "type": ["string", "null"] }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": true,
  "$defs": {
    "ToolProfileMode": {
      "type": "string",
      "enum": ["Allowlist", "All"]
    },
    "ToolFilesystemMode": {
      "type": "string",
      "enum": ["None", "Roots", "All"]
    },
    "ToolFilesystemAccessProfile": {
      "type": "object",
      "properties": {
        "Mode": { "$ref": "#/$defs/ToolFilesystemMode" },
        "Roots": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "additionalProperties": false
    },
    "ToolAudienceProfile": {
      "type": "object",
      "properties": {
        "ToolsMode": { "$ref": "#/$defs/ToolProfileMode" },
        "AllowedTools": {
          "type": "array",
          "items": { "type": "string" }
        },
        "McpServersMode": { "$ref": "#/$defs/ToolProfileMode" },
        "AllowedMcpServers": {
          "type": "array",
          "items": { "type": "string" }
        },
        "McpServerToolGrants": {
          "type": ["object", "null"],
          "description": "Per-server tool allowlists. Keys are server names, values are arrays of allowed tool names. Servers not listed expose all tools.",
          "additionalProperties": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "ReadFiles": { "$ref": "#/$defs/ToolFilesystemAccessProfile" },
        "WriteFiles": { "$ref": "#/$defs/ToolFilesystemAccessProfile" },
        "AttachFiles": { "$ref": "#/$defs/ToolFilesystemAccessProfile" },
        "ApprovalPolicy": { "$ref": "#/$defs/ToolApprovalConfig" },
        "ChannelAttachments": { "$ref": "#/$defs/ChannelAttachmentPolicy" }
      },
      "additionalProperties": false
    },
    "AttachmentCategory": {
      "type": "string",
      "enum": ["Image", "Pdf", "Document", "Archive", "Media", "Other"],
      "description": "Coarse MIME classification used for per-audience attachment policy."
    },
    "ChannelAttachmentPolicy": {
      "type": "object",
      "description": "Per-audience inbound channel attachment policy. Channel adapters query this before downloading or delivering any user-uploaded file.",
      "properties": {
        "AllowedCategories": {
          "type": "array",
          "items": { "$ref": "#/$defs/AttachmentCategory" },
          "default": [],
          "description": "Attachment categories permitted for this audience. Empty rejects all inbound attachments."
        },
        "MaxFileBytes": {
          "type": "integer",
          "minimum": 0,
          "default": 26214400,
          "description": "Maximum per-file size in bytes. Files whose transport-reported size exceeds this are rejected before download. Default: 25 MiB."
        },
        "MaxFilesPerMessage": {
          "type": "integer",
          "minimum": 0,
          "default": 10,
          "description": "Maximum number of attachments accepted on a single inbound message. Messages exceeding this have all attachments rejected."
        }
      },
      "additionalProperties": false
    },
    "ToolApprovalConfig": {
      "type": ["object", "null"],
      "description": "Per-audience tool approval gate configuration. Controls which tools require interactive user approval before execution.",
      "properties": {
        "DefaultMode": {
          "type": "string",
          "enum": ["Auto", "Approval", "Deny"],
          "default": "Auto",
          "description": "Default approval mode for tools not explicitly overridden."
        },
        "ToolOverrides": {
          "type": "object",
          "default": {},
          "description": "Per-tool approval mode overrides. Keys are exact tool names (e.g., shell_execute, file_write) or MCP tool keys of the form {serverName}/{toolName} (e.g., notion/create-pages) or matcher-specific keys such as file_write:control-plane and file_edit:control-plane.",
          "additionalProperties": {
            "type": "string",
            "enum": ["Auto", "Approval", "Deny"]
          }
        },
        "McpServerDefaults": {
          "type": "object",
          "default": {},
          "description": "Per-MCP-server approval mode defaults. Keys are MCP server names (e.g., notion). Applies to all tools exposed by that server unless an exact entry in ToolOverrides takes precedence. Tools discovered on the server after config was written inherit this default automatically.",
          "additionalProperties": {
            "type": "string",
            "enum": ["Auto", "Approval", "Deny"]
          }
        }
      },
      "additionalProperties": false
    },
    "ToolAudienceProfiles": {
      "type": "object",
      "properties": {
        "Public": { "$ref": "#/$defs/ToolAudienceProfile" },
        "Team": { "$ref": "#/$defs/ToolAudienceProfile" },
        "Personal": { "$ref": "#/$defs/ToolAudienceProfile" },
        "GlobalReadRoots": {
          "type": "array",
          "description": "Filesystem roots readable by all audiences. Supports tokens: {skills_dir}, {identity_dir}, {workspaces_dir}.",
          "items": { "type": "string" }
        }
      },
      "additionalProperties": false
    },
    "ModelModality": {
      "type": "string",
      "enum": ["Text", "Image", "Audio", "Video"],
      "description": "A single content modality."
    },
    "ModelReference": {
      "type": "object",
      "properties": {
        "Provider": { "type": "string", "description": "Key into the Providers dictionary." },
        "ModelId": { "type": "string", "description": "Model identifier for API calls." },
        "ContextWindow": { "type": "integer", "description": "Effective runtime context window in tokens. When set, clamps the detected provider value." },
        "Provenance": {
          "type": ["string", "null"],
          "enum": ["Live", "Defaults", "Manual", null],
          "description": "Optional model provenance marker (Live, Defaults, or Manual)."
        },
        "InputModalities": {
          "type": "string",
          "description": "Manual override for input modalities. Comma-separated ModelModality flags (e.g. \"Text\", \"Text, Image\"). Bypasses automated detection.",
          "pattern": "^(Text|Image|Audio|Video)(\\s*,\\s*(Text|Image|Audio|Video))*$"
        },
        "OutputModalities": {
          "type": "string",
          "description": "Manual override for output modalities. Comma-separated ModelModality flags (e.g. \"Text\"). Bypasses automated detection.",
          "pattern": "^(Text|Image|Audio|Video)(\\s*,\\s*(Text|Image|Audio|Video))*$"
        }
      },
      "additionalProperties": false
    },
    "NotificationTarget": {
      "type": "object",
      "properties": {
        "Kind": {
          "type": "string",
          "enum": ["Slack"],
          "default": "Slack"
        },
        "ChannelId": {
          "type": ["string", "null"]
        }
      },
      "additionalProperties": false
    },
    "WebhookVerification": {
      "type": "object",
      "properties": {
        "Kind": {
          "type": "string",
          "enum": ["Hmac", "HeaderSecret"],
          "default": "Hmac"
        },
        "HmacAlgorithm": {
          "type": "string",
          "enum": ["Sha256"],
          "default": "Sha256"
        },
        "Secret": {
          "type": ["string", "null"]
        },
        "SignatureHeaderName": {
          "type": ["string", "null"]
        },
        "SignaturePrefix": {
          "type": ["string", "null"]
        },
        "SecretHeaderName": {
          "type": ["string", "null"]
        },
        "EventHeaderName": {
          "type": ["string", "null"]
        },
        "DeliveryIdHeaderName": {
          "type": ["string", "null"]
        }
      },
      "additionalProperties": false
    },
    "WebhookRoute": {
      "type": "object",
      "properties": {
        "Enabled": {
          "type": "boolean",
          "default": true
        },
        "Verification": {
          "$ref": "#/$defs/WebhookVerification"
        },
        "Events": {
          "type": "array",
          "items": { "type": "string" }
        },
        "Audience": {
          "type": "string",
          "enum": ["Public", "Team", "Personal"],
          "default": "Public"
        },
        "Prompt": {
          "type": "string",
          "default": ""
        },
        "NotifyInstructions": {
          "type": "string",
          "default": ""
        },
        "DeliveryRequired": {
          "type": "boolean",
          "default": true
        },
        "NotificationTarget": {
          "anyOf": [
            { "$ref": "#/$defs/NotificationTarget" },
            { "type": "null" }
          ],
          "default": null
        },
        "MaxBodyBytes": {
          "type": "integer",
          "minimum": 1,
          "default": 1048576
        },
        "RateLimitPerMinute": {
          "type": "integer",
          "minimum": 1,
          "default": 30
        }
      },
      "additionalProperties": false
    }
  }
}