lcclaude 1.0.0

package/dist/src/utils/settings/types.js

@@ -0,0 +1,224 @@
+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";
+export {
+  HookCommandSchema,
+  HookMatcherSchema,
+  HooksSchema
+} from "../../schemas/hooks.js";
+import { HooksSchema } from "../../schemas/hooks.js";
+import { count } from "../array.js";
+export const EnvironmentVariablesSchema = lazySchema(() => z.record(z.string(), z.coerce.string()));
+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(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"),
+  ...{},
+  additionalDirectories: z.array(z.string()).optional().describe("Additional directories to include in the permission scope")
+}).passthrough());
+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")
+}));
+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')
+}).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"'
+}));
+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')
+}).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"'
+}));
+export const CUSTOMIZATION_SURFACES = [
+  "skills",
+  "agents",
+  "hooks",
+  "mcp"
+];
+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)"),
+  ...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: 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"),
+  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."),
+  enableAllProjectMcpServers: z.boolean().optional().describe("Whether to automatically approve all MCP servers in the project"),
+  enabledMcpjsonServers: z.array(z.string()).optional().describe("List of approved MCP servers from .mcp.json"),
+  disabledMcpjsonServers: z.array(z.string()).optional().describe("List of rejected MCP servers from .mcp.json"),
+  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."),
+  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."),
+  disableAllHooks: z.boolean().optional().describe("Disable all hooks and statusLine execution"),
+  defaultShell: z.enum(["bash", "powershell"]).optional().describe("Default shell for input-box ! commands. " + "Defaults to 'bash' on all platforms (no Windows auto-flip)."),
+  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."),
+  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)."),
+  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)."),
+  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."),
+  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."),
+  strictPluginOnlyCustomization: z.preprocess((v) => Array.isArray(v) ? v.filter((x) => CUSTOMIZATION_SURFACES.includes(x)) : v, z.union([z.boolean(), z.array(z.enum(CUSTOMIZATION_SURFACES))])).optional().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."),
+  statusLine: z.object({
+    type: z.literal("command"),
+    command: z.string(),
+    padding: z.number().optional()
+  }).optional().describe("Custom status line display configuration"),
+  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.'),
+  extraKnownMarketplaces: z.record(z.string(), ExtraKnownMarketplaceSchema()).check((ctx) => {
+    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."),
+  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."),
+  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."),
+  forceLoginMethod: z.enum(["claudeai", "console"]).optional().describe('Force a specific login method: "claudeai" for Claude Pro/Max, "console" for Console billing'),
+  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)"),
+  ...{},
+  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")
+  } : {},
+  ...{},
+  ...{},
+  ...{},
+  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."),
+  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."),
+  ...{},
+  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"),
+  ...{},
+  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());
+export function isMcpServerNameEntry(entry) {
+  return "serverName" in entry && entry.serverName !== undefined;
+}
+export function isMcpServerCommandEntry(entry) {
+  return "serverCommand" in entry && entry.serverCommand !== undefined;
+}
+export function isMcpServerUrlEntry(entry) {
+  return "serverUrl" in entry && entry.serverUrl !== undefined;
+}

package/dist/src/utils/settings/validateEditTool.js

@@ -0,0 +1,26 @@
+import { isClaudeSettingsPath } from "../permissions/filesystem.js";
+import { validateSettingsFileContent } from "./validation.js";
+export function validateInputForSettingsFileEdit(filePath, originalContent, getUpdatedContent) {
+  if (!isClaudeSettingsPath(filePath)) {
+    return null;
+  }
+  const beforeValidation = validateSettingsFileContent(originalContent);
+  if (!beforeValidation.isValid) {
+    return null;
+  }
+  const updatedContent = getUpdatedContent();
+  const afterValidation = validateSettingsFileContent(updatedContent);
+  if (!afterValidation.isValid) {
+    return {
+      result: false,
+      message: `Claude Code settings.json validation failed after edit:
+${afterValidation.error}
+
+Full schema:
+${afterValidation.fullSchema}
+IMPORTANT: Do not update the env unless explicitly instructed to do so.`,
+      errorCode: 10
+    };
+  }
+  return null;
+}

package/dist/src/utils/settings/validation.js

