@tanstack/ai-claude-code 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @tanstack/ai-claude-code
+
+Claude Code harness adapter for [TanStack AI](https://tanstack.com/ai) — run [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (via `@anthropic-ai/claude-agent-sdk`) as a chat backend with local tool execution, stateful coding sessions, and TanStack tool bridging.
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+
+const stream = chat({
+  adapter: claudeCodeText('claude-opus-4-8', {
+    cwd: '/path/to/project',
+    permissionMode: 'acceptEdits',
+  }),
+  messages: [{ role: 'user', content: 'Fix the failing test.' }],
+})
+```
+
+Server-only (Node). See the [Claude Code adapter docs](https://tanstack.com/ai/latest/docs/adapters/claude-code) for sessions, tool bridging, permissions, and limitations.

package/dist/esm/adapters/policy-map.d.ts

@@ -0,0 +1,8 @@
+import { SandboxPolicy } from '@tanstack/ai-sandbox';
+import { ClaudeCodePermissionMode } from './text.js';
+export interface ClaudePolicyFlags {
+    permissionMode?: ClaudeCodePermissionMode;
+    allowedTools: Array<string>;
+    disallowedTools: Array<string>;
+}
+export declare function mapPolicyToClaudeFlags(policy: SandboxPolicy | undefined): ClaudePolicyFlags;

package/dist/esm/adapters/policy-map.js

@@ -0,0 +1,51 @@
+const WRITE_TOOLS = ["Write", "Edit", "MultiEdit"];
+const NETWORK_TOOLS = ["WebFetch", "WebSearch"];
+const BUILTIN_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "Bash",
+  "Read",
+  "Write",
+  "Edit",
+  "MultiEdit",
+  "Glob",
+  "Grep",
+  "WebFetch",
+  "WebSearch",
+  "NotebookEdit",
+  "Task"
+]);
+function modeFor(decision) {
+  switch (decision) {
+    case "allow":
+      return "bypassPermissions";
+    case "ask":
+      return "acceptEdits";
+    case "deny":
+      return "default";
+  }
+}
+function mapPolicyToClaudeFlags(policy) {
+  const allowedTools = [];
+  const disallowedTools = [];
+  if (!policy) return { allowedTools, disallowedTools };
+  if (policy.capabilities?.fileWrite === "deny")
+    disallowedTools.push(...WRITE_TOOLS);
+  if (policy.capabilities?.network === "deny")
+    disallowedTools.push(...NETWORK_TOOLS);
+  for (const pattern of policy.commands?.deny ?? []) {
+    if (BUILTIN_TOOL_NAMES.has(pattern)) disallowedTools.push(pattern);
+  }
+  for (const pattern of policy.commands?.allow ?? []) {
+    if (BUILTIN_TOOL_NAMES.has(pattern)) allowedTools.push(pattern);
+  }
+  const result = {
+    allowedTools: [...new Set(allowedTools)],
+    disallowedTools: [...new Set(disallowedTools)]
+  };
+  if (policy.default !== void 0)
+    result.permissionMode = modeFor(policy.default);
+  return result;
+}
+export {
+  mapPolicyToClaudeFlags
+};
+//# sourceMappingURL=policy-map.js.map

package/dist/esm/adapters/policy-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-map.js","sources":["../../../src/adapters/policy-map.ts"],"sourcesContent":["/**\n * Map a portable {@link SandboxPolicy} onto Claude Code CLI permission flags.\n *\n * This is a best-effort, coarse mapping (the CLI's permission model is\n * tool-level + a permission mode, not arbitrary command globs):\n *\n * - `default` decision → `--permission-mode`:\n *     `'allow'` → `bypassPermissions`, `'acceptEdits'`-ish `'ask'` → `acceptEdits`,\n *     `'deny'` → `default` (in `-p` mode, prompts are auto-denied).\n * - `capabilities.fileWrite === 'deny'` → disallow `Write`,`Edit`,`MultiEdit`.\n * - `capabilities.network === 'deny'` → disallow `WebFetch`,`WebSearch`.\n * - `commands.deny` that name a bare built-in tool (e.g. `Bash`) are added to\n *   `--disallowedTools`; fine-grained command-glob enforcement is left to the\n *   MCP permission-prompt tool (interactive approvals).\n *\n * Returns the permission mode plus tool allow/deny additions; the adapter\n * merges these with its own config.\n */\nimport type { PolicyDecision, SandboxPolicy } from '@tanstack/ai-sandbox'\nimport type { ClaudeCodePermissionMode } from './text'\n\nexport interface ClaudePolicyFlags {\n  permissionMode?: ClaudeCodePermissionMode\n  allowedTools: Array<string>\n  disallowedTools: Array<string>\n}\n\nconst WRITE_TOOLS = ['Write', 'Edit', 'MultiEdit']\nconst NETWORK_TOOLS = ['WebFetch', 'WebSearch']\nconst BUILTIN_TOOL_NAMES = new Set([\n  'Bash',\n  'Read',\n  'Write',\n  'Edit',\n  'MultiEdit',\n  'Glob',\n  'Grep',\n  'WebFetch',\n  'WebSearch',\n  'NotebookEdit',\n  'Task',\n])\n\nfunction modeFor(decision: PolicyDecision): ClaudeCodePermissionMode {\n  switch (decision) {\n    case 'allow':\n      return 'bypassPermissions'\n    case 'ask':\n      return 'acceptEdits'\n    case 'deny':\n      return 'default'\n  }\n}\n\nexport function mapPolicyToClaudeFlags(\n  policy: SandboxPolicy | undefined,\n): ClaudePolicyFlags {\n  const allowedTools: Array<string> = []\n  const disallowedTools: Array<string> = []\n  if (!policy) return { allowedTools, disallowedTools }\n\n  if (policy.capabilities?.fileWrite === 'deny')\n    disallowedTools.push(...WRITE_TOOLS)\n  if (policy.capabilities?.network === 'deny')\n    disallowedTools.push(...NETWORK_TOOLS)\n\n  // Tool-name-level command rules map directly; everything else is left to the\n  // permission-prompt tool.\n  for (const pattern of policy.commands?.deny ?? []) {\n    if (BUILTIN_TOOL_NAMES.has(pattern)) disallowedTools.push(pattern)\n  }\n  for (const pattern of policy.commands?.allow ?? []) {\n    if (BUILTIN_TOOL_NAMES.has(pattern)) allowedTools.push(pattern)\n  }\n\n  const result: ClaudePolicyFlags = {\n    allowedTools: [...new Set(allowedTools)],\n    disallowedTools: [...new Set(disallowedTools)],\n  }\n  if (policy.default !== undefined)\n    result.permissionMode = modeFor(policy.default)\n  return result\n}\n"],"names":[],"mappings":"AA2BA,MAAM,cAAc,CAAC,SAAS,QAAQ,WAAW;AACjD,MAAM,gBAAgB,CAAC,YAAY,WAAW;AAC9C,MAAM,yCAAyB,IAAI;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,SAAS,QAAQ,UAAoD;AACnE,UAAQ,UAAA;AAAA,IACN,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,EAAA;AAEb;AAEO,SAAS,uBACd,QACmB;AACnB,QAAM,eAA8B,CAAA;AACpC,QAAM,kBAAiC,CAAA;AACvC,MAAI,CAAC,OAAQ,QAAO,EAAE,cAAc,gBAAA;AAEpC,MAAI,OAAO,cAAc,cAAc;AACrC,oBAAgB,KAAK,GAAG,WAAW;AACrC,MAAI,OAAO,cAAc,YAAY;AACnC,oBAAgB,KAAK,GAAG,aAAa;AAIvC,aAAW,WAAW,OAAO,UAAU,QAAQ,CAAA,GAAI;AACjD,QAAI,mBAAmB,IAAI,OAAO,EAAG,iBAAgB,KAAK,OAAO;AAAA,EACnE;AACA,aAAW,WAAW,OAAO,UAAU,SAAS,CAAA,GAAI;AAClD,QAAI,mBAAmB,IAAI,OAAO,EAAG,cAAa,KAAK,OAAO;AAAA,EAChE;AAEA,QAAM,SAA4B;AAAA,IAChC,cAAc,CAAC,GAAG,IAAI,IAAI,YAAY,CAAC;AAAA,IACvC,iBAAiB,CAAC,GAAG,IAAI,IAAI,eAAe,CAAC;AAAA,EAAA;AAE/C,MAAI,OAAO,YAAY;AACrB,WAAO,iBAAiB,QAAQ,OAAO,OAAO;AAChD,SAAO;AACT;"}

package/dist/esm/adapters/projection.d.ts

@@ -0,0 +1,14 @@
+import { SandboxHandle, WorkspaceProjection } from '@tanstack/ai-sandbox';
+/**
+ * Project a `WorkspaceProjection` into the Claude Code sandbox. Safe to call on
+ * every `chatStream`. The secret-bearing `.mcp.json` is (re)written on every
+ * call, re-resolving secrets, so claude always reads current values and a
+ * snapshot can never serve a stale or rotated secret. The safe, idempotent,
+ * non-secret operations (gitSkill links, plugin installs, agentSkill handling)
+ * are guarded by a one-time marker so they run only on the first call after
+ * create/restore.
+ *
+ * @param handle     - The sandbox handle (`fs` + `process`).
+ * @param projection - The portable workspace inputs from `withSandbox`.
+ */
+export declare function projectClaudeWorkspace(handle: SandboxHandle, projection: WorkspaceProjection): Promise<void>;

package/dist/esm/adapters/projection.js

@@ -0,0 +1,101 @@
+import { resolveGitSkillDir, isSecretRef } from "@tanstack/ai-sandbox";
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function basenameOf(path) {
+  const segments = path.split("/").filter((segment) => segment !== "");
+  return segments[segments.length - 1] ?? path;
+}
+function isBearerMarker(value) {
+  return typeof value === "object" && value !== null && isSecretRef(value.__bearerRef);
+}
+function resolveHeaderValue(value, resolveSecret) {
+  if (isSecretRef(value)) return resolveSecret(value);
+  if (isBearerMarker(value)) return `Bearer ${resolveSecret(value.__bearerRef)}`;
+  return value;
+}
+function buildMcpConfig(skills, resolveSecret) {
+  const mcpServers = {};
+  let count = 0;
+  for (const skill of skills) {
+    if (skill.kind !== "mcp") continue;
+    count += 1;
+    const headers = {};
+    const rawHeaders = skill.config.headers ?? {};
+    for (const [name, value] of Object.entries(rawHeaders)) {
+      headers[name] = resolveHeaderValue(value, resolveSecret);
+    }
+    const rawUrl = skill.config["url"];
+    const url = typeof rawUrl === "string" ? rawUrl : "";
+    mcpServers[skill.name] = { type: "http", url, headers };
+  }
+  return count > 0 ? { mcpServers } : void 0;
+}
+async function projectMcpServers(handle, projection) {
+  const config = buildMcpConfig(projection.skills, projection.resolveSecret);
+  if (config === void 0) return;
+  const target = `${projection.root}/.mcp.json`;
+  await handle.fs.write(target, JSON.stringify(config, null, 2));
+}
+async function projectGitSkills(handle, projection) {
+  const skillsDir = `${projection.root}/.claude/skills`;
+  let madeDir = false;
+  for (const skill of projection.skills) {
+    if (skill.kind !== "git") continue;
+    if (!madeDir) {
+      await handle.fs.mkdir(skillsDir);
+      madeDir = true;
+    }
+    const source = skill.into ?? resolveGitSkillDir(projection.root, skill);
+    const target = `${skillsDir}/${basenameOf(source)}`;
+    const lnCmd = `ln -s ${shellQuote(source)} ${shellQuote(target)}`;
+    const result = await handle.process.exec(lnCmd, { cwd: projection.root });
+    if (result.exitCode !== 0) {
+      const cpCmd = `cp -r ${shellQuote(source)} ${shellQuote(target)}`;
+      const copied = await handle.process.exec(cpCmd, { cwd: projection.root });
+      if (copied.exitCode !== 0) {
+        console.warn(
+          `[claude-code] failed to link gitSkill "${skill.repo}" into ${target}: ${copied.stderr.trim()}`
+        );
+      }
+    }
+  }
+}
+function projectAgentSkills(projection) {
+  for (const skill of projection.skills) {
+    if (skill.kind !== "agent-skill") continue;
+    console.warn(
+      `[claude-code] agentSkill "${skill.name}" cannot be projected: Claude Code has no command to install a public skill by bare name. Provide it as a gitSkill or a plugin instead. Skipping.`
+    );
+  }
+}
+async function projectPlugins(handle, projection) {
+  for (const name of projection.plugins) {
+    const cmd = `claude plugin install ${shellQuote(name)}`;
+    try {
+      const result = await handle.process.exec(cmd, { cwd: projection.root });
+      if (result.exitCode !== 0) {
+        console.warn(
+          `[claude-code] "claude plugin install ${name}" exited ${result.exitCode}: ${result.stderr.trim()}`
+        );
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(
+        `[claude-code] failed to install plugin "${name}": ${message}`
+      );
+    }
+  }
+}
+async function projectClaudeWorkspace(handle, projection) {
+  await projectMcpServers(handle, projection);
+  if (await handle.fs.exists(projection.markerPath)) return;
+  await projectGitSkills(handle, projection);
+  projectAgentSkills(projection);
+  await projectPlugins(handle, projection);
+  await handle.fs.write(projection.markerPath, "");
+}
+export {
+  projectClaudeWorkspace
+};
+//# sourceMappingURL=projection.js.map

package/dist/esm/adapters/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sources":["../../../src/adapters/projection.ts"],"sourcesContent":["/**\n * Claude Code workspace projector — the reference implementation the other\n * harness projectors (codex, opencode) mirror.\n *\n * `withSandbox` surfaces a portable `WorkspaceProjection` (skills, plugins, a\n * secret resolver, and a one-time marker path) via a capability. Each harness\n * adapter reads it in its `chatStream` setup and projects those inputs into the\n * CLI's native format. For Claude Code that means:\n *\n *   - MCP servers   → a project-scoped `.mcp.json` at the workspace root.\n *   - gitSkill repos → linked under `.claude/skills/<basename>`.\n *   - agentSkill     → no reliable claude primitive pulls a public skill by\n *                      bare name, so we warn and skip rather than invent one.\n *   - plugins        → `claude plugin install <name>` (best-effort).\n *\n * The secret-bearing `.mcp.json` is (re)written on EVERY call, re-resolving\n * secrets each time, so claude always reads current values and a snapshot can\n * never serve a stale or rotated secret. Only the safe, idempotent, non-secret\n * operations (gitSkill links, plugin installs, agentSkill handling) are guarded\n * by a one-time marker file under the workspace.\n *\n * External-convention caveat: the `.mcp.json` location/shape, the skills dir,\n * and the plugin-install command are verified against the installed `claude`\n * CLI. Where claude has no clean primitive (agentSkill by bare name) we no-op\n * with a warning instead of fabricating a command.\n */\nimport { isSecretRef, resolveGitSkillDir } from '@tanstack/ai-sandbox'\nimport type {\n  BearerRef,\n  SandboxHandle,\n  SecretRef,\n  WorkspaceProjection,\n  WorkspaceSkill,\n} from '@tanstack/ai-sandbox'\n\n/** POSIX single-quote escape for embedding a value in a shell command. */\nfunction shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`\n}\n\n/** Last path segment of a `gitSkill` clone dir, used as the skills-dir name. */\nfunction basenameOf(path: string): string {\n  const segments = path.split('/').filter((segment) => segment !== '')\n  return segments[segments.length - 1] ?? path\n}\n\n/** True when `value` is a `bearer(ref)` marker created by `@tanstack/ai-sandbox`. */\nfunction isBearerMarker(value: unknown): value is BearerRef {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    isSecretRef((value as { __bearerRef?: unknown }).__bearerRef)\n  )\n}\n\n/**\n * Resolve a single MCP header value: a `SecretRef` resolves to its plaintext, a\n * `bearer(ref)` marker resolves to `Bearer <plaintext>`, and a plain string is\n * passed through unchanged.\n */\nfunction resolveHeaderValue(\n  value: string | SecretRef | BearerRef,\n  resolveSecret: (ref: SecretRef) => string,\n): string {\n  if (isSecretRef(value)) return resolveSecret(value)\n  if (isBearerMarker(value)) return `Bearer ${resolveSecret(value.__bearerRef)}`\n  return value\n}\n\n/** A claude-format HTTP MCP server entry. */\ninterface ClaudeMcpServer {\n  type: 'http'\n  url: string\n  headers: Record<string, string>\n}\n\n/**\n * Build claude's project-scoped MCP config from the `{ kind: 'mcp' }` skills,\n * resolving every header value (SecretRef / bearer / string). Returns\n * `undefined` when there are no MCP skills so the caller can skip the write.\n */\nfunction buildMcpConfig(\n  skills: Array<WorkspaceSkill>,\n  resolveSecret: (ref: SecretRef) => string,\n): { mcpServers: Record<string, ClaudeMcpServer> } | undefined {\n  const mcpServers: Record<string, ClaudeMcpServer> = {}\n  let count = 0\n  for (const skill of skills) {\n    if (skill.kind !== 'mcp') continue\n    count += 1\n    const headers: Record<string, string> = {}\n    const rawHeaders = skill.config.headers ?? {}\n    for (const [name, value] of Object.entries(rawHeaders)) {\n      headers[name] = resolveHeaderValue(value, resolveSecret)\n    }\n    const rawUrl = skill.config['url']\n    const url = typeof rawUrl === 'string' ? rawUrl : ''\n    mcpServers[skill.name] = { type: 'http', url, headers }\n  }\n  return count > 0 ? { mcpServers } : undefined\n}\n\n/**\n * Write the project-scoped `.mcp.json`, re-resolving every secret. This runs on\n * EVERY projection call (never gated by the marker) so claude always reads the\n * current secret values and a snapshot can never serve a stale or rotated one.\n * With `snapshot:'after-run'` the file may still be captured in the image, so\n * secret-bearing MCP material is best used with the default `after-setup`\n * strategy. When there are no MCP skills the write is skipped.\n */\nasync function projectMcpServers(\n  handle: SandboxHandle,\n  projection: WorkspaceProjection,\n): Promise<void> {\n  const config = buildMcpConfig(projection.skills, projection.resolveSecret)\n  if (config === undefined) return\n  const target = `${projection.root}/.mcp.json`\n  await handle.fs.write(target, JSON.stringify(config, null, 2))\n}\n\n/**\n * Ensure each cloned `gitSkill` repo is available under claude's project skills\n * dir (`<root>/.claude/skills/<basename>`) via a symlink, falling back to a\n * recursive copy on platforms without `ln -s`.\n */\nasync function projectGitSkills(\n  handle: SandboxHandle,\n  projection: WorkspaceProjection,\n): Promise<void> {\n  const skillsDir = `${projection.root}/.claude/skills`\n  let madeDir = false\n  for (const skill of projection.skills) {\n    if (skill.kind !== 'git') continue\n    if (!madeDir) {\n      await handle.fs.mkdir(skillsDir)\n      madeDir = true\n    }\n    const source = skill.into ?? resolveGitSkillDir(projection.root, skill)\n    const target = `${skillsDir}/${basenameOf(source)}`\n    const lnCmd = `ln -s ${shellQuote(source)} ${shellQuote(target)}`\n    const result = await handle.process.exec(lnCmd, { cwd: projection.root })\n    if (result.exitCode !== 0) {\n      const cpCmd = `cp -r ${shellQuote(source)} ${shellQuote(target)}`\n      const copied = await handle.process.exec(cpCmd, { cwd: projection.root })\n      if (copied.exitCode !== 0) {\n        console.warn(\n          `[claude-code] failed to link gitSkill \"${skill.repo}\" into ${target}: ${copied.stderr.trim()}`,\n        )\n      }\n    }\n  }\n}\n\n/**\n * `agentSkill` references a public skill by bare name. Claude Code has no\n * primitive to fetch a skill from a bare name (skills resolve from local\n * `.claude/skills/` dirs and plugin marketplaces), so we warn and skip rather\n * than fabricate a command.\n */\nfunction projectAgentSkills(projection: WorkspaceProjection): void {\n  for (const skill of projection.skills) {\n    if (skill.kind !== 'agent-skill') continue\n    console.warn(\n      `[claude-code] agentSkill \"${skill.name}\" cannot be projected: Claude Code has ` +\n        'no command to install a public skill by bare name. Provide it as a gitSkill ' +\n        'or a plugin instead. Skipping.',\n    )\n  }\n}\n\n/**\n * Install each declared plugin via `claude plugin install <name>`. Plugin\n * installs are best-effort: a failure (no marketplace, network, …) warns but\n * never throws, so a missing plugin can't break the run.\n */\nasync function projectPlugins(\n  handle: SandboxHandle,\n  projection: WorkspaceProjection,\n): Promise<void> {\n  for (const name of projection.plugins) {\n    const cmd = `claude plugin install ${shellQuote(name)}`\n    try {\n      const result = await handle.process.exec(cmd, { cwd: projection.root })\n      if (result.exitCode !== 0) {\n        console.warn(\n          `[claude-code] \"claude plugin install ${name}\" exited ${result.exitCode}: ${result.stderr.trim()}`,\n        )\n      }\n    } catch (error: unknown) {\n      const message = error instanceof Error ? error.message : String(error)\n      console.warn(\n        `[claude-code] failed to install plugin \"${name}\": ${message}`,\n      )\n    }\n  }\n}\n\n/**\n * Project a `WorkspaceProjection` into the Claude Code sandbox. Safe to call on\n * every `chatStream`. The secret-bearing `.mcp.json` is (re)written on every\n * call, re-resolving secrets, so claude always reads current values and a\n * snapshot can never serve a stale or rotated secret. The safe, idempotent,\n * non-secret operations (gitSkill links, plugin installs, agentSkill handling)\n * are guarded by a one-time marker so they run only on the first call after\n * create/restore.\n *\n * @param handle     - The sandbox handle (`fs` + `process`).\n * @param projection - The portable workspace inputs from `withSandbox`.\n */\nexport async function projectClaudeWorkspace(\n  handle: SandboxHandle,\n  projection: WorkspaceProjection,\n): Promise<void> {\n  // Always re-resolve and rewrite the secret-bearing MCP config so rotated\n  // secrets re-apply and snapshots can't serve stale values.\n  await projectMcpServers(handle, projection)\n\n  // Gate only the safe, idempotent, non-secret operations on the marker.\n  if (await handle.fs.exists(projection.markerPath)) return\n\n  await projectGitSkills(handle, projection)\n  projectAgentSkills(projection)\n  await projectPlugins(handle, projection)\n\n  await handle.fs.write(projection.markerPath, '')\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/adapters/text.d.ts

@@ -0,0 +1,75 @@
+import { BaseTextAdapter, StructuredOutputOptions, StructuredOutputResult } from '@tanstack/ai/adapters';
+import { SandboxHandle } from '@tanstack/ai-sandbox';
+import { DefaultMessageMetadataByModality, Modality, StreamChunk, TextOptions } from '@tanstack/ai';
+import { ClaudeCodeModel } from '../model-meta.js';
+import { ClaudeCodeTextProviderOptions } from '../provider-options.js';
+export type ClaudeCodePermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
+export interface ClaudeCodeTextConfig {
+    /**
+     * Working directory inside the sandbox where `claude` runs. Defaults to
+     * `/workspace` (the conventional sandbox workspace root).
+     */
+    cwd?: string;
+    /**
+     * Claude Code permission mode passed via `--permission-mode`. Defaults to
+     * `'bypassPermissions'` — a sandbox is isolated, so the agent is allowed to
+     * edit files and run commands without prompting. Tighten via `defineSandboxPolicy`
+     * / this option for less autonomy.
+     */
+    permissionMode?: ClaudeCodePermissionMode;
+    /** Built-in tools the harness may use (`--allowedTools`). */
+    allowedTools?: Array<string>;
+    /** Built-in tools removed from the harness (`--disallowedTools`). */
+    disallowedTools?: Array<string>;
+    /** Extra directories the agent may access (`--add-dir`). */
+    addDirs?: Array<string>;
+    /** Maximum harness-internal turns (`--max-turns`). */
+    maxTurns?: number;
+    /**
+     * How `systemPrompts` from `chat()` are applied:
+     * - `'append'` (default): `--append-system-prompt` on top of the preset.
+     * - `'replace'`: `--system-prompt` as the entire system prompt.
+     */
+    systemPromptMode?: 'append' | 'replace';
+    /** Path/name of the claude executable inside the sandbox. Defaults to `claude`. */
+    claudeExecutable?: string;
+    /** Emit token-level deltas via `--include-partial-messages` (default true). */
+    streamPartials?: boolean;
+    /** Extra environment variables for the claude process inside the sandbox. */
+    env?: Record<string, string>;
+    /** Emit a `file.changed` CUSTOM event with the git diff after the run (default true). */
+    emitDiff?: boolean;
+}
+export declare class ClaudeCodeTextAdapter<TModel extends ClaudeCodeModel> extends BaseTextAdapter<TModel, ClaudeCodeTextProviderOptions, ReadonlyArray<Modality> & readonly ['text'], DefaultMessageMetadataByModality, ReadonlyArray<string>, unknown, never> {
+    readonly name: "claude-code";
+    readonly requires: readonly [import('@tanstack/ai').Capability<SandboxHandle, "sandbox">];
+    private readonly adapterConfig;
+    constructor(config: ClaudeCodeTextConfig, model: TModel);
+    private sandboxFrom;
+    private workdir;
+    /** Build the `claude` command line (prompt goes via stdin, not argv). */
+    private buildCommand;
+    /**
+     * Build the permission-prompt resolver the host MCP bridge exposes to claude
+     * (`--permission-prompt-tool`). Maps claude's permission request onto the
+     * sandbox policy + client approvals; on an `ask` action with no decision yet,
+     * records an approval-requested event and denies (the client re-runs to grant).
+     */
+    private buildPermissionResolver;
+    chatStream(options: TextOptions<ClaudeCodeTextProviderOptions>): AsyncIterable<StreamChunk>;
+    structuredOutput(_options: StructuredOutputOptions<ClaudeCodeTextProviderOptions>): Promise<StructuredOutputResult<unknown>>;
+}
+/**
+ * Creates a Claude Code harness adapter that runs **inside a sandbox**.
+ *
+ * Unlike HTTP provider adapters, this is a *harness* adapter: it spawns the
+ * `claude` CLI inside the sandbox provided by `withSandbox(...)` (the adapter
+ * declares `requires: [SandboxCapability]`), streams its `stream-json` stdout
+ * back as AG-UI events, and lets Claude Code run its own agent loop and native
+ * tools (Bash, file edits, search, …) against the sandbox workspace. The
+ * sandbox image must provide the `claude` executable and `ANTHROPIC_API_KEY`
+ * in its environment (e.g. via `workspace.secrets`). The session id is
+ * surfaced via a CUSTOM `claude-code.session-id` event so follow-up calls can
+ * resume through `modelOptions.sessionId`.
+ */
+export declare function claudeCodeText<TModel extends ClaudeCodeModel>(model: TModel, config?: ClaudeCodeTextConfig): ClaudeCodeTextAdapter<TModel>;

package/dist/esm/adapters/text.js

@@ -0,0 +1,306 @@
+import { normalizeSystemPrompts, EventType } from "@tanstack/ai";
+import { toRunErrorRawEvent } from "@tanstack/ai/adapter-internals";
+import { BaseTextAdapter } from "@tanstack/ai/adapters";
+import { SandboxCapability, getSandbox, approvalId, resolveApproval, buildApprovalRequestedEvent, createBridgeEventChannel, getWorkspaceProjection, getSandboxPolicy, getToolBridgeProvisioner, nodeHttpBridgeProvisioner, spawnNdjson, mergeChunkStreams } from "@tanstack/ai-sandbox";
+import { buildPrompt } from "../messages/prompt.js";
+import { translateSdkStream } from "../stream/translate.js";
+import { mapPolicyToClaudeFlags } from "./policy-map.js";
+import { projectClaudeWorkspace } from "./projection.js";
+const DEFAULT_WORKDIR = "/workspace";
+function q(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function bridgeToMcpConfig(bridge) {
+  return JSON.stringify({
+    mcpServers: {
+      [bridge.name]: {
+        type: "http",
+        url: bridge.url,
+        headers: { Authorization: `Bearer ${bridge.token}` }
+      }
+    }
+  });
+}
+class ClaudeCodeTextAdapter extends BaseTextAdapter {
+  name = "claude-code";
+  // Harness adapter: requires a sandbox to run the agent CLI inside.
+  requires = [SandboxCapability];
+  adapterConfig;
+  constructor(config, model) {
+    super({}, model);
+    this.adapterConfig = config;
+  }
+  sandboxFrom(options) {
+    const ctx = options.capabilities;
+    if (!ctx) {
+      throw new Error(
+        'Adapter "claude-code" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware (e.g. with the local-process or docker provider).'
+      );
+    }
+    return getSandbox(ctx);
+  }
+  workdir(options) {
+    return options.modelOptions?.cwd ?? this.adapterConfig.cwd ?? DEFAULT_WORKDIR;
+  }
+  /** Build the `claude` command line (prompt goes via stdin, not argv). */
+  buildCommand(options, resume, policyFlags, mcpConfigPath, permissionPromptTool) {
+    const config = this.adapterConfig;
+    const modelOptions = options.modelOptions;
+    const exe = config.claudeExecutable ?? "claude";
+    const args = [
+      "-p",
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      "--model",
+      q(this.model)
+    ];
+    if (config.streamPartials !== false) args.push("--include-partial-messages");
+    if (resume !== void 0) args.push("--resume", q(resume));
+    const permissionMode = modelOptions?.permissionMode ?? config.permissionMode ?? policyFlags.permissionMode ?? "bypassPermissions";
+    args.push("--permission-mode", q(permissionMode));
+    const maxTurns = modelOptions?.maxTurns ?? config.maxTurns;
+    if (maxTurns !== void 0) args.push("--max-turns", String(maxTurns));
+    for (const dir of config.addDirs ?? []) args.push("--add-dir", q(dir));
+    const allowedTools = [
+      ...modelOptions?.allowedTools ?? config.allowedTools ?? [],
+      ...policyFlags.allowedTools
+    ];
+    if (allowedTools.length > 0) {
+      args.push("--allowedTools", q([...new Set(allowedTools)].join(",")));
+    }
+    const disallowedTools = [
+      ...modelOptions?.disallowedTools ?? config.disallowedTools ?? [],
+      ...policyFlags.disallowedTools
+    ];
+    if (disallowedTools.length > 0) {
+      args.push("--disallowedTools", q([...new Set(disallowedTools)].join(",")));
+    }
+    const systemPrompts = normalizeSystemPrompts(options.systemPrompts).map((prompt) => prompt.content).filter((content) => content.trim() !== "");
+    if (systemPrompts.length > 0) {
+      const joined = systemPrompts.join("\n\n");
+      const flag = config.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt";
+      args.push(flag, q(joined));
+    }
+    if (mcpConfigPath !== void 0) args.push("--mcp-config", q(mcpConfigPath));
+    if (permissionPromptTool !== void 0) {
+      args.push("--permission-prompt-tool", q(permissionPromptTool));
+    }
+    return `${exe} ${args.join(" ")}`;
+  }
+  /**
+   * Build the permission-prompt resolver the host MCP bridge exposes to claude
+   * (`--permission-prompt-tool`). Maps claude's permission request onto the
+   * sandbox policy + client approvals; on an `ask` action with no decision yet,
+   * records an approval-requested event and denies (the client re-runs to grant).
+   */
+  buildPermissionResolver(policy, approvals, scripts, sink, threadId, runId) {
+    const writeTools = /* @__PURE__ */ new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+    const networkTools = /* @__PURE__ */ new Set(["WebFetch", "WebSearch"]);
+    return (request) => {
+      const toolName = request.tool_name ?? "tool";
+      const cmdInput = request.input;
+      const command = toolName === "Bash" && cmdInput !== null && typeof cmdInput === "object" && "command" in cmdInput && typeof cmdInput.command === "string" ? cmdInput.command : void 0;
+      const capability = writeTools.has(toolName) ? "fileWrite" : networkTools.has(toolName) ? "network" : void 0;
+      const id = approvalId({
+        provider: "claude-code",
+        kind: command !== void 0 ? "command" : capability ?? "tool",
+        target: command ?? toolName
+      });
+      const outcome = resolveApproval({
+        policy,
+        approvals,
+        id,
+        scripts,
+        ...command !== void 0 ? { command } : {},
+        ...capability !== void 0 ? { capability } : {}
+      });
+      if (outcome.needsApproval) {
+        sink.push(
+          buildApprovalRequestedEvent({
+            approvalId: id,
+            title: `Approve ${toolName}${command !== void 0 ? `: ${command}` : ""}`,
+            threadId,
+            runId,
+            detail: { provider: "claude-code", toolName }
+          })
+        );
+        return {
+          behavior: "deny",
+          message: "Awaiting client approval. Approve in the UI and re-run to continue."
+        };
+      }
+      return outcome.decision === "allow" ? { behavior: "allow" } : { behavior: "deny", message: "Denied by sandbox policy." };
+    };
+  }
+  async *chatStream(options) {
+    const { logger } = options;
+    let bridge;
+    let channel;
+    const approvalRequests = [];
+    let cleanupSandbox;
+    const tempFiles = [];
+    try {
+      const sandbox = this.sandboxFrom(options);
+      cleanupSandbox = sandbox;
+      const cwd = this.workdir(options);
+      const runId = options.runId ?? this.generateId();
+      const threadId = options.threadId ?? this.generateId();
+      channel = createBridgeEventChannel({ model: this.model, threadId, runId });
+      const projection = options.capabilities ? getWorkspaceProjection(options.capabilities, { optional: true }) : void 0;
+      if (projection) await projectClaudeWorkspace(sandbox, projection);
+      const policy = options.capabilities ? getSandboxPolicy(options.capabilities, { optional: true }) : void 0;
+      const permission = policy !== void 0 ? {
+        toolName: "approval_prompt",
+        resolve: this.buildPermissionResolver(
+          policy,
+          options.approvals,
+          projection?.scripts,
+          approvalRequests,
+          threadId,
+          runId
+        )
+      } : void 0;
+      const hasTools = options.tools !== void 0 && options.tools.length > 0;
+      if (hasTools || permission !== void 0) {
+        const provisioner = (options.capabilities ? getToolBridgeProvisioner(options.capabilities, { optional: true }) : void 0) ?? nodeHttpBridgeProvisioner;
+        bridge = await provisioner.provision(options.tools ?? [], {
+          provider: sandbox.provider,
+          context: options.context,
+          emitCustomEvent: channel.emitCustomEvent,
+          ...permission !== void 0 ? { permission } : {},
+          ...options.abortController?.signal ? { signal: options.abortController.signal } : {}
+        });
+      }
+      const { prompt, resume } = buildPrompt(
+        options.messages,
+        options.modelOptions?.sessionId
+      );
+      let mcpConfigArg;
+      if (bridge) {
+        const mcpConfigFile = `.tanstack-mcp-bridge-${runId}.json`;
+        const mcpConfigPath = `${cwd}/${mcpConfigFile}`;
+        await sandbox.fs.write(mcpConfigPath, bridgeToMcpConfig(bridge));
+        tempFiles.push(mcpConfigPath);
+        mcpConfigArg = mcpConfigFile;
+      }
+      const command = this.buildCommand(
+        options,
+        resume,
+        mapPolicyToClaudeFlags(policy),
+        mcpConfigArg,
+        bridge && permission ? `mcp__${bridge.name}__${permission.toolName}` : void 0
+      );
+      let runCommand = command;
+      let stdinInput = prompt;
+      if (sandbox.capabilities.writableStdin === false) {
+        const promptPath = `/tmp/tanstack-claude-prompt-${runId}`;
+        await sandbox.fs.write(promptPath, prompt);
+        tempFiles.push(promptPath);
+        runCommand = `${command} < ${q(promptPath)}`;
+        stdinInput = void 0;
+      }
+      logger.request(
+        `activity=chat provider=claude-code model=${this.model} sandbox=${sandbox.provider} messages=${options.messages.length} resume=${resume ?? "none"}`,
+        { provider: "claude-code", model: this.model }
+      );
+      const rawEvents = spawnNdjson(sandbox, runCommand, {
+        cwd,
+        ...stdinInput !== void 0 ? { input: stdinInput } : {},
+        // claude maps `bypassPermissions` to `--dangerously-skip-permissions`,
+        // which it refuses to run as root. Sandbox containers routinely run as
+        // root (Docker / Cloudflare), so set `IS_SANDBOX=1` — claude's
+        // documented escape hatch for skip-permissions in an isolated
+        // environment — merged over the sandbox env (a caller-provided value
+        // wins). Safe to set unconditionally; it is a no-op for stricter modes.
+        env: { IS_SANDBOX: "1", ...this.adapterConfig.env },
+        ...options.abortController?.signal ? { signal: options.abortController.signal } : options.request?.signal ? { signal: options.request.signal } : {},
+        onNonJsonLine: (line) => logger.provider(`provider=claude-code non-json line: ${line}`, {
+          chunk: line
+        })
+      });
+      async function* asMessages() {
+        for await (const event of rawEvents) yield event;
+      }
+      yield* mergeChunkStreams(
+        translateSdkStream(asMessages(), {
+          model: this.model,
+          runId,
+          threadId,
+          ...options.parentRunId !== void 0 && {
+            parentRunId: options.parentRunId
+          },
+          genId: () => this.generateId(),
+          onSdkMessage: (message) => logger.provider(`provider=claude-code type=${message.type}`, {
+            chunk: message
+          })
+        }),
+        channel.stream
+      );
+      if (this.adapterConfig.emitDiff !== false) {
+        try {
+          const diff = await sandbox.process.exec(`git -C ${q(cwd)} diff`, {
+            cwd
+          });
+          if (diff.exitCode === 0 && diff.stdout.trim() !== "") {
+            yield {
+              type: EventType.CUSTOM,
+              name: "file.changed",
+              value: { path: ".", diff: diff.stdout },
+              timestamp: Date.now(),
+              threadId,
+              runId
+            };
+          }
+        } catch {
+        }
+      }
+      for (const event of approvalRequests) yield event;
+    } catch (error) {
+      const err = error;
+      const rawEvent = toRunErrorRawEvent(error);
+      logger.errors("claude-code.chatStream fatal", {
+        error,
+        source: "claude-code.chatStream"
+      });
+      yield {
+        type: EventType.RUN_ERROR,
+        model: options.model,
+        timestamp: Date.now(),
+        message: err.message || "Unknown error occurred",
+        ...err.code !== void 0 && { code: err.code },
+        ...rawEvent !== void 0 && { rawEvent },
+        error: {
+          message: err.message || "Unknown error occurred",
+          ...err.code !== void 0 && { code: err.code }
+        }
+      };
+    } finally {
+      channel?.close();
+      if (bridge) await bridge.close();
+      if (cleanupSandbox) {
+        for (const path of tempFiles) {
+          try {
+            await cleanupSandbox.fs.remove(path);
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  structuredOutput(_options) {
+    return Promise.reject(
+      new Error(
+        "Structured output is not yet supported by the in-sandbox Claude Code adapter. Use a model adapter (e.g. anthropic) for structured output, or omit outputSchema."
+      )
+    );
+  }
+}
+function claudeCodeText(model, config = {}) {
+  return new ClaudeCodeTextAdapter(config, model);
+}
+export {
+  ClaudeCodeTextAdapter,
+  claudeCodeText
+};
+//# sourceMappingURL=text.js.map