deepseek-web-retrieval 0.7.0 → 0.9.0

package/src/core/search.ts

@@ -1,25 +1,103 @@
+import { MAX_QUERY_CHARS } from "./constants";
 import { normalizeDomains } from "./domains";
 import { truncate } from "./format";
 import type { DeepSeekSearchResult, SearchOptions, SearchResult } from "./types";
 import { normalizeResultUrl } from "./url";
 
+/** The fewest body characters a degraded query keeps before operators start dropping. */
+const MIN_BODY_CHARS = 8;
+
+function charCount(value: string): number {
+  return Array.from(value).length;
+}
+
+/** The query string plus every adjustment made to fit it under the length limit. */
+export interface ComposedQuery {
+  readonly query: string;
+  readonly notes: readonly string[];
+}
+
+interface OperatorParts {
+  readonly blocked: readonly string[];
+  readonly include?: string;
+  readonly language?: string;
+}
+
 /**
- * Appends DeepSeek search operators:
- *   blocked: -site:example.com (space separated for multiple)
- *   include: site:a.com OR site:b.com
- *   language: lang:zh or lang:zh,en
+ * Operators are official API surface, documented in the guide's search-syntax
+ * section (搜索语法): site:, -site:, lang:, quoted phrases, after:/before:.
  */
-export function buildQuery(
+function operatorParts(options: Pick<SearchOptions, "blockedDomains" | "includeDomains" | "language">): OperatorParts {
+  const blocked = normalizeDomains(options.blockedDomains).map((domain) => `-site:${domain}`);
+  const include = normalizeDomains(options.includeDomains).map((domain) => `site:${domain}`);
+  const language = options.language?.trim().replace(/^lang:/i, "");
+  return {
+    blocked,
+    include: include.length ? include.join(" OR ") : undefined,
+    language: language ? `lang:${language}` : undefined,
+  };
+}
+
+function assemble(body: string, parts: OperatorParts, withInclude: boolean, withLang: boolean): string {
+  const segments = [body, ...parts.blocked];
+  if (withInclude && parts.include) segments.push(parts.include);
+  if (withLang && parts.language) segments.push(parts.language);
+  return segments.filter((segment) => segment.length > 0).join(" ");
+}
+
+/** Characters left for the query body once the kept operators and separators are paid for. */
+function bodyBudget(parts: OperatorParts, withInclude: boolean, withLang: boolean, maxChars: number): number {
+  const fixed = [
+    ...parts.blocked,
+    ...(withInclude && parts.include ? [parts.include] : []),
+    ...(withLang && parts.language ? [parts.language] : []),
+  ].join(" ");
+  return maxChars - (fixed ? charCount(fixed) + 1 : 0);
+}
+
+/**
+ * Builds the wire query within the API's character budget, degrading instead of
+ * failing when operators push it over: the query body is truncated first (user
+ * configuration outranks model verbosity), the language filter drops next, the
+ * include list last; blocked domains never drop. Only when the -site:
+ * operators alone crowd out the body does the call fail. Every adjustment is
+ * reported in `notes` so the model can be shown what was actually searched.
+ */
+export function composeSearchQuery(
   query: string,
   options: Pick<SearchOptions, "blockedDomains" | "includeDomains" | "language">,
-): string {
-  const parts = [query.trim()];
-  for (const domain of normalizeDomains(options.blockedDomains)) parts.push(`-site:${domain}`);
-  const include = normalizeDomains(options.includeDomains);
-  if (include.length) parts.push(include.map((domain) => `site:${domain}`).join(" OR "));
-  const language = options.language?.trim().replace(/^lang:/i, "");
-  if (language) parts.push(`lang:${language}`);
-  return parts.filter((part) => part.length > 0).join(" ");
+  maxChars: number = MAX_QUERY_CHARS,
+): ComposedQuery {
+  const parts = operatorParts(options);
+  const body = query.trim();
+  const notes: string[] = [];
+
+  const attempt = (withInclude: boolean, withLang: boolean): string | undefined => {
+    const budget = bodyBudget(parts, withInclude, withLang, maxChars);
+    if (charCount(body) <= budget) return assemble(body, parts, withInclude, withLang);
+    if (budget >= MIN_BODY_CHARS) {
+      notes.push(`query truncated to ${budget} characters (query length limit)`);
+      return assemble(truncate(body, budget), parts, withInclude, withLang);
+    }
+    return undefined;
+  };
+
+  let assembled = attempt(true, true);
+  if (assembled === undefined && parts.language) {
+    notes.push("language filter dropped (query length limit)");
+    assembled = attempt(true, false);
+  }
+  if (assembled === undefined && parts.include) {
+    notes.push("includeDomains filter dropped (query length limit)");
+    assembled = attempt(false, false);
+  }
+  if (assembled === undefined) {
+    throw new Error(
+      `DeepSeek search query cannot fit ${maxChars} characters: the blockedDomains -site: ` +
+        `operators alone occupy ${charCount(parts.blocked.join(" "))} characters`,
+    );
+  }
+  return { query: assembled, notes };
 }
 
 export function parsePublished(value: unknown): number | undefined {
@@ -64,7 +142,12 @@ export function processResults(raw: readonly DeepSeekSearchResult[], options: Se
     }
 
     seen.add(url);
-    const content = truncate(optionalText(item.summary) ?? optionalText(item.snippet) ?? "", options.maxSummaryChars);
+    const rawContent = optionalText(item.summary) ?? optionalText(item.snippet) ?? "";
+    const cutContent = truncate(rawContent, options.maxSummaryChars);
+    // The ellipsis marks a summary the cap actually shortened; official
+    // summaries are typically 600-800 characters, so the 1,200 default
+    // rarely triggers it.
+    const content = cutContent && charCount(rawContent) > options.maxSummaryChars ? `${cutContent}…` : cutContent;
     const published = parsePublished(item.date);
     const title = optionalText(item.title);
     const rerankScore = typeof rerank === "number" && Number.isFinite(rerank) ? rerank : undefined;

package/src/core/types.ts

@@ -47,6 +47,12 @@ export interface ResolvedOptions {
   readonly fetch: FetchOptions;
   readonly auth: AuthOptions;
   readonly retry: RetryOptions;
+  /**
+   * The API root both retrieval endpoints are composed from. Infrastructure
+   * routing, not a result-shaping knob: proxies and mock upstreams override it;
+   * anything but an http(s) URL is dropped at resolution back to the default.
+   */
+  readonly baseUrl: string;
 }
 
 export interface DeepSeekSearchResult {
@@ -72,6 +78,17 @@ export interface SearchResult {
   readonly siteName?: string;
 }
 
+/** What one search call executed: the processed results plus the query actually sent. */
+export interface SearchOutcome {
+  readonly results: readonly SearchResult[];
+  /** The query as the caller provided it, trimmed. */
+  readonly inputQuery: string;
+  /** The query sent to DeepSeek, operators included. */
+  readonly effectiveQuery: string;
+  /** One entry per degradation applied to fit the query budget; empty means nothing was adjusted. */
+  readonly notes: readonly string[];
+}
+
 export interface FetchedPage {
   readonly url: string;
   readonly title: string;

package/src/installer/apply.ts

@@ -5,8 +5,8 @@ import { codecFor, writeConfig } from "./formats";
 import { deepEqual, valueAt } from "./formats/value";
 import { withOperationLock } from "./operation-lock";
 import { acquireFileOwnership, assertFileOwnership, releaseFileOwnership } from "./ownership";
+import { deleteRecord, readRecord, recordPathFor, writeRecord } from "./record";
 import { pruneEmptyDir, revertRecordedFile } from "./revert";
-import { deleteRecord, readRecord, statePathFor, writeRecord } from "./state";
 import type { ConfigOp, FileEdit, InstallerInput, InstallPlan, InstallRecord, RecordedFile } from "./types";
 
 /** What a successful apply reports; every failure mode throws instead. */
@@ -37,7 +37,7 @@ interface PreparedEdit {
  * rendered (the plan and the record must describe one plan-time snapshot —
  * ADR-0001), prepares every edit in memory (a malformed existing config fails
  * before any file is written), writes the files, reverts artifacts orphaned by
- * a tier change, verifies the result, then records surgical-undo state. Write
+ * a tier change, verifies the result, then records the install record. Write
  * and verification failures restore touched files and the previous record.
  * Incomplete recovery is reported explicitly and keeps new ownership claims
  * so another install cannot adopt partially applied configuration.
@@ -46,7 +46,7 @@ export function applyPlan(plan: InstallPlan, input: InstallerInput): ApplyResult
   if (plan.errors.length > 0) {
     throw new Error(`refusing to apply a plan with errors: ${plan.errors.map((error) => error.message).join("; ")}`);
   }
-  return withOperationLock([statePathFor(input)], () =>
+  return withOperationLock([recordPathFor(input)], () =>
     withOperationLock(
       [...plan.edits, ...(plan.reverts ?? [])].map((file) => file.file),
       () => applyLocked(plan, input),
@@ -231,7 +231,7 @@ function rollbackApply(
   try {
     if (previous !== undefined) writeRecord(input, previous);
     else deleteRecord(input);
-    if (previous === undefined ? existsSync(statePathFor(input)) : !deepEqual(readRecord(input), previous)) {
+    if (previous === undefined ? existsSync(recordPathFor(input)) : !deepEqual(readRecord(input), previous)) {
       throw new Error("restored install record differs from its previous state");
     }
   } catch (restoreError) {

package/src/installer/cli.ts

@@ -7,8 +7,8 @@ import { ApplyError, applyPlan } from "./apply";
 import { runConfigCommand } from "./config-command";
 import { HOST_PLANNERS, HOST_VERSION_PROBES, planForHost } from "./hosts";
 import { pinPackageRef } from "./ownership";
+import { legacyGlobalRecordDir, listRecords, readingLegacyGlobalRecords } from "./record";
 import { renderPlan } from "./render";
-import { legacyGlobalStateDir, listRecords, readingLegacyGlobalRecords } from "./state";
 import type { HostName, InstallerInput, Scope, Tier } from "./types";
 import { uninstall } from "./uninstall";
 
@@ -161,7 +161,7 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
     }
     if (readingLegacyGlobalRecords({ ...roots, configHome })) {
       out(
-        `Global install records are being read from the legacy ${legacyGlobalStateDir(roots)} ` +
+        `Global install records are being read from the legacy ${legacyGlobalRecordDir(roots)} ` +
           "(written before the Windows config home moved to %APPDATA%).",
       );
     }

package/src/installer/config-command.ts

@@ -68,17 +68,18 @@ export async function runConfigCommand(
   const client = deps.client ?? createRetrievalClient();
   const startedAt = Date.now();
   try {
-    const results = await client.searchWeb(query, resolved.search, {
+    const outcome = await client.searchWeb(query, resolved.search, {
       signal: new AbortController().signal,
       auth: { apiKey },
       retry: resolved.retry,
+      baseUrl: resolved.baseUrl,
     });
     const elapsedMs = Date.now() - startedAt;
     io.out(
-      `search "${query.trim()}" — ${results.length} ${results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`,
+      `search "${query.trim()}" — ${outcome.results.length} ${outcome.results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`,
     );
     io.out("");
-    for (const line of formatSearchResults(results).split("\n")) io.out(line);
+    for (const line of formatSearchResults(outcome.results, outcome).split("\n")) io.out(line);
     return 0;
   } catch (error) {
     io.err(error instanceof Error ? error.message : String(error));

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

@@ -0,0 +1,311 @@
+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, probeHostVersion } 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}`;
+}
+
+/** Probes `claude --version` for the version-drift note (see probeHostVersion). */
+export function probeClaudeCodeVersion(err: (line: string) => void): string | undefined {
+  return probeHostVersion("claude", parseClaudeCodeVersion, err);
+}
+
+/**
+ * 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,4 +1,3 @@
-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";
@@ -8,7 +7,7 @@ import { isPlainObject } from "../formats/value";
 import { join } from "../paths";
 import { MCP_TOOL_IDS, RAW_MCP_TOOL_IDS, rulesLines } from "../rulesContent";
 import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord } from "../types";
-import { planHeader } from "./shared";
+import { planHeader, probeHostVersion } from "./shared";
 
 /**
  * The Codex release this installer's facts are verified against — the lock in
@@ -16,19 +15,9 @@ import { planHeader } from "./shared";
  */
 export const CODEX_TESTED_VERSION = "0.163.0";
 
-/**
- * The one subprocess the installer runs: `codex --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.
- */
+/** Probes `codex --version` for the version-drift note (see probeHostVersion). */
 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 });
-  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");
-  }
-  return version;
+  return probeHostVersion("codex", parseCodexVersion, err);
 }
 
 /** Parses `codex --version` output (`codex-cli 0.163.0`) into the bare version. */

package/src/installer/hosts/index.ts

@@ -1,8 +1,9 @@
 import { API_KEY_ENV } from "../../core/constants";
 import { deepEqual, isPlainObject } from "../formats/value";
 import { assertFileOwnership, fileOwnershipNotes } from "../ownership";
-import { claimedByOtherScope, InstallRecordError, readRecord } from "../state";
+import { claimedByOtherScope, InstallRecordError, readRecord } from "../record";
 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 {
@@ -150,7 +153,7 @@ function withSecretGuard(plan: InstallPlan): InstallPlan {
             {
               message:
                 `${edit.file}: the existing value at ${op.path.join(".")} contains a credential-looking key ` +
-                `(${offender}). The installer refuses to snapshot secrets into its state file. Move the key to ` +
+                `(${offender}). The installer refuses to snapshot secrets into its install record. Move the key to ` +
                 `environment indirection ("\${${API_KEY_ENV}}" expansion or env_vars) and re-run.`,
             },
           ],

package/src/installer/hosts/opencode.ts

@@ -4,8 +4,8 @@ import { buildRulesBlock } from "../formats/rules";
 import { isPlainObject } from "../formats/value";
 import { lineageMatcher } from "../ownership";
 import { configHome, join } from "../paths";
+import { appendedByPrevious } from "../record";
 import { rulesLines } from "../rulesContent";
-import { appendedByPrevious } from "../state";
 import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord } from "../types";
 import { planHeader } from "./shared";