@posthog/agent 2.3.647 → 2.3.656

package/dist/types.d.ts

@@ -26,7 +26,7 @@ interface Task {
     slug?: string;
     title: string;
     description: string;
-    origin_product: "error_tracking" | "eval_clusters" | "user_created" | "support_queue" | "session_summaries";
+    origin_product: "error_tracking" | "eval_clusters" | "user_created" | "support_queue" | "session_summaries" | "signal_report";
     github_integration?: number | null;
     repository: string;
     json_schema?: Record<string, unknown> | null;

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type {\n  GitHandoffCheckpoint,\n  HandoffLocalGitState as GitHandoffLocalGitState,\n} from \"@posthog/git/handoff\";\n\n/**\n * Stored custom notification following ACP extensibility model.\n * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).\n * See: https://agentclientprotocol.com/docs/extensibility\n */\nexport interface StoredNotification {\n  type: \"notification\";\n  /** When this notification was stored */\n  timestamp: string;\n  /** JSON-RPC 2.0 notification (no id field = notification, not request) */\n  notification: {\n    jsonrpc: \"2.0\";\n    method: string;\n    params?: Record<string, unknown>;\n  };\n}\n\n/**\n * Type alias for stored log entries.\n */\nexport type StoredEntry = StoredNotification;\n\n// PostHog Task model (matches PostHog Code's OpenAPI schema)\nexport interface Task {\n  id: string;\n  task_number?: number;\n  slug?: string;\n  title: string;\n  description: string;\n  origin_product:\n    | \"error_tracking\"\n    | \"eval_clusters\"\n    | \"user_created\"\n    | \"support_queue\"\n    | \"session_summaries\";\n  github_integration?: number | null;\n  repository: string; // Format: \"organization/repository\" (e.g., \"posthog/posthog-js\")\n  json_schema?: Record<string, unknown> | null; // JSON schema for task output validation\n  internal?: boolean;\n  created_at: string;\n  updated_at: string;\n  created_by?: {\n    id: number;\n    uuid: string;\n    distinct_id: string;\n    first_name: string;\n    email: string;\n  };\n  latest_run?: TaskRun;\n}\n\n// Log entry structure for TaskRun.log\n\nexport type ArtifactType =\n  | \"plan\"\n  | \"context\"\n  | \"reference\"\n  | \"output\"\n  | \"artifact\"\n  | \"user_attachment\";\n\nexport interface TaskRunArtifact {\n  id?: string;\n  name: string;\n  type: ArtifactType;\n  source?: string;\n  size?: number;\n  content_type?: string;\n  storage_path?: string;\n  uploaded_at?: string;\n}\n\nexport type TaskRunStatus =\n  | \"not_started\"\n  | \"queued\"\n  | \"in_progress\"\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\";\n\nexport type TaskRunEnvironment = \"local\" | \"cloud\";\n\n// TaskRun model - represents individual execution runs of tasks\nexport interface TaskRun {\n  id: string;\n  task: string; // Task ID\n  team: number;\n  branch: string | null;\n  stage: string | null; // Current stage (e.g., 'research', 'plan', 'build')\n  environment: TaskRunEnvironment;\n  status: TaskRunStatus;\n  log_url: string;\n  error_message: string | null;\n  output: Record<string, unknown> | null; // Structured output (PR URL, commit SHA, etc.)\n  state: Record<string, unknown>; // Intermediate run state (defaults to {}, never null)\n  artifacts?: TaskRunArtifact[];\n  created_at: string;\n  updated_at: string;\n  completed_at: string | null;\n}\n\nexport interface ProcessSpawnedCallback {\n  onProcessSpawned?: (info: {\n    pid: number;\n    command: string;\n    sessionId?: string;\n  }) => void;\n  onProcessExited?: (pid: number) => void;\n  onMcpServersReady?: (serverNames: string[]) => void;\n}\n\nexport interface TaskExecutionOptions {\n  repositoryPath?: string;\n  adapter?: \"claude\" | \"codex\";\n  model?: string;\n  gatewayUrl?: string;\n  codexBinaryPath?: string;\n  instructions?: string;\n  processCallbacks?: ProcessSpawnedCallback;\n  /** Callback invoked when the agent calls the create_output tool for structured output */\n  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;\n}\n\nexport type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nexport type OnLogCallback = (\n  level: LogLevel,\n  scope: string,\n  message: string,\n  data?: unknown,\n) => void;\n\nexport interface PostHogAPIConfig {\n  apiUrl: string;\n  getApiKey: () => string | Promise<string>;\n  refreshApiKey?: () => string | Promise<string>;\n  projectId: number;\n  userAgent?: string;\n}\n\nexport interface OtelTransportConfig {\n  /** PostHog ingest host, e.g., \"https://us.i.posthog.com\" */\n  host: string;\n  /** Project API key */\n  apiKey: string;\n  /** Override the logs endpoint path (default: /i/v1/logs) */\n  logsPath?: string;\n}\n\nexport interface AgentConfig {\n  posthog?: PostHogAPIConfig;\n  /** OTEL transport config for shipping logs to PostHog Logs */\n  otelTransport?: OtelTransportConfig;\n  /** Skip session log persistence (e.g. for preview sessions with no real task) */\n  skipLogPersistence?: boolean;\n  /** Local cache path for instant log loading (e.g., ~/.posthog-code) */\n  localCachePath?: string;\n  /**\n   * Annotate files the agent reads with PostHog enrichment (event volume,\n   * flag rollout/staleness, experiment links). Defaults to enabled when\n   * `posthog` config is present; set `{ enabled: false }` to opt out.\n   */\n  enricher?: { enabled?: boolean };\n  debug?: boolean;\n  onLog?: OnLogCallback;\n}\n\n// Device info for tracking where work happens\nexport interface DeviceInfo {\n  type: \"local\" | \"cloud\";\n  name?: string;\n}\n\n// Agent execution mode - for tracking interactive vs background runs, when backgrounded an agent will continue working without asking questions\nexport type AgentMode = \"interactive\" | \"background\";\n\n// Git file status codes\nexport type FileStatus = \"A\" | \"M\" | \"D\";\n\nexport interface FileChange {\n  path: string;\n  status: FileStatus;\n}\n\nexport type HandoffLocalGitState = GitHandoffLocalGitState;\n\nexport interface GitCheckpoint extends GitHandoffCheckpoint {\n  artifactPath?: string;\n  indexArtifactPath?: string;\n}\n\nexport interface GitCheckpointEvent extends GitCheckpoint {\n  device?: DeviceInfo;\n}\n\n/**\n * Keeps the emitted `@posthog/agent/types` entrypoint as a runtime ESM module.\n *\n * `export {}` is stripped by tsup in this package, which leaves `dist/types.js`\n * empty and breaks downstream type resolution for the exported subpath.\n */\nexport const AGENT_TYPES_MODULE = true;\n"],"mappings":";AA8MO,IAAM,qBAAqB;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type {\n  GitHandoffCheckpoint,\n  HandoffLocalGitState as GitHandoffLocalGitState,\n} from \"@posthog/git/handoff\";\n\n/**\n * Stored custom notification following ACP extensibility model.\n * Custom notifications use underscore-prefixed methods (e.g., `_posthog/phase_start`).\n * See: https://agentclientprotocol.com/docs/extensibility\n */\nexport interface StoredNotification {\n  type: \"notification\";\n  /** When this notification was stored */\n  timestamp: string;\n  /** JSON-RPC 2.0 notification (no id field = notification, not request) */\n  notification: {\n    jsonrpc: \"2.0\";\n    method: string;\n    params?: Record<string, unknown>;\n  };\n}\n\n/**\n * Type alias for stored log entries.\n */\nexport type StoredEntry = StoredNotification;\n\n// PostHog Task model (matches PostHog Code's OpenAPI schema)\nexport interface Task {\n  id: string;\n  task_number?: number;\n  slug?: string;\n  title: string;\n  description: string;\n  origin_product:\n    | \"error_tracking\"\n    | \"eval_clusters\"\n    | \"user_created\"\n    | \"support_queue\"\n    | \"session_summaries\"\n    | \"signal_report\";\n  github_integration?: number | null;\n  repository: string; // Format: \"organization/repository\" (e.g., \"posthog/posthog-js\")\n  json_schema?: Record<string, unknown> | null; // JSON schema for task output validation\n  internal?: boolean;\n  created_at: string;\n  updated_at: string;\n  created_by?: {\n    id: number;\n    uuid: string;\n    distinct_id: string;\n    first_name: string;\n    email: string;\n  };\n  latest_run?: TaskRun;\n}\n\n// Log entry structure for TaskRun.log\n\nexport type ArtifactType =\n  | \"plan\"\n  | \"context\"\n  | \"reference\"\n  | \"output\"\n  | \"artifact\"\n  | \"user_attachment\";\n\nexport interface TaskRunArtifact {\n  id?: string;\n  name: string;\n  type: ArtifactType;\n  source?: string;\n  size?: number;\n  content_type?: string;\n  storage_path?: string;\n  uploaded_at?: string;\n}\n\nexport type TaskRunStatus =\n  | \"not_started\"\n  | \"queued\"\n  | \"in_progress\"\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\";\n\nexport type TaskRunEnvironment = \"local\" | \"cloud\";\n\n// TaskRun model - represents individual execution runs of tasks\nexport interface TaskRun {\n  id: string;\n  task: string; // Task ID\n  team: number;\n  branch: string | null;\n  stage: string | null; // Current stage (e.g., 'research', 'plan', 'build')\n  environment: TaskRunEnvironment;\n  status: TaskRunStatus;\n  log_url: string;\n  error_message: string | null;\n  output: Record<string, unknown> | null; // Structured output (PR URL, commit SHA, etc.)\n  state: Record<string, unknown>; // Intermediate run state (defaults to {}, never null)\n  artifacts?: TaskRunArtifact[];\n  created_at: string;\n  updated_at: string;\n  completed_at: string | null;\n}\n\nexport interface ProcessSpawnedCallback {\n  onProcessSpawned?: (info: {\n    pid: number;\n    command: string;\n    sessionId?: string;\n  }) => void;\n  onProcessExited?: (pid: number) => void;\n  onMcpServersReady?: (serverNames: string[]) => void;\n}\n\nexport interface TaskExecutionOptions {\n  repositoryPath?: string;\n  adapter?: \"claude\" | \"codex\";\n  model?: string;\n  gatewayUrl?: string;\n  codexBinaryPath?: string;\n  instructions?: string;\n  processCallbacks?: ProcessSpawnedCallback;\n  /** Callback invoked when the agent calls the create_output tool for structured output */\n  onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;\n}\n\nexport type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nexport type OnLogCallback = (\n  level: LogLevel,\n  scope: string,\n  message: string,\n  data?: unknown,\n) => void;\n\nexport interface PostHogAPIConfig {\n  apiUrl: string;\n  getApiKey: () => string | Promise<string>;\n  refreshApiKey?: () => string | Promise<string>;\n  projectId: number;\n  userAgent?: string;\n}\n\nexport interface OtelTransportConfig {\n  /** PostHog ingest host, e.g., \"https://us.i.posthog.com\" */\n  host: string;\n  /** Project API key */\n  apiKey: string;\n  /** Override the logs endpoint path (default: /i/v1/logs) */\n  logsPath?: string;\n}\n\nexport interface AgentConfig {\n  posthog?: PostHogAPIConfig;\n  /** OTEL transport config for shipping logs to PostHog Logs */\n  otelTransport?: OtelTransportConfig;\n  /** Skip session log persistence (e.g. for preview sessions with no real task) */\n  skipLogPersistence?: boolean;\n  /** Local cache path for instant log loading (e.g., ~/.posthog-code) */\n  localCachePath?: string;\n  /**\n   * Annotate files the agent reads with PostHog enrichment (event volume,\n   * flag rollout/staleness, experiment links). Defaults to enabled when\n   * `posthog` config is present; set `{ enabled: false }` to opt out.\n   */\n  enricher?: { enabled?: boolean };\n  debug?: boolean;\n  onLog?: OnLogCallback;\n}\n\n// Device info for tracking where work happens\nexport interface DeviceInfo {\n  type: \"local\" | \"cloud\";\n  name?: string;\n}\n\n// Agent execution mode - for tracking interactive vs background runs, when backgrounded an agent will continue working without asking questions\nexport type AgentMode = \"interactive\" | \"background\";\n\n// Git file status codes\nexport type FileStatus = \"A\" | \"M\" | \"D\";\n\nexport interface FileChange {\n  path: string;\n  status: FileStatus;\n}\n\nexport type HandoffLocalGitState = GitHandoffLocalGitState;\n\nexport interface GitCheckpoint extends GitHandoffCheckpoint {\n  artifactPath?: string;\n  indexArtifactPath?: string;\n}\n\nexport interface GitCheckpointEvent extends GitCheckpoint {\n  device?: DeviceInfo;\n}\n\n/**\n * Keeps the emitted `@posthog/agent/types` entrypoint as a runtime ESM module.\n *\n * `export {}` is stripped by tsup in this package, which leaves `dist/types.js`\n * empty and breaks downstream type resolution for the exported subpath.\n */\nexport const AGENT_TYPES_MODULE = true;\n"],"mappings":";AA+MO,IAAM,qBAAqB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.647",
+  "version": "2.3.656",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {

package/src/adapters/claude/claude-agent.ts

@@ -57,10 +57,17 @@ import {
   type FileEnrichmentDeps,
 } from "../../enrichment/file-enricher";
 import type { PostHogAPIConfig } from "../../types";
-import { unreachable, withTimeout } from "../../utils/common";
+import {
+  isCloudRun,
+  resolveGithubToken,
+  unreachable,
+  withTimeout,
+} from "../../utils/common";
 import { Logger } from "../../utils/logger";
 import { Pushable } from "../../utils/streams";
 import { BaseAcpAgent } from "../base-acp-agent";
+import { LOCAL_TOOLS_MCP_NAME } from "../local-tools";
+import { resolveTaskId } from "../session-meta";
 import { promptToClaude } from "./conversion/acp-to-sdk";
 import {
   handleResultMessage,
@@ -69,6 +76,7 @@ import {
   handleUserAssistantMessage,
 } from "./conversion/sdk-to-acp";
 import type { EnrichedReadCache } from "./hooks";
+import { createLocalToolsMcpServer } from "./mcp/local-tools";
 import {
   fetchMcpToolMetadata,
   getConnectedMcpServerNames,
@@ -1091,7 +1099,10 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     const isResume = !!resume;
 
     const meta = params._meta as NewSessionMeta | undefined;
-    const taskId = meta?.persistence?.taskId;
+    const taskId = resolveTaskId(meta);
+    // Gate signed-commit wiring on cloud-run detection so the desktop (which
+    // signs via CommitSaga) is untouched.
+    const cloudRun = isCloudRun(meta);
     const effort = meta?.claudeCode?.options?.effort as EffortLevel | undefined;
 
     // We want to create a new session id unless it is resume,
@@ -1115,6 +1126,24 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     const mcpServers = supportsMcpInjection(earlyModelId)
       ? parseMcpServers(params)
       : {};
+
+    // Register the in-process general local-tools MCP server. Tools self-gate
+    // via the registry (e.g. signed-commit is cloud-only and needs a GH token),
+    // so adding a tool needs no change here. In cloud runs `git commit`/`git
+    // push` are blocked by the PreToolUse guard (and the sandbox git shim), so
+    // the agent commits via the signed-commit tool instead.
+    const localToolsServer = createLocalToolsMcpServer(
+      { cwd, token: resolveGithubToken(), taskId },
+      meta,
+    );
+    if (localToolsServer) {
+      mcpServers[LOCAL_TOOLS_MCP_NAME] = localToolsServer;
+    } else if (cloudRun) {
+      this.logger.warn(
+        "Cloud run registered no local tools — missing GH_TOKEN/GITHUB_TOKEN? signed commits unavailable",
+      );
+    }
+
     const systemPrompt = buildSystemPrompt(meta?.systemPrompt);
 
     if (meta?.mcpToolApprovals) {
@@ -1164,6 +1193,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       effort,
       enrichmentDeps: this.enrichment?.deps,
       enrichedReadCache: this.enrichedReadCache,
+      cloudMode: cloudRun,
     });
 
     // Use the same abort controller that buildSessionOptions gave to the query

package/src/adapters/claude/hooks.test.ts

@@ -11,6 +11,7 @@ import { Logger } from "../../utils/logger";
 import {
   createPreToolUseHook,
   createReadEnrichmentHook,
+  createSignedCommitGuardHook,
   type EnrichedReadCache,
 } from "./hooks";
 import type {
@@ -311,3 +312,56 @@ describe("createPreToolUseHook", () => {
     });
   });
 });
