subagent-cli 0.3.0 → 0.3.1

package/src/utils/settings/types.ts

@@ -1,1148 +0,0 @@
-import { feature } from 'src/_stubs/bun-bundle.js'
-import { z } from 'zod/v4'
-import { SandboxSettingsSchema } from '../../entrypoints/sandboxTypes.js'
-import { isEnvTruthy } from '../envUtils.js'
-import { lazySchema } from '../lazySchema.js'
-import {
-  EXTERNAL_PERMISSION_MODES,
-  PERMISSION_MODES,
-} from '../permissions/PermissionMode.js'
-import { MarketplaceSourceSchema } from '../plugins/schemas.js'
-import { CLAUDE_CODE_SETTINGS_SCHEMA_URL } from './constants.js'
-import { PermissionRuleSchema } from './permissionValidation.js'
-
-// Re-export hook schemas and types from centralized location for backward compatibility
-export {
-  type AgentHook,
-  type BashCommandHook,
-  type HookCommand,
-  HookCommandSchema,
-  type HookMatcher,
-  HookMatcherSchema,
-  HooksSchema,
-  type HooksSettings,
-  type HttpHook,
-  type PromptHook,
-} from '../../schemas/hooks.js'
-
-// Also import for use within this file
-import { type HookCommand, HooksSchema } from '../../schemas/hooks.js'
-import { count } from '../array.js'
-
-/**
- * Schema for environment variables
- */
-export const EnvironmentVariablesSchema = lazySchema(() =>
-  z.record(z.string(), z.coerce.string()),
-)
-
-/**
- * Schema for permissions section
- */
-export const PermissionsSchema = lazySchema(() =>
-  z
-    .object({
-      allow: z
-        .array(PermissionRuleSchema())
-        .optional()
-        .describe('List of permission rules for allowed operations'),
-      deny: z
-        .array(PermissionRuleSchema())
-        .optional()
-        .describe('List of permission rules for denied operations'),
-      ask: z
-        .array(PermissionRuleSchema())
-        .optional()
-        .describe(
-          'List of permission rules that should always prompt for confirmation',
-        ),
-      defaultMode: z
-        .enum(
-          feature('TRANSCRIPT_CLASSIFIER')
-            ? PERMISSION_MODES
-            : EXTERNAL_PERMISSION_MODES,
-        )
-        .optional()
-        .describe('Default permission mode when Claude Code needs access'),
-      disableBypassPermissionsMode: z
-        .enum(['disable'])
-        .optional()
-        .describe('Disable the ability to bypass permission prompts'),
-      ...(feature('TRANSCRIPT_CLASSIFIER')
-        ? {
-            disableAutoMode: z
-              .enum(['disable'])
-              .optional()
-              .describe('Disable auto mode'),
-          }
-        : {}),
-      additionalDirectories: z
-        .array(z.string())
-        .optional()
-        .describe('Additional directories to include in the permission scope'),
-    })
-    .passthrough(),
-)
-
-/**
- * Schema for extra marketplaces defined in repository settings
- * Same as KnownMarketplace but without lastUpdated (which is managed automatically)
- */
-export const ExtraKnownMarketplaceSchema = lazySchema(() =>
-  z.object({
-    source: MarketplaceSourceSchema().describe(
-      'Where to fetch the marketplace from',
-    ),
-    installLocation: z
-      .string()
-      .optional()
-      .describe(
-        'Local cache path where marketplace manifest is stored (auto-generated if not provided)',
-      ),
-    autoUpdate: z
-      .boolean()
-      .optional()
-      .describe(
-        'Whether to automatically update this marketplace and its installed plugins on startup',
-      ),
-  }),
-)
-
-/**
- * Schema for allowed MCP server entry in enterprise allowlist.
- * Supports matching by serverName, serverCommand, or serverUrl (mutually exclusive).
- */
-export const AllowedMcpServerEntrySchema = lazySchema(() =>
-  z
-    .object({
-      serverName: z
-        .string()
-        .regex(
-          /^[a-zA-Z0-9_-]+$/,
-          'Server name can only contain letters, numbers, hyphens, and underscores',
-        )
-        .optional()
-        .describe('Name of the MCP server that users are allowed to configure'),
-      serverCommand: z
-        .array(z.string())
-        .min(1, 'Server command must have at least one element (the command)')
-        .optional()
-        .describe(
-          'Command array [command, ...args] to match exactly for allowed stdio servers',
-        ),
-      serverUrl: z
-        .string()
-        .optional()
-        .describe(
-          'URL pattern with wildcard support (e.g., "https://*.example.com/*") for allowed remote MCP servers',
-        ),
-      // Future extensibility: allowedTransports, requiredArgs, maxInstances, etc.
-    })
-    .refine(
-      data => {
-        const defined = count(
-          [
-            data.serverName !== undefined,
-            data.serverCommand !== undefined,
-            data.serverUrl !== undefined,
-          ],
-          Boolean,
-        )
-        return defined === 1
-      },
-      {
-        message:
-          'Entry must have exactly one of "serverName", "serverCommand", or "serverUrl"',
-      },
-    ),
-)
-
-/**
- * Schema for denied MCP server entry in enterprise denylist.
- * Supports matching by serverName, serverCommand, or serverUrl (mutually exclusive).
- */
-export const DeniedMcpServerEntrySchema = lazySchema(() =>
-  z
-    .object({
-      serverName: z
-        .string()
-        .regex(
-          /^[a-zA-Z0-9_-]+$/,
-          'Server name can only contain letters, numbers, hyphens, and underscores',
-        )
-        .optional()
-        .describe('Name of the MCP server that is explicitly blocked'),
-      serverCommand: z
-        .array(z.string())
-        .min(1, 'Server command must have at least one element (the command)')
-        .optional()
-        .describe(
-          'Command array [command, ...args] to match exactly for blocked stdio servers',
-        ),
-      serverUrl: z
-        .string()
-        .optional()
-        .describe(
-          'URL pattern with wildcard support (e.g., "https://*.example.com/*") for blocked remote MCP servers',
-        ),
-      // Future extensibility: reason, blockedSince, etc.
-    })
-    .refine(
-      data => {
-        const defined = count(
-          [
-            data.serverName !== undefined,
-            data.serverCommand !== undefined,
-            data.serverUrl !== undefined,
-          ],
-          Boolean,
-        )
-        return defined === 1
-      },
-      {
-        message:
-          'Entry must have exactly one of "serverName", "serverCommand", or "serverUrl"',
-      },
-    ),
-)
-
-/**
- * Unified schema for settings files
- *
- * ⚠️ BACKWARD COMPATIBILITY NOTICE ⚠️
- *
- * This schema defines the structure of user settings files (.claude/settings.json).
- * We support backward-compatible changes! Here's how:
- *
- * ✅ ALLOWED CHANGES:
- * - Adding new optional fields (always use .optional())
- * - Adding new enum values (keeping existing ones)
- * - Adding new properties to objects
- * - Making validation more permissive
- * - Using union types for gradual migration (e.g., z.union([oldType, newType]))
- *
- * ❌ BREAKING CHANGES TO AVOID:
- * - Removing fields (mark as deprecated instead)
- * - Removing enum values
- * - Making optional fields required
- * - Making types more restrictive
- * - Renaming fields without keeping the old name
- *
- * TO ENSURE BACKWARD COMPATIBILITY:
- * 1. Run: npm run test:file -- test/utils/settings/backward-compatibility.test.ts
- * 2. If tests fail, you've introduced a breaking change
- * 3. When adding new fields, add a test to BACKWARD_COMPATIBILITY_CONFIGS
- *
- * The settings system handles backward compatibility automatically:
- * - When updating settings, invalid fields are preserved in the file (see settings.ts lines 233-249)
- * - Type coercion via z.coerce (e.g., env vars convert numbers to strings)
- * - .passthrough() preserves unknown fields in permissions object
- * - Invalid settings are simply not used, but remain in the file to be fixed by the user
- */
-
-/**
- * Surfaces lockable by `strictPluginOnlyCustomization`. Exported so the
- * schema preprocess (below) and the runtime helper (pluginOnlyPolicy.ts)
- * share one source of truth.
- */
-export const CUSTOMIZATION_SURFACES = [
-  'skills',
-  'agents',
-  'hooks',
-  'mcp',
-] as const
-
-export const SettingsSchema = lazySchema(() =>
-  z
-    .object({
-      $schema: z
-        .literal(CLAUDE_CODE_SETTINGS_SCHEMA_URL)
-        .optional()
-        .describe('JSON Schema reference for Claude Code settings'),
-      apiKeyHelper: z
-        .string()
-        .optional()
-        .describe('Path to a script that outputs authentication values'),
-      awsCredentialExport: z
-        .string()
-        .optional()
-        .describe('Path to a script that exports AWS credentials'),
-      awsAuthRefresh: z
-        .string()
-        .optional()
-        .describe('Path to a script that refreshes AWS authentication'),
-      gcpAuthRefresh: z
-        .string()
-        .optional()
-        .describe(
-          'Command to refresh GCP authentication (e.g., gcloud auth application-default login)',
-        ),
-      // Gated so the SDK generator (which runs without CLAUDE_CODE_ENABLE_XAA)
-      // doesn't surface this in GlobalClaudeSettings. Read via getXaaIdpSettings().
-      // .passthrough() on the outer object keeps an existing settings.json key
-      // alive across env-var-off sessions — it's just not schema-validated then.
-      ...(isEnvTruthy(process.env.CLAUDE_CODE_ENABLE_XAA)
-        ? {
-            xaaIdp: z
-              .object({
-                issuer: z
-                  .string()
-                  .url()
-                  .describe('IdP issuer URL for OIDC discovery'),
-                clientId: z
-                  .string()
-                  .describe("Claude Code's client_id registered at the IdP"),
-                callbackPort: z
-                  .number()
-                  .int()
-                  .positive()
-                  .optional()
-                  .describe(
-                    'Fixed loopback callback port for the IdP OIDC login. ' +
-                      'Only needed if the IdP does not honor RFC 8252 port-any matching.',
-                  ),
-              })
-              .optional()
-              .describe(
-                'XAA (SEP-990) IdP connection. Configure once; all XAA-enabled MCP servers reuse this.',
-              ),
-          }
-        : {}),
-      fileSuggestion: z
-        .object({
-          type: z.literal('command'),
-          command: z.string(),
-        })
-        .optional()
-        .describe('Custom file suggestion configuration for @ mentions'),
-      respectGitignore: z
-        .boolean()
-        .optional()
-        .describe(
-          'Whether file picker should respect .gitignore files (default: true). ' +
-            'Note: .ignore files are always respected.',
-        ),
-      cleanupPeriodDays: z
-        .number()
-        .nonnegative()
-        .int()
-        .optional()
-        .describe(
-          'Number of days to retain chat transcripts (default: 30). Setting to 0 disables session persistence entirely: no transcripts are written and existing transcripts are deleted at startup.',
-        ),
-      env: EnvironmentVariablesSchema()
-        .optional()
-        .describe('Environment variables to set for Claude Code sessions'),
-      // Attribution for commits and PRs
-      attribution: z
-        .object({
-          commit: z
-            .string()
-            .optional()
-            .describe(
-              'Attribution text for git commits, including any trailers. ' +
-                'Empty string hides attribution.',
-            ),
-          pr: z
-            .string()
-            .optional()
-            .describe(
-              'Attribution text for pull request descriptions. ' +
-                'Empty string hides attribution.',
-            ),
-        })
-        .optional()
-        .describe(
-          'Customize attribution text for commits and PRs. ' +
-            'Each field defaults to the standard Claude Code attribution if not set.',
-        ),
-      includeCoAuthoredBy: z
-        .boolean()
-        .optional()
-        .describe(
-          'Deprecated: Use attribution instead. ' +
-            "Whether to include Claude's co-authored by attribution in commits and PRs (defaults to true)",
-        ),
-      includeGitInstructions: z
-        .boolean()
-        .optional()
-        .describe(
-          "Include built-in commit and PR workflow instructions in Claude's system prompt (default: true)",
-        ),
-      permissions: PermissionsSchema()
-        .optional()
-        .describe('Tool usage permissions configuration'),
-      model: z
-        .string()
-        .optional()
-        .describe('Override the default model used by Claude Code'),
-      // Enterprise allowlist of models
-      availableModels: z
-        .array(z.string())
-        .optional()
-        .describe(
-          'Allowlist of models that users can select. ' +
-            'Accepts family aliases ("opus" allows any opus version), ' +
-            'version prefixes ("opus-4-5" allows only that version), ' +
-            'and full model IDs. ' +
-            'If undefined, all models are available. If empty array, only the default model is available. ' +
-            'Typically set in managed settings by enterprise administrators.',
-        ),
-      modelOverrides: z
-        .record(z.string(), z.string())
-        .optional()
-        .describe(
-          'Override mapping from Anthropic model ID (e.g. "claude-opus-4-6") to provider-specific ' +
-            'model ID (e.g. a Bedrock inference profile ARN). Typically set in managed settings by ' +
-            'enterprise administrators.',
-        ),
-      // Whether to automatically approve all MCP servers in the project
-      enableAllProjectMcpServers: z
-        .boolean()
-        .optional()
-        .describe(
-          'Whether to automatically approve all MCP servers in the project',
-        ),
-      // List of approved MCP servers from .mcp.json
-      enabledMcpjsonServers: z
-        .array(z.string())
-        .optional()
-        .describe('List of approved MCP servers from .mcp.json'),
-      // List of rejected MCP servers from .mcp.json
-      disabledMcpjsonServers: z
-        .array(z.string())
-        .optional()
-        .describe('List of rejected MCP servers from .mcp.json'),
-      // Enterprise allowlist of MCP servers
-      allowedMcpServers: z
-        .array(AllowedMcpServerEntrySchema())
-        .optional()
-        .describe(
-          'Enterprise allowlist of MCP servers that can be used. ' +
-            'Applies to all scopes including enterprise servers from managed-mcp.json. ' +
-            'If undefined, all servers are allowed. If empty array, no servers are allowed. ' +
-            'Denylist takes precedence - if a server is on both lists, it is denied.',
-        ),
-      // Enterprise denylist of MCP servers
-      deniedMcpServers: z
-        .array(DeniedMcpServerEntrySchema())
-        .optional()
-        .describe(
-          'Enterprise denylist of MCP servers that are explicitly blocked. ' +
-            'If a server is on the denylist, it will be blocked across all scopes including enterprise. ' +
-            'Denylist takes precedence over allowlist - if a server is on both lists, it is denied.',
-        ),
-      hooks: HooksSchema()
-        .optional()
-        .describe('Custom commands to run before/after tool executions'),
-      worktree: z
-        .object({
-          symlinkDirectories: z
-            .array(z.string())
-            .optional()
-            .describe(
-              'Directories to symlink from main repository to worktrees to avoid disk bloat. ' +
-                'Must be explicitly configured - no directories are symlinked by default. ' +
-                'Common examples: "node_modules", ".cache", ".bin"',
-            ),
-          sparsePaths: z
-            .array(z.string())
-            .optional()
-            .describe(
-              'Directories to include when creating worktrees, via git sparse-checkout (cone mode). ' +
-                'Dramatically faster in large monorepos — only the listed paths are written to disk.',
-            ),
-        })
-        .optional()
-        .describe('Git worktree configuration for --worktree flag.'),
-      // Whether to disable all hooks and statusLine
-      disableAllHooks: z
-        .boolean()
-        .optional()
-        .describe('Disable all hooks and statusLine execution'),
-      // Which shell backs input-box `!` (see docs/design/ps-shell-selection.md §4.2)
-      defaultShell: z
-        .enum(['bash', 'powershell'])
-        .optional()
-        .describe(
-          'Default shell for input-box ! commands. ' +
-            "Defaults to 'bash' on all platforms (no Windows auto-flip).",
-        ),
-      // Only run hooks defined in managed settings (managed-settings.json)
-      allowManagedHooksOnly: z
-        .boolean()
-        .optional()
-        .describe(
-          'When true (and set in managed settings), only hooks from managed settings run. ' +
-            'User, project, and local hooks are ignored.',
-        ),
-      // Allowlist of URL patterns HTTP hooks may target (follows allowedMcpServers precedent)
-      allowedHttpHookUrls: z
-        .array(z.string())
-        .optional()
-        .describe(
-          'Allowlist of URL patterns that HTTP hooks may target. ' +
-            'Supports * as a wildcard (e.g. "https://hooks.example.com/*"). ' +
-            'When set, HTTP hooks with non-matching URLs are blocked. ' +
-            'If undefined, all URLs are allowed. If empty array, no HTTP hooks are allowed. ' +
-            'Arrays merge across settings sources (same semantics as allowedMcpServers).',
-        ),
-      // Allowlist of env var names HTTP hooks may interpolate into headers
-      httpHookAllowedEnvVars: z
-        .array(z.string())
-        .optional()
-        .describe(
-          'Allowlist of environment variable names HTTP hooks may interpolate into headers. ' +
-            "When set, each hook's effective allowedEnvVars is the intersection with this list. " +
-            'If undefined, no restriction is applied. ' +
-            'Arrays merge across settings sources (same semantics as allowedMcpServers).',
-        ),
-      // Only use permission rules defined in managed settings (managed-settings.json)
-      allowManagedPermissionRulesOnly: z
-        .boolean()
-        .optional()
-        .describe(
-          'When true (and set in managed settings), only permission rules (allow/deny/ask) from managed settings are respected. ' +
-            'User, project, local, and CLI argument permission rules are ignored.',
-        ),
-      // Only read MCP allowlist policy from managed settings
-      allowManagedMcpServersOnly: z
-        .boolean()
-        .optional()
-        .describe(
-          'When true (and set in managed settings), allowedMcpServers is only read from managed settings. ' +
-            'deniedMcpServers still merges from all sources, so users can deny servers for themselves. ' +
-            'Users can still add their own MCP servers, but only the admin-defined allowlist applies.',
-        ),
-      // Force customizations through plugins only (LinkedIn ask via GTM)
-      strictPluginOnlyCustomization: z
-        .preprocess(
-          // Forwards-compat: drop unknown surface names so a future enum
-          // value (e.g. 'commands') doesn't fail safeParse and null out the
-          // ENTIRE managed-settings file (settings.ts:101). ["skills",
-          // "commands"] on an old client → ["skills"] → locks what it knows,
-          // ignores what it doesn't. Degrades to less-locked, never to
-          // everything-unlocked.
-          v =>
-            Array.isArray(v)
-              ? v.filter(x =>
-                  (CUSTOMIZATION_SURFACES as readonly string[]).includes(x),
-                )
-              : v,
-          z.union([z.boolean(), z.array(z.enum(CUSTOMIZATION_SURFACES))]),
-        )
-        .optional()
-        // Non-array invalid values ("skills" string, {object}) pass through
-        // the preprocess unchanged and would fail the union → null the whole
-        // managed-settings file. .catch drops the field to undefined instead.
-        // Degrades to unlocked-for-this-field, never to everything-broken.
-        // Doctor flags the raw value.
-        .catch(undefined)
-        .describe(
-          'When set in managed settings, blocks non-plugin customization sources for the listed surfaces. ' +
-            'Array form locks specific surfaces (e.g. ["skills", "hooks"]); `true` locks all four; `false` is an explicit no-op. ' +
-            'Blocked: ~/.claude/{surface}/, .claude/{surface}/ (project), settings.json hooks, .mcp.json. ' +
-            'NOT blocked: managed (policySettings) sources, plugin-provided customizations. ' +
-            'Composes with strictKnownMarketplaces for end-to-end admin control — plugins gated by ' +
-            'marketplace allowlist, everything else blocked here.',
-        ),
-      // Status line for custom status line display
-      statusLine: z
-        .object({
-          type: z.literal('command'),
-          command: z.string(),
-          padding: z.number().optional(),
-        })
-        .optional()
-        .describe('Custom status line display configuration'),
-      // Enabled plugins using marketplace-first format
-      enabledPlugins: z
-        .record(
-          z.string(),
-          z.union([z.array(z.string()), z.boolean(), z.undefined()]),
-        )
-        .optional()
-        .describe(
-          'Enabled plugins using plugin-id@marketplace-id format. Example: { "formatter@anthropic-tools": true }. Also supports extended format with version constraints.',
-        ),
-      // Extra marketplaces for this repository (usually for project settings)
-      extraKnownMarketplaces: z
-        .record(z.string(), ExtraKnownMarketplaceSchema())
-        .check(ctx => {
-          // For settings sources, key must equal source.name. diffMarketplaces
-          // looks up materialized state by dict key; addMarketplaceSource stores
-          // under marketplace.name (= source.name for settings). A mismatch means
-          // the reconciler never converges — every session: key-lookup misses →
-          // 'missing' → source-idempotency returns alreadyMaterialized but
-          // installed++ anyway → pointless cache clears. For github/git/url the
-          // name comes from a fetched marketplace.json (mismatch is expected and
-          // benign); for settings, both key and name are user-authored in the
-          // same JSON object.
-          for (const [key, entry] of Object.entries(ctx.value)) {
-            if (
-              entry.source.source === 'settings' &&
-              entry.source.name !== key
-            ) {
-              ctx.issues.push({
-                code: 'custom',
-                input: entry.source.name,
-                path: [key, 'source', 'name'],
-                message:
-                  `Settings-sourced marketplace name must match its extraKnownMarketplaces key ` +
-                  `(got key "${key}" but source.name "${entry.source.name}")`,
-              })
-            }
-          }
-        })
-        .optional()
-        .describe(
-          'Additional marketplaces to make available for this repository. Typically used in repository .claude/settings.json to ensure team members have required plugin sources.',
-        ),
-      // Enterprise strict list of allowed marketplace sources (policy settings only)
-      // When set, ONLY these exact sources can be added. Check happens BEFORE download.
-      strictKnownMarketplaces: z
-        .array(MarketplaceSourceSchema())
-        .optional()
-        .describe(
-          'Enterprise strict list of allowed marketplace sources. When set in managed settings, ' +
-            'ONLY these exact sources can be added as marketplaces. The check happens BEFORE ' +
-            'downloading, so blocked sources never touch the filesystem. ' +
-            'Note: this is a policy gate only — it does NOT register marketplaces. ' +
-            'To pre-register allowed marketplaces for users, also set extraKnownMarketplaces.',
-        ),
-      // Enterprise blocklist of marketplace sources (policy settings only)
-      // When set, these exact sources are blocked. Check happens BEFORE download.
-      blockedMarketplaces: z
-        .array(MarketplaceSourceSchema())
-        .optional()
-        .describe(
-          'Enterprise blocklist of marketplace sources. When set in managed settings, ' +
-            'these exact sources are blocked from being added as marketplaces. The check happens BEFORE ' +
-            'downloading, so blocked sources never touch the filesystem.',
-        ),
-      // Force a specific login method: 'claudeai' for Claude Pro/Max, 'console' for Console billing
-      forceLoginMethod: z
-        .enum(['claudeai', 'console'])
-        .optional()
-        .describe(
-          'Force a specific login method: "claudeai" for Claude Pro/Max, "console" for Console billing',
-        ),
-      // Organization UUID to use for OAuth login (will be added as URL param to authorization URL)
-      forceLoginOrgUUID: z
-        .string()
-        .optional()
-        .describe('Organization UUID to use for OAuth login'),
-      otelHeadersHelper: z
-        .string()
-        .optional()
-        .describe('Path to a script that outputs OpenTelemetry headers'),
-      outputStyle: z
-        .string()
-        .optional()
-        .describe('Controls the output style for assistant responses'),
-      language: z
-        .string()
-        .optional()
-        .describe(
-          'Preferred language for Claude responses and voice dictation (e.g., "japanese", "spanish")',
-        ),
-      skipWebFetchPreflight: z
-        .boolean()
-        .optional()
-        .describe(
-          'Skip the WebFetch blocklist check for enterprise environments with restrictive security policies',
-        ),
-      sandbox: SandboxSettingsSchema().optional(),
-      feedbackSurveyRate: z
-        .number()
-        .min(0)
-        .max(1)
-        .optional()
-        .describe(
-          'Probability (0–1) that the session quality survey appears when eligible. 0.05 is a reasonable starting point.',
-        ),
-      spinnerTipsEnabled: z
-        .boolean()
-        .optional()
-        .describe('Whether to show tips in the spinner'),
-      spinnerVerbs: z
-        .object({
-          mode: z.enum(['append', 'replace']),
-          verbs: z.array(z.string()),
-        })
-        .optional()
-        .describe(
-          'Customize spinner verbs. mode: "append" adds verbs to defaults, "replace" uses only your verbs.',
-        ),
-      spinnerTipsOverride: z
-        .object({
-          excludeDefault: z.boolean().optional(),
-          tips: z.array(z.string()),
-        })
-        .optional()
-        .describe(
-          'Override spinner tips. tips: array of tip strings. excludeDefault: if true, only show custom tips (default: false).',
-        ),
-      syntaxHighlightingDisabled: z
-        .boolean()
-        .optional()
-        .describe('Whether to disable syntax highlighting in diffs'),
-      terminalTitleFromRename: z
-        .boolean()
-        .optional()
-        .describe(
-          'Whether /rename updates the terminal tab title (defaults to true). Set to false to keep auto-generated topic titles.',
-        ),
-      alwaysThinkingEnabled: z
-        .boolean()
-        .optional()
-        .describe(
-          'When false, thinking is disabled. When absent or true, thinking is ' +
-            'enabled automatically for supported models.',
-        ),
-      effortLevel: z
-        .enum(
-          process.env.USER_TYPE === 'ant'
-            ? ['low', 'medium', 'high', 'max']
-            : ['low', 'medium', 'high'],
-        )
-        .optional()
-        .catch(undefined)
-        .describe('Persisted effort level for supported models.'),
-      advisorModel: z
-        .string()
-        .optional()
-        .describe('Advisor model for the server-side advisor tool.'),
-      fastMode: z
-        .boolean()
-        .optional()
-        .describe(
-          'When true, fast mode is enabled. When absent or false, fast mode is off.',
-        ),
-      fastModePerSessionOptIn: z
-        .boolean()
-        .optional()
-        .describe(
-          'When true, fast mode does not persist across sessions. Each session starts with fast mode off.',
-        ),
-      promptSuggestionEnabled: z
-        .boolean()
-        .optional()
-        .describe(
-          'When false, prompt suggestions are disabled. When absent or true, ' +
-            'prompt suggestions are enabled.',
-        ),
-      showClearContextOnPlanAccept: z
-        .boolean()
-        .optional()
-        .describe(
-          'When true, the plan-approval dialog offers a "clear context" option. Defaults to false.',
-        ),
-      agent: z
-        .string()
-        .optional()
-        .describe(
-          'Name of an agent (built-in or custom) to use for the main thread. ' +
-            "Applies the agent's system prompt, tool restrictions, and model.",
-        ),
-      companyAnnouncements: z
-        .array(z.string())
-        .optional()
-        .describe(
-          'Company announcements to display at startup (one will be randomly selected if multiple are provided)',
-        ),
-      pluginConfigs: z
-        .record(
-          z.string(),
-          z.object({
-            mcpServers: z
-              .record(
-                z.string(),
-                z.record(
-                  z.string(),
-                  z.union([
-                    z.string(),
-                    z.number(),
-                    z.boolean(),
-                    z.array(z.string()),
-                  ]),
-                ),
-              )
-              .optional()
-              .describe(
-                'User configuration values for MCP servers keyed by server name',
-              ),
-            options: z
-              .record(
-                z.string(),
-                z.union([
-                  z.string(),
-                  z.number(),
-                  z.boolean(),
-                  z.array(z.string()),
-                ]),
-              )
-              .optional()
-              .describe(
-                'Non-sensitive option values from plugin manifest userConfig, keyed by option name. Sensitive values go to secure storage instead.',
-              ),
-          }),
-        )
-        .optional()
-        .describe(
-          'Per-plugin configuration including MCP server user configs, keyed by plugin ID (plugin@marketplace format)',
-        ),
-      remote: z
-        .object({
-          defaultEnvironmentId: z
-            .string()
-            .optional()
-            .describe('Default environment ID to use for remote sessions'),
-        })
-        .optional()
-        .describe('Remote session configuration'),
-      autoUpdatesChannel: z
-        .enum(['latest', 'stable'])
-        .optional()
-        .describe('Release channel for auto-updates (latest or stable)'),
-      ...(feature('LODESTONE')
-        ? {
-            disableDeepLinkRegistration: z
-              .enum(['disable'])
-              .optional()
-              .describe(
-                'Prevent claude-cli:// protocol handler registration with the OS',
-              ),
-          }
-        : {}),
-      minimumVersion: z
-        .string()
-        .optional()
-        .describe(
-          'Minimum version to stay on - prevents downgrades when switching to stable channel',
-        ),
-      plansDirectory: z
-        .string()
-        .optional()
-        .describe(
-          'Custom directory for plan files, relative to project root. ' +
-            'If not set, defaults to ~/.claude/plans/',
-        ),
-      ...(process.env.USER_TYPE === 'ant'
-        ? {
-            classifierPermissionsEnabled: z
-              .boolean()
-              .optional()
-              .describe(
-                'Enable AI-based classification for Bash(prompt:...) permission rules',
-              ),
-          }
-        : {}),
-      ...(feature('PROACTIVE') || feature('KAIROS')
-        ? {
-            minSleepDurationMs: z
-              .number()
-              .nonnegative()
-              .int()
-              .optional()
-              .describe(
-                'Minimum duration in milliseconds that the Sleep tool must sleep for. ' +
-                  'Useful for throttling proactive tick frequency.',
-              ),
-            maxSleepDurationMs: z
-              .number()
-              .int()
-              .min(-1)
-              .optional()
-              .describe(
-                'Maximum duration in milliseconds that the Sleep tool can sleep for. ' +
-                  'Set to -1 for indefinite sleep (waits for user input). ' +
-                  'Useful for limiting idle time in remote/managed environments.',
-              ),
-          }
-        : {}),
-      ...(feature('VOICE_MODE')
-        ? {
-            voiceEnabled: z
-              .boolean()
-              .optional()
-              .describe('Enable voice mode (hold-to-talk dictation)'),
-          }
-        : {}),
-      ...(feature('KAIROS')
-        ? {
-            assistant: z
-              .boolean()
-              .optional()
-              .describe(
-                'Start Claude in assistant mode (custom system prompt, brief view, scheduled check-in skills)',
-              ),
-            assistantName: z
-              .string()
-              .optional()
-              .describe(
-                'Display name for the assistant, shown in the claude.ai session list',
-              ),
-          }
-        : {}),
-      // Teams/Enterprise opt-IN for channel notifications. Default OFF.
-      // MCP servers that declare the claude/channel capability can push
-      // inbound messages into the conversation; for managed orgs this only
-      // works when explicitly enabled. Which servers can connect at all is
-      // still governed by allowedMcpServers/deniedMcpServers. Not
-      // feature-spread: KAIROS_CHANNELS is external:true, and the spread
-      // wrecks type inference for allowedChannelPlugins (the .passthrough()
-      // catch-all gives {} instead of the array type).
-      channelsEnabled: z
-        .boolean()
-        .optional()
-        .describe(
-          'Teams/Enterprise opt-in for channel notifications (MCP servers with the ' +
-            'claude/channel capability pushing inbound messages). Default off. ' +
-            'Set true to allow; users then select servers via --channels.',
-        ),
-      // Org-level channel plugin allowlist. When set, REPLACES the
-      // Anthropic ledger — admin owns the trust decision. Undefined means
-      // fall back to the ledger. Plugin-only entry shape (same as the
-      // ledger); server-kind entries still need the dev flag.
-      allowedChannelPlugins: z
-        .array(
-          z.object({
-            marketplace: z.string(),
-            plugin: z.string(),
-          }),
-        )
-        .optional()
-        .describe(
-          'Teams/Enterprise allowlist of channel plugins. When set, ' +
-            'replaces the default Anthropic allowlist — admins decide which ' +
-            'plugins may push inbound messages. Undefined falls back to the default. ' +
-            'Requires channelsEnabled: true.',
-        ),
-      ...(feature('KAIROS') || feature('KAIROS_BRIEF')
-        ? {
-            defaultView: z
-              .enum(['chat', 'transcript'])
-              .optional()
-              .describe(
-                'Default transcript view: chat (SendUserMessage checkpoints only) or transcript (full)',
-              ),
-          }
-        : {}),
-      prefersReducedMotion: z
-        .boolean()
-        .optional()
-        .describe(
-          'Reduce or disable animations for accessibility (spinner shimmer, flash effects, etc.)',
-        ),
-      autoMemoryEnabled: z
-        .boolean()
-        .optional()
-        .describe(
-          'Enable auto-memory for this project. When false, Claude will not read from or write to the auto-memory directory.',
-        ),
-      autoMemoryDirectory: z
-        .string()
-        .optional()
-        .describe(
-          'Custom directory path for auto-memory storage. Supports ~/ prefix for home directory expansion. Ignored if set in projectSettings (checked-in .claude/settings.json) for security. When unset, defaults to ~/.claude/projects/<sanitized-cwd>/memory/.',
-        ),
-      autoDreamEnabled: z
-        .boolean()
-        .optional()
-        .describe(
-          'Enable background memory consolidation (auto-dream). When set, overrides the server-side default.',
-        ),
-      showThinkingSummaries: z
-        .boolean()
-        .optional()
-        .describe(
-          'Show thinking summaries in the transcript view (ctrl+o). Default: false.',
-        ),
-      skipDangerousModePermissionPrompt: z
-        .boolean()
-        .optional()
-        .describe(
-          'Whether the user has accepted the bypass permissions mode dialog',
-        ),
-      ...(feature('TRANSCRIPT_CLASSIFIER')
-        ? {
-            skipAutoPermissionPrompt: z
-              .boolean()
-              .optional()
-              .describe(
-                'Whether the user has accepted the auto mode opt-in dialog',
-              ),
-            useAutoModeDuringPlan: z
-              .boolean()
-              .optional()
-              .describe(
-                'Whether plan mode uses auto mode semantics when auto mode is available (default: true)',
-              ),
-            autoMode: z
-              .object({
-                allow: z
-                  .array(z.string())
-                  .optional()
-                  .describe('Rules for the auto mode classifier allow section'),
-                soft_deny: z
-                  .array(z.string())
-                  .optional()
-                  .describe('Rules for the auto mode classifier deny section'),
-                ...(process.env.USER_TYPE === 'ant'
-                  ? {
-                      // Back-compat alias for ant users; external users use soft_deny
-                      deny: z.array(z.string()).optional(),
-                    }
-                  : {}),
-                environment: z
-                  .array(z.string())
-                  .optional()
-                  .describe(
-                    'Entries for the auto mode classifier environment section',
-                  ),
-              })
-              .optional()
-              .describe('Auto mode classifier prompt customization'),
-          }
-        : {}),
-      disableAutoMode: z
-        .enum(['disable'])
-        .optional()
-        .describe('Disable auto mode'),
-      sshConfigs: z
-        .array(
-          z.object({
-            id: z
-              .string()
-              .describe(
-                'Unique identifier for this SSH config. Used to match configs across settings sources.',
-              ),
-            name: z.string().describe('Display name for the SSH connection'),
-            sshHost: z
-              .string()
-              .describe(
-                'SSH host in format "user@hostname" or "hostname", or a host alias from ~/.ssh/config',
-              ),
-            sshPort: z
-              .number()
-              .int()
-              .optional()
-              .describe('SSH port (default: 22)'),
-            sshIdentityFile: z
-              .string()
-              .optional()
-              .describe('Path to SSH identity file (private key)'),
-            startDirectory: z
-              .string()
-              .optional()
-              .describe(
-                'Default working directory on the remote host. ' +
-                  'Supports tilde expansion (e.g. ~/projects). ' +
-                  'If not specified, defaults to the remote user home directory. ' +
-                  'Can be overridden by the [dir] positional argument in `claude ssh <config> [dir]`.',
-              ),
-          }),
-        )
-        .optional()
-        .describe(
-          'SSH connection configurations for remote environments. ' +
-            'Typically set in managed settings by enterprise administrators ' +
-            'to pre-configure SSH connections for team members.',
-        ),
-      claudeMdExcludes: z
-        .array(z.string())
-        .optional()
-        .describe(
-          'Glob patterns or absolute paths of CLAUDE.md files to exclude from loading. ' +
-            'Patterns are matched against absolute file paths using picomatch. ' +
-            'Only applies to User, Project, and Local memory types (Managed/policy files cannot be excluded). ' +
-            'Examples: "/home/user/monorepo/CLAUDE.md", "**/code/CLAUDE.md", "**/some-dir/.claude/rules/**"',
-        ),
-      pluginTrustMessage: z
-        .string()
-        .optional()
-        .describe(
-          'Custom message to append to the plugin trust warning shown before installation. ' +
-            'Only read from policy settings (managed-settings.json / MDM). ' +
-            'Useful for enterprise administrators to add organization-specific context ' +
-            '(e.g., "All plugins from our internal marketplace are vetted and approved.").',
-        ),
-    })
-    .passthrough(),
-)
-
-/**
- * Internal type for plugin hooks - includes plugin context for execution.
- * Not a Zod schema since it's not user-facing (plugins provide native hooks).
- */
-export type PluginHookMatcher = {
-  matcher?: string
-  hooks: HookCommand[]
-  pluginRoot: string
-  pluginName: string
-  pluginId: string // format: "pluginName@marketplaceName"
-}
-
-/**
- * Internal type for skill hooks - includes skill context for execution.
- * Not a Zod schema since it's not user-facing (skills provide native hooks).
- */
-export type SkillHookMatcher = {
-  matcher?: string
-  hooks: HookCommand[]
-  skillRoot: string
-  skillName: string
-}
-
-export type AllowedMcpServerEntry = z.infer<
-  ReturnType<typeof AllowedMcpServerEntrySchema>
->
-export type DeniedMcpServerEntry = z.infer<
-  ReturnType<typeof DeniedMcpServerEntrySchema>
->
-export type SettingsJson = z.infer<ReturnType<typeof SettingsSchema>>
-
-/**
- * Type guard for MCP server entry with serverName
- */
-export function isMcpServerNameEntry(
-  entry: AllowedMcpServerEntry | DeniedMcpServerEntry,
-): entry is { serverName: string } {
-  return 'serverName' in entry && entry.serverName !== undefined
-}
-
-/**
- * Type guard for MCP server entry with serverCommand
- */
-export function isMcpServerCommandEntry(
-  entry: AllowedMcpServerEntry | DeniedMcpServerEntry,
-): entry is { serverCommand: string[] } {
-  return 'serverCommand' in entry && entry.serverCommand !== undefined
-}
-
-/**
- * Type guard for MCP server entry with serverUrl
- */
-export function isMcpServerUrlEntry(
-  entry: AllowedMcpServerEntry | DeniedMcpServerEntry,
-): entry is { serverUrl: string } {
-  return 'serverUrl' in entry && entry.serverUrl !== undefined
-}
-
-/**
- * User configuration values for MCPB MCP servers
- */
-export type UserConfigValues = Record<
-  string,
-  string | number | boolean | string[]
->
-
-/**
- * Plugin configuration stored in settings.json
- */
-export type PluginConfig = {
-  mcpServers?: {
-    [serverName: string]: UserConfigValues
-  }
-}