@@ -0,0 +1,160 @@
+import { jsonParse } from "../slowOperations.js";
+import { plural } from "../stringUtils.js";
+import { validatePermissionRule } from "./permissionValidation.js";
+import { generateSettingsJSONSchema } from "./schemaOutput.js";
+import { SettingsSchema } from "./types.js";
+import { getValidationTip } from "./validationTips.js";
+function isInvalidTypeIssue(issue) {
+  return issue.code === "invalid_type";
+}
+function isInvalidValueIssue(issue) {
+  return issue.code === "invalid_value";
+}
+function isUnrecognizedKeysIssue(issue) {
+  return issue.code === "unrecognized_keys";
+}
+function isTooSmallIssue(issue) {
+  return issue.code === "too_small";
+}
+function getReceivedType(value) {
+  if (value === null)
+    return "null";
+  if (value === undefined)
+    return "undefined";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+}
+function extractReceivedFromMessage(msg) {
+  const match = msg.match(/received (\w+)/);
+  return match ? match[1] : undefined;
+}
+export function formatZodError(error, filePath) {
+  return error.issues.map((issue) => {
+    const path = issue.path.map(String).join(".");
+    let message = issue.message;
+    let expected;
+    let enumValues;
+    let expectedValue;
+    let receivedValue;
+    let invalidValue;
+    if (isInvalidValueIssue(issue)) {
+      enumValues = issue.values.map((v) => String(v));
+      expectedValue = enumValues.join(" | ");
+      receivedValue = undefined;
+      invalidValue = undefined;
+    } else if (isInvalidTypeIssue(issue)) {
+      expectedValue = issue.expected;
+      const receivedType = extractReceivedFromMessage(issue.message);
+      receivedValue = receivedType ?? getReceivedType(issue.input);
+      invalidValue = receivedType ?? getReceivedType(issue.input);
+    } else if (isTooSmallIssue(issue)) {
+      expectedValue = String(issue.minimum);
+    } else if (issue.code === "custom" && "params" in issue) {
+      const params = issue.params;
+      receivedValue = params.received;
+      invalidValue = receivedValue;
+    }
+    const tip = getValidationTip({
+      path,
+      code: issue.code,
+      expected: expectedValue,
+      received: receivedValue,
+      enumValues,
+      message: issue.message,
+      value: receivedValue
+    });
+    if (isInvalidValueIssue(issue)) {
+      expected = enumValues?.map((v) => `"${v}"`).join(", ");
+      message = `Invalid value. Expected one of: ${expected}`;
+    } else if (isInvalidTypeIssue(issue)) {
+      const receivedType = extractReceivedFromMessage(issue.message) ?? getReceivedType(issue.input);
+      if (issue.expected === "object" && receivedType === "null" && path === "") {
+        message = "Invalid or malformed JSON";
+      } else {
+        message = `Expected ${issue.expected}, but received ${receivedType}`;
+      }
+    } else if (isUnrecognizedKeysIssue(issue)) {
+      const keys = issue.keys.join(", ");
+      message = `Unrecognized ${plural(issue.keys.length, "field")}: ${keys}`;
+    } else if (isTooSmallIssue(issue)) {
+      message = `Number must be greater than or equal to ${issue.minimum}`;
+      expected = String(issue.minimum);
+    }
+    return {
+      file: filePath,
+      path,
+      message,
+      expected,
+      invalidValue,
+      suggestion: tip?.suggestion,
+      docLink: tip?.docLink
+    };
+  });
+}
+export function validateSettingsFileContent(content) {
+  try {
+    const jsonData = jsonParse(content);
+    const result = SettingsSchema().strict().safeParse(jsonData);
+    if (result.success) {
+      return { isValid: true };
+    }
+    const errors = formatZodError(result.error, "settings");
+    const errorMessage = `Settings validation failed:
+` + errors.map((err) => `- ${err.path}: ${err.message}`).join(`
+`);
+    return {
+      isValid: false,
+      error: errorMessage,
+      fullSchema: generateSettingsJSONSchema()
+    };
+  } catch (parseError) {
+    return {
+      isValid: false,
+      error: `Invalid JSON: ${parseError instanceof Error ? parseError.message : "Unknown parsing error"}`,
+      fullSchema: generateSettingsJSONSchema()
+    };
+  }
+}
+export function filterInvalidPermissionRules(data, filePath) {
+  if (!data || typeof data !== "object")
+    return [];
+  const obj = data;
+  if (!obj.permissions || typeof obj.permissions !== "object")
+    return [];
+  const perms = obj.permissions;
+  const warnings = [];
+  for (const key of ["allow", "deny", "ask"]) {
+    const rules = perms[key];
+    if (!Array.isArray(rules))
+      continue;
+    perms[key] = rules.filter((rule) => {
+      if (typeof rule !== "string") {
+        warnings.push({
+          file: filePath,
+          path: `permissions.${key}`,
+          message: `Non-string value in ${key} array was removed`,
+          invalidValue: rule
+        });
+        return false;
+      }
+      const result = validatePermissionRule(rule);
+      if (!result.valid) {
+        let message = `Invalid permission rule "${rule}" was skipped`;
+        if (result.error)
+          message += `: ${result.error}`;
+        if (result.suggestion)
+          message += `. ${result.suggestion}`;
+        warnings.push({
+          file: filePath,
+          path: `permissions.${key}`,
+          message,
+          invalidValue: rule
+        });
+        return false;
+      }
+      return true;
+    });
+  }
+  return warnings;
+}