+
+describe("createSignedCommitGuardHook", () => {
+  const logger = new Logger();
+
+  function bashInput(command: string): HookInput {
+    return {
+      session_id: "s",
+      transcript_path: "/tmp/t",
+      cwd: "/tmp",
+      hook_event_name: "PreToolUse",
+      tool_name: "Bash",
+      tool_use_id: "toolu_1",
+      tool_input: { command },
+    } as HookInput;
+  }
+
+  const guard = createSignedCommitGuardHook(logger);
+  const opts = { signal: new AbortController().signal };
+
+  test.each([
+    "git commit -m x",
+    "git push origin main",
+    "git add . && git commit -m 'y'",
+    "git -C /repo commit",
+    "git --no-pager push",
+  ])("denies %s", async (command) => {
+    const result = await guard(bashInput(command), undefined, opts);
+    expect(result).toMatchObject({
+      hookSpecificOutput: { permissionDecision: "deny" },
+    });
+  });
+
+  test.each([
+    "git status",
+    "git add .",
+    "git fetch origin",
+    "git log --grep=commit",
+    "git stash push",
+    "git ls-remote --heads origin x",
+  ])("allows %s", async (command) => {
+    const result = await guard(bashInput(command), undefined, opts);
+    expect(result).toEqual({ continue: true });
+  });
+
+  test("ignores non-Bash tools", async () => {
+    const result = await guard(
+      { ...bashInput("git commit"), tool_name: "Read" } as HookInput,
+      undefined,
+      opts,
+    );
+    expect(result).toEqual({ continue: true });
+  });
+});

