@posthog/agent 2.3.349 → 2.3.353

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.3.349",
+  "version": "2.3.353",
   "repository": "https://github.com/PostHog/code",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {
@@ -87,8 +87,8 @@
     "typescript": "^5.5.0",
     "vitest": "^2.1.8",
     "@posthog/shared": "1.0.0",
-    "@posthog/git": "1.0.0",
-    "@posthog/enricher": "1.0.0"
+    "@posthog/enricher": "1.0.0",
+    "@posthog/git": "1.0.0"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.19.0",

package/src/adapters/claude/hooks.ts

@@ -173,12 +173,12 @@ export const createPostToolUseHook =
  *
  * https://github.com/anthropics/claude-agent-sdk-typescript/issues/267
  */
-const SUBAGENT_REWRITES: Record<string, string> = {
+export const SUBAGENT_REWRITES: Record<string, string> = {
   Explore: "ph-explore",
 };
 
 export const createSubagentRewriteHook =
-  (logger: Logger): HookCallback =>
+  (logger: Logger, registeredAgents: ReadonlySet<string>): HookCallback =>
   async (input: HookInput, _toolUseID: string | undefined) => {
     if (input.hook_event_name !== "PreToolUse") {
       return { continue: true };
@@ -195,6 +195,13 @@ export const createSubagentRewriteHook =
     }
 
     const target = SUBAGENT_REWRITES[subagentType];
+    if (!registeredAgents.has(target)) {
+      logger.warn(
+        `[SubagentRewriteHook] Skipping rewrite ${subagentType} → ${target}: target agent not registered for this session. Falling back to built-in ${subagentType}.`,
+      );
+      return { continue: true };
+    }
+
     logger.info(
       `[SubagentRewriteHook] Rewriting subagent_type: ${subagentType} → ${target}`,
     );

package/src/adapters/claude/permissions/permission-handlers.ts

@@ -2,7 +2,10 @@ import type {
   AgentSideConnection,
   RequestPermissionResponse,
 } from "@agentclientprotocol/sdk";
-import type { PermissionUpdate } from "@anthropic-ai/claude-agent-sdk";
+import type {
+  PermissionRuleValue,
+  PermissionUpdate,
+} from "@anthropic-ai/claude-agent-sdk";
 import { text } from "../../../utils/acp-content";
 import type { Logger } from "../../../utils/logger";
 import { toolInfoFromToolUse } from "../conversion/tool-use-to-acp";
@@ -347,7 +350,7 @@ async function handleDefaultPermissionFlow(
   const options = buildPermissionOptions(
     toolName,
     toolInput as Record<string, unknown>,
-    session?.cwd,
+    session.settingsManager.getRepoRoot(),
     suggestions,
   );
 
@@ -374,17 +377,19 @@ async function handleDefaultPermissionFlow(
       response.outcome.optionId === "allow_always")
   ) {
     if (response.outcome.optionId === "allow_always") {
+      const rules = extractAllowRules(suggestions, toolName);
+      try {
+        await session.settingsManager.addAllowRules(rules);
+      } catch (error) {
+        context.logger.warn(
+          "[canUseTool] Failed to persist allow rules to repository settings",
+          { error: error instanceof Error ? error.message : String(error) },
+        );
+      }
       return {
         behavior: "allow",
         updatedInput: toolInput as Record<string, unknown>,
-        updatedPermissions: suggestions ?? [
-          {
-            type: "addRules",
-            rules: [{ toolName }],
-            behavior: "allow",
-            destination: "localSettings",
-          },
-        ],
+        updatedPermissions: buildSessionPermissions(suggestions, rules),
       };
     }
     return {
@@ -429,6 +434,44 @@ function handlePlanFileException(
   };
 }
 
+function extractAllowRules(
+  suggestions: PermissionUpdate[] | undefined,
+  toolName: string,
+): PermissionRuleValue[] {
+  if (!suggestions || suggestions.length === 0) {
+    return [{ toolName }];
+  }
+  return suggestions
+    .filter(
+      (update) => update.type === "addRules" && update.behavior === "allow",
+    )
+    .flatMap((update) => ("rules" in update ? update.rules : []));
+}
+
+/**
+ * Forwards any non-addRules suggestions from the SDK (e.g. addDirectories)
+ * with their destination remapped to `session`. Our own allow rules are
+ * persisted via `settingsManager.addAllowRules`, so the SDK must not write
+ * them to its default per-cwd location.
+ */
+function buildSessionPermissions(
+  suggestions: PermissionUpdate[] | undefined,
+  rules: PermissionRuleValue[],
+): PermissionUpdate[] {
+  const passthrough = (suggestions ?? [])
+    .filter(
+      (update) => !(update.type === "addRules" && update.behavior === "allow"),
+    )
+    .map((update) => ({ ...update, destination: "session" as const }));
+  if (rules.length === 0) {
+    return passthrough;
+  }
+  return [
+    { type: "addRules", rules, behavior: "allow", destination: "session" },
+    ...passthrough,
+  ];
+}
+
 function extractDomainFromUrl(url: string): string | null {
   try {
     return new URL(url).hostname;

package/src/adapters/claude/permissions/permission-options.ts

@@ -25,7 +25,7 @@ function permissionOptions(allowAlwaysLabel: string): PermissionOption[] {
 export function buildPermissionOptions(
   toolName: string,
   toolInput: Record<string, unknown>,
-  cwd?: string,
+  repoRoot?: string,
   suggestions?: PermissionUpdate[],
 ): PermissionOption[] {
   if (BASH_TOOLS.has(toolName)) {
@@ -36,11 +36,11 @@ export function buildPermissionOptions(
 
     const command = toolInput?.command as string | undefined;
     const cmdName = command?.split(/\s+/)[0] ?? "this command";
-    const cwdLabel = cwd ? ` in ${cwd}` : "";
+    const scopeLabel = repoRoot ? ` in ${repoRoot}` : "";
     const label = ruleContent ?? `\`${cmdName}\` commands`;
 
     return permissionOptions(
-      `Yes, and don't ask again for ${label}${cwdLabel}`,
+      `Yes, and don't ask again for ${label}${scopeLabel}`,
     );
   }
 

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

@@ -0,0 +1,72 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+import { Logger } from "../../../utils/logger";
+import { SUBAGENT_REWRITES } from "../hooks";
+import { buildSessionOptions } from "./options";
+import { SettingsManager } from "./settings";
+
+function makeParams() {
+  const cwd = path.join(os.tmpdir(), `options-test-${Date.now()}`);
+  return {
+    cwd,
+    mcpServers: {},
+    permissionMode: "default" as const,
+    canUseTool: async () => ({ behavior: "allow" as const, updatedInput: {} }),
+    logger: new Logger(),
+    sessionId: "test-session",
+    isResume: false,
+    settingsManager: new SettingsManager(cwd),
+  };
+}
+
+describe("buildSessionOptions", () => {
+  it.each(Object.entries(SUBAGENT_REWRITES))(
+    'registers rewrite target "%s" → "%s" in options.agents',
+    (_source, target) => {
+      const options = buildSessionOptions(makeParams());
+      const registered = new Set(Object.keys(options.agents ?? {}));
+
+      expect(
+        registered.has(target),
+        `Rewrite target "${target}" is not registered in options.agents — either register the agent in buildAgents or remove the rewrite.`,
+      ).toBe(true);
+    },
+  );
+
+  it("preserves caller-provided agents alongside defaults", () => {
+    const params = makeParams();
+    const options = buildSessionOptions({
+      ...params,
+      userProvidedOptions: {
+        agents: {
+          "custom-agent": {
+            description: "Custom",
+            prompt: "Custom prompt",
+          },
+        },
+      },
+    });
+
+    expect(options.agents?.["custom-agent"]).toBeDefined();
+    expect(options.agents?.["ph-explore"]).toBeDefined();
+  });
+
+  it("lets caller-provided agents override defaults by name", () => {
+    const params = makeParams();
+    const override = {
+      description: "Overridden",
+      prompt: "Overridden prompt",
+    };
+    const options = buildSessionOptions({
+      ...params,
+      userProvidedOptions: {
+        agents: {
+          "ph-explore": override,
+        },
+      },
+    });
+
+    expect(options.agents?.["ph-explore"]).toEqual(override);
+  });
+});

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

@@ -117,6 +117,7 @@ function buildHooks(
   logger: Logger,
   enrichmentDeps: FileEnrichmentDeps | undefined,
   enrichedReadCache: EnrichedReadCache | undefined,
+  registeredAgents: ReadonlySet<string>,
 ): Options["hooks"] {
   const postToolUseHooks = [createPostToolUseHook({ onModeChange, logger })];
   if (enrichmentDeps && enrichedReadCache) {
@@ -136,13 +137,62 @@ function buildHooks(
       {
         hooks: [
           createPreToolUseHook(settingsManager, logger),
-          createSubagentRewriteHook(logger),
+          createSubagentRewriteHook(logger, registeredAgents),
         ],
       },
     ],
   };
 }
 
+/**
+ * Read-only Haiku-powered exploration agent. Registered under the `ph-explore`
+ * name rather than `Explore` to work around a Claude Agent SDK bug where
+ * `options.agents` cannot shadow built-in agent definitions. The
+ * `createSubagentRewriteHook` rewrites `subagent_type: "Explore"` to
+ * `"ph-explore"` so callers don't have to know about the alias.
+ */
+const PH_EXPLORE_AGENT: NonNullable<Options["agents"]>[string] = {
+  description:
+    'Fast agent for exploring and understanding codebases. Use this when you need to find files by pattern (eg. "src/components/**/*.tsx"), search for code or keywords (eg. "where is the auth middleware?"), or answer questions about how the codebase works (eg. "how does the session service handle reconnects?"). When calling this agent, specify a thoroughness level: "quick" for targeted lookups, "medium" for broader exploration, or "very thorough" for comprehensive analysis across multiple locations.',
+  model: "haiku",
+  prompt: `You are a fast, read-only codebase exploration agent.
+
+Your job is to find files, search code, read the most relevant sources, and report findings clearly.
+
+Rules:
+- Never create, modify, delete, move, or copy files.
+- Never use shell redirection or any command that changes system state.
+- Use Glob for broad file pattern matching.
+- Use Grep for searching file contents.
+- Use Read when you know the exact file path to inspect.
+- Use Bash only for safe read-only commands like ls, git status, git log, git diff, find, cat, head, and tail.
+- Adapt your search approach based on the thoroughness level specified by the caller.
+- Return file paths as absolute paths in your final response.
+- Avoid using emojis.
+- Wherever possible, spawn multiple parallel tool calls for grepping and reading files.
+- Search efficiently, then read only the most relevant files.
+- Return findings directly in your final response — do not create files.`,
+  tools: [
+    "Bash",
+    "Glob",
+    "Grep",
+    "Read",
+    "WebFetch",
+    "WebSearch",
+    "NotebookRead",
+    "TodoWrite",
+  ],
+};
+
+function buildAgents(
+  userAgents: Options["agents"],
+): NonNullable<Options["agents"]> {
+  return {
+    "ph-explore": PH_EXPLORE_AGENT,
+    ...(userAgents || {}),
+  };
+}
+
 function getAbortController(
   userProvidedController: AbortController | undefined,
 ): AbortController {
@@ -256,6 +306,9 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
       ? []
       : { type: "preset", preset: "claude_code" });
 
+  const agents = buildAgents(params.userProvidedOptions?.agents);
+  const registeredAgentNames = new Set(Object.keys(agents));
+
   const options: Options = {
     ...params.userProvidedOptions,
     betas: ["context-1m-2025-08-07"],
@@ -269,6 +322,7 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
     canUseTool: params.canUseTool,
     executable: "node",
     tools,
+    agents,
     extraArgs: {
       ...params.userProvidedOptions?.extraArgs,
       "replay-user-messages": "",
@@ -285,6 +339,7 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
       params.logger,
       params.enrichmentDeps,
       params.enrichedReadCache,
+      registeredAgentNames,
     ),
     outputFormat: params.outputFormat,
     abortController: getAbortController(

package/src/adapters/claude/session/repo-path.ts

@@ -0,0 +1,22 @@
+import { listWorktrees } from "@posthog/git/queries";
+
+/**
+ * Resolves the primary worktree (main repository) path for a given cwd.
+ *
+ * Secondary git worktrees share a `.git` common directory with the primary
+ * worktree. Returning the primary worktree path lets us scope per-repo
+ * settings — such as "don't ask again" permission rules — to a single
+ * location that every worktree of the same repository can read from.
+ *
+ * `git worktree list --porcelain` always emits the primary worktree first.
+ * Returns `cwd` when the directory is not inside a git repository or when
+ * git is unavailable.
+ */
+export async function resolveMainRepoPath(cwd: string): Promise<string> {
+  try {
+    const worktrees = await listWorktrees(cwd);
+    return worktrees[0]?.path ?? cwd;
+  } catch {
+    return cwd;
+  }
+}

package/src/adapters/claude/session/settings.test.ts

@@ -0,0 +1,159 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { resolveMainRepoPath } from "./repo-path";
+import { SettingsManager } from "./settings";
+
+function runGit(cwd: string, args: string[]): void {
+  execFileSync("git", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+}
+
+describe("SettingsManager per-repo persistence", () => {
+  let mainRepo: string;
+  let worktree: string;
+  let tmpRoot: string;
+
+  beforeEach(async () => {
+    tmpRoot = await fs.promises.realpath(
+      await fs.promises.mkdtemp(path.join(os.tmpdir(), "settings-manager-")),
+    );
+    mainRepo = path.join(tmpRoot, "main");
+    worktree = path.join(tmpRoot, "wt");
+    await fs.promises.mkdir(mainRepo, { recursive: true });
+
+    runGit(mainRepo, ["init", "-b", "main"]);
+    runGit(mainRepo, ["config", "user.email", "test@example.com"]);
+    runGit(mainRepo, ["config", "user.name", "test"]);
+    runGit(mainRepo, ["commit", "--allow-empty", "-m", "init"]);
+    runGit(mainRepo, ["worktree", "add", "-b", "feat", worktree]);
+  });
+
+  afterEach(async () => {
+    await fs.promises.rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  it("persists allow rules to the primary worktree when invoked from a secondary worktree", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await manager.addAllowRules([
+      { toolName: "Bash", ruleContent: "pnpm test:*" },
+    ]);
+
+    const repoLocalPath = path.join(mainRepo, ".claude", "settings.local.json");
+    const contents = JSON.parse(
+      await fs.promises.readFile(repoLocalPath, "utf-8"),
+    );
+    expect(contents.permissions.allow).toContain("Bash(pnpm test:*)");
+
+    const worktreeLocalPath = path.join(
+      worktree,
+      ".claude",
+      "settings.local.json",
+    );
+    expect(fs.existsSync(worktreeLocalPath)).toBe(false);
+  });
+
+  it("sees rules persisted by a sibling worktree after re-initialization", async () => {
+    const writer = new SettingsManager(worktree);
+    await writer.initialize();
+    await writer.addAllowRules([{ toolName: "TodoWrite" }]);
+
+    const sibling = path.join(tmpRoot, "wt2");
+    runGit(mainRepo, ["worktree", "add", "-b", "other", sibling]);
+
+    const reader = new SettingsManager(sibling);
+    await reader.initialize();
+    const decision = reader.checkPermission("TodoWrite", {});
+    expect(decision.decision).toBe("allow");
+  });
+
+  it("widens name-based matching for argumentless rules", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await manager.addAllowRules([{ toolName: "TodoWrite" }]);
+
+    expect(manager.checkPermission("TodoWrite", {}).decision).toBe("allow");
+  });
+
+  it("does not widen name-based matching when the rule has an argument", async () => {
+    // A rule *with* an argument for a tool we don't have an accessor for must
+    // not match regardless of the actual input — otherwise a deny rule like
+    // `Bash(rm -rf)` applied to a non-ACP Bash invocation would match any
+    // command.
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await manager.addAllowRules([
+      { toolName: "UnknownTool", ruleContent: "something" },
+    ]);
+
+    expect(
+      manager.checkPermission("UnknownTool", { command: "anything" }).decision,
+    ).toBe("ask");
+  });
+
+  it("still allows ACP-prefixed Bash invocations when a Bash(...) rule is persisted", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await manager.addAllowRules([
+      { toolName: "Bash", ruleContent: "pnpm test:*" },
+    ]);
+
+    const decision = manager.checkPermission("mcp__acp__Bash", {
+      command: "pnpm test --filter agent",
+    });
+    expect(decision.decision).toBe("allow");
+  });
+
+  it("refuses to overwrite the file when existing contents cannot be parsed", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    const filePath = path.join(mainRepo, ".claude", "settings.local.json");
+    const original = "{ this is not valid json";
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.promises.writeFile(filePath, original);
+
+    await expect(
+      manager.addAllowRules([{ toolName: "TodoWrite" }]),
+    ).rejects.toThrow();
+
+    // File must be untouched — overwriting would wipe whatever the user had.
+    expect(await fs.promises.readFile(filePath, "utf-8")).toBe(original);
+  });
+
+  it("concurrent addAllowRules calls do not clobber each other", async () => {
+    const manager = new SettingsManager(worktree);
+    await manager.initialize();
+
+    await Promise.all([
+      manager.addAllowRules([{ toolName: "A" }]),
+      manager.addAllowRules([{ toolName: "B" }]),
+      manager.addAllowRules([{ toolName: "C" }]),
+    ]);
+
+    const filePath = path.join(mainRepo, ".claude", "settings.local.json");
+    const contents = JSON.parse(await fs.promises.readFile(filePath, "utf-8"));
+    expect(contents.permissions.allow).toEqual(
+      expect.arrayContaining(["A", "B", "C"]),
+    );
+  });
+});
+
+describe("resolveMainRepoPath", () => {
+  it("returns cwd when the directory is not inside a git repository", async () => {
+    const tmp = await fs.promises.realpath(
+      await fs.promises.mkdtemp(path.join(os.tmpdir(), "repo-path-")),
+    );
+    try {
+      expect(await resolveMainRepoPath(tmp)).toBe(tmp);
+    } finally {
+      await fs.promises.rm(tmp, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -1,7 +1,10 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { PermissionRuleValue } from "@anthropic-ai/claude-agent-sdk";
 import { minimatch } from "minimatch";
+import { AsyncMutex } from "../../../utils/async-mutex";
+import { resolveMainRepoPath } from "./repo-path";
 
 const ACP_TOOL_NAME_PREFIX = "mcp__acp__";
 
@@ -86,7 +89,8 @@ function matchesRule(
   const ruleAppliesToTool =
     (rule.toolName === "Bash" && toolName === acpToolNames.bash) ||
     (rule.toolName === "Edit" && FILE_EDITING_TOOLS.includes(toolName)) ||
-    (rule.toolName === "Read" && FILE_READING_TOOLS.includes(toolName));
+    (rule.toolName === "Read" && FILE_READING_TOOLS.includes(toolName)) ||
+    (rule.toolName === toolName && !rule.argument);
 
   if (!ruleAppliesToTool) {
     return false;
@@ -123,6 +127,23 @@ function matchesRule(
   return matchesGlob(rule.argument, actualArg, cwd);
 }
 
+function formatRule(rule: PermissionRuleValue): string {
+  return rule.ruleContent
+    ? `${rule.toolName}(${rule.ruleContent})`
+    : rule.toolName;
+}
+
+async function writeFileAtomic(filePath: string, data: string): Promise<void> {
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.promises.writeFile(tmpPath, data);
+  try {
+    await fs.promises.rename(tmpPath, filePath);
+  } catch (error) {
+    await fs.promises.rm(tmpPath, { force: true });
+    throw error;
+  }
+}
+
 async function loadSettingsFile(
   filePath: string | undefined,
 ): Promise<ClaudeCodeSettings> {
@@ -143,6 +164,26 @@ async function loadSettingsFile(
   }
 }
 
+/**
+ * Reads a settings file for a read-modify-write cycle. Unlike
+ * `loadSettingsFile`, this throws on any error other than ENOENT — we refuse
+ * to overwrite a file we couldn't parse, because doing so would wipe the
+ * user's existing settings (other allow/deny/ask rules, env, model, etc).
+ */
+async function readSettingsFileForUpdate(
+  filePath: string,
+): Promise<ClaudeCodeSettings> {
+  try {
+    const content = await fs.promises.readFile(filePath, "utf-8");
+    return JSON.parse(content) as ClaudeCodeSettings;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return {};
+    }
+    throw error;
+  }
+}
+
 export interface PermissionSettings {
   allow?: string[];
   deny?: string[];
@@ -177,8 +218,10 @@ export function getManagedSettingsPath(): string {
       return "/etc/claude-code/managed-settings.json";
   }
 }
+
 export class SettingsManager {
   private cwd: string;
+  private repoRoot: string;
   private userSettings: ClaudeCodeSettings = {};
   private projectSettings: ClaudeCodeSettings = {};
   private localSettings: ClaudeCodeSettings = {};
@@ -186,9 +229,11 @@ export class SettingsManager {
   private mergedSettings: ClaudeCodeSettings = {};
   private initialized = false;
   private initPromise: Promise<void> | null = null;
+  private writeMutex = new AsyncMutex();
 
   constructor(cwd: string) {
     this.cwd = cwd;
+    this.repoRoot = cwd;
   }
 
   async initialize(): Promise<void> {
@@ -211,11 +256,17 @@ export class SettingsManager {
     return path.join(this.cwd, ".claude", "settings.json");
   }
 
+  /**
+   * Local settings are anchored to the primary worktree so every worktree of
+   * the same repository shares a single `.claude/settings.local.json`. This
+   * avoids re-prompting for the same permission in every worktree.
+   */
   private getLocalSettingsPath(): string {
-    return path.join(this.cwd, ".claude", "settings.local.json");
+    return path.join(this.repoRoot, ".claude", "settings.local.json");
   }
 
   private async loadAllSettings(): Promise<void> {
+    this.repoRoot = await resolveMainRepoPath(this.cwd);
     const [userSettings, projectSettings, localSettings, enterpriseSettings] =
       await Promise.all([
         loadSettingsFile(this.getUserSettingsPath()),
@@ -278,10 +329,6 @@ export class SettingsManager {
   }
 
   checkPermission(toolName: string, toolInput: unknown): PermissionCheckResult {
-    if (!toolName.startsWith(ACP_TOOL_NAME_PREFIX)) {
-      return { decision: "ask" };
-    }
-
     const permissions = this.mergedSettings.permissions;
     if (!permissions) {
       return { decision: "ask" };
@@ -319,6 +366,45 @@ export class SettingsManager {
     return this.cwd;
   }
 
+  getRepoRoot(): string {
+    return this.repoRoot;
+  }
+
+  /**
+   * Persists allow rules to `<primary-worktree>/.claude/settings.local.json`.
+   * Because local settings are resolved against the primary worktree, every
+   * worktree of the same repository picks up the new rule on next load.
+   *
+   * Writes are serialised via `writeMutex` to prevent concurrent callers from
+   * clobbering each other, and use a temp-file + rename to keep the file
+   * consistent if the process dies mid-write.
+   */
+  async addAllowRules(rules: PermissionRuleValue[]): Promise<void> {
+    if (rules.length === 0) return;
+    if (!this.initialized) await this.initialize();
+    await this.writeMutex.acquire();
+    try {
+      const filePath = this.getLocalSettingsPath();
+      const existing = await readSettingsFileForUpdate(filePath);
+      const permissions: PermissionSettings = {
+        ...(existing.permissions ?? {}),
+      };
+      const current = new Set(permissions.allow ?? []);
+      for (const rule of rules) {
+        current.add(formatRule(rule));
+      }
+      permissions.allow = Array.from(current);
+      const next: ClaudeCodeSettings = { ...existing, permissions };
+      await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+      await writeFileAtomic(filePath, `${JSON.stringify(next, null, 2)}\n`);
+
+      this.localSettings = next;
+      this.mergeAllSettings();
+    } finally {
+      this.writeMutex.release();
+    }
+  }
+
   async setCwd(cwd: string): Promise<void> {
     if (this.cwd === cwd) return;
     if (this.initPromise) await this.initPromise;