agent-shim 8.9.0 → 8.10.0

package/README.md

@@ -95,7 +95,8 @@ agent-shim identity resolve-conflicts <name>  # interactively resolve a retained
 agent-shim profile add [name] [--extends <profile>]... [--description <text>]   # interactive with no options on a terminal [--json]
 agent-shim profile set <name> [--category <category>=<bool>]... [--entry <category>/<path>=<bool>]... [--json]
 agent-shim profile set <name> [--extends <profile>]... [--no-extends] [--description <text> | --no-description] [--json]
-agent-shim profile set <name> [--[no-]launch-skip-permissions] [--[no-]launch-remote-control] [--[no-]launch-headroom] [--[no-]launch-track-usage] [--json]
+agent-shim profile set <name> [--[no-]launch-skip-permissions] [--[no-]launch-remote-control] [--[no-]launch-headroom] [--[no-]launch-track-usage]
+agent-shim profile set <name> [--launch-claude-version <version> | --no-launch-claude-version] [--json] [--json]
 agent-shim profile set <name> [--launch-provider <provider> | --no-launch-provider] [--json]
 agent-shim profile list [--json]
 agent-shim profile show <name> [--json]
@@ -150,6 +151,7 @@ agent-shim run [@<identity>] [launch flags] [claude arguments]
   #   --identity <name>  --config-profile <name>  --provider <name> | --no-provider
   #   --category <category>=<bool>  --share <category>/<path>  --hide <category>/<path>   (each repeatable)
   #   --[no-]skip-permissions  --[no-]remote-control  --[no-]headroom  --[no-]track-usage  --[no-]wait