package/dist/src/utils/settings/validationTips.js

@@ -0,0 +1,94 @@
+const DOCUMENTATION_BASE = "https://code.claude.com/docs/en";
+const TIP_MATCHERS = [
+  {
+    matches: (ctx) => ctx.path === "permissions.defaultMode" && ctx.code === "invalid_value",
+    tip: {
+      suggestion: 'Valid modes: "acceptEdits" (ask before file changes), "plan" (analysis only), "bypassPermissions" (auto-accept all), or "default" (standard behavior)',
+      docLink: `${DOCUMENTATION_BASE}/iam#permission-modes`
+    }
+  },
+  {
+    matches: (ctx) => ctx.path === "apiKeyHelper" && ctx.code === "invalid_type",
+    tip: {
+      suggestion: 'Provide a shell command that outputs your API key to stdout. The script should output only the API key. Example: "/bin/generate_temp_api_key.sh"'
+    }
+  },
+  {
+    matches: (ctx) => ctx.path === "cleanupPeriodDays" && ctx.code === "too_small" && ctx.expected === "0",
+    tip: {
+      suggestion: "Must be 0 or greater. Set a positive number for days to retain transcripts (default is 30). Setting 0 disables session persistence entirely: no transcripts are written and existing transcripts are deleted at startup."
+    }
+  },
+  {
+    matches: (ctx) => ctx.path.startsWith("env.") && ctx.code === "invalid_type",
+    tip: {
+      suggestion: 'Environment variables must be strings. Wrap numbers and booleans in quotes. Example: "DEBUG": "true", "PORT": "3000"',
+      docLink: `${DOCUMENTATION_BASE}/settings#environment-variables`
+    }
+  },
+  {
+    matches: (ctx) => (ctx.path === "permissions.allow" || ctx.path === "permissions.deny") && ctx.code === "invalid_type" && ctx.expected === "array",
+    tip: {
+      suggestion: 'Permission rules must be in an array. Format: ["Tool(specifier)"]. Examples: ["Bash(npm run build)", "Edit(docs/**)", "Read(~/.zshrc)"]. Use * for wildcards.'
+    }
+  },
+  {
+    matches: (ctx) => ctx.path.includes("hooks") && ctx.code === "invalid_type",
+    tip: {
+      suggestion: 'Hooks use a matcher + hooks array. The matcher is a string: a tool name ("Bash"), pipe-separated list ("Edit|Write"), or empty to match all. Example: {"PostToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "echo Done"}]}]}'
+    }
+  },
+  {
+    matches: (ctx) => ctx.code === "invalid_type" && ctx.expected === "boolean",
+    tip: {
+      suggestion: 'Use true or false without quotes. Example: "includeCoAuthoredBy": true'
+    }
+  },
+  {
+    matches: (ctx) => ctx.code === "unrecognized_keys",
+    tip: {
+      suggestion: "Check for typos or refer to the documentation for valid fields",
+      docLink: `${DOCUMENTATION_BASE}/settings`
+    }
+  },
+  {
+    matches: (ctx) => ctx.code === "invalid_value" && ctx.enumValues !== undefined,
+    tip: {
+      suggestion: undefined
+    }
+  },
+  {
+    matches: (ctx) => ctx.code === "invalid_type" && ctx.expected === "object" && ctx.received === null && ctx.path === "",
+    tip: {
+      suggestion: "Check for missing commas, unmatched brackets, or trailing commas. Use a JSON validator to identify the exact syntax error."
+    }
+  },
+  {
+    matches: (ctx) => ctx.path === "permissions.additionalDirectories" && ctx.code === "invalid_type",
+    tip: {
+      suggestion: 'Must be an array of directory paths. Example: ["~/projects", "/tmp/workspace"]. You can also use --add-dir flag or /add-dir command',
+      docLink: `${DOCUMENTATION_BASE}/iam#working-directories`
+    }
+  }
+];
+const PATH_DOC_LINKS = {
+  permissions: `${DOCUMENTATION_BASE}/iam#configuring-permissions`,
+  env: `${DOCUMENTATION_BASE}/settings#environment-variables`,
+  hooks: `${DOCUMENTATION_BASE}/hooks`
+};
+export function getValidationTip(context) {
+  const matcher = TIP_MATCHERS.find((m) => m.matches(context));
+  if (!matcher)
+    return null;
+  const tip = { ...matcher.tip };
+  if (context.code === "invalid_value" && context.enumValues && !tip.suggestion) {
+    tip.suggestion = `Valid values: ${context.enumValues.map((v) => `"${v}"`).join(", ")}`;
+  }
+  if (!tip.docLink && context.path) {
+    const pathPrefix = context.path.split(".")[0];
+    if (pathPrefix) {
+      tip.docLink = PATH_DOC_LINKS[pathPrefix];
+    }
+  }
+  return tip;
+}