package/src/adapters/claude/hooks.ts

@@ -4,6 +4,7 @@ import {
   type FileEnrichmentDeps,
 } from "../../enrichment/file-enricher";
 import type { Logger } from "../../utils/logger";
+import { SIGNED_COMMIT_QUALIFIED_TOOL_NAME } from "../signed-commit-shared";
 import { stripCatLineNumbers } from "./conversion/sdk-to-acp";
 import {
   extractPostHogSubTool,
@@ -222,6 +223,91 @@ export const createSubagentRewriteHook =
     };
   };
 
+// git global options that consume the following token as their value, so the
+// subcommand detector must skip both (mirrors the sandbox `git` PATH shim).
+const GIT_VALUE_FLAGS = new Set([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--exec-path",
+]);
+
+function gitSubcommand(segment: string): string | null {
+  const tokens = segment.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return null;
+  // Strip a leading path so `/usr/bin/git` is still recognised as git.
+  const head = tokens[0].split("/").pop();
+  if (head !== "git") return null;
+
+  let skipNext = false;
+  for (const tok of tokens.slice(1)) {
+    if (skipNext) {
+      skipNext = false;
+      continue;
+    }
+    if (GIT_VALUE_FLAGS.has(tok)) {
+      skipNext = true;
+      continue;
+    }
+    if (tok.startsWith("-")) continue;
+    return tok;
+  }
+  return null;
+}
+
+/**
+ * True when any top-level shell segment of `command` is a direct `git commit` /
+ * `git push` invocation (allowing `git`-level global flags like `-C path` or
+ * `--no-pager`). Does not match subcommands such as `git stash push` or
+ * `git log --grep=commit`. Git reached via command substitution (`$(git push)`)
+ * is not caught here — the sandbox `git` PATH shim is the authoritative backstop;
+ * this hook is a fast in-band deny with a helpful message.
+ */
+function blocksUnsignedGit(command: string): boolean {
+  // Cheap reject for the overwhelmingly common non-git Bash call before splitting.
+  if (!command.includes("git")) return false;
+  return command.split(/&&|\|\||[;\n|]/).some((segment) => {
+    const sub = gitSubcommand(segment);
+    return sub === "commit" || sub === "push";
+  });
+}
+
+/**
+ * Cloud-only guard: blocks raw `git commit` / `git push` so unsigned commits
+ * cannot leave the sandbox. The agent must use the `git_signed_commit` tool,
+ * which creates GitHub-signed (Verified) commits via the API.
+ */
+export const createSignedCommitGuardHook =
+  (logger: Logger): HookCallback =>
+  async (input: HookInput, _toolUseID: string | undefined) => {
+    if (input.hook_event_name !== "PreToolUse") return { continue: true };
+    if (input.tool_name !== "Bash") return { continue: true };
+
+    const command = (input.tool_input as { command?: string } | undefined)
+      ?.command;
+    if (!command || !blocksUnsignedGit(command)) {
+      return { continue: true };
+    }
+
+    logger.info(
+      `[SignedCommitGuard] Blocking unsigned git command: ${command}`,
+    );
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse" as const,
+        permissionDecision: "deny" as const,
+        permissionDecisionReason:
+          "Commits must be signed: `git commit` and `git push` are disabled here. " +
+          "Stage changes with `git add`, then call the `git_signed_commit` tool " +
+          `(${SIGNED_COMMIT_QUALIFIED_TOOL_NAME}) with a \`message\` to create a signed ` +
+          "commit on the branch.",
+      },
+    };
+  };
+
 export const createPreToolUseHook =
   (settingsManager: SettingsManager, logger: Logger): HookCallback =>
   async (input: HookInput, _toolUseID: string | undefined) => {

package/src/adapters/claude/mcp/local-tools.test.ts

@@ -0,0 +1,50 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createLocalToolsMcpServer } from "./local-tools";
+
+describe("createLocalToolsMcpServer", () => {
+  const savedSandbox = process.env.IS_SANDBOX;
+
+  beforeEach(() => {
+    // isCloudRun also keys off IS_SANDBOX; clear it so the meta arg is the only
+    // cloud signal under test.
+    delete process.env.IS_SANDBOX;
+  });
+
+  afterEach(() => {
+    if (savedSandbox === undefined) {
+      delete process.env.IS_SANDBOX;
+    } else {
+      process.env.IS_SANDBOX = savedSandbox;
+    }
+  });
+
+  it("returns undefined when no tool's gate passes (desktop run)", () => {
+    expect(
+      createLocalToolsMcpServer({ cwd: "/repo", token: "ghs_x" }, undefined),
+    ).toBeUndefined();
+  });
+
+  it("exposes git_signed_commit over MCP in a cloud run with a token", async () => {
+    const server = createLocalToolsMcpServer(
+      { cwd: "/repo", token: "ghs_x" },
+      { taskRunId: "run-1" },
+    );
+    if (!server) {
+      throw new Error("expected the local-tools server to be registered");
+    }
+    expect(server.name).toBe("posthog-local");
+
+    const [clientTransport, serverTransport] =
+      InMemoryTransport.createLinkedPair();
+    await server.instance.connect(serverTransport);
+    const client = new Client({ name: "test", version: "1.0.0" });
+    await client.connect(clientTransport);
+
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toContain("git_signed_commit");
+
+    await client.close();
+  });
+});

