@velum-labs/routekit-tool-claude 0.17.0 → 0.17.2

package/dist/install.d.ts

@@ -7,6 +7,8 @@ export type ClaudeInstallOwner = {
 };
 export type ClaudeInstallInput = {
     gatewayUrl: string;
+    /** Canonical RouteKit catalog ids permitted by the current model policy. */
+    models: readonly string[];
     owner: ClaudeInstallOwner;
     claudeConfigDir?: string;
 };

package/dist/install.js

@@ -6,9 +6,12 @@ import { SUBSCRIPTIONS } from "@velum-labs/routekit-registry";
 import { acquireLifecycleLock, trimTrailingSlashes, writeFileAtomic } from "@velum-labs/routekit-runtime";
 const MANAGED_ENV_KEYS = [
     "ANTHROPIC_BASE_URL",
+    "CLAUDE_CODE_ALWAYS_ENABLE_EFFORT"
+];
+const RETIRED_MANAGED_ENV_KEYS = [
+    "ANTHROPIC_AUTH_TOKEN",
     "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"
 ];
-const RETIRED_MANAGED_ENV_KEYS = ["ANTHROPIC_AUTH_TOKEN"];
 function reached(boundary) {
     // Deliberately not part of the package API: tests install a same-process
     // throw hook to model termination immediately after an atomic boundary.
@@ -91,6 +94,9 @@ function isStringRecord(value) {
     return (isRecord(value) &&
         Object.values(value).every((entry) => typeof entry === "string"));
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
 function isInstalledManifest(value) {
     return (isRecord(value) &&
         value.version === 2 &&
@@ -99,7 +105,11 @@ function isInstalledManifest(value) {
         isSnapshot(value.original) &&
         typeof value.exactRestoreEligible === "boolean" &&
         typeof value.installedContentHash === "string" &&
-        isStringRecord(value.managedEnvValues));
+        isStringRecord(value.managedEnvValues) &&
+        (value.managedPickerModels === undefined || isStringArray(value.managedPickerModels)) &&
+        (value.managedAvailableModels === undefined || value.managedAvailableModels === true) &&
+        (value.managedEnforceAvailableModels === undefined ||
+            value.managedEnforceAvailableModels === true));
 }
 function parseManifest(content, manifestPath) {
     let parsed;
@@ -159,9 +169,36 @@ function serialize(value) {
 function managedEnv(input) {
     return {
         ANTHROPIC_BASE_URL: trimTrailingSlashes(input.gatewayUrl),
-        CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1"
+        CLAUDE_CODE_ALWAYS_ENABLE_EFFORT: "1"
     };
 }
+const CLAUDE_PICKER_PREFIX = "anthropic.routekit.";
+function pickerModels(input) {
+    const models = new Set();
+    for (const model of input.models) {
+        if (typeof model !== "string" || model.length === 0) {
+            throw new Error("RouteKit's Claude picker catalog contains an invalid model id");
+        }
+        models.add(`${CLAUDE_PICKER_PREFIX}${model}`);
+    }
+    return [...models];
+}
+function availableModels(settings, configPath) {
+    if (settings.availableModels === undefined)
+        return undefined;
+    if (!isStringArray(settings.availableModels)) {
+        throw new Error(`the "availableModels" field in your Claude settings (${configPath}) must be an array of strings`);
+    }
+    return [...settings.availableModels];
+}
+function enforceAvailableModels(settings, configPath) {
+    if (settings.enforceAvailableModels === undefined)
+        return undefined;
+    if (typeof settings.enforceAvailableModels !== "boolean") {
+        throw new Error(`the "enforceAvailableModels" field in your Claude settings (${configPath}) must be a boolean`);
+    }
+    return settings.enforceAvailableModels;
+}
 function entryIfExists(path) {
     try {
         return lstatSync(path);
@@ -412,6 +449,10 @@ export async function installClaudeIntegration(input) {
         const settings = parseSettings(beforeSettings.content ?? "{}\n", configPath);
         const env = { ...(settings.env ?? {}) };
         const nextManaged = managedEnv(input);
+        const desiredPickerModels = pickerModels(input);
+        if (desiredPickerModels.length === 0) {
+            throw new Error("RouteKit's Claude picker catalog cannot be empty");
+        }
         if (previousManifest === undefined) {
             for (const key of MANAGED_ENV_KEYS) {
                 if (env[key] !== undefined) {
@@ -426,7 +467,33 @@ export async function installClaudeIntegration(input) {
         for (const key of removableKeys)
             delete env[key];
         Object.assign(env, nextManaged);
-        const nextSettings = { ...settings, env };
+        const currentPickerModels = availableModels(settings, configPath);
+        const priorManagedPickerModels = previousManifest?.managedPickerModels ?? [];
+        if (priorManagedPickerModels.some((model) => currentPickerModels === undefined || !currentPickerModels.includes(model))) {
+            throw new Error(`your Claude settings changed RouteKit-managed availableModels in ${configPath}; ` +
+                `restore those entries before rerunning the install command`);
+        }
+        const userPickerModels = (currentPickerModels ?? []).filter((model) => !priorManagedPickerModels.includes(model));
+        const nextManagedPickerModels = desiredPickerModels.filter((model) => !userPickerModels.includes(model));
+        const nextPickerModels = [...userPickerModels, ...nextManagedPickerModels];
+        const currentEnforceAvailableModels = enforceAvailableModels(settings, configPath);
+        if (previousManifest?.managedEnforceAvailableModels === true &&
+            currentEnforceAvailableModels !== true) {
+            throw new Error(`your Claude settings changed RouteKit-managed enforceAvailableModels in ${configPath}; ` +
+                "restore that value before rerunning the install command");
+        }
+        const nextManagedEnforceAvailableModels = previousManifest?.managedEnforceAvailableModels === true ||
+            currentEnforceAvailableModels === undefined
+            ? true
+            : undefined;
+        const nextSettings = {
+            ...settings,
+            env,
+            availableModels: nextPickerModels,
+            ...(nextManagedEnforceAvailableModels === true
+                ? { enforceAvailableModels: true }
+                : {})
+        };
         const nextContent = serialize(nextSettings);
         const targetSettings = snapshot(nextContent, 0o600);
         const exactRestoreEligible = previousManifest === undefined
@@ -440,7 +507,14 @@ export async function installClaudeIntegration(input) {
             original: previousManifest?.original ?? beforeSettings,
             exactRestoreEligible,
             installedContentHash: targetSettings.hash,
-            managedEnvValues: nextManaged
+            managedEnvValues: nextManaged,
+            managedPickerModels: nextManagedPickerModels,
+            ...(previousManifest?.managedAvailableModels === true || currentPickerModels === undefined
+                ? { managedAvailableModels: true }
+                : {}),
+            ...(nextManagedEnforceAvailableModels === true
+                ? { managedEnforceAvailableModels: true }
+                : {})
         };
         const pendingManifest = {
             version: 2,
@@ -467,7 +541,11 @@ export async function installClaudeIntegration(input) {
         return {
             configPath,
             action: previousManifest === undefined ? "installed" : "updated",
-            managedKeys: Object.keys(nextManaged)
+            managedKeys: [
+                ...Object.keys(nextManaged),
+                "availableModels",
+                ...(nextManagedEnforceAvailableModels === true ? ["enforceAvailableModels"] : [])
+            ]
         };
     });
 }
@@ -521,6 +599,21 @@ export async function uninstallClaudeIntegration(input) {
                 delete next.env;
             else
                 next.env = env;
+            const currentPickerModels = availableModels(settings, configPath);
+            if (currentPickerModels !== undefined) {
+                const remainingPickerModels = currentPickerModels.filter((model) => !(installed.managedPickerModels ?? []).includes(model));
+                if (installed.managedAvailableModels === true && remainingPickerModels.length === 0) {
+                    delete next.availableModels;
+                }
+                else {
+                    next.availableModels = remainingPickerModels;
+                }
+            }
+            const currentEnforceAvailableModels = enforceAvailableModels(settings, configPath);
+            if (installed.managedEnforceAvailableModels === true &&
+                currentEnforceAvailableModels === true) {
+                delete next.enforceAvailableModels;
+            }
             targetSettings = snapshot(serialize(next), beforeSettings.mode);
         }
         else {

package/dist/launch.js

@@ -1,22 +1,16 @@
-import { EFFORT_QUALIFIED_MODEL_CODEC, effortQualifiedClientModel } from "@velum-labs/routekit-contracts";
 import { spawnTool } from "@velum-labs/routekit-runtime";
 export function claudeEnv(gatewayUrl, authToken) {
     return {
         ANTHROPIC_BASE_URL: gatewayUrl,
         ANTHROPIC_AUTH_TOKEN: authToken ?? "routekit",
-        CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1",
+        CLAUDE_CODE_ALWAYS_ENABLE_EFFORT: "1",
         ...(process.env.CLAUDE_CONFIG_DIR !== undefined
             ? { CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR }
             : {})
     };
 }
 export function claudeModelId(modelId) {
-    const pickerId = modelId.startsWith("claude-code/")
-        ? modelId.slice("claude-code/".length)
-        : modelId;
-    return pickerId.startsWith("claude") || pickerId.startsWith("anthropic")
-        ? pickerId
-        : `claude-${pickerId}`;
+    return `anthropic.routekit.${modelId}`;
 }
 /** Serialize host-authored profiles once into Claude's session agent format. */
 export function claudeAgentsJson(profiles) {
@@ -35,10 +29,16 @@ function hasAgentsArg(args) {
 function hasModelArg(args) {
     return args.some((arg) => arg === "--model" || arg.startsWith("--model="));
 }
+function hasEffortArg(args) {
+    return args.some((arg) => arg === "--effort" || arg.startsWith("--effort="));
+}
 export function claudeLaunchArgs(ctx) {
     const args = [...ctx.spec.args];
     if (!hasModelArg(args)) {
-        args.unshift("--model", effortQualifiedClientModel(claudeModelId(ctx.spec.defaultModel), ctx.spec.reasoning, EFFORT_QUALIFIED_MODEL_CODEC));
+        args.unshift("--model", claudeModelId(ctx.spec.defaultModel));
+        if (ctx.spec.reasoning?.mode === "effort" && !hasEffortArg(args)) {
+            args.unshift("--effort", ctx.spec.reasoning.effort);
+        }
     }
     const profiles = ctx.spec.agentProfiles ?? [];
     if (profiles.length > 0 && !hasAgentsArg(args)) {

package/dist/test/install.test.js

@@ -18,6 +18,7 @@ const OWNER = {
 function install(configDirectory, gatewayUrl = "http://127.0.0.1:9999/", _authToken) {
     return installClaudeIntegration({
         gatewayUrl,
+        models: ["openai/mock-model"],
         owner: OWNER,
         claudeConfigDir: configDirectory
     });
@@ -32,11 +33,16 @@ test("Claude managed install updates and restores the exact original settings",
         assert.equal(installed.action, "installed");
         assert.deepEqual(installed.managedKeys.sort(), [
             "ANTHROPIC_BASE_URL",
-            "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"
+            "CLAUDE_CODE_ALWAYS_ENABLE_EFFORT",
+            "availableModels",
+            "enforceAvailableModels"
         ]);
         const settings = JSON.parse(readFileSync(configPath, "utf8"));
         assert.deepEqual(settings.permissions, { allow: ["Bash(git status)"] });
         assert.equal(settings.env.ANTHROPIC_BASE_URL, "http://127.0.0.1:9999");
+        assert.equal(settings.env.CLAUDE_CODE_ALWAYS_ENABLE_EFFORT, "1");
+        assert.deepEqual(settings.availableModels, ["anthropic.routekit.openai/mock-model"]);
+        assert.equal(settings.enforceAvailableModels, true);
         assert.equal("ANTHROPIC_AUTH_TOKEN" in settings.env, false);
         assert.equal(statSync(configPath).mode & 0o777, 0o600);
         const manifestPath = join(configDirectory, `.${OWNER.id}-integration.json`);
@@ -83,6 +89,48 @@ test("Claude uninstall preserves user edits made after install", async () => {
         rmSync(configDirectory, { recursive: true, force: true });
     }
 });
+test("Claude install merges and refreshes only RouteKit-owned picker entries", async () => {
+    const configDirectory = mkdtempSync(join(tmpdir(), "routekit-claude-picker-merge-"));
+    const configPath = join(configDirectory, "settings.json");
+    writeFileSync(configPath, `${JSON.stringify({
+        availableModels: ["claude-opus-4-6"],
+        enforceAvailableModels: false
+    })}\n`);
+    try {
+        await installClaudeIntegration({
+            gatewayUrl: "http://127.0.0.1:9999",
+            models: ["openai/gpt-5.6", "codex/gpt-5.6"],
+            owner: OWNER,
+            claudeConfigDir: configDirectory
+        });
+        let settings = JSON.parse(readFileSync(configPath, "utf8"));
+        assert.deepEqual(settings.availableModels, [
+            "claude-opus-4-6",
+            "anthropic.routekit.openai/gpt-5.6",
+            "anthropic.routekit.codex/gpt-5.6"
+        ]);
+        assert.equal(settings.enforceAvailableModels, false);
+        await installClaudeIntegration({
+            gatewayUrl: "http://127.0.0.1:9999",
+            models: ["openai/gpt-5.7"],
+            owner: OWNER,
+            claudeConfigDir: configDirectory
+        });
+        settings = JSON.parse(readFileSync(configPath, "utf8"));
+        assert.deepEqual(settings.availableModels, [
+            "claude-opus-4-6",
+            "anthropic.routekit.openai/gpt-5.7"
+        ]);
+        await uninstallClaudeIntegration({ ownerId: OWNER.id, claudeConfigDir: configDirectory });
+        assert.deepEqual(JSON.parse(readFileSync(configPath, "utf8")), {
+            availableModels: ["claude-opus-4-6"],
+            enforceAvailableModels: false
+        });
+    }
+    finally {
+        rmSync(configDirectory, { recursive: true, force: true });
+    }
+});
 test("Claude install refuses malformed settings and user-owned env conflicts", async () => {
     const configDirectory = mkdtempSync(join(tmpdir(), "routekit-claude-conflict-"));
     const configPath = join(configDirectory, "settings.json");
@@ -121,6 +169,7 @@ function spawnBlockedInstall(configDirectory, boundary) {
     };
     await installClaudeIntegration({
       gatewayUrl: "http://127.0.0.1:9999",
+      models: ["openai/mock-model"],
       owner: ${JSON.stringify(OWNER)},
       claudeConfigDir: configDirectory
     });
@@ -287,11 +336,13 @@ test("explicit config directory wins over CLAUDE_CONFIG_DIR, which wins over the
         process.env.CLAUDE_CONFIG_DIR = environmentDirectory;
         const fromEnvironment = await installClaudeIntegration({
             gatewayUrl: "http://127.0.0.1:9999",
+            models: ["openai/mock-model"],
             owner: OWNER
         });
         assert.equal(fromEnvironment.configPath, join(environmentDirectory, "settings.json"));
         const explicit = await installClaudeIntegration({
             gatewayUrl: "http://127.0.0.1:9999",
+            models: ["openai/mock-model"],
             owner: OWNER,
             claudeConfigDir: explicitDirectory
         });
@@ -361,6 +412,8 @@ test("updating a v2 install removes an owned token without persisting its replac
         const settings = JSON.parse(readFileSync(configPath, "utf8"));
         const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
         assert.equal("ANTHROPIC_AUTH_TOKEN" in settings.env, false);
+        assert.equal("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY" in settings.env, false);
+        assert.equal(settings.env.CLAUDE_CODE_ALWAYS_ENABLE_EFFORT, "1");
         assert.equal("ANTHROPIC_AUTH_TOKEN" in manifest.managedEnvValues, false);
         assert.equal(readFileSync(manifestPath, "utf8").includes("old-secret"), false);
         assert.equal(readFileSync(manifestPath, "utf8").includes("new-secret"), false);

package/dist/test/launch.test.js

@@ -30,14 +30,14 @@ test("claudeAgentsJson serializes generic profiles", () => {
         reviewer: {
             description: "Review changes.",
             prompt: "Return findings.",
-            model: "claude-opaque-model"
+            model: "anthropic.routekit.opaque-model"
         }
     });
 });
-test("Claude launcher projects claude-code models to native picker ids", () => {
+test("Claude launcher projects RouteKit models to native picker ids", () => {
     assert.deepEqual(claudeLaunchArgs(context([], [], "claude-code/claude-sonnet-4-6")), [
         "--model",
-        "claude-sonnet-4-6"
+        "anthropic.routekit.claude-code/claude-sonnet-4-6"
     ]);
     assert.deepEqual(JSON.parse(claudeAgentsJson([
         {
@@ -56,12 +56,12 @@ test("Claude launcher projects claude-code models to native picker ids", () => {
         native: {
             description: "Use the subscription pool.",
             prompt: "Review.",
-            model: "claude-opus-4-8"
+            model: "anthropic.routekit.claude-code/claude-opus-4-8"
         },
         cross: {
             description: "Use Codex.",
             prompt: "Review.",
-            model: "claude-codex/gpt-5.5"
+            model: "anthropic.routekit.codex/gpt-5.5"
         }
     });
 });
@@ -80,13 +80,21 @@ test("Claude launcher forwards an explicit isolated config directory", () => {
 });
 test("claudeLaunchArgs adds profiles unless the user supplied agents", () => {
     const args = claudeLaunchArgs(context(["--verbose"]));
-    assert.deepEqual(args.slice(0, 4), ["--model", "claude-opaque-model", "--verbose", "--agents"]);
+    assert.deepEqual(args.slice(0, 4), [
+        "--model",
+        "anthropic.routekit.opaque-model",
+        "--verbose",
+        "--agents"
+    ]);
     assert.deepEqual(claudeLaunchArgs(context(["--agents={}"])), [
         "--model",
-        "claude-opaque-model",
+        "anthropic.routekit.opaque-model",
         "--agents={}"
     ]);
-    assert.deepEqual(claudeLaunchArgs(context([], [])), ["--model", "claude-opaque-model"]);
+    assert.deepEqual(claudeLaunchArgs(context([], [])), [
+        "--model",
+        "anthropic.routekit.opaque-model"
+    ]);
     assert.deepEqual(claudeLaunchArgs(context(["--model", "claude-user-selected"], [])), [
         "--model",
         "claude-user-selected"
@@ -100,7 +108,12 @@ test("Claude launcher projects validated effort onto the picker model id", () =>
             reasoning: { mode: "effort", effort: "high" }
         }
     };
-    assert.deepEqual(claudeLaunchArgs(withEffort), ["--model", "claude-sonnet-4-6:high"]);
+    assert.deepEqual(claudeLaunchArgs(withEffort), [
+        "--effort",
+        "high",
+        "--model",
+        "anthropic.routekit.claude-code/claude-sonnet-4-6"
+    ]);
     const crossProvider = {
         ...context([], [], "codex/gpt-5.5"),
         spec: {
@@ -108,7 +121,12 @@ test("Claude launcher projects validated effort onto the picker model id", () =>
             reasoning: { mode: "effort", effort: "deep" }
         }
     };
-    assert.deepEqual(claudeLaunchArgs(crossProvider), ["--model", "claude-codex/gpt-5.5:deep"]);
+    assert.deepEqual(claudeLaunchArgs(crossProvider), [
+        "--effort",
+        "deep",
+        "--model",
+        "anthropic.routekit.codex/gpt-5.5"
+    ]);
     assert.deepEqual(claudeLaunchArgs({
         ...withEffort,
         spec: {
@@ -120,7 +138,7 @@ test("Claude launcher projects validated effort onto the picker model id", () =>
 test("Claude launches keep native session flags under native-client control", () => {
     assert.deepEqual(claudeLaunchArgs(context(["--continue", "--resume", "native-id"], [])), [
         "--model",
-        "claude-opaque-model",
+        "anthropic.routekit.opaque-model",
         "--continue",
         "--resume",
         "native-id"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-tool-claude",
   "private": false,
-  "version": "0.17.0",
+  "version": "0.17.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -28,11 +28,11 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.198",
     "zod": "4.4.3",
-    "@velum-labs/routekit-contracts": "0.17.0",
-    "@velum-labs/routekit-harness-core": "0.17.0",
-    "@velum-labs/routekit-registry": "0.17.0",
-    "@velum-labs/routekit-runtime": "0.17.0",
-    "@velum-labs/routekit-tools": "0.17.0"
+    "@velum-labs/routekit-contracts": "0.17.2",
+    "@velum-labs/routekit-harness-core": "0.17.2",
+    "@velum-labs/routekit-registry": "0.17.2",
+    "@velum-labs/routekit-runtime": "0.17.2",
+    "@velum-labs/routekit-tools": "0.17.2"
   },
   "keywords": [
     "llm",