offrouter-adapter-claude 0.0.0

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "offrouter-adapter-claude",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --root ../.. packages/adapter-claude/src"
+  },
+  "dependencies": {
+    "offrouter-core": "0.0.0",
+    "zod": "0.0.0"
+  }
+}

package/package.json.bak

@@ -0,0 +1,16 @@
+{
+  "name": "offrouter-adapter-claude",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --root ../.. packages/adapter-claude/src"
+  },
+  "dependencies": {
+    "offrouter-core": "*",
+    "zod": "^3.23.0"
+  },
+  "private": true
+}

package/src/hooks/pre-tool-use.ts

@@ -0,0 +1,19 @@
+/**
+ * Claude Code PreToolUse hook placeholder for OffRouter V1.
+ *
+ * No enforcement behavior is claimed here. Future milestones may add
+ * audit/policy guards; V1 only reserves the export surface.
+ */
+
+export interface PreToolUseHookOutput {
+  /** Placeholder: PreToolUse decisions are not produced in V1. */
+  continue?: boolean;
+}
+
+/**
+ * No-op placeholder for the future PreToolUse hook surface.
+ */
+export function handlePreToolUse(input: unknown): PreToolUseHookOutput {
+  void input;
+  return {};
+}

package/src/hooks/user-prompt-submit.test.ts