package/src/adapters/claude/mcp/local-tools.ts

@@ -0,0 +1,40 @@
+import {
+  createSdkMcpServer,
+  type McpSdkServerConfigWithInstance,
+  tool,
+} from "@anthropic-ai/claude-agent-sdk";
+import {
+  enabledLocalTools,
+  LOCAL_TOOLS_MCP_NAME,
+  type LocalToolCtx,
+  type LocalToolGateMeta,
+} from "../../local-tools";
+
+/**
+ * In-process SDK MCP server exposing the enabled local tools to the Claude
+ * adapter (see `../../local-tools` for the registry). Returns `undefined` when
+ * no tool's gate passes, so the caller can skip registering an empty server.
+ * Registered per session in `claude-agent.ts`.
+ */
+export function createLocalToolsMcpServer(
+  ctx: LocalToolCtx,
+  meta: LocalToolGateMeta | undefined,
+): McpSdkServerConfigWithInstance | undefined {
+  const tools = enabledLocalTools(ctx, meta);
+  if (tools.length === 0) {
+    return undefined;
+  }
+  return createSdkMcpServer({
+    name: LOCAL_TOOLS_MCP_NAME,
+    version: "1.0.0",
+    tools: tools.map((t) =>
+      tool(
+        t.name,
+        t.description,
+        t.schema,
+        async (args) => t.handler(ctx, args),
+        { alwaysLoad: t.alwaysLoad ?? false },
+      ),
+    ),
+  });
+}