package/dist/src/utils/shell/bashProvider.js

@@ -0,0 +1,123 @@
+import { access } from "fs/promises";
+import { tmpdir as osTmpdir } from "os";
+import { join as nativeJoin } from "path";
+import { join as posixJoin } from "path/posix";
+import { rearrangePipeCommand } from "../bash/bashPipeCommand.js";
+import { createAndSaveSnapshot } from "../bash/ShellSnapshot.js";
+import { formatShellPrefixCommand } from "../bash/shellPrefix.js";
+import { quote } from "../bash/shellQuote.js";
+import {
+  quoteShellCommand,
+  rewriteWindowsNullRedirect,
+  shouldAddStdinRedirect
+} from "../bash/shellQuoting.js";
+import { logForDebugging } from "../debug.js";
+import { getPlatform } from "../platform.js";
+import { getSessionEnvironmentScript } from "../sessionEnvironment.js";
+import { getSessionEnvVars } from "../sessionEnvVars.js";
+import {
+  ensureSocketInitialized,
+  getClaudeTmuxEnv,
+  hasTmuxToolBeenUsed
+} from "../tmuxSocket.js";
+import { windowsPathToPosixPath } from "../windowsPaths.js";
+function getDisableExtglobCommand(shellPath) {
+  if (process.env.CLAUDE_CODE_SHELL_PREFIX) {
+    return "{ shopt -u extglob || setopt NO_EXTENDED_GLOB; } >/dev/null 2>&1 || true";
+  }
+  if (shellPath.includes("bash")) {
+    return "shopt -u extglob 2>/dev/null || true";
+  } else if (shellPath.includes("zsh")) {
+    return "setopt NO_EXTENDED_GLOB 2>/dev/null || true";
+  }
+  return null;
+}
+export async function createBashShellProvider(shellPath, options) {
+  let currentSandboxTmpDir;
+  const snapshotPromise = options?.skipSnapshot ? Promise.resolve(undefined) : createAndSaveSnapshot(shellPath).catch((error) => {
+    logForDebugging(`Failed to create shell snapshot: ${error}`);
+    return;
+  });
+  let lastSnapshotFilePath;
+  return {
+    type: "bash",
+    shellPath,
+    detached: true,
+    async buildExecCommand(command, opts) {
+      let snapshotFilePath = await snapshotPromise;
+      if (snapshotFilePath) {
+        try {
+          await access(snapshotFilePath);
+        } catch {
+          logForDebugging(`Snapshot file missing, falling back to login shell: ${snapshotFilePath}`);
+          snapshotFilePath = undefined;
+        }
+      }
+      lastSnapshotFilePath = snapshotFilePath;
+      currentSandboxTmpDir = opts.sandboxTmpDir;
+      const tmpdir = osTmpdir();
+      const isWindows = getPlatform() === "windows";
+      const shellTmpdir = isWindows ? windowsPathToPosixPath(tmpdir) : tmpdir;
+      const shellCwdFilePath = opts.useSandbox ? posixJoin(opts.sandboxTmpDir, `cwd-${opts.id}`) : posixJoin(shellTmpdir, `claude-${opts.id}-cwd`);
+      const cwdFilePath = opts.useSandbox ? posixJoin(opts.sandboxTmpDir, `cwd-${opts.id}`) : nativeJoin(tmpdir, `claude-${opts.id}-cwd`);
+      const normalizedCommand = rewriteWindowsNullRedirect(command);
+      const addStdinRedirect = shouldAddStdinRedirect(normalizedCommand);
+      let quotedCommand = quoteShellCommand(normalizedCommand, addStdinRedirect);
+      if (false) {}
+      if (normalizedCommand.includes("|") && addStdinRedirect) {
+        quotedCommand = rearrangePipeCommand(normalizedCommand);
+      }
+      const commandParts = [];
+      if (snapshotFilePath) {
+        const finalPath = getPlatform() === "windows" ? windowsPathToPosixPath(snapshotFilePath) : snapshotFilePath;
+        commandParts.push(`source ${quote([finalPath])} 2>/dev/null || true`);
+      }
+      const sessionEnvScript = await getSessionEnvironmentScript();
+      if (sessionEnvScript) {
+        commandParts.push(sessionEnvScript);
+      }
+      const disableExtglobCmd = getDisableExtglobCommand(shellPath);
+      if (disableExtglobCmd) {
+        commandParts.push(disableExtglobCmd);
+      }
+      commandParts.push(`eval ${quotedCommand}`);
+      commandParts.push(`pwd -P >| ${quote([shellCwdFilePath])}`);
+      let commandString = commandParts.join(" && ");
+      if (process.env.CLAUDE_CODE_SHELL_PREFIX) {
+        commandString = formatShellPrefixCommand(process.env.CLAUDE_CODE_SHELL_PREFIX, commandString);
+      }
+      return { commandString, cwdFilePath };
+    },
+    getSpawnArgs(commandString) {
+      const skipLoginShell = lastSnapshotFilePath !== undefined;
+      if (skipLoginShell) {
+        logForDebugging("Spawning shell without login (-l flag skipped)");
+      }
+      return ["-c", ...skipLoginShell ? [] : ["-l"], commandString];
+    },
+    async getEnvironmentOverrides(command) {
+      const commandUsesTmux = command.includes("tmux");
+      if (process.env.USER_TYPE === "ant" && (hasTmuxToolBeenUsed() || commandUsesTmux)) {
+        await ensureSocketInitialized();
+      }
+      const claudeTmuxEnv = getClaudeTmuxEnv();
+      const env = {};
+      if (claudeTmuxEnv) {
+        env.TMUX = claudeTmuxEnv;
+      }
+      if (currentSandboxTmpDir) {
+        let posixTmpDir = currentSandboxTmpDir;
+        if (getPlatform() === "windows") {
+          posixTmpDir = windowsPathToPosixPath(posixTmpDir);
+        }
+        env.TMPDIR = posixTmpDir;
+        env.CLAUDE_CODE_TMPDIR = posixTmpDir;
+        env.TMPPREFIX = posixJoin(posixTmpDir, "zsh");
+      }
+      for (const [key, value] of getSessionEnvVars()) {
+        env[key] = value;
+      }
+      return env;
+    }
+  };
+}

package/dist/src/utils/shell/outputLimits.js

@@ -0,0 +1,7 @@
+import { validateBoundedIntEnvVar } from "../envValidation.js";
+export const BASH_MAX_OUTPUT_UPPER_LIMIT = 150000;
+export const BASH_MAX_OUTPUT_DEFAULT = 30000;
+export function getMaxOutputLength() {
+  const result = validateBoundedIntEnvVar("BASH_MAX_OUTPUT_LENGTH", process.env.BASH_MAX_OUTPUT_LENGTH, BASH_MAX_OUTPUT_DEFAULT, BASH_MAX_OUTPUT_UPPER_LIMIT);
+  return result.effective;
+}