@@ -0,0 +1,222 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import type { PolicyConfig, ProviderCandidate } from "offrouter-core";
+import {
+  handleUserPromptSubmit,
+  runUserPromptSubmitHook,
+} from "./user-prompt-submit.js";
+
+const fixturePath = fileURLToPath(
+  new URL(
+    "../../../../tests/fixtures/claude/user-prompt-submit.json",
+    import.meta.url,
+  ),
+);
+
+const policy: PolicyConfig = {
+  allowlistedProfiles: ["claude-personal"],
+  deniedProfilePatterns: ["*-work"],
+};
+
+const candidates: ProviderCandidate[] = [
+  {
+    providerId: "fake",
+    modelId: "fake-coder",
+    displayName: "Fake Coder",
+    authTier: "api-key",
+    authScope: "third-party",
+    health: "healthy",
+    supportsTools: true,
+    supportsStreaming: true,
+    supportsJson: true,
+    supportsImages: false,
+    estimatedCostUsd: 0,
+  },
+];
+
+async function fixture(): Promise<string> {
+  return readFile(fixturePath, "utf8");
+}
+
+function parseStdout(stdout: string): Record<string, unknown> {
+  expect(stdout.trim()).toBe(stdout);
+  expect(stdout).not.toContain("\n\n");
+  return JSON.parse(stdout) as Record<string, unknown>;
+}
+
+describe("Claude UserPromptSubmit hook", () => {
+  it("injects additionalContext for an allowed claude-personal profile", async () => {
+    const input = JSON.parse(await fixture());
+
+    const output = handleUserPromptSubmit(input, {
+      profile: "claude-personal",
+      policy,
+      candidates,
+      trustedWorkspace: true,
+      routeConstraints: { allowApiKeyFallback: true },
+    });
+
+    expect(output.decision).toBeUndefined();
+    expect(output.hookSpecificOutput).toMatchObject({
+      hookEventName: "UserPromptSubmit",
+    });
+    expect(output.hookSpecificOutput?.additionalContext).toContain(
+      "Claude Code's primary model is unchanged in V1; OffRouter routes delegated work.",
+    );
+    expect(output.hookSpecificOutput?.additionalContext).toContain(
+      "fake/fake-coder",
+    );
+    expect(output.hookSpecificOutput?.additionalContext).not.toContain(
+      input.prompt,
+    );
+  });
+
+  it("blocks a denied claude-work profile with a clear reason", async () => {
+    const input = JSON.parse(await fixture());
+
+    const output = handleUserPromptSubmit(input, {
+      profile: "claude-work",
+      policy,
+      candidates,
+      trustedWorkspace: true,
+      routeConstraints: { allowApiKeyFallback: true },
+    });
+
+    expect(output).toMatchObject({
+      decision: "block",
+    });
+    expect(output.reason).toContain("claude-work");
+    expect(output.reason).toContain("denied");
+  });
+
+  it("blocks an unallowlisted profile with a clear reason", async () => {
+    const input = JSON.parse(await fixture());
+
+    const output = handleUserPromptSubmit(input, {
+      profile: "claude-personal-extra",
+      policy,
+      candidates,
+      trustedWorkspace: true,
+      routeConstraints: { allowApiKeyFallback: true },
+    });
+
+    expect(output).toMatchObject({
+      decision: "block",
+    });
+    expect(output.reason).toContain("claude-personal-extra");
+    expect(output.reason).toContain("not allowlisted");
+  });
+
+  it("does not route from an untrusted workspace by default", async () => {
+    const input = JSON.parse(await fixture());
+
+    const output = handleUserPromptSubmit(input, {
+      profile: "claude-personal",
+      policy,
+      candidates,
+      routeConstraints: { allowApiKeyFallback: true },
+    });
+
+    expect(output.decision).toBeUndefined();
+    expect(output.hookSpecificOutput?.additionalContext).toContain(
+      "could not select",
+    );
+    expect(output.hookSpecificOutput?.additionalContext).toContain("untrusted");
+    expect(output.hookSpecificOutput?.additionalContext).not.toContain(
+      "fake/fake-coder",
+    );
+  });
+
+  it("does not recommend API-key fallback unless explicitly allowed", async () => {
+    const input = JSON.parse(await fixture());
+
+    const output = handleUserPromptSubmit(input, {
+      profile: "claude-personal",
+      policy,
+      candidates,
+      trustedWorkspace: true,
+    });
+
+    expect(output.decision).toBeUndefined();
+    expect(output.hookSpecificOutput?.additionalContext).toContain(
+      "could not select",
+    );
+    expect(output.hookSpecificOutput?.additionalContext).toContain(
+      "allowApiKeyFallback is false",
+    );
+    expect(output.hookSpecificOutput?.additionalContext).not.toContain(
+      "fake/fake-coder",
+    );
+  });
+
+  it("continues Claude primary flow when routing needs configuration", async () => {
+    const input = JSON.parse(await fixture());
+
+    const output = handleUserPromptSubmit(input, {
+      profile: "claude-personal",
+      policy,
+      candidates: [],
+      trustedWorkspace: true,
+    });
+
+    expect(output.decision).toBeUndefined();
+    expect(output.hookSpecificOutput?.additionalContext).toContain(
+      "needs configuration",
+    );
+  });
+
+  it("fails closed for schema-invalid hook JSON", async () => {
+    const output = handleUserPromptSubmit(
+      { hook_event_name: "PreToolUse", prompt: "" },
+      {
+        profile: "claude-personal",
+        policy,
+        candidates,
+        trustedWorkspace: true,
+        routeConstraints: { allowApiKeyFallback: true },
+      },
+    );
+
+    expect(output).toMatchObject({
+      decision: "block",
+    });
+    expect(output.reason).toContain("Invalid Claude hook JSON");
+  });
+
+  it("fails closed for invalid hook JSON", async () => {
+    const result = await runUserPromptSubmitHook("{not-json", {
+      profile: "claude-personal",
+      policy,
+      candidates,
+      trustedWorkspace: true,
+      routeConstraints: { allowApiKeyFallback: true },
+    });
+
+    expect(result.exitCode).toBe(0);
+    const output = parseStdout(result.stdout);
+    expect(output).toMatchObject({
+      decision: "block",
+    });
+    expect(output.reason).toContain("Invalid Claude hook JSON");
+    expect(result.stderr).toBe("");
+  });
+
+  it("writes valid JSON to stdout with no extra text", async () => {
+    const result = await runUserPromptSubmitHook(await fixture(), {
+      profile: "claude-personal",
+      policy,
+      candidates,
+      trustedWorkspace: true,
+      routeConstraints: { allowApiKeyFallback: true },
+    });
+
+    expect(result.exitCode).toBe(0);
+    const output = parseStdout(result.stdout);
+    expect(output).toHaveProperty("hookSpecificOutput");
+    expect(result.stdout).not.toContain(
+      "Explain this repository and suggest the next test to write.",
+    );
+    expect(result.stderr).toBe("");
+  });
+});

package/src/hooks/user-prompt-submit.ts