package/src/adapters/claude/session/options.ts

@@ -17,6 +17,7 @@ import {
   createPostToolUseHook,
   createPreToolUseHook,
   createReadEnrichmentHook,
+  createSignedCommitGuardHook,
   createSubagentRewriteHook,
   type EnrichedReadCache,
   type OnModeChange,
@@ -55,6 +56,8 @@ export interface BuildOptionsParams {
   effort?: EffortLevel;
   enrichmentDeps?: FileEnrichmentDeps;
   enrichedReadCache?: EnrichedReadCache;
+  /** Cloud task session — enables the signed-commit guard. */
+  cloudMode?: boolean;
 }
 
 export function buildSystemPrompt(
@@ -129,6 +132,7 @@ function buildHooks(
   enrichmentDeps: FileEnrichmentDeps | undefined,
   enrichedReadCache: EnrichedReadCache | undefined,
   registeredAgents: ReadonlySet<string>,
+  cloudMode: boolean,
 ): Options["hooks"] {
   const postToolUseHooks = [createPostToolUseHook({ onModeChange })];
   if (enrichmentDeps && enrichedReadCache) {
@@ -137,21 +141,21 @@ function buildHooks(
     );
   }
 
+  const preToolUseHooks = [
+    createPreToolUseHook(settingsManager, logger),
+    createSubagentRewriteHook(logger, registeredAgents),
+  ];
+  if (cloudMode) {
+    preToolUseHooks.push(createSignedCommitGuardHook(logger));
+  }
+
   return {
     ...userHooks,
     PostToolUse: [
       ...(userHooks?.PostToolUse || []),
       { hooks: postToolUseHooks },
     ],
-    PreToolUse: [
-      ...(userHooks?.PreToolUse || []),
-      {
-        hooks: [
-          createPreToolUseHook(settingsManager, logger),
-          createSubagentRewriteHook(logger, registeredAgents),
-        ],
-      },
-    ],
+    PreToolUse: [...(userHooks?.PreToolUse || []), { hooks: preToolUseHooks }],
   };
 }
 
@@ -352,6 +356,7 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
       params.enrichmentDeps,
       params.enrichedReadCache,
       registeredAgentNames,
+      params.cloudMode ?? false,
     ),
     outputFormat: params.outputFormat,
     abortController: getAbortController(

package/src/adapters/claude/types.ts

@@ -120,6 +120,7 @@ export type SDKMessageFilter = {
 
 export type NewSessionMeta = {
   taskRunId?: string;
+  taskId?: string;
   disableBuiltInTools?: boolean;
   systemPrompt?: unknown;
   sessionId?: string;