+  #   --claude-version <version>   run exactly this installed Claude Code version
   #   --native   run the real claude with nothing from agent-shim applied; cannot be combined with the flags above
 claude @<identity> ...                      # the same, once `agent-shim shim enable` has run
 ```

package/dist/cli.cjs

@@ -55043,9 +55043,9 @@ function applyPatch(filePath, schema, patch, options = {}) {
   if (!result.success) {
     throw new ConfigValidationError(filePath, result.error.issues);
   }
-  const validated = result.data;
-  writeJsonAtomic(filePath, validated, storeFs);
-  return validated;
+  const validated2 = result.data;
+  writeJsonAtomic(filePath, validated2, storeFs);
+  return validated2;
 }
 
 // src/realPorts.ts
@@ -55085,6 +55085,23 @@ function compareVersions(a2, b) {
   }
   return 0;
 }
+var ClaudeVersionNotInstalledError = class extends CliError {
+  constructor(version2, versionsDir, installed) {
+    super(
+      `Claude Code ${version2} is pinned for this launch but is not installed under "${versionsDir}"` + (installed.length === 0 ? " (no versions are installed there)." : `. Installed: ${installed.join(", ")}.`) + " Install it, or change or remove the pin (--claude-version, AGENT_SHIM_CLAUDE_VERSION, or launch.claudeVersion)."
+    );
+    this.version = version2;
+    this.versionsDir = versionsDir;
+    this.installed = installed;
+    this.name = "ClaudeVersionNotInstalledError";
+  }
+  version;
+  versionsDir;
+  installed;
+};
+function installedVersions(entries) {
+  return entries.filter((entry) => entry.isFile && entry.isExecutable && entry.sizeBytes > 0 && isNumericDottedVersion(entry.name)).map((entry) => entry.name).sort(compareVersions);
+}
 function pickHighestVersion(entries) {
   const candidates = entries.filter(
     (entry) => entry.isFile && entry.isExecutable && entry.sizeBytes > 0 && isNumericDottedVersion(entry.name)
@@ -55100,6 +55117,13 @@ function discoverClaudeBinary(options) {
   const versionsDir = options.versionsDir ?? defaultVersionsDir();
   const entries = options.listVersionsDir(versionsDir);
   const highestVersion = pickHighestVersion(entries);
+  if (options.version !== void 0) {
+    const installed = installedVersions(entries);
+    if (!installed.includes(options.version)) {
+      throw new ClaudeVersionNotInstalledError(options.version, versionsDir, installed);
+    }
+    return { path: import_node_path3.default.join(versionsDir, options.version), source: "versions-dir", version: options.version };
+  }
   if (highestVersion !== void 0) {
     return {
       path: import_node_path3.default.join(versionsDir, highestVersion),
@@ -55167,7 +55191,9 @@ var LaunchSchema = external_exports.strictObject({
   remoteControl: external_exports.boolean().optional(),
   provider: external_exports.string().min(1).optional(),
   headroom: external_exports.boolean().optional(),
-  trackUsage: external_exports.boolean().optional()
+  trackUsage: external_exports.boolean().optional(),
+  /** The exact Claude Code version to run, as it is named in Claude Code's versions directory (`2.1.220`). A pin that is not installed fails the launch; it never falls back to the highest version. */
+  claudeVersion: external_exports.string().regex(NUMERIC_DOTTED_VERSION_RE, "must be an exact dotted-numeric Claude Code version such as 2.1.220").optional()
 });
 var CREDENTIAL_TARGETS = ["bearer", "apiKey", "oauthToken"];
 var PROVIDER_CREDENTIAL_TARGETS = ["bearer", "apiKey"];
@@ -56501,13 +56527,17 @@ function realContentSourcePath() {
   return resolveContentSourcePath({ isSea: (0, import_node_sea.isSea)(), execPath: process.execPath, argv1: process.argv[1] });
 }
 function realResolveClaudeBinary(isOwnBinary) {
-  return () => discoverClaudeBinary({
+  return (request7) => discoverClaudeBinary({
     listVersionsDir,
     pathDirs: (process.env.PATH ?? "").split(import_node_path8.default.delimiter).filter((dir) => dir !== ""),
     findExecutableInDir,
-    isOwnBinary
+    isOwnBinary,
+    ...request7?.version === void 0 ? {} : { version: request7.version }
   });
 }
+function realInstalledClaudeVersions() {
+  return installedVersions(listVersionsDir(defaultVersionsDir()));
+}
 
 // src/claudeShim.ts
 var EXECUTABLE_FILE_MODE = 493;
@@ -59284,6 +59314,9 @@ function flattenLayers(layers, options) {
       if (layer.launch.trackUsage !== void 0) {
         launch.trackUsage = layer.launch.trackUsage;
       }
+      if (layer.launch.claudeVersion !== void 0) {
+        launch.claudeVersion = layer.launch.claudeVersion;
+      }
     }
     if (layer.entries === void 0) {
       continue;
@@ -61264,6 +61297,9 @@ function applyProfileSet(paths, name, options) {
   if (options.launchProvider !== void 0) {
     launchPatch.provider = options.launchProvider === false ? void 0 : options.launchProvider;
   }
+  if (options.launchClaudeVersion !== void 0) {
+    launchPatch.claudeVersion = options.launchClaudeVersion === false ? void 0 : options.launchClaudeVersion;
+  }
   if (Object.keys(launchPatch).length > 0) {
     setProfileLaunchFlags(paths, name, launchPatch);
     touched = true;
@@ -61305,7 +61341,7 @@ function registerProfileCommand(program2, deps) {
   withExamples(
     profile.command("set <name>").description(
       "Update a configuration profile's categories, entries, extends list, description or launch settings. With no options on a terminal, walks through its categories."
-    ).option("--category <category=bool>", "Share (true) or hide (false) a whole category (repeatable).", collectBoolPair).option("--entry <path=bool>", "Share (true) or hide (false) one <category>/<path> entry (repeatable).", collectBoolPair).option("--extends <profile>", "Replace the extends list with these profiles (repeatable, in order).", collectRepeated).option("--no-extends", "Clear the extends list.").option("--description <text>", "Replace the description.").option("--no-description", "Clear the description.").option("--launch-skip-permissions", "Launches under this profile skip permission prompts.").option("--no-launch-skip-permissions", "Launches under this profile keep permission prompts.").option("--launch-remote-control", "Launches under this profile enable Remote Control.").option("--no-launch-remote-control", "Launches under this profile leave Remote Control off.").option("--launch-headroom", "Launches under this profile route through headroom.").option("--no-launch-headroom", "Launches under this profile route direct.").option("--launch-track-usage", "Launches under this profile route through the front door so their requests and quota are recorded, with no headroom needed.").option("--no-launch-track-usage", "Launches under this profile are not recorded unless a provider or headroom routes them anyway.").option("--launch-provider <provider>", "Launches under this profile route through this provider.").option("--no-launch-provider", "Clear this profile's provider selection.").option("--json", "Print the result as JSON.").action(async (name, allOptions) => {
+    ).option("--category <category=bool>", "Share (true) or hide (false) a whole category (repeatable).", collectBoolPair).option("--entry <path=bool>", "Share (true) or hide (false) one <category>/<path> entry (repeatable).", collectBoolPair).option("--extends <profile>", "Replace the extends list with these profiles (repeatable, in order).", collectRepeated).option("--no-extends", "Clear the extends list.").option("--description <text>", "Replace the description.").option("--no-description", "Clear the description.").option("--launch-skip-permissions", "Launches under this profile skip permission prompts.").option("--no-launch-skip-permissions", "Launches under this profile keep permission prompts.").option("--launch-remote-control", "Launches under this profile enable Remote Control.").option("--no-launch-remote-control", "Launches under this profile leave Remote Control off.").option("--launch-headroom", "Launches under this profile route through headroom.").option("--no-launch-headroom", "Launches under this profile route direct.").option("--launch-track-usage", "Launches under this profile route through the front door so their requests and quota are recorded, with no headroom needed.").option("--no-launch-track-usage", "Launches under this profile are not recorded unless a provider or headroom routes them anyway.").option("--launch-provider <provider>", "Launches under this profile route through this provider.").option("--no-launch-provider", "Clear this profile's provider selection.").option("--launch-claude-version <version>", "Launches under this profile run exactly this installed Claude Code version (such as 2.1.220); a version that is not installed fails the launch.").option("--no-launch-claude-version", "Clear this profile's Claude Code version pin.").option("--json", "Print the result as JSON.").action(async (name, allOptions) => {
       const { json: json2, ...options } = allOptions;
       requireProfileExists(paths, name);
       if (Object.entries(allOptions).every(([key, value2]) => key === "json" || value2 === void 0)) {
@@ -61673,7 +61709,7 @@ function registerIdentityCommand(program2, deps) {
 // package.json
 var package_default = {
   name: "agent-shim",
-  version: "8.9.0",
+  version: "8.10.0",
   description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   license: "MIT",
   author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -63553,6 +63589,34 @@ function parseEnvBool(variable, value2) {
   return parsed;
 }
 
+// src/launcher/claudeVersion.ts
+var InvalidClaudeVersionError = class extends UsageError {
+  constructor(value2, origin) {
+    super(`${origin} names Claude Code version "${value2}", which is not an exact dotted-numeric version such as 2.1.220.`);
+    this.value = value2;
+    this.origin = origin;
+    this.name = "InvalidClaudeVersionError";
+  }
+  value;
+  origin;
+};
+function validated(value2, origin) {
+  if (!NUMERIC_DOTTED_VERSION_RE.test(value2)) {
+    throw new InvalidClaudeVersionError(value2, origin);
+  }
+  return value2;
+}
+function resolveClaudeVersion(params) {
+  if (params.flag !== void 0) {
+    return { version: validated(params.flag, "--claude-version"), source: "flag" };
+  }
+  const fromEnv = params.env.AGENT_SHIM_CLAUDE_VERSION;
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    return { version: validated(fromEnv, "AGENT_SHIM_CLAUDE_VERSION"), source: "environment" };
+  }
+  return params.cascade === void 0 ? void 0 : { version: params.cascade, source: "cascade" };
+}
+
 // src/launcher/guard.ts
 var AMBIENT_CREDENTIAL_VARS = [
   "ANTHROPIC_API_KEY",
@@ -63750,6 +63814,19 @@ function buildCredentialReport(provider, identity, identityName, cacheEnv) {
     ...identityCached === void 0 ? {} : { identityCached }
   };
 }
+function buildClaudeVersionReport(params, cascadePin) {
+  const installed = params.installedClaudeVersions;
+  if (installed === void 0) {
+    return void 0;
+  }
+  const pin = resolveClaudeVersion({ env: params.env, ...cascadePin === void 0 ? {} : { cascade: cascadePin } });
+  const highestInstalled = installed.at(-1);
+  return {
+    ...pin === void 0 ? {} : { pinned: { ...pin, installed: installed.includes(pin.version) } },
+    ...highestInstalled === void 0 ? {} : { highestInstalled },
+    installed
+  };
+}
 function runCheck(params) {
   const facts = buildEntryFacts({
     fs: params.farmFs,
@@ -63774,6 +63851,7 @@ function runCheck(params) {
   const settingsShared = resolved.flattened.categories.get("settings") ?? SHIPPED_CATEGORY_DEFAULTS.settings;
   const settingsExposure = inspectSettingsExposure({ settingsShared, files: params.settingsFiles });
   const keychain = params.platform === "darwin" && params.run !== void 0 && params.farmRoot !== void 0 ? lookupKeychainService(params.run, params.farmRoot) : void 0;
+  const claudeVersion = buildClaudeVersionReport(params, resolved.flattened.launch.claudeVersion);
   return {
     ...params.identityName === void 0 ? {} : { identityName: params.identityName },
     identitySource: params.identitySource,
@@ -63786,7 +63864,8 @@ function runCheck(params) {
     ambientCredential,
     ...keychain === void 0 ? {} : { keychain },
     settingsExposure,
-    credential: buildCredentialReport(params.provider, params.identity, params.identityName, params.credentialCache)
+    credential: buildCredentialReport(params.provider, params.identity, params.identityName, params.credentialCache),
+    ...claudeVersion === void 0 ? {} : { claudeVersion }
   };
 }
 function formatCheckReport(report) {
@@ -63835,6 +63914,17 @@ function formatCheckReport(report) {
   if (credential.applies === "stored-login") {
     lines.push("  The identity's stored login (no credential block applies).");
   }
+  if (report.claudeVersion !== void 0) {
+    lines.push("", "Claude Code version:");
+    const { pinned, highestInstalled, installed } = report.claudeVersion;
+    if (pinned !== void 0) {
+      lines.push(
+        pinned.installed ? `  ${pinned.version}, pinned by the ${pinned.source} (installed)` : `  ${pinned.version}, pinned by the ${pinned.source}, but NOT installed; a launch here fails. Installed: ${installed.length === 0 ? "none" : installed.join(", ")}`
+      );
+    } else {
+      lines.push(highestInstalled === void 0 ? "  none installed in the versions directory (a launch falls back to a claude on PATH)" : `  ${highestInstalled} (the highest installed; nothing pins a version)`);
+    }
+  }
   lines.push("", "Ambient-credential exposure:");
   lines.push(
     report.ambientCredential.ok ? `  OK \u2014 none of ${AMBIENT_CREDENTIAL_VARS.join(", ")} is set to a non-empty value.` : report.ambientCredential.message.split("\n").map((line) => `  ${line}`).join("\n")
@@ -63873,11 +63963,12 @@ function checkReportToJson(report) {
     ambientCredential: report.ambientCredential.ok ? { ok: true } : { ok: false, variable: report.ambientCredential.variable, message: report.ambientCredential.message },
     ...report.keychain === void 0 ? {} : { keychain: report.keychain },
     settingsExposure: report.settingsExposure,
-    credential: report.credential
+    credential: report.credential,
+    ...report.claudeVersion === void 0 ? {} : { claudeVersion: report.claudeVersion }
   };
 }
 function checkReportHasWarnings(report) {
-  return report.resolved.diagnostics.some((diagnostic) => diagnostic.severity !== "info") || report.projectEncodingAmbiguities.length > 0 || !report.ambientCredential.ok || report.credential.provider?.problem !== void 0;
+  return report.resolved.diagnostics.some((diagnostic) => diagnostic.severity !== "info") || report.projectEncodingAmbiguities.length > 0 || !report.ambientCredential.ok || report.credential.provider?.problem !== void 0 || report.claudeVersion?.pinned?.installed === false;
 }
 function loadCheckProvider(paths, name) {
   let definition;
@@ -63963,6 +64054,7 @@ function collectCheckReport(params) {
     settingsFiles,
     run: realRunPort,
     credentialCache: realCredentialCacheEnv(paths),
+    installedClaudeVersions: realInstalledClaudeVersions(),
     ...farmRoot === void 0 ? {} : { farmRoot },
     platform: process.platform,
     ...provider === void 0 ? {} : { provider }
@@ -68686,11 +68778,11 @@ async function validateORPCError(map3, error62) {
   if (!config2.data) {
     return defined ? error62 : new ORPCError(code, { defined: true, status, message, data, cause });
   }
-  const validated = await config2.data["~standard"].validate(error62.data);
-  if (validated.issues) {
+  const validated2 = await config2.data["~standard"].validate(error62.data);
+  if (validated2.issues) {
     return defined ? new ORPCError(code, { defined: false, status, message, data, cause }) : error62;
   }
-  return new ORPCError(code, { defined: true, status, message, data: validated.value, cause });
+  return new ORPCError(code, { defined: true, status, message, data: validated2.value, cause });
 }
 var ContractProcedure = class {
   /**
@@ -72649,7 +72741,7 @@ var ConflictingIdentityError = class extends UsageError {
   positional;
   flag;
 };
-var VALUED_FLAGS = ["--identity", "--config-profile", "--provider", "--category", "--share", "--hide"];
+var VALUED_FLAGS = ["--identity", "--config-profile", "--provider", "--claude-version", "--category", "--share", "--hide"];
 var BOOLEAN_FLAGS = [
   { flag: "--headroom", key: "headroom" },
   { flag: "--track-usage", key: "trackUsage" },
@@ -72695,6 +72787,7 @@ function parseLauncherArgv(argv) {
   let flagIdentity;
   let configProfile;
   let provider;
+  let claudeVersion;
   const booleans = {};
   const categoryFlags = [];
   const shareFlags = [];
@@ -72749,6 +72842,9 @@ function parseLauncherArgv(argv) {
       case "--provider":
         provider = value2;
         break;
+      case "--claude-version":
+        claudeVersion = value2;
+        break;
       case "--category":
         categoryFlags.push(value2);
         break;
@@ -72770,6 +72866,7 @@ function parseLauncherArgv(argv) {
     ...identity === void 0 ? {} : { identity },
     ...configProfile === void 0 ? {} : { configProfile },
     ...provider === void 0 ? {} : { provider },
+    ...claudeVersion === void 0 ? {} : { claudeVersion },
     ...native ? { native: true } : {},
     ...booleans,
     categoryFlags,
@@ -73173,13 +73270,13 @@ function pushProvider(push, entry, cacheEnv) {
     push("provider", "fail", new LegacyProviderFileError(entry.path, conversion).message, entry.name);
     return;
   }
-  const validated = ProviderSchema.safeParse(parsed);
-  if (!validated.success) {
-    push("provider", "fail", new ConfigValidationError(entry.path, validated.error.issues).message, entry.name);
+  const validated2 = ProviderSchema.safeParse(parsed);
+  if (!validated2.success) {
+    push("provider", "fail", new ConfigValidationError(entry.path, validated2.error.issues).message, entry.name);
     return;
   }
-  const cache = cacheClause(cacheEnv, `provider ${entry.name}`, validated.data.credential);
-  push("provider", cache.unreadable ? "fail" : "pass", `${entry.name} is valid (${describeProviderEndpoint(validated.data)}, credential ${describeCredential(validated.data.credential)})${cache.text}.`, entry.name);
+  const cache = cacheClause(cacheEnv, `provider ${entry.name}`, validated2.data.credential);
+  push("provider", cache.unreadable ? "fail" : "pass", `${entry.name} is valid (${describeProviderEndpoint(validated2.data)}, credential ${describeCredential(validated2.data.credential)})${cache.text}.`, entry.name);
 }
 function pushLegacyName(push, params) {
   const legacyVariables = Object.keys(params.env).filter((name) => name.startsWith(LEGACY_ENV_PREFIX) && params.env[name] !== void 0).sort();
@@ -73203,6 +73300,13 @@ function runDoctor(params) {
   const push = (section, severity, message, subject) => {
     findings.push({ section, severity, message, ...subject === void 0 ? {} : { subject } });
   };
+  const checkPin = (section, subject, where, version2) => {
+    const installed = params.installedClaudeVersions;
+    if (version2 === void 0 || installed === void 0 || installed.includes(version2)) {
+      return;
+    }
+    push(section, "warn", `${where} pins Claude Code ${version2}, which is not installed (installed: ${installed.length === 0 ? "none" : installed.join(", ")}); a launch that resolves to it fails.`, subject);
+  };
   const ambient = detectAmbientCredential(params.env);
   if (ambient === void 0) {
     push("ambient-credential", "pass", "No ambient-credential environment variable is set.");
@@ -73235,12 +73339,13 @@ function runDoctor(params) {
   pushLegacyName(push, params);
   const profileSources = /* @__PURE__ */ new Map();
   for (const entry of params.configProfiles) {
-    const validated = validateJson(ConfigProfileSchema, entry);
-    if (!validated.ok) {
-      push("config-profile", "fail", validated.message, entry.name);
+    const validated2 = validateJson(ConfigProfileSchema, entry);
+    if (!validated2.ok) {
+      push("config-profile", "fail", validated2.message, entry.name);
       continue;
     }
-    profileSources.set(entry.name, { name: entry.name, profile: validated.data });
+    profileSources.set(entry.name, { name: entry.name, profile: validated2.data });
+    checkPin("config-profile", entry.name, `Configuration profile "${entry.name}"`, validated2.data.launch?.claudeVersion);
   }
   const loadProfile = (name) => profileSources.get(name);
   for (const name of profileSources.keys()) {
@@ -73256,13 +73361,13 @@ function runDoctor(params) {
   const validProfileNames = new Set(profileSources.keys());
   const validIdentityNames = /* @__PURE__ */ new Set();
   for (const entry of params.identities) {
-    const validated = validateJson(IdentitySchema, entry);
-    if (!validated.ok) {
-      push("identity", "fail", validated.message, entry.name);
+    const validated2 = validateJson(IdentitySchema, entry);
+    if (!validated2.ok) {
+      push("identity", "fail", validated2.message, entry.name);
       continue;
     }
     validIdentityNames.add(entry.name);
-    const defaultProfile = validated.data.defaultConfigProfile;
+    const defaultProfile = validated2.data.defaultConfigProfile;
     if (defaultProfile !== void 0 && !validProfileNames.has(defaultProfile)) {
       push(
         "identity",
@@ -73271,7 +73376,7 @@ function runDoctor(params) {
         entry.name
       );
     } else {
-      const credential = validated.data.credential;
+      const credential = validated2.data.credential;
       const cache = credential === void 0 ? { text: "", unreadable: false } : cacheClause(params.credentialCache, `identity ${entry.name}`, credential);
       push(
         "identity",
@@ -73309,12 +73414,12 @@ function runDoctor(params) {
   if (params.directoryRules.raw === void 0) {
     push("directory-rules", "pass", "No directory-rules.json configured.");
   } else {
-    const validated = validateJson(DirectoryRulesSchema, params.directoryRules);
-    if (!validated.ok) {
-      push("directory-rules", "fail", validated.message);
+    const validated2 = validateJson(DirectoryRulesSchema, params.directoryRules);
+    if (!validated2.ok) {
+      push("directory-rules", "fail", validated2.message);
     } else {
       push("directory-rules", "pass", `${params.directoryRules.path} is valid.`);
-      for (const rule of validated.data.rules) {
+      for (const rule of validated2.data.rules) {
         const badRefs = [];
         if (rule.identity !== void 0 && !selectionExists(rule.identity)) {
           badRefs.push(poolNameOf(rule.identity) === void 0 ? `identity "${rule.identity}"` : `pool "${poolNameOf(rule.identity) ?? ""}"`);
@@ -73322,6 +73427,7 @@ function runDoctor(params) {
         if (rule.configProfile !== void 0 && !validProfileNames.has(rule.configProfile)) {
           badRefs.push(`configuration profile "${rule.configProfile}"`);
         }
+        checkPin("directory-rules", rule.path, `Rule for "${rule.path}"`, rule.launch?.claudeVersion);
         if (badRefs.length > 0) {
           push("directory-rules", "fail", `Rule for "${rule.path}" names ${badRefs.join(" and ")}, which do not exist.`, rule.path);
         } else {
@@ -73333,11 +73439,11 @@ function runDoctor(params) {
   if (params.globalConfig.raw === void 0) {
     push("global-config", "pass", "No config.json configured.");
   } else {
-    const validated = validateJson(GlobalConfigSchema, params.globalConfig);
-    if (!validated.ok) {
-      push("global-config", "fail", validated.message);
+    const validated2 = validateJson(GlobalConfigSchema, params.globalConfig);
+    if (!validated2.ok) {
+      push("global-config", "fail", validated2.message);
     } else {
-      const defaultProfile = validated.data.defaultConfigProfile;
+      const defaultProfile = validated2.data.defaultConfigProfile;
       if (defaultProfile !== void 0 && !validProfileNames.has(defaultProfile)) {
         push(
           "global-config",
@@ -73346,27 +73452,28 @@ function runDoctor(params) {
         );
       } else {
         push("global-config", "pass", `${params.globalConfig.path} is valid.`);
+        checkPin("global-config", void 0, "config.json", validated2.data.launch?.claudeVersion);
       }
     }
   }
   if (params.categoriesLocal.raw === void 0) {
     push("categories-local", "pass", "No categories.local.json configured.");
   } else {
-    const validated = validateJson(CategoryClassificationOverlaySchema, params.categoriesLocal);
+    const validated2 = validateJson(CategoryClassificationOverlaySchema, params.categoriesLocal);
     push(
       "categories-local",
-      validated.ok ? "pass" : "fail",
-      validated.ok ? `${params.categoriesLocal.path} is valid.` : validated.message
+      validated2.ok ? "pass" : "fail",
+      validated2.ok ? `${params.categoriesLocal.path} is valid.` : validated2.message
     );
   }
   if (params.headroom.state.raw === void 0) {
     push("headroom", "pass", "No headroom daemon has ever run; nothing to check.");
   } else {
-    const validated = validateJson(HeadroomStateSchema, params.headroom.state);
-    if (!validated.ok) {
-      push("headroom", "fail", validated.message);
+    const validated2 = validateJson(HeadroomStateSchema, params.headroom.state);
+    if (!validated2.ok) {
+      push("headroom", "fail", validated2.message);
     } else {
-      const state = validated.data;
+      const state = validated2.data;
       const supervisorAlive = state.supervisorPid !== void 0 && params.headroom.isRunning(state.supervisorPid);
       const headroomAlive = state.headroomPid !== void 0 && params.headroom.isRunning(state.headroomPid);
       if (state.supervisorPid === void 0) {
@@ -73536,6 +73643,7 @@ function collectDoctorReport(params) {
   const report = runDoctor({
     env: params.env,
     credentialCache: realCredentialCacheEnv(paths),
+    installedClaudeVersions: realInstalledClaudeVersions(),
     identities,
     configProfiles,
     providers,
@@ -74686,6 +74794,7 @@ Launching:
     --category <category=bool>   share or hide a category (repeatable)
     --share <path>, --hide <path>  share or hide one <category>/<path> entry (repeatable)
     --[no-]skip-permissions, --[no-]remote-control, --[no-]headroom, --[no-]track-usage
+    --claude-version <version>   run exactly this installed Claude Code version (not the highest)
     --[no-]wait                  with @pool:<name>, sleep until the earliest member returns when all are refused
     --native                     run the real claude with nothing from agent-shim applied (no other launch flag allowed)
 
@@ -75173,7 +75282,11 @@ function prepareLaunch(params) {
   } else if (params.farm !== void 0) {
     cascadeLaunch = flattenLayers(assembleCascade(params.farm.loadCascade(configProfileDecision.name, cliOverride)).layers, { home: params.farm.home }).launch;
   }
-  const discovered = params.resolveClaudeBinary();
+  const pinnedVersion = resolveClaudeVersion({ env, ...parsedArgv.claudeVersion === void 0 ? {} : { flag: parsedArgv.claudeVersion }, ...cascadeLaunch?.claudeVersion === void 0 ? {} : { cascade: cascadeLaunch.claudeVersion } });
+  const discovered = params.resolveClaudeBinary(pinnedVersion === void 0 ? void 0 : { version: pinnedVersion.version });
+  if (pinnedVersion !== void 0) {
+    log.info(`agent-shim: Claude Code ${pinnedVersion.version} (pinned by ${pinnedVersion.source})`);
+  }
   const resolvedFlags = resolveLaunchFlags({
     env,
     // A pool pick reads the usage the front door records, so a pool launch records its own unless something says otherwise.
@@ -75319,6 +75432,7 @@ function otherLaunchFlags(parsed) {
     ...parsed.identity === void 0 ? [] : ["@<identity> / --identity"],
     ...parsed.configProfile === void 0 ? [] : ["--config-profile"],
     ...parsed.provider === void 0 ? [] : [parsed.provider === false ? "--no-provider" : "--provider"],
+    ...parsed.claudeVersion === void 0 ? [] : ["--claude-version"],
     ...parsed.headroom === void 0 ? [] : ["--[no-]headroom"],
     ...parsed.trackUsage === void 0 ? [] : ["--[no-]track-usage"],
     ...parsed.skipPermissions === void 0 ? [] : ["--[no-]skip-permissions"],