feat(hook): one-click clear-context + bypass via native plan-accept + keystroke injection

apps/hook/server/clearContextSetting.test.ts

@@ -0,0 +1,146 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+let tmpHome: string;
+
+beforeEach(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), "plannotator-clear-context-test-"));
+  mock.module("os", () => {
+    const realOs = require("node:os");
+    return { ...realOs, homedir: () => tmpHome };
+  });
+});
+
+afterEach(() => {
+  mock.restore();
+  rmSync(tmpHome, { recursive: true, force: true });
+});
+
+async function freshImport() {
+  return (await import(
+    `./clearContextSetting?t=${Date.now()}-${Math.random()}`
+  )) as typeof import("./clearContextSetting");
+}
+
+function writeConsent() {
+  mkdirSync(join(tmpHome, ".plannotator", "consent"), { recursive: true });
+  writeFileSync(
+    join(tmpHome, ".plannotator", "consent", "clear-context-setting.json"),
+    JSON.stringify({ consented: true }),
+    "utf8",
+  );
+}
+
+describe("clearContextSetting", () => {
+  test("does not create settings without consent", async () => {
+    const { ensureClearContextSettingEnabled } = await freshImport();
+    await ensureClearContextSettingEnabled();
+    expect(existsSync(join(tmpHome, ".claude", "settings.json"))).toBe(false);
+  });
+
+  test("creates settings with showClearContextOnPlanAccept when consent exists", async () => {
+    writeConsent();
+    const { ensureClearContextSettingEnabled } = await freshImport();
+    await ensureClearContextSettingEnabled();
+
+    const settings = JSON.parse(
+      readFileSync(join(tmpHome, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings.showClearContextOnPlanAccept).toBe(true);
+  });
+
+  test("preserves existing settings keys", async () => {
+    writeConsent();
+    mkdirSync(join(tmpHome, ".claude"), { recursive: true });
+    writeFileSync(
+      join(tmpHome, ".claude", "settings.json"),
+      JSON.stringify({ theme: "dark", env: { A: "B" } }),
+      "utf8",
+    );
+
+    const { ensureClearContextSettingEnabled } = await freshImport();
+    await ensureClearContextSettingEnabled();
+
+    const settings = JSON.parse(
+      readFileSync(join(tmpHome, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings.theme).toBe("dark");
+    expect(settings.env).toEqual({ A: "B" });
+    expect(settings.showClearContextOnPlanAccept).toBe(true);
+  });
+
+  test("is idempotent when setting is already enabled", async () => {
+    writeConsent();
+    mkdirSync(join(tmpHome, ".claude"), { recursive: true });
+    writeFileSync(
+      join(tmpHome, ".claude", "settings.json"),
+      JSON.stringify({ showClearContextOnPlanAccept: true }),
+      "utf8",
+    );
+
+    const { ensureClearContextSettingEnabled } = await freshImport();
+    await ensureClearContextSettingEnabled();
+    await ensureClearContextSettingEnabled();
+
+    const settings = JSON.parse(
+      readFileSync(join(tmpHome, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings.showClearContextOnPlanAccept).toBe(true);
+  });
+
+  test("leaves malformed settings JSON untouched", async () => {
+    writeConsent();
+    mkdirSync(join(tmpHome, ".claude"), { recursive: true });
+    const malformed = "{ this is not valid json";
+    writeFileSync(join(tmpHome, ".claude", "settings.json"), malformed, "utf8");
+
+    const { ensureClearContextSettingEnabled } = await freshImport();
+    await ensureClearContextSettingEnabled();
+
+    expect(readFileSync(join(tmpHome, ".claude", "settings.json"), "utf8")).toBe(
+      malformed,
+    );
+  });
+
+  test("records consent atomically", async () => {
+    const { recordConsent } = await freshImport();
+    recordConsent();
+
+    const consentPath = join(
+      tmpHome,
+      ".plannotator",
+      "consent",
+      "clear-context-setting.json",
+    );
+    expect(existsSync(consentPath)).toBe(true);
+    const consent = JSON.parse(readFileSync(consentPath, "utf8"));
+    expect(consent.consented).toBe(true);
+    expect(typeof consent.recordedAt).toBe("string");
+  });
+
+  test("reports disabled when settings are missing", async () => {
+    const { isClearContextSettingEnabled } = await freshImport();
+    expect(isClearContextSettingEnabled()).toBe(false);
+  });
+
+  test("reports enabled when setting is true", async () => {
+    mkdirSync(join(tmpHome, ".claude"), { recursive: true });
+    writeFileSync(
+      join(tmpHome, ".claude", "settings.json"),
+      JSON.stringify({ showClearContextOnPlanAccept: true }),
+      "utf8",
+    );
+
+    const { isClearContextSettingEnabled } = await freshImport();
+    expect(isClearContextSettingEnabled()).toBe(true);
+  });
+});

apps/hook/server/clearContextSetting.ts

@@ -0,0 +1,105 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "fs";
+import { randomBytes } from "crypto";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+const SETTING_KEY = "showClearContextOnPlanAccept";
+
+function consentPath(): string {
+  return join(
+    homedir(),
+    ".plannotator",
+    "consent",
+    "clear-context-setting.json",
+  );
+}
+
+function settingsPath(): string {
+  return join(homedir(), ".claude", "settings.json");
+}
+
+function hasConsent(): boolean {
+  try {
+    if (!existsSync(consentPath())) return false;
+    const data = JSON.parse(readFileSync(consentPath(), "utf8"));
+    return data?.consented === true;
+  } catch {
+    return false;
+  }
+}
+
+function writeJsonAtomic(path: string, data: Record<string, unknown>): void {
+  const tmp = join(
+    dirname(path),
+    `plannotator-settings-${randomBytes(4).toString("hex")}.json`,
+  );
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", "utf8");
+  renameSync(tmp, path);
+}
+
+export function recordConsent(): void {
+  const dir = join(homedir(), ".plannotator", "consent");
+  mkdirSync(dir, { recursive: true });
+  writeJsonAtomic(consentPath(), {
+    consented: true,
+    recordedAt: new Date().toISOString(),
+  });
+}
+
+export function isClearContextSettingEnabled(): boolean {
+  try {
+    if (!existsSync(settingsPath())) return false;
+    const settings = JSON.parse(readFileSync(settingsPath(), "utf8"));
+    return settings?.[SETTING_KEY] === true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureClearContextSettingEnabled(): Promise<boolean> {
+  if (!hasConsent()) {
+    console.error(
+      "[plannotator] clearContextSetting: no consent recorded; skipping settings mutation",
+    );
+    return isClearContextSettingEnabled();
+  }
+
+  let settings: Record<string, unknown>;
+  try {
+    settings = existsSync(settingsPath())
+      ? JSON.parse(readFileSync(settingsPath(), "utf8"))
+      : {};
+  } catch (error: any) {
+    console.error(
+      `[plannotator] clearContextSetting: malformed settings JSON; skipping mutation: ${error?.message}`,
+    );
+    return false;
+  }
+
+  if (settings[SETTING_KEY] === true) return true;
+
+  settings[SETTING_KEY] = true;
+  mkdirSync(join(homedir(), ".claude"), { recursive: true });
+
+  try {
+    writeJsonAtomic(settingsPath(), settings);
+  } catch (error: any) {
+    try {
+      await Bun.sleep(50);
+      writeJsonAtomic(settingsPath(), settings);
+    } catch (retryError: any) {
+      console.error(
+        `[plannotator] clearContextSetting: write failed after retry; skipping: ${retryError?.message}`,
+      );
+      return false;
+    }
+  }
+
+  return true;
+}

apps/hook/server/hookDecision.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { formatClaudePlanHookOutput } from "./hookDecision";
+
+describe("formatClaudePlanHookOutput", () => {
+  test("native handoff emits PreToolUse ask only when native clear was enabled", () => {
+    expect(formatClaudePlanHookOutput({
+      result: { approved: true, permissionMode: "bypassPermissions", deferToNativeForClear: true },
+      hookEventName: "PreToolUse",
+      toolName: "ExitPlanMode",
+      detectedOrigin: "claude-code",
+      nativeClearEnabled: true,
+    })).toEqual({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "ask",
+      },
+    });
+  });
+
+  test("PermissionRequest native defer falls back to explicit allow JSON", () => {
+    const output = formatClaudePlanHookOutput({
+      result: { approved: true, deferToNativeForClear: true },
+      hookEventName: "PermissionRequest",
+      toolName: "ExitPlanMode",
+      detectedOrigin: "claude-code",
+      nativeClearEnabled: true,
+    }) as any;
+
+    expect(output.hookSpecificOutput.hookEventName).toBe("PermissionRequest");
+    expect(output.hookSpecificOutput.decision.behavior).toBe("allow");
+    expect(output.hookSpecificOutput.decision.updatedPermissions).toEqual([
+      { type: "setMode", mode: "bypassPermissions", destination: "session" },
+    ]);
+    expect(output.systemMessage).toContain("/clear");
+  });
+
+  test("normal PermissionRequest approval includes updatedPermissions", () => {
+    expect(formatClaudePlanHookOutput({
+      result: { approved: true, permissionMode: "bypassPermissions", clearContextNudge: true },
+      hookEventName: "PermissionRequest",
+      toolName: "ExitPlanMode",
+      detectedOrigin: "claude-code",
+    })).toEqual({
+      systemMessage: expect.stringContaining("/clear"),
+      hookSpecificOutput: {
+        hookEventName: "PermissionRequest",
+        decision: {
+          behavior: "allow",
+          updatedPermissions: [
+            { type: "setMode", mode: "bypassPermissions", destination: "session" },
+          ],
+        },
+      },
+    });
+  });
+});