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

package/README.md

@@ -5,6 +5,7 @@ Product-neutral Claude Code launcher and canonical harness driver.
 ## Architecture
 
 This package owns the one Claude Code profile serializer, launcher, and driver.
+The native Claude client owns its transcript store and session lifecycle.
 
 ## Usage
 
@@ -18,3 +19,9 @@ import { claudeTool } from "@velum-labs/routekit-tool-claude";
 
 - CLI reference: [../../docs/cli.md](../../docs/cli.md)
 - Maintainer reference: [../../docs/typescript-reference.md](../../docs/typescript-reference.md)
+
+## Native client ownership
+
+RouteKit does not observe, store, resume, or delete Claude sessions. Use Claude's
+native history and resume/delete commands directly; launcher arguments after `--`
+are forwarded to Claude unchanged.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { ToolIntegration } from "@velum-labs/routekit-tools";
 export declare const claudeTool: ToolIntegration;
-export { claudeDriverConfigSchema, createClaudeDriver } from "./driver.js";
 export type { ClaudeDriverConfig, ClaudeDriverOptions, ClaudeQueryFn } from "./driver.js";
-export { installClaudeIntegration, uninstallClaudeIntegration } from "./install.js";
+export { claudeDriverConfigSchema, createClaudeDriver } from "./driver.js";
 export type { ClaudeInstallInput, ClaudeInstallOwner, ClaudeInstallResult } from "./install.js";
+export { claudeIntegrationConfigPath, installClaudeIntegration, uninstallClaudeIntegration } from "./install.js";
 export { claudeAgentsJson, claudeEnv, claudeLaunchArgs, launchClaude } from "./launch.js";

package/dist/index.js

@@ -30,5 +30,5 @@ export const claudeTool = {
     }
 };
 export { claudeDriverConfigSchema, createClaudeDriver } from "./driver.js";
-export { installClaudeIntegration, uninstallClaudeIntegration } from "./install.js";
+export { claudeIntegrationConfigPath, installClaudeIntegration, uninstallClaudeIntegration } from "./install.js";
 export { claudeAgentsJson, claudeEnv, claudeLaunchArgs, launchClaude } from "./launch.js";

package/dist/install.d.ts

@@ -7,7 +7,6 @@ export type ClaudeInstallOwner = {
 };
 export type ClaudeInstallInput = {
     gatewayUrl: string;
-    authToken?: string;
     owner: ClaudeInstallOwner;
     claudeConfigDir?: string;
 };
@@ -16,6 +15,7 @@ export type ClaudeInstallResult = {
     action: "installed" | "updated";
     managedKeys: string[];
 };
+export declare function claudeIntegrationConfigPath(claudeConfigDir?: string): string;
 export declare function installClaudeIntegration(input: ClaudeInstallInput): Promise<ClaudeInstallResult>;
 export declare function uninstallClaudeIntegration(input: {
     ownerId: string;

package/dist/install.js

@@ -6,9 +6,9 @@ import { SUBSCRIPTIONS } from "@velum-labs/routekit-registry";
 import { acquireLifecycleLock, trimTrailingSlashes, writeFileAtomic } from "@velum-labs/routekit-runtime";
 const MANAGED_ENV_KEYS = [
     "ANTHROPIC_BASE_URL",
-    "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.
@@ -31,14 +31,16 @@ function defaultClaudeConfigDir() {
         : registryPath;
     return dirname(configPath);
 }
+export function claudeIntegrationConfigPath(claudeConfigDir) {
+    return join(claudeConfigDir ?? process.env.CLAUDE_CONFIG_DIR ?? defaultClaudeConfigDir(), "settings.json");
+}
 function paths(input) {
     assertSafeOwnerId(input.ownerId);
-    const configDirectory = input.claudeConfigDir ??
-        process.env.CLAUDE_CONFIG_DIR ??
-        defaultClaudeConfigDir();
+    const configPath = claudeIntegrationConfigPath(input.claudeConfigDir);
+    const configDirectory = dirname(configPath);
     return {
         configDirectory,
-        configPath: join(configDirectory, "settings.json"),
+        configPath,
         manifestPath: join(configDirectory, `.${input.ownerId}-integration.json`),
         lockPath: join(configDirectory, ".routekit-claude-integration.lock")
     };
@@ -157,7 +159,6 @@ function serialize(value) {
 function managedEnv(input) {
     return {
         ANTHROPIC_BASE_URL: trimTrailingSlashes(input.gatewayUrl),
-        ANTHROPIC_AUTH_TOKEN: input.authToken ?? "routekit",
         CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1"
     };
 }
@@ -283,14 +284,20 @@ function recoverPending(manifest, configPath, manifestPath) {
     assertRegularFileIfExists(manifestPath, "Claude ownership metadata");
     rmSync(manifestPath, { force: true });
 }
-function assertManagedValuesUnchanged(env, managedEnvValues, configPath) {
+function removableManagedKeys(env, managedEnvValues, configPath) {
+    const removable = [];
     for (const [key, expected] of Object.entries(managedEnvValues)) {
         const accepted = Array.isArray(expected) ? expected : [expected];
-        if (!accepted.includes(String(env[key]))) {
-            throw new Error(`your Claude settings changed RouteKit-managed env.${key} in ${configPath}; ` +
-                `remove or restore that value before rerunning the install command`);
+        if (accepted.includes(String(env[key]))) {
+            removable.push(key);
+            continue;
         }
+        if (RETIRED_MANAGED_ENV_KEYS.includes(key))
+            continue;
+        throw new Error(`your Claude settings changed RouteKit-managed env.${key} in ${configPath}; ` +
+            `remove or restore that value before rerunning the install command`);
     }
+    return removable;
 }
 const CLAUDE_LOCK_TIMEOUT_MS = 5_000;
 async function withConfigLock(resolved, operation) {
@@ -320,8 +327,31 @@ function migrateLegacyManifest(manifest, current, configPath, manifestPath) {
         rmSync(manifestPath, { force: true });
         return undefined;
     }
-    if (current.hash === null ||
-        !manifest.installedContentHashes.includes(current.hash)) {
+    const currentHash = current.hash;
+    if (currentHash === null) {
+        throw new Error(`RouteKit's legacy Claude ownership metadata (${manifestPath}) cannot ` +
+            "match missing settings; refusing to overwrite them");
+    }
+    let recognizedContent = manifest.installedContentHashes.includes(currentHash);
+    if (!recognizedContent) {
+        for (const key of RETIRED_MANAGED_ENV_KEYS) {
+            const accepted = manifest.managedEnvValues[key];
+            const value = env[key];
+            if (accepted === undefined || accepted.includes(String(value)))
+                continue;
+            for (const candidate of accepted) {
+                const candidateSettings = {
+                    ...settings,
+                    env: { ...env, [key]: candidate }
+                };
+                if (manifest.installedContentHashes.includes(hash(serialize(candidateSettings)))) {
+                    recognizedContent = true;
+                    break;
+                }
+            }
+        }
+    }
+    if (!recognizedContent) {
         throw new Error(`RouteKit's legacy Claude ownership metadata (${manifestPath}) does not ` +
             "match the current settings; refusing to overwrite them");
     }
@@ -329,6 +359,8 @@ function migrateLegacyManifest(manifest, current, configPath, manifestPath) {
     for (const [key, accepted] of Object.entries(manifest.managedEnvValues)) {
         const value = env[key];
         if (value === undefined || !accepted.includes(String(value))) {
+            if (RETIRED_MANAGED_ENV_KEYS.includes(key))
+                continue;
             throw new Error(`RouteKit's legacy Claude ownership metadata (${manifestPath}) cannot ` +
                 `safely identify the current env.${key} value; refusing to overwrite settings`);
         }
@@ -339,8 +371,9 @@ function migrateLegacyManifest(manifest, current, configPath, manifestPath) {
         state: "installed",
         ownerId: manifest.ownerId,
         original: snapshot(manifest.originalContent, null),
-        exactRestoreEligible: manifest.exactRestoreEligible,
-        installedContentHash: current.hash,
+        exactRestoreEligible: manifest.exactRestoreEligible &&
+            manifest.installedContentHashes.includes(currentHash),
+        installedContentHash: currentHash,
         managedEnvValues: selectedValues
     };
     writeManifest(manifestPath, migrated);
@@ -387,12 +420,11 @@ export async function installClaudeIntegration(input) {
                 }
             }
         }
-        else {
-            assertManagedValuesUnchanged(env, previousManifest.managedEnvValues, configPath);
-        }
-        for (const key of Object.keys(previousManifest?.managedEnvValues ?? {})) {
+        const removableKeys = previousManifest === undefined
+            ? []
+            : removableManagedKeys(env, previousManifest.managedEnvValues, configPath);
+        for (const key of removableKeys)
             delete env[key];
-        }
         Object.assign(env, nextManaged);
         const nextSettings = { ...settings, env };
         const nextContent = serialize(nextSettings);

package/dist/test/install.test.js

@@ -15,10 +15,9 @@ const OWNER = {
     uninstallCommand: "example uninstall claude",
     startCommand: "example serve"
 };
-function install(configDirectory, gatewayUrl = "http://127.0.0.1:9999/", authToken) {
+function install(configDirectory, gatewayUrl = "http://127.0.0.1:9999/", _authToken) {
     return installClaudeIntegration({
         gatewayUrl,
-        ...(authToken !== undefined ? { authToken } : {}),
         owner: OWNER,
         claudeConfigDir: configDirectory
     });
@@ -32,21 +31,23 @@ test("Claude managed install updates and restores the exact original settings",
         const installed = await install(configDirectory, "http://127.0.0.1:9999/", "gateway-secret");
         assert.equal(installed.action, "installed");
         assert.deepEqual(installed.managedKeys.sort(), [
-            "ANTHROPIC_AUTH_TOKEN",
             "ANTHROPIC_BASE_URL",
             "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"
         ]);
         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.ANTHROPIC_AUTH_TOKEN, "gateway-secret");
+        assert.equal("ANTHROPIC_AUTH_TOKEN" in settings.env, false);
         assert.equal(statSync(configPath).mode & 0o777, 0o600);
         const manifestPath = join(configDirectory, `.${OWNER.id}-integration.json`);
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
         assert.deepEqual({
-            version: JSON.parse(readFileSync(manifestPath, "utf8")).version,
-            state: JSON.parse(readFileSync(manifestPath, "utf8")).state,
+            version: manifest.version,
+            state: manifest.state,
             mode: statSync(manifestPath).mode & 0o777
         }, { version: 2, state: "installed", mode: 0o600 });
+        assert.equal("ANTHROPIC_AUTH_TOKEN" in manifest.managedEnvValues, false);
+        assert.equal(readFileSync(manifestPath, "utf8").includes("gateway-secret"), false);
         assert.equal((await install(configDirectory, "http://127.0.0.1:8888", "updated-secret")).action, "updated");
         assert.equal(JSON.parse(readFileSync(configPath, "utf8")).env.ANTHROPIC_BASE_URL, "http://127.0.0.1:8888");
         assert.equal((await uninstallClaudeIntegration({
@@ -324,6 +325,71 @@ test("install never persists or takes ownership of ANTHROPIC_MODEL", async () =>
         rmSync(configDirectory, { recursive: true, force: true });
     }
 });
+test("updating a v2 install removes an owned token without persisting its replacement", async () => {
+    const configDirectory = mkdtempSync(join(tmpdir(), "routekit-claude-v2-token-"));
+    const configPath = join(configDirectory, "settings.json");
+    const manifestPath = join(configDirectory, `.${OWNER.id}-integration.json`);
+    const original = '{"theme":"light"}\n';
+    const installed = `${JSON.stringify({
+        theme: "light",
+        env: {
+            ANTHROPIC_BASE_URL: "http://127.0.0.1:7000",
+            ANTHROPIC_AUTH_TOKEN: "old-secret",
+            CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1"
+        }
+    }, null, 2)}\n`;
+    writeFileSync(configPath, installed);
+    writeFileSync(manifestPath, `${JSON.stringify({
+        version: 2,
+        state: "installed",
+        ownerId: OWNER.id,
+        original: {
+            content: original,
+            mode: 0o644,
+            hash: createHash("sha256").update(original).digest("hex")
+        },
+        exactRestoreEligible: true,
+        installedContentHash: createHash("sha256").update(installed).digest("hex"),
+        managedEnvValues: {
+            ANTHROPIC_BASE_URL: "http://127.0.0.1:7000",
+            ANTHROPIC_AUTH_TOKEN: "old-secret",
+            CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1"
+        }
+    }, null, 2)}\n`);
+    try {
+        await install(configDirectory, "http://127.0.0.1:7001", "new-secret");
+        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("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);
+    }
+    finally {
+        rmSync(configDirectory, { recursive: true, force: true });
+    }
+});
+test("updating a v2 install preserves a user-edited token", async () => {
+    const configDirectory = mkdtempSync(join(tmpdir(), "routekit-claude-v2-user-token-"));
+    const configPath = join(configDirectory, "settings.json");
+    try {
+        await install(configDirectory, "http://127.0.0.1:7000");
+        const manifestPath = join(configDirectory, `.${OWNER.id}-integration.json`);
+        const settings = JSON.parse(readFileSync(configPath, "utf8"));
+        settings.env.ANTHROPIC_AUTH_TOKEN = "user-secret";
+        writeFileSync(configPath, `${JSON.stringify(settings, null, 2)}\n`);
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        manifest.managedEnvValues.ANTHROPIC_AUTH_TOKEN = "old-secret";
+        writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+        await install(configDirectory, "http://127.0.0.1:7001", "new-secret");
+        assert.equal(JSON.parse(readFileSync(configPath, "utf8")).env.ANTHROPIC_AUTH_TOKEN, "user-secret");
+        assert.equal("ANTHROPIC_AUTH_TOKEN" in
+            JSON.parse(readFileSync(manifestPath, "utf8")).managedEnvValues, false);
+    }
+    finally {
+        rmSync(configDirectory, { recursive: true, force: true });
+    }
+});
 test("updating a legacy install removes its formerly managed ANTHROPIC_MODEL", async () => {
     const configDirectory = mkdtempSync(join(tmpdir(), "routekit-claude-legacy-model-"));
     const configPath = join(configDirectory, "settings.json");
@@ -414,12 +480,14 @@ test("install migrates interrupted v1 updates before and after settings", async
             assert.equal(result.action, "updated");
             const settings = JSON.parse(readFileSync(configPath, "utf8"));
             assert.equal(settings.env.ANTHROPIC_BASE_URL, "http://127.0.0.1:7002");
-            assert.equal(settings.env.ANTHROPIC_AUTH_TOKEN, "final-token");
+            assert.equal("ANTHROPIC_AUTH_TOKEN" in settings.env, false);
             assert.equal("ANTHROPIC_MODEL" in settings.env, false);
-            assert.deepEqual({
-                version: JSON.parse(readFileSync(manifestPath, "utf8")).version,
-                state: JSON.parse(readFileSync(manifestPath, "utf8")).state
-            }, { version: 2, state: "installed" });
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            assert.deepEqual({ version: manifest.version, state: manifest.state }, { version: 2, state: "installed" });
+            assert.equal("ANTHROPIC_AUTH_TOKEN" in manifest.managedEnvValues, false);
+            assert.equal(readFileSync(manifestPath, "utf8").includes("final-token"), false);
+            assert.equal(readFileSync(manifestPath, "utf8").includes("before-token"), false);
+            assert.equal(readFileSync(manifestPath, "utf8").includes("after-token"), false);
             await uninstallClaudeIntegration({
                 ownerId: OWNER.id,
                 claudeConfigDir: configDirectory

package/dist/test/launch.test.js

@@ -35,7 +35,10 @@ test("claudeAgentsJson serializes generic profiles", () => {
     });
 });
 test("Claude launcher projects claude-code models to native picker ids", () => {
-    assert.deepEqual(claudeLaunchArgs(context([], [], "claude-code/claude-sonnet-4-6")), ["--model", "claude-sonnet-4-6"]);
+    assert.deepEqual(claudeLaunchArgs(context([], [], "claude-code/claude-sonnet-4-6")), [
+        "--model",
+        "claude-sonnet-4-6"
+    ]);
     assert.deepEqual(JSON.parse(claudeAgentsJson([
         {
             id: "native",
@@ -77,22 +80,17 @@ 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", "claude-opaque-model", "--verbose", "--agents"]);
     assert.deepEqual(claudeLaunchArgs(context(["--agents={}"])), [
         "--model",
         "claude-opaque-model",
         "--agents={}"
     ]);
-    assert.deepEqual(claudeLaunchArgs(context([], [])), [
+    assert.deepEqual(claudeLaunchArgs(context([], [])), ["--model", "claude-opaque-model"]);
+    assert.deepEqual(claudeLaunchArgs(context(["--model", "claude-user-selected"], [])), [
         "--model",
-        "claude-opaque-model"
+        "claude-user-selected"
     ]);
-    assert.deepEqual(claudeLaunchArgs(context(["--model", "claude-user-selected"], [])), ["--model", "claude-user-selected"]);
 });
 test("Claude launcher projects validated effort onto the picker model id", () => {
     const withEffort = {
@@ -102,10 +100,7 @@ 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), ["--model", "claude-sonnet-4-6:high"]);
     const crossProvider = {
         ...context([], [], "codex/gpt-5.5"),
         spec: {
@@ -113,10 +108,7 @@ 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), ["--model", "claude-codex/gpt-5.5:deep"]);
     assert.deepEqual(claudeLaunchArgs({
         ...withEffort,
         spec: {
@@ -125,3 +117,12 @@ test("Claude launcher projects validated effort onto the picker model id", () =>
         }
     }), ["--model", "claude-user-selected"]);
 });
+test("Claude launches keep native session flags under native-client control", () => {
+    assert.deepEqual(claudeLaunchArgs(context(["--continue", "--resume", "native-id"], [])), [
+        "--model",
+        "claude-opaque-model",
+        "--continue",
+        "--resume",
+        "native-id"
+    ]);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-tool-claude",
   "private": false,
-  "version": "0.16.8",
+  "version": "0.17.0",
   "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.16.8",
-    "@velum-labs/routekit-harness-core": "0.16.8",
-    "@velum-labs/routekit-registry": "0.16.8",
-    "@velum-labs/routekit-runtime": "0.16.8",
-    "@velum-labs/routekit-tools": "0.16.8"
+    "@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"
   },
   "keywords": [
     "llm",