deepseek-web-retrieval 0.6.0 → 0.8.0

package/src/installer/cli.ts

@@ -1,10 +1,14 @@
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { userConfigHome } from "../core/config-file";
+import type { Env } from "../core/env";
 import { TOOL_VERSION } from "../version";
 import { ApplyError, applyPlan } from "./apply";
+import { runConfigCommand } from "./config-command";
 import { HOST_PLANNERS, HOST_VERSION_PROBES, planForHost } from "./hosts";
+import { pinPackageRef } from "./ownership";
 import { renderPlan } from "./render";
-import { listRecords } from "./state";
+import { legacyGlobalStateDir, listRecords, readingLegacyGlobalRecords } from "./state";
 import type { HostName, InstallerInput, Scope, Tier } from "./types";
 import { uninstall } from "./uninstall";
 
@@ -20,9 +24,10 @@ const EXIT_RECOVERY = 3;
 const USAGE = `Usage:
   deepseek-web-retrieval init --host ${HOST_CHOICES} --scope <project|global> \
 --search <optional|preferred|forced|off> --fetch <optional|preferred|forced|off> \
-[--path <extension|mcp>] [--package <npm ref>] [--cwd <dir>] [--apply]
+[--path <extension|mcp>] [--package <npm ref>] [--pin] [--cwd <dir>] [--apply]
   deepseek-web-retrieval uninstall --host ${HOST_CHOICES} --scope <project|global> [--cwd <dir>]
   deepseek-web-retrieval list [--cwd <dir>]
+  deepseek-web-retrieval config [--search <query>]
   deepseek-web-retrieval version
 
 init prints the full plan (every file, old value → new value) and writes nothing
@@ -31,7 +36,17 @@ the integration mechanism for hosts with more than one (Pi: extension by
 default, mcp for the stdio MCP server). --package overrides the package ref
 written into host config; the Pi extension path turns it into the packages
 source (a bare name is prefixed with npm:, a ref that already starts with npm:
-is written as-is).
+is written as-is). --pin appends the running CLI's version to the package ref
+(a ref already ending in a version keeps it), so hosts resolve that exact
+release instead of the latest publish; re-run init --pin to move the pin.
+
+config prints the effective configuration — every knob with its value and its
+source (default, shared file, or environment), resolved the way the MCP server
+resolves it — and exits 1 when the config file or the DEEPSEEK_* environment
+has problems (unknown or rejected keys, unparseable JSON, set-but-unusable
+variable values; a missing file is fine). config --search <query>
+runs one billed search through that configuration to verify the key, config,
+and network end to end; it exits 1 when the key is missing or the search fails.
 
 Exit codes: 0 success; 1 refused or failed with nothing written (a failed apply
 is fully rolled back); 2 invalid command line; 3 recovery required — a failed
@@ -45,7 +60,7 @@ interface Flags {
 }
 
 const VALUE_FLAGS = new Set(["host", "scope", "search", "fetch", "path", "package", "cwd"]);
-const BOOLEAN_FLAGS = new Set(["apply"]);
+const BOOLEAN_FLAGS = new Set(["apply", "pin"]);
 const PATH_CHOICES: readonly ["extension", "mcp"] = ["extension", "mcp"];
 
 function parseFlags(args: readonly string[]): Flags {
@@ -99,6 +114,8 @@ function parseFlags(args: readonly string[]): Flags {
 export interface CliIo {
   readonly out?: (line: string) => void;
   readonly err?: (line: string) => void;
+  /** Platform the CLI resolves paths for; tests pin "win32" on any host. */
+  readonly platform?: NodeJS.Platform;
 }
 
 /** CLI entry for the init/uninstall/list subcommands; returns the process exit code. */
@@ -126,12 +143,14 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
   }
   const cwd = resolve(flags.values.get("cwd") ?? process.cwd());
   const home = process.env.HOME ?? homedir();
-  const configHome = resolveConfigHome(home);
+  const platform = io.platform ?? process.platform;
+  const roots = { home, cwd, platform } as const;
+  const configHome = resolveConfigHome(process.env, home, platform);
 
   if (command === "list") {
     let records: ReturnType<typeof listRecords>;
     try {
-      records = listRecords({ home, cwd, configHome });
+      records = listRecords({ ...roots, configHome });
     } catch (error) {
       err(error instanceof Error ? error.message : String(error));
       return 1;
@@ -140,6 +159,12 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
       out("No installs recorded.");
       return 0;
     }
+    if (readingLegacyGlobalRecords({ ...roots, configHome })) {
+      out(
+        `Global install records are being read from the legacy ${legacyGlobalStateDir(roots)} ` +
+          "(written before the Windows config home moved to %APPDATA%).",
+      );
+    }
     for (const record of records) {
       const by = record.installerVersion ? ` by v${record.installerVersion}` : "";
       out(
@@ -150,8 +175,12 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
     return 0;
   }
 
+  if (command === "config") {
+    return runConfigCommand(flags.values.get("search"), { out, err });
+  }
+
   if (command === "uninstall") {
-    const required = requireInput(flags, cwd, home, configHome, false);
+    const required = requireInput(flags, cwd, home, configHome, platform, false);
     if (!required.ok) return usageError(required.problems, err);
     try {
       for (const line of uninstall(required.input)) out(line);
@@ -167,7 +196,7 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
     return EXIT_USAGE;
   }
 
-  const required = requireInput(flags, cwd, home, configHome, true);
+  const required = requireInput(flags, cwd, home, configHome, platform, true);
   if (!required.ok) return usageError(required.problems, err);
   const { input } = required;
   const probe = HOST_VERSION_PROBES[input.host];
@@ -205,13 +234,15 @@ function usageError(problems: readonly string[], err: (line: string) => void): n
 }
 
 /**
- * XDG_CONFIG_HOME is honored only when it belongs to the real home; the one
- * environment read happens here, at the edge, and flows down as explicit input.
+ * The installer edge's one config-home resolution, built on the canonical
+ * helper (userConfigHome): an inherited XDG_CONFIG_HOME is honored only when it
+ * belongs to the real home — a rewritten HOME must not smuggle in someone
+ * else's config root — and every other case takes the helper's platform
+ * default (win32: %APPDATA% or `<home>\AppData\Roaming`; otherwise ~/.config).
  */
-function resolveConfigHome(home: string): string | undefined {
-  const xdg = process.env.XDG_CONFIG_HOME;
-  if (xdg && home === (process.env.HOME ?? "")) return xdg;
-  return undefined;
+export function resolveConfigHome(env: Env, home: string, platform: NodeJS.Platform = process.platform): string {
+  const xdgTrusted = env.XDG_CONFIG_HOME !== undefined && env.XDG_CONFIG_HOME !== "" && home === (env.HOME ?? "");
+  return userConfigHome({ env: xdgTrusted ? env : { ...env, XDG_CONFIG_HOME: undefined }, home, platform });
 }
 
 type RequireInputResult =
@@ -222,7 +253,8 @@ function requireInput(
   flags: Flags,
   cwd: string,
   home: string,
-  configHome: string | undefined,
+  configHome: string,
+  platform: NodeJS.Platform,
   needsTiers: boolean,
 ): RequireInputResult {
   const problems: string[] = [];
@@ -262,6 +294,7 @@ function requireInput(
   }
   if (home === "") problems.push("HOME is not set and the user home cannot be resolved; cannot proceed");
   if (problems.length > 0) return { ok: false, problems };
+  const packageRef = flags.values.get("package") ?? "deepseek-web-retrieval";
   return {
     ok: true,
     input: {
@@ -269,10 +302,11 @@ function requireInput(
       scope: scope as Scope,
       search: search as Tier,
       fetch: fetch as Tier,
-      packageRef: flags.values.get("package") ?? "deepseek-web-retrieval",
+      packageRef: flags.booleans.has("pin") ? pinPackageRef(packageRef, TOOL_VERSION) : packageRef,
       home,
       cwd,
       configHome,
+      platform,
       ...(path !== undefined ? { path: path as "extension" | "mcp" } : {}),
     },
   };

package/src/installer/config-command.ts

@@ -0,0 +1,116 @@
+import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } from "../core/auth";
+import { createRetrievalClient, type RetrievalClient } from "../core/client";
+import { configFilePath, readFileOptionsReport } from "../core/config-file";
+import { configSummaryValues, formatConfigValue } from "../core/config-summary";
+import type { Env } from "../core/env";
+import { envOptionsReport, resolveEnvOptions } from "../core/env";
+import { formatSearchResults } from "../core/format";
+
+const EXIT_CONFIG_PROBLEMS = 1;
+const EXIT_USAGE = 2;
+
+const HOST_OVERRIDE_NOTE =
+  "Host-native layers (OpenCode options, Pi settings) may override file and env values per host.";
+
+/** Where the config command writes; the installer CLI resolves its CliIo into this. */
+export interface ConfigCommandIo {
+  readonly out: (line: string) => void;
+  readonly err: (line: string) => void;
+}
+
+/** Injectable seams: the environment to resolve, and the client for --search. */
+export interface ConfigCommandDeps {
+  readonly env?: Env;
+  readonly client?: RetrievalClient;
+}
+
+/**
+ * The `config` subcommand: the user-facing arm of configuration visibility.
+ * Prints the effective options exactly as the MCP server would resolve them
+ * (defaults < shared file < environment), each knob with its value and source,
+ * and replays the problems that would only whisper past on stderr at runtime —
+ * shared-file problems and set-but-unusable `DEEPSEEK_*` variables alike. With
+ * `query` set, runs one real billed search through that config — the
+ * end-to-end verifier for key, config, and network. Returns the exit code: 0
+ * normally, 1 for file or environment problems (plain form) or a failed
+ * search, 2 for a blank --search query. A missing file is not a problem.
+ */
+export async function runConfigCommand(
+  query: string | undefined,
+  io: ConfigCommandIo,
+  deps: ConfigCommandDeps = {},
+): Promise<number> {
+  if (query !== undefined && !query.trim()) {
+    io.err('error: --search requires a query (for example: config --search "deepseek mcp")');
+    return EXIT_USAGE;
+  }
+
+  const env = deps.env ?? process.env;
+  const file = configFilePath({ env });
+  const report = readFileOptionsReport(file);
+  for (const warning of report.warnings) io.err(`warning: ${warning}`);
+  const envReport = envOptionsReport(env);
+  for (const warning of envReport.warnings) io.err(`warning: ${warning}`);
+
+  // The same layers, in the same order, as the MCP server's startup resolution.
+  const resolved = resolveEnvOptions(env, report.options);
+
+  if (query === undefined) {
+    printConfigReport(file, report.exists, report.options, envReport.options, resolved, io);
+    return report.warnings.length > 0 || envReport.warnings.length > 0 ? EXIT_CONFIG_PROBLEMS : 0;
+  }
+
+  const apiKey = apiKeyFromEnv(env);
+  if (!apiKey) {
+    io.err(MISSING_API_KEY_MESSAGE);
+    return EXIT_CONFIG_PROBLEMS;
+  }
+  const client = deps.client ?? createRetrievalClient();
+  const startedAt = Date.now();
+  try {
+    const results = await client.searchWeb(query, resolved.search, {
+      signal: new AbortController().signal,
+      auth: { apiKey },
+      retry: resolved.retry,
+    });
+    const elapsedMs = Date.now() - startedAt;
+    io.out(
+      `search "${query.trim()}" — ${results.length} ${results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`,
+    );
+    io.out("");
+    for (const line of formatSearchResults(results).split("\n")) io.out(line);
+    return 0;
+  } catch (error) {
+    io.err(error instanceof Error ? error.message : String(error));
+    return EXIT_CONFIG_PROBLEMS;
+  }
+}
+
+/** The knob table, in the vocabulary order the startup deviation summary uses. */
+function printConfigReport(
+  file: string,
+  exists: boolean,
+  fileOptions: Readonly<Record<string, unknown>>,
+  envOptions: Readonly<Record<string, unknown>>,
+  resolved: ReturnType<typeof resolveEnvOptions>,
+  io: ConfigCommandIo,
+): void {
+  io.out(`Config file: ${file} (${exists ? "exists" : "missing"})`);
+  io.out("");
+  const effective = configSummaryValues(resolved);
+  const fileKeys = new Set(Object.keys(fileOptions));
+  const envKeys = new Set(Object.keys(envOptions));
+  for (const name of Object.keys(effective)) {
+    // The environment wins over the file for the same key, exactly as resolution does.
+    let source = envKeys.has(name) ? "env" : fileKeys.has(name) ? "file" : "default";
+    // maxResults follows the effective count when unset (options.ts), so when
+    // the count knob was configured its derived value is not "default" — its
+    // source is the count setting that drove it.
+    if (name === "maxResults" && source === "default" && (envKeys.has("count") || fileKeys.has("count"))) {
+      source = "count";
+    }
+    io.out(`${name} = ${formatConfigValue(effective[name], "join")} (${source})`);
+  }
+  io.out("");
+  io.out(HOST_OVERRIDE_NOTE);
+}

package/src/installer/hosts/claude-code.ts

@@ -0,0 +1,325 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { API_KEY_ENV } from "../../core/constants";
+import { FORCED_COST_NOTE, othersStayRegisteredNote, replacingExistingEntryNote, splitCompetitors } from "../detect";
+import { codecFor, type LoadedConfig } from "../formats";
+import { buildRulesBlock } from "../formats/rules";
+import { isPlainObject } from "../formats/value";
+import { join } from "../paths";
+import { MCP_TOOL_IDS, rulesLines } from "../rulesContent";
+import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord } from "../types";
+import { planHeader } from "./shared";
+
+/**
+ * The Claude Code release this installer's facts are verified against — the lock in
+ * docs/hosts.jsonc; the drift note fires when the probed CLI differs.
+ */
+export const CLAUDE_CODE_TESTED_VERSION = "2.1.303";
+
+/** The built-in web tools the forced tier denies; bare names remove them from context. */
+const BUILTIN_TOOL_IDS = { search: "WebSearch", fetch: "WebFetch" } as const;
+
+/** Human name for a wrong-typed config value in plan errors ("an array", "a string"). */
+function valueKind(value: unknown): string {
+  return Array.isArray(value) ? "an array" : `a ${typeof value}`;
+}
+
+/**
+ * The one subprocess the installer runs: `claude --version`, probed for the
+ * version-drift note. A missing binary or unreadable output skips the check with
+ * a stderr note and never blocks the plan — honor or report.
+ */
+export function probeClaudeCodeVersion(err: (line: string) => void): string | undefined {
+  // env passed explicitly: runtime PATH edits (tests) must reach the lookup.
+  // shell: npm's global install on Windows provides only a claude.cmd shim,
+  // which spawnSync cannot launch without a shell; the command and args are
+  // hardcoded, so the shell hop is safe.
+  const result = spawnSync("claude", ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
+  const version = result.status === 0 ? parseClaudeCodeVersion(result.stdout ?? "") : undefined;
+  if (version === undefined) {
+    err("note: claude was not found on PATH or printed no version; the version-drift check was skipped");
+  }
+  return version;
+}
+
+/**
+ * Parses `claude --version` output (`2.1.303 (Claude Code)`) into the bare version.
+ * The last semver wins: an update banner advertising a newer release must not
+ * anchor the drift note on the wrong number.
+ */
+export function parseClaudeCodeVersion(output: string): string | undefined {
+  return [...output.matchAll(/\b\d+\.\d+\.\d+\b/g)].map((match) => match[0]).at(-1);
+}
+
+/**
+ * Claude Code config, settings, and rules files per scope; the host module owns
+ * this mapping. MCP registration and the settings file are disjoint per scope
+ * (project: `.mcp.json` + `.claude/settings.json`; global: `~/.claude.json` +
+ * `~/.claude/settings.json`), so the two scopes can coexist unlike Codex's.
+ */
+function claudeCodePaths(input: InstallerInput): HostPaths & { readonly settings: string } {
+  return input.scope === "global"
+    ? {
+        config: join(input.home, ".claude.json"),
+        settings: join(input.home, ".claude", "settings.json"),
+        rules: join(input.home, ".claude", "CLAUDE.md"),
+      }
+    : {
+        config: join(input.cwd, ".mcp.json"),
+        settings: join(input.cwd, ".claude", "settings.json"),
+        rules: join(input.cwd, "CLAUDE.md"),
+      };
+}
+
+/**
+ * The managed-policy layer, the one settings layer above the user. Its existence
+ * (never its contents) is reported: deny and allow rules there outrank anything
+ * this plan writes at either scope.
+ */
+function managedSettingsPath(input: InstallerInput): string {
+  const platform = input.platform ?? process.platform;
+  if (platform === "darwin") return "/Library/Application Support/ClaudeCode/managed-settings.json";
+  if (platform === "win32") return "C:\\Program Files\\ClaudeCode\\managed-settings.json";
+  return "/etc/claude-code/managed-settings.json";
+}
+
+export function planClaudeCode(input: InstallerInput, _previous: InstallRecord | undefined): InstallPlan {
+  const paths = claudeCodePaths(input);
+  const loaded = codecFor("json", input.host).load(paths.config);
+  const tiers = { search: input.search, fetch: input.fetch };
+  const header = planHeader(input, paths, loaded, "JSON");
+  if (header.abort) {
+    return { host: "claude-code", scope: input.scope, tiers, edits: [], notes: header.notes, errors: header.errors };
+  }
+  const notes = [...header.notes];
+  const errors = [...header.errors];
+  const edits: FileEdit[] = [];
+
+  if (input.hostVersion !== undefined && input.hostVersion !== CLAUDE_CODE_TESTED_VERSION) {
+    notes.push(
+      `Claude Code ${input.hostVersion} is installed, but this installer's Claude Code facts are verified against ` +
+        `${CLAUDE_CODE_TESTED_VERSION} (the docs/hosts.jsonc lock). Deny-rule and tool-visibility behavior may have ` +
+        "drifted between the two — re-verify the tiers if routing misbehaves.",
+    );
+  }
+  const managed = managedSettingsPath(input);
+  if (existsSync(managed)) {
+    notes.push(
+      `${managed} exists: the managed policy layer outranks every settings file this plan writes, so a deny or allow ` +
+        "there overrides these changes. Check with your administrator if routing does not take effect.",
+    );
+  }
+
+  // The server registration. `${VAR}` expansion is Claude Code's own mechanism, so
+  // the key expands from the environment that launches Claude Code and never sits
+  // in the file.
+  const servers = loaded.value.mcpServers;
+  if (servers !== undefined && !isPlainObject(servers)) {
+    errors.push({
+      message: `${paths.config}: mcpServers is ${valueKind(servers)}, not an object; fix it before installing.`,
+    });
+  }
+  const existingEntry = isPlainObject(servers) ? servers.deepseek : undefined;
+  const entry = {
+    command: "npx",
+    args: ["-y", input.packageRef],
+    env: { [API_KEY_ENV]: `\${${API_KEY_ENV}}` },
+  };
+  const ops: ConfigOp[] = [{ op: "set", path: ["mcpServers", "deepseek"], value: entry, previous: existingEntry }];
+  edits.push({
+    file: paths.config,
+    format: "json",
+    // Global-scope files live outside the install record's config home, so they
+    // need the owner sidecar that stops a second install (another project or
+    // XDG_CONFIG_HOME) from claiming them — the codex topology.
+    ...(input.scope === "global" ? { shared: true as const } : {}),
+    ops,
+  });
+
+  if (isPlainObject(servers)) {
+    if ("deepseek" in servers) notes.push(replacingExistingEntryNote("mcpServers.deepseek"));
+  }
+  notes.push(
+    `\`${API_KEY_ENV}\` is written as "\${${API_KEY_ENV}}" in the server's env block, so the key expands from the ` +
+      "environment that launches Claude Code and stays out of the file.",
+  );
+  if (input.scope === "project") {
+    notes.push(
+      "Claude Code asks once per project whether to use servers from .mcp.json; approve the deepseek server when " +
+        "prompted (or via the /mcp menu), or its tools will not load in that project.",
+    );
+  } else {
+    notes.push(
+      `User-scope servers live in the mcpServers key of ${paths.config} — Claude Code's own user-level store, where ` +
+        "`claude mcp add --scope user` writes too; every other key in the file is left untouched.",
+    );
+  }
+
+  // Forced-tier competitor detection also scans the other stack's file — a project
+  // install sees user-scope servers and a global install runs inside a cwd — since
+  // a server-level deny rule in this scope's settings file excludes either origin.
+  const forced = input.search === "forced" || input.fetch === "forced";
+  const scanned: Record<string, unknown> = {};
+  if (isPlainObject(servers)) Object.assign(scanned, servers);
+  const otherFile = input.scope === "project" ? join(input.home, ".claude.json") : join(input.cwd, ".mcp.json");
+  if (forced && existsSync(otherFile)) {
+    let otherLoaded: LoadedConfig | undefined;
+    try {
+      otherLoaded = codecFor("json", input.host).load(otherFile);
+    } catch (error) {
+      // A directory or unreadable file (EISDIR/EACCES) must refuse the tier —
+      // honor or report — instead of crashing on a file we never edit.
+      errors.push({
+        message: `${otherFile} exists but cannot be read (${error instanceof Error ? error.message : String(error)}); the forced-tier competitor scan requires it. Fix the file or its permissions, or choose a lower tier.`,
+      });
+    }
+    if (otherLoaded?.parseError) {
+      errors.push({ message: `${otherFile} exists but does not parse as JSON: ${otherLoaded.parseError}` });
+    } else if (
+      otherLoaded !== undefined &&
+      otherLoaded.value.mcpServers !== undefined &&
+      !isPlainObject(otherLoaded.value.mcpServers)
+    ) {
+      errors.push({
+        message: `${otherFile}: mcpServers is ${valueKind(otherLoaded.value.mcpServers)}, not an object; the forced-tier competitor scan cannot read it. Fix the file or choose a lower tier.`,
+      });
+    } else if (otherLoaded !== undefined && isPlainObject(otherLoaded.value.mcpServers)) {
+      const otherServers = otherLoaded.value.mcpServers;
+      Object.assign(scanned, otherServers);
+      if ("deepseek" in otherServers) {
+        notes.push(
+          `A deepseek server is also registered in ${otherFile}; Claude Code resolves the name local first, then ` +
+            "project, then user scope, so consider uninstalling the other scope to keep one registration.",
+        );
+      }
+    }
+  }
+
+  const denyEntries: string[] = [];
+  const { competitors, bystanders } = splitCompetitors(scanned);
+  if (forced && competitors.length > 0) {
+    // Claude Code has a per-server kill switch: a bare `mcp__<server>` deny rule
+    // denies every tool of that server, so detected web-capable competitors are
+    // excluded instead of refusing the tier (unlike Codex).
+    const rules = competitors.map((name) => `mcp__${name}`);
+    denyEntries.push(...rules);
+    notes.push(
+      `Forced tier: web-capable MCP servers are denied by server-level rules (${rules.join(", ")}), so DeepSeek ` +
+        "routing is exclusive while the entries stay." +
+        (input.scope === "global"
+          ? " These denies apply in every project on this machine and match by server name, so a same-named server in another project is denied too."
+          : ""),
+    );
+  }
+  const stayRegistered = forced ? bystanders : [...competitors, ...bystanders];
+  if (stayRegistered.length > 0) notes.push(othersStayRegisteredNote(stayRegistered));
+
+  if (input.search === "forced") denyEntries.push(BUILTIN_TOOL_IDS.search);
+  if (input.fetch === "forced") denyEntries.push(BUILTIN_TOOL_IDS.fetch);
+  if (input.search === "off") denyEntries.push(MCP_TOOL_IDS.search);
+  if (input.fetch === "off") denyEntries.push(MCP_TOOL_IDS.fetch);
+
+  if (denyEntries.length > 0) {
+    const settingsLoaded = codecFor("json", input.host).load(paths.settings);
+    if (settingsLoaded.parseError) {
+      errors.push({ message: `${paths.settings} exists but does not parse as JSON: ${settingsLoaded.parseError}` });
+    } else {
+      const permissions = settingsLoaded.value.permissions;
+      const deny = isPlainObject(permissions) ? permissions.deny : undefined;
+      if (permissions !== undefined && !isPlainObject(permissions)) {
+        errors.push({
+          message: `${paths.settings}: the permissions key is ${valueKind(permissions)}, not an object; fix it before installing.`,
+        });
+      } else if (deny !== undefined && !Array.isArray(deny)) {
+        errors.push({
+          message: `${paths.settings}: permissions.deny is ${valueKind(deny)}, not an array; fix it before installing.`,
+        });
+      } else {
+        const existingCount = Array.isArray(deny) ? deny.length : 0;
+        const existingDeny = Array.isArray(deny) ? deny.filter((item): item is string => typeof item === "string") : [];
+        const denyOps: ConfigOp[] = [
+          {
+            op: "append-array",
+            path: ["permissions", "deny"],
+            entries: denyEntries,
+            existingCount,
+          },
+        ];
+        edits.push({
+          file: paths.settings,
+          format: "json",
+          ...(input.scope === "global" ? { shared: true as const } : {}),
+          ops: denyOps,
+        });
+        if (existingCount > 0) {
+          notes.push(
+            `permissions.deny already holds ${existingCount} ${existingCount === 1 ? "entry" : "entries"}; ` +
+              "the plan appends only its own and never removes yours.",
+          );
+        }
+        const preexisting = denyEntries.filter((name) => existingDeny.includes(name));
+        if (preexisting.length > 0) {
+          notes.push(
+            `${preexisting.join(", ")} ${preexisting.length === 1 ? "is" : "are"} already present in permissions.deny — present entries are not duplicated.`,
+          );
+        }
+      }
+    }
+  }
+  if (errors.length > 0) {
+    return { host: "claude-code", scope: input.scope, tiers, edits: [], notes, errors };
+  }
+
+  const forcedIds = [
+    ...(input.search === "forced" ? [BUILTIN_TOOL_IDS.search] : []),
+    ...(input.fetch === "forced" ? [BUILTIN_TOOL_IDS.fetch] : []),
+  ];
+  if (forcedIds.length > 0) {
+    notes.push(
+      `Forced is exclusion: bare deny rules (${forcedIds.join(", ")}) in permissions.deny remove the built-in tool ` +
+        "from the model's context entirely — deny outranks allow at every settings level and cannot be carved out, so " +
+        `the exclusion also applies to every other workflow that relied on the tool ${
+          input.scope === "global" ? "in every project on this machine" : "in this project"
+        }. ` +
+        FORCED_COST_NOTE,
+    );
+  }
+  const offIds = [
+    ...(input.search === "off" ? [MCP_TOOL_IDS.search] : []),
+    ...(input.fetch === "off" ? [MCP_TOOL_IDS.fetch] : []),
+  ];
+  if (offIds.length > 0) {
+    notes.push(
+      `Off capabilities are written as their full tool ids (${offIds.join(", ")}) in permissions.deny: the tool ` +
+        "leaves the model's context while the server keeps running; delete the entry to re-enable it.",
+    );
+  }
+  if (input.search === "optional" || input.fetch === "optional") {
+    notes.push(
+      "Claude Code ships built-in WebSearch and WebFetch tools; under the optional tier they stay available " +
+        "alongside the DeepSeek tools.",
+    );
+  }
+
+  if (input.search === "preferred" || input.fetch === "preferred") {
+    if (input.scope === "project" && !existsSync(paths.rules) && existsSync(join(input.cwd, "AGENTS.md"))) {
+      notes.push(
+        `This plan creates ${paths.rules} where none exists, and ${join(input.cwd, "AGENTS.md")} is present: Claude ` +
+          "Code reads AGENTS.md only when no CLAUDE.md exists above the cwd, so the new CLAUDE.md takes precedence — " +
+          "merge anything you rely on from AGENTS.md before applying.",
+      );
+    }
+    edits.push({
+      file: paths.rules,
+      format: "rules",
+      block: buildRulesBlock(input.host, rulesLines(MCP_TOOL_IDS, input.search, input.fetch)),
+    });
+    notes.push(
+      input.scope === "global"
+        ? `Rules block upserted in ${paths.rules}; Claude Code loads the user CLAUDE.md plus every CLAUDE.md from the cwd up the directory tree, concatenating the levels.`
+        : `Rules block upserted in ${paths.rules}; Claude Code loads every CLAUDE.md from the cwd up the directory tree, concatenating the levels.`,
+    );
+  }
+
+  return { host: "claude-code", scope: input.scope, tiers, edits, notes, errors };
+}

package/src/installer/hosts/codex.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { API_KEY_ENV } from "../../core/constants";
+import { OPTION_ENV_VARS } from "../../core/env";
 import { FORCED_COST_NOTE, othersStayRegisteredNote, replacingExistingEntryNote, splitCompetitors } from "../detect";
 import { codecFor } from "../formats";
 import { buildRulesBlock } from "../formats/rules";
@@ -22,7 +23,10 @@ export const CODEX_TESTED_VERSION = "0.163.0";
  */
 export function probeCodexVersion(err: (line: string) => void): string | undefined {
   // env passed explicitly: runtime PATH edits (tests) must reach the lookup.
-  const result = spawnSync("codex", ["--version"], { timeout: 5000, encoding: "utf8", env: process.env });
+  // shell: npm's global install on Windows provides only a codex.cmd shim,
+  // which spawnSync cannot launch without a shell; the command and args are
+  // hardcoded, so the shell hop is safe.
+  const result = spawnSync("codex", ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
   const version = result.status === 0 ? parseCodexVersion(result.stdout ?? "") : undefined;
   if (version === undefined) {
     err("note: codex was not found on PATH or printed no version; the version-drift check was skipped");
@@ -111,7 +115,7 @@ export function planCodex(input: InstallerInput, _previous: InstallRecord | unde
     command: "npx",
     args: ["-y", input.packageRef],
     ...(keptDisabled.length > 0 || offDisabled.length > 0 ? { disabled_tools: [...keptDisabled, ...offDisabled] } : {}),
-    env_vars: [API_KEY_ENV],
+    env_vars: [API_KEY_ENV, ...OPTION_ENV_VARS],
   };
 
   const ops: ConfigOp[] = [{ op: "set", path: ["mcp_servers", "deepseek"], value: entry, previous: existingEntry }];
@@ -133,8 +137,9 @@ export function planCodex(input: InstallerInput, _previous: InstallRecord | unde
   edits.push({ file: paths.config, format: "toml", shared: true, ops });
 
   notes.push(
-    `Codex stdio children do not inherit the parent environment, so the entry forwards ${API_KEY_ENV} explicitly ` +
-      "via env_vars; the key must be set in the shell that launches Codex.",
+    `Codex stdio children do not inherit the parent environment, so the entry forwards ${API_KEY_ENV} and every ` +
+      "DEEPSEEK_* option variable explicitly via env_vars; shell-set knobs reach the server without hand-editing " +
+      "config.toml (the shared config file works without any forwarding).",
   );
   if (input.scope === "project") {
     notes.push(

package/src/installer/hosts/index.ts

@@ -3,6 +3,7 @@ import { deepEqual, isPlainObject } from "../formats/value";
 import { assertFileOwnership, fileOwnershipNotes } from "../ownership";
 import { claimedByOtherScope, InstallRecordError, readRecord } from "../state";
 import type { HostName, InstallerInput, InstallPlan, InstallRecord, RecordedFile } from "../types";
+import { planClaudeCode, probeClaudeCodeVersion } from "./claude-code";
 import { planCodex, probeCodexVersion } from "./codex";
 import { planOpenCode } from "./opencode";
 import { planPi } from "./pi";
@@ -23,6 +24,7 @@ export const HOST_PLANNERS: Readonly<Record<HostName, HostPlanner>> = {
   opencode: planOpenCode,
   pi: planPi,
   codex: planCodex,
+  "claude-code": planClaudeCode,
 };
 
 /**
@@ -32,6 +34,7 @@ export const HOST_PLANNERS: Readonly<Record<HostName, HostPlanner>> = {
  */
 export const HOST_VERSION_PROBES: Partial<Record<HostName, (err: (line: string) => void) => string | undefined>> = {
   codex: probeCodexVersion,
+  "claude-code": probeClaudeCodeVersion,
 };
 
 export function planForHost(host: HostName, input: InstallerInput): InstallPlan {