@@ -0,0 +1,262 @@
+/**
+ * Claude Code UserPromptSubmit hook adapter.
+ *
+ * V1 boundary: do not claim to intercept or replace Claude Code's primary
+ * model. This handler injects audit-safe routing guidance for OffRouter-
+ * managed delegation (or blocks profiles OffRouter refuses to serve).
+ */
+import { createHash } from "node:crypto";
+import {
+  ROUTE_PROTOCOL_VERSION,
+  routeRequest,
+  type PolicyConfig,
+  type ProviderCandidate,
+  type RouteDecision,
+  type RouteConstraints,
+  type RouteRequest,
+  type RouteTask,
+} from "offrouter-core";
+import { z } from "zod";
+
+const HONESTY_SENTENCE =
+  "Claude Code's primary model is unchanged in V1; OffRouter routes delegated work.";
+
+type InferredRouteTask = Pick<
+  RouteTask,
+  "kind" | "risk" | "requiresTools" | "requiresImages" | "requiresJson"
+>;
+
+const ClaudeUserPromptSubmitSchema = z
+  .object({
+    hook_event_name: z.literal("UserPromptSubmit"),
+    prompt: z.string().min(1),
+    cwd: z.string().optional(),
+    session_id: z.string().optional(),
+    transcript_path: z.string().optional(),
+    permission_mode: z.string().optional(),
+  })
+  .passthrough();
+
+export type ClaudeUserPromptSubmitPayload = z.infer<
+  typeof ClaudeUserPromptSubmitSchema
+>;
+
+export interface UserPromptSubmitOptions {
+  profile: string;
+  policy: PolicyConfig;
+  candidates: ProviderCandidate[];
+  trustedWorkspace?: boolean;
+  routeConstraints?: Partial<RouteConstraints>;
+}
+
+export interface UserPromptSubmitHookOutput {
+  decision?: "block";
+  reason?: string;
+  hookSpecificOutput?: {
+    hookEventName: "UserPromptSubmit";
+    additionalContext: string;
+  };
+}
+
+export interface HookRunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+function promptDigest(prompt: string): string {
+  return `sha256:${createHash("sha256").update(prompt).digest("hex")}`;
+}
+
+function auditSafePromptPreview(digest: string, prompt: string): string {
+  return `redacted:${digest.replace("sha256:", "").slice(0, 12)} chars=${prompt.length}`;
+}
+
+function inferTask(prompt: string): InferredRouteTask {
+  const normalized = prompt.toLowerCase();
+  let kind: RouteTask["kind"] = "other";
+  if (/\b(review|pr|diff|audit)\b/.test(normalized)) {
+    kind = "review";
+  } else if (/\b(plan|spec|roadmap|design)\b/.test(normalized)) {
+    kind = "plan";
+  } else if (/\b(implement|code|fix|test|refactor|debug)\b/.test(normalized)) {
+    kind = "code";
+  } else if (/\b(research|latest|look up|web)\b/.test(normalized)) {
+    kind = "research";
+  } else if (/\b(image|screenshot|diagram|draw)\b/.test(normalized)) {
+    kind = "image";
+  } else if (/\b(explain|summari[sz]e)\b/.test(normalized)) {
+    kind = "explain";
+  }
+
+  let risk: RouteTask["risk"] = "low";
+  if (
+    /\b(production|deploy|delete|migrate|credential|secret|payment|security|auth|database|data loss|rm -rf)\b/.test(
+      normalized,
+    )
+  ) {
+    risk = "high";
+  } else if (
+    /\b(refactor|install|write|commit|merge|api key|profile|hook)\b/.test(
+      normalized,
+    )
+  ) {
+    risk = "medium";
+  }
+
+  return {
+    kind,
+    risk,
+    requiresTools:
+      kind === "code" ||
+      kind === "review" ||
+      /\b(run|test|build|edit|write|git|shell|command)\b/.test(normalized),
+    requiresImages: kind === "image",
+    requiresJson: /\b(json|schema|structured)\b/.test(normalized),
+  };
+}
+
+function buildRouteRequest(
+  payload: ClaudeUserPromptSubmitPayload,
+  options: UserPromptSubmitOptions,
+): RouteRequest {
+  const prompt = payload.prompt;
+  const digest = promptDigest(prompt);
+  const inferredTask = inferTask(prompt);
+  return {
+    protocolVersion: ROUTE_PROTOCOL_VERSION,
+    requestId: `claude_hook_${digest.replace("sha256:", "").slice(0, 12)}`,
+    harness: {
+      kind: "claude",
+      profile: options.profile,
+    },
+    task: {
+      ...inferredTask,
+      promptPreview: auditSafePromptPreview(digest, prompt),
+      promptDigest: digest,
+    },
+    workspace: {
+      cwd: payload.cwd ?? process.cwd(),
+      trusted: options.trustedWorkspace === true,
+    },
+    constraints: {
+      subscriptionFirst: options.routeConstraints?.subscriptionFirst ?? true,
+      allowApiKeyFallback:
+        options.routeConstraints?.allowApiKeyFallback ?? false,
+      maxCostUsd: options.routeConstraints?.maxCostUsd,
+      localOnly: options.routeConstraints?.localOnly,
+    },
+  };
+}
+
+function formatAllowedContext(decision: RouteDecision): string {
+  const lines = [HONESTY_SENTENCE];
+
+  if (decision.route) {
+    lines.push(
+      `OffRouter recommended delegated route ${decision.route.provider}/${decision.route.model} (${decision.route.authTier}).`,
+    );
+    lines.push(`Reason: ${decision.reason}. ${decision.explanation}`.trim());
+  } else if (decision.needsConfiguration) {
+    lines.push(
+      "OffRouter needs configuration before it can select a delegated route.",
+    );
+    lines.push(decision.explanation);
+  } else if (decision.blocked) {
+    // Profile denials are surfaced as decision:block by the caller; other
+    // blocked outcomes still provide context rather than claiming primary
+    // model substitution.
+    lines.push(
+      `OffRouter could not select a delegated route (${decision.reason}).`,
+    );
+    lines.push(decision.explanation);
+  } else {
+    lines.push("OffRouter could not select a delegated route.");
+  }
+
+  // Never include raw prompt text; decision fields are already audit-safe.
+  return lines.filter(Boolean).join("\n");
+}
+
+function invalidHookOutput(detail?: string): UserPromptSubmitHookOutput {
+  const reason = detail
+    ? `Invalid Claude hook JSON: ${detail}`
+    : "Invalid Claude hook JSON";
+  return {
+    decision: "block",
+    reason,
+  };
+}
+
+function isProfileDenial(decision: RouteDecision): boolean {
+  return (
+    decision.blocked === true &&
+    (decision.policyDenials ?? []).some(
+      (d) =>
+        d.code === "work_profile_denied" ||
+        d.code === "profile_not_allowlisted",
+    )
+  );
+}
+
+/**
+ * Pure UserPromptSubmit handler used by tests and the stdio runner.
+ */
+export function handleUserPromptSubmit(
+  input: unknown,
+  options: UserPromptSubmitOptions,
+): UserPromptSubmitHookOutput {
+  const parsed = ClaudeUserPromptSubmitSchema.safeParse(input);
+  if (!parsed.success) {
+    return invalidHookOutput("payload did not match UserPromptSubmit schema");
+  }
+
+  const request = buildRouteRequest(parsed.data, options);
+  const decision = routeRequest(request, options.candidates, options.policy);
+
+  // Denied / disallowed profiles block closed at the hook boundary.
+  if (isProfileDenial(decision)) {
+    const denial = (decision.policyDenials ?? []).find(
+      (d) =>
+        d.code === "work_profile_denied" ||
+        d.code === "profile_not_allowlisted",
+    );
+    return {
+      decision: "block",
+      reason:
+        denial?.message ??
+        `Profile ${options.profile} is denied by OffRouter policy.`,
+    };
+  }
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: formatAllowedContext(decision),
+    },
+  };
+}
+
+/**
+ * Stdio-style runner: parse stdin JSON, handle, emit a single JSON object on
+ * stdout. Always exit 0 so Claude receives structured block/allow decisions.
+ */
+export async function runUserPromptSubmitHook(
+  stdin: string,
+  options: UserPromptSubmitOptions,
+): Promise<HookRunResult> {
+  let output: UserPromptSubmitHookOutput;
+
+  try {
+    const raw: unknown = JSON.parse(stdin);
+    output = handleUserPromptSubmit(raw, options);
+  } catch {
+    output = invalidHookOutput();
+  }
+
+  return {
+    exitCode: 0,
+    stdout: JSON.stringify(output),
+    stderr: "",
+  };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * offrouter-adapter-claude public surface.
+ * Hook handlers for Claude Code personal profiles.
+ */
+
+export const ADAPTER_CLAUDE_PACKAGE = "offrouter-adapter-claude" as const;
+
+export {
+  handleUserPromptSubmit,
+  runUserPromptSubmitHook,
+} from "./hooks/user-prompt-submit.js";
+export type {
+  ClaudeUserPromptSubmitPayload,
+  HookRunResult,
+  UserPromptSubmitHookOutput,
+  UserPromptSubmitOptions,
+} from "./hooks/user-prompt-submit.js";
+
+export { handlePreToolUse } from "./hooks/pre-tool-use.js";
+export type { PreToolUseHookOutput } from "./hooks/pre-tool-use.js";
+
+export {
+  CLAUDE_INSTALL_STATE_REL,
+  ClaudeInstallStateSchema,
+  defaultPluginSourceDir,
+  evaluateInstallProfilePolicy,
+  formatInstallDiffText,
+  installClaudeProfile,
+  INSTALLED_PLUGIN_REL,
+  isClaudeHarnessProfile,
+  isSafeProfileId,
+  isWorkLikeProfile,
+  listAllowlistedPersonalClaudeProfiles,
+  resolveClaudeProfileDir,
+} from "./install.js";
+export type {
+  ClaudeInstallOptions,
+  ClaudeInstallResult,
+  ClaudeInstallState,
+  InstallChangeKind,
+  InstallFileChange,
+  ResolveClaudeProfileDirOptions,
+} from "./install.js";
+
+export { rollbackClaudeProfile } from "./rollback.js";
+export type {
+  ClaudeRollbackOptions,
+  ClaudeRollbackResult,
+} from "./rollback.js";