@stigmer/runner 3.0.8-dev.20260612100207 → 3.0.8-dev.20260612122433

package/src/activities/execute-cursor/__tests__/hitl-ledger.test.ts

@@ -299,11 +299,12 @@ describe("reconstructAdjudicatedApprovals", () => {
 describe("generateHookScript ledger wiring", () => {
   it("wires the ledger path and records denials in both deny branches", () => {
     const script = generateHookScript(
-      "/ws/.cursor/hooks/stigmer-approval-state.json",
-      "/ws/.cursor/hooks/stigmer-denials.jsonl",
+      "/hitl/approval-state.json",
+      "/hitl/denials.jsonl",
+      process.pid,
     );
 
-    expect(script).toContain('LEDGER_FILE="/ws/.cursor/hooks/stigmer-denials.jsonl"');
+    expect(script).toContain('LEDGER_FILE="/hitl/denials.jsonl"');
     expect(script).toContain("record_denial()");
     // One definition + a call in the gated-built-in branch + a call in the MCP
     // branch = 3 occurrences.

package/src/activities/execute-cursor/__tests__/hook-script.test.ts

@@ -47,6 +47,11 @@ function setup(opts: {
   grants?: ApprovalGrant[];
   mcpPolicies?: Record<string, McpToolPolicyEntry>;
   noStateFile?: boolean;
+  // Process the hook treats as "the runner". Defaults to this test process,
+  // which is an ancestor of the bash child execFileSync spawns — so the scope
+  // guard sees the call as the runner's own agent and applies the gate. Pass a
+  // non-ancestor PID to exercise the foreign-client path (issue #173).
+  runnerPid?: number;
 }): Harness {
   const ws = mkdtempSync(join(tmpdir(), "hook-script-"));
   tempDirs.push(ws);
@@ -55,7 +60,7 @@ function setup(opts: {
   const statePath = join(dir, "state.json");
   const ledgerPath = join(dir, "denials.jsonl");
   const scriptPath = join(dir, "hook.sh");
-  writeFileSync(scriptPath, generateHookScript(statePath, ledgerPath), "utf-8");
+  writeFileSync(scriptPath, generateHookScript(statePath, ledgerPath, opts.runnerPid ?? process.pid), "utf-8");
 
   if (!opts.noStateFile) {
     const policies = new Map(
@@ -179,6 +184,50 @@ d("generated preToolUse hook", () => {
     expect(h.decide(hookShell('rm -rf "/x"')).permission).toBe("deny");
   });
 
+  // Issue #173: the hook ships on the workspace's shared .cursor/hooks.json, so
+  // the user's own Cursor IDE (a DIFFERENT process tree) would load and run it
+  // too. The scope guard must allow any invocation that does not descend from
+  // the runner process — without gating it and without writing the denial ledger
+  // (a foreign denial would surface as a phantom approval card in the session).
+  describe("scope guard (issue #173): foreign invocations are not gated", () => {
+    // A PID that cannot be an ancestor of the test's bash child. macOS pid_max is
+    // 99998; this is comfortably above it and above a freshly-booted Linux
+    // pid range, so get_ppid yields nothing and the walk reports "not own".
+    const FOREIGN_PID = 2_147_483_600;
+
+    it("allows a gated built-in when the invocation is not the runner's own agent", () => {
+      const h = setup({ runnerPid: FOREIGN_PID });
+      // The IDE would have this DENIED if the gate applied — it must be allowed.
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("allow");
+      expect(h.decide(hookShell("rm -rf build")).permission).toBe("allow");
+    });
+
+    it("never writes the denial ledger for a foreign invocation (no phantom approvals)", () => {
+      const h = setup({ runnerPid: FOREIGN_PID });
+      h.resetLedger();
+      h.decide(hookWrite("/x/a.txt"));
+      h.decide(hookShell("gh issue view 173"));
+      // The IDE's tool calls must NOT leak into the ledger the runner reads back.
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("allows a foreign invocation even when the state file is missing", () => {
+      // Fail-closed is for the runner's OWN agent; a foreign client must never be
+      // blocked by a missing state file (that was the multi-root exit-127 lockup).
+      const h = setup({ runnerPid: FOREIGN_PID, noStateFile: true });
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("still gates the runner's own agent (control: gate applies in-process)", () => {
+      // Same inputs, but runnerPid defaults to this process (an ancestor of the
+      // bash child) — the gate must apply, proving the guard discriminates.
+      const h = setup({});
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("deny");
+      expect(h.ledger()).toHaveLength(1);
+    });
+  });
+
   it("still denies gated tools via the bash fallback when the Node binary is unavailable", () => {
     const ws = mkdtempSync(join(tmpdir(), "hook-script-fallback-"));
     tempDirs.push(ws);
@@ -188,7 +237,7 @@ d("generated preToolUse hook", () => {
     const ledgerPath = join(dir, "denials.jsonl");
     const scriptPath = join(dir, "hook.sh");
     // Break the baked Node path to force the grep/cut fallback.
-    const script = generateHookScript(statePath, ledgerPath)
+    const script = generateHookScript(statePath, ledgerPath, process.pid)
       .replace(`NODE_BIN="${process.execPath}"`, 'NODE_BIN="/nonexistent/node"');
     writeFileSync(scriptPath, script, "utf-8");
     writeFileSync(statePath, JSON.stringify(buildApprovalState(new Map(), false)), "utf-8");

package/src/activities/execute-cursor/__tests__/workspace-setup.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Tests for the HITL gate's workspace lifecycle (issue #173).
+ *
+ * The gate must leave the user's real repo untouched: its runtime artifacts live
+ * outside the workspace, the only in-repo file (`.cursor/hooks.json`) is merged
+ * with any pre-existing user config and points at the hook by absolute path, and
+ * the whole surface is restored when the turn ends. These tests pin all four of
+ * those guarantees plus the self-healing strip of a crash-leftover entry.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  installHitlGate,
+  removeHitlGate,
+  buildMergedConfig,
+} from "../workspace-setup.js";
+import { buildApprovalState } from "../approval-state.js";
+
+const tempDirs: string[] = [];
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function freshRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "ws-setup-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+// A script path that looks like the real one so isStigmerHookEntry recognizes it.
+const stigmerScript = (root: string) =>
+  join(root, ".stigmer", "sessions", "ses-1", "hitl", "stigmer-approval.sh");
+
+describe("buildMergedConfig", () => {
+  it("writes a standalone config and restores by delete when no hooks.json exists", () => {
+    const { merged, restoreTo } = buildMergedConfig(null, "/abs/hitl/stigmer-approval.sh");
+    const parsed = JSON.parse(merged);
+    expect(parsed.hooks.preToolUse).toHaveLength(1);
+    expect(parsed.hooks.preToolUse[0].command).toBe("/abs/hitl/stigmer-approval.sh");
+    expect(parsed.hooks.preToolUse[0].failClosed).toBe(true);
+    // null restore target → teardown deletes the file we created.
+    expect(restoreTo).toBeNull();
+  });
+
+  it("merges with a user's hooks.json and restores the original bytes verbatim", () => {
+    const original = JSON.stringify(
+      {
+        version: 1,
+        hooks: {
+          preToolUse: [{ command: "./user-hook.sh", timeout: 5 }],
+          postToolUse: [{ command: "./user-post.sh" }],
+        },
+      },
+      null,
+      2,
+    );
+    const script = "/abs/.stigmer/sessions/ses-1/hitl/stigmer-approval.sh";
+    const { merged, restoreTo } = buildMergedConfig(original, script);
+    const parsed = JSON.parse(merged);
+
+    // Our entry is appended; the user's preToolUse hook is preserved...
+    expect(parsed.hooks.preToolUse).toHaveLength(2);
+    expect(parsed.hooks.preToolUse[0].command).toBe("./user-hook.sh");
+    expect(parsed.hooks.preToolUse[1].command).toBe(script);
+    // ...as is every other hook type and field.
+    expect(parsed.hooks.postToolUse).toEqual([{ command: "./user-post.sh" }]);
+    // Restore is byte-identical to the user's original.
+    expect(restoreTo).toBe(original);
+  });
+
+  it("strips a stale Stigmer entry (crash leftover) from both merged and restore", () => {
+    const root = "/abs";
+    const stale = stigmerScript(root); // a previous turn's entry
+    const original = JSON.stringify({
+      version: 1,
+      hooks: {
+        preToolUse: [
+          { command: "./user-hook.sh" },
+          { command: stale, timeout: 10, failClosed: true },
+        ],
+      },
+    });
+    const fresh = join(root, ".stigmer", "sessions", "ses-2", "hitl", "stigmer-approval.sh");
+    const { merged, restoreTo } = buildMergedConfig(original, fresh);
+
+    const mergedParsed = JSON.parse(merged);
+    // No duplicate: user entry + exactly one fresh Stigmer entry.
+    expect(mergedParsed.hooks.preToolUse).toHaveLength(2);
+    expect(mergedParsed.hooks.preToolUse.map((e: any) => e.command)).toEqual([
+      "./user-hook.sh",
+      fresh,
+    ]);
+    // Restore is the CLEANED user config — the stale entry is gone (self-healing).
+    const restoreParsed = JSON.parse(restoreTo!);
+    expect(restoreParsed.hooks.preToolUse).toEqual([{ command: "./user-hook.sh" }]);
+  });
+
+  it("replaces an unparseable hooks.json for the turn but restores its exact bytes", () => {
+    const garbage = "{ this is not json ";
+    const { merged, restoreTo } = buildMergedConfig(garbage, "/abs/hitl/stigmer-approval.sh");
+    // We still install a working gate for the turn...
+    expect(JSON.parse(merged).hooks.preToolUse).toHaveLength(1);
+    // ...and never "fix" the user's file: restore their exact original bytes.
+    expect(restoreTo).toBe(garbage);
+  });
+});
+
+describe("installHitlGate / removeHitlGate", () => {
+  const approvalState = buildApprovalState(new Map(), false);
+
+  function dirs() {
+    const root = freshRoot();
+    const workspaceRoot = join(root, "repo");
+    const hitlDir = join(root, ".stigmer", "sessions", "ses-1", "hitl");
+    mkdirSync(workspaceRoot, { recursive: true });
+    return { workspaceRoot, hitlDir };
+  }
+
+  it("writes artifacts OUTSIDE the workspace and a hooks.json with an absolute command", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    await installHitlGate({ workspaceRoot, hitlDir, approvalState, runnerPid: process.pid });
+
+    // Gate artifacts live in the HITL dir, never in the repo.
+    expect(existsSync(join(hitlDir, "stigmer-approval.sh"))).toBe(true);
+    expect(existsSync(join(hitlDir, "approval-state.json"))).toBe(true);
+    expect(existsSync(join(hitlDir, "denials.jsonl"))).toBe(true);
+    // The script is executable.
+    expect(statSync(join(hitlDir, "stigmer-approval.sh")).mode & 0o111).toBeTruthy();
+
+    // The only in-repo file is hooks.json, pointing at the script by ABSOLUTE
+    // path (the relative path was the multi-root exit-127 bug).
+    const hooksJson = JSON.parse(
+      readFileSync(join(workspaceRoot, ".cursor", "hooks.json"), "utf-8"),
+    );
+    const command = hooksJson.hooks.preToolUse[0].command;
+    expect(command).toBe(join(hitlDir, "stigmer-approval.sh"));
+    expect(command.startsWith("/")).toBe(true);
+    // The workspace holds no relocated artifacts.
+    expect(existsSync(join(workspaceRoot, ".cursor", "hooks"))).toBe(false);
+  });
+
+  it("leaves NO Stigmer files in the repo after teardown (failure mode 4)", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    const handle = await installHitlGate({
+      workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+    });
+    expect(existsSync(join(workspaceRoot, ".cursor", "hooks.json"))).toBe(true);
+
+    await removeHitlGate(handle);
+
+    // The repo is clean: no hooks.json, no hook scripts, no ledger.
+    expect(existsSync(join(workspaceRoot, ".cursor", "hooks.json"))).toBe(false);
+    expect(existsSync(join(workspaceRoot, ".cursor", "hooks"))).toBe(false);
+  });
+
+  it("restores a pre-existing user hooks.json byte-for-byte after teardown", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    const cursorDir = join(workspaceRoot, ".cursor");
+    mkdirSync(cursorDir, { recursive: true });
+    const userConfig = JSON.stringify(
+      { version: 1, hooks: { preToolUse: [{ command: "./mine.sh" }] } },
+      null,
+      2,
+    );
+    const hooksPath = join(cursorDir, "hooks.json");
+    writeFileSync(hooksPath, userConfig, "utf-8");
+
+    const handle = await installHitlGate({
+      workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+    });
+    // During the turn our entry is present alongside the user's.
+    const during = JSON.parse(readFileSync(hooksPath, "utf-8"));
+    expect(during.hooks.preToolUse).toHaveLength(2);
+
+    await removeHitlGate(handle);
+
+    // After the turn the file is byte-identical to what the user had.
+    expect(readFileSync(hooksPath, "utf-8")).toBe(userConfig);
+  });
+
+  it("is repeatable across turns (install/remove/install/remove) and ends clean", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    for (let turn = 0; turn < 2; turn++) {
+      const handle = await installHitlGate({
+        workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+      });
+      expect(existsSync(join(workspaceRoot, ".cursor", "hooks.json"))).toBe(true);
+      await removeHitlGate(handle);
+      expect(existsSync(join(workspaceRoot, ".cursor", "hooks.json"))).toBe(false);
+    }
+  });
+});

package/src/activities/execute-cursor/approval-state.ts

@@ -2,8 +2,9 @@
  * Approval state management for the hook-deny + reinvoke HITL model.
  *
  * Before starting a Cursor Agent run, the cursor-runner writes a state file
- * to the workspace. The preToolUse hook script reads this file to decide
- * whether to allow or deny each tool call.
+ * into the session's runner-owned HITL directory (outside the user's
+ * workspace). The preToolUse hook script reads this file to decide whether to
+ * allow or deny each tool call.
  *
  * State file format (JSON):
  * {
@@ -40,7 +41,7 @@
  *
  * Denial ledger (hook → runner):
  * The state file is the runner's INPUT to the hook. Its symmetric OUTPUT is the
- * denial ledger (stigmer-denials.jsonl): when the hook denies a tool, it appends
+ * denial ledger (denials.jsonl): when the hook denies a tool, it appends
  * the call's identity token to this file. The runner reads the ledger after the
  * run to learn which tool calls were gated — the hook is the only component that
  * actually makes the per-call allow/deny decision, so its ledger is the
@@ -209,11 +210,17 @@ export function buildApprovalState(
   };
 }
 
-const STATE_FILE_DIR = ".cursor/hooks";
-const STATE_FILE_NAME = "stigmer-approval-state.json";
+const STATE_FILE_NAME = "approval-state.json";
 
 /**
- * Write the approval state file to the workspace for the hook script to read.
+ * Write the approval state file into the session's HITL directory for the hook
+ * script to read.
+ *
+ * The HITL directory is runner-owned and lives outside the user's workspace
+ * (`~/.stigmer/sessions/{id}/hitl/`), so this file never lands in the attached
+ * repo — only a minimal `.cursor/hooks.json` pointing here by absolute path does
+ * (see issue #173). The hook reads this file fresh on every tool call, so its
+ * dynamic policy is always current even if the SDK caches `hooks.json`.
  *
  * Written as COMPACT JSON (no indentation): the bash hook parses it with
  * line-oriented grep patterns that assume `"key":value` with no spaces or
@@ -221,12 +228,11 @@ const STATE_FILE_NAME = "stigmer-approval-state.json";
  * would break every lookup.
  */
 export async function writeApprovalStateFile(
-  workspaceRoot: string,
+  hitlDir: string,
   state: ApprovalStateFile,
 ): Promise<string> {
-  const dir = join(workspaceRoot, STATE_FILE_DIR);
-  await mkdir(dir, { recursive: true });
-  const filePath = join(dir, STATE_FILE_NAME);
+  await mkdir(hitlDir, { recursive: true });
+  const filePath = join(hitlDir, STATE_FILE_NAME);
   await writeFile(filePath, JSON.stringify(state), "utf-8");
   return filePath;
 }
@@ -235,7 +241,7 @@ export async function writeApprovalStateFile(
 // Denial ledger (hook → runner): the authoritative record of what the hook gated
 // ─────────────────────────────────────────────────────────────────────────────
 
-const DENIAL_LEDGER_FILE = "stigmer-denials.jsonl";
+const DENIAL_LEDGER_FILE = "denials.jsonl";
 
 /**
  * One denial recorded by the preToolUse hook. `token` is the call's identity in
@@ -248,23 +254,26 @@ export interface DeniedLedgerEntry {
   token: string;
 }
 
-/** Absolute path of the per-turn denial ledger the hook appends to. */
-export function denialLedgerPath(workspaceRoot: string): string {
-  return join(workspaceRoot, STATE_FILE_DIR, DENIAL_LEDGER_FILE);
+/**
+ * Absolute path of the per-turn denial ledger the hook appends to, inside the
+ * session's runner-owned HITL directory (never the user's workspace).
+ */
+export function denialLedgerPath(hitlDir: string): string {
+  return join(hitlDir, DENIAL_LEDGER_FILE);
 }
 
 /**
  * Truncate the denial ledger to empty for a fresh turn, returning its path.
  *
- * Called every turn alongside writeApprovalStateFile (the workspace is durable
- * and reused across HITL reinvocations), so the runner only ever reads denials
- * produced by the current run. A Temporal activity retry re-runs this reset
- * before re-running the agent, so the read stays deterministic under retries.
+ * Called every turn alongside writeApprovalStateFile (the HITL directory is
+ * durable and reused across HITL reinvocations), so the runner only ever reads
+ * denials produced by the current run. A Temporal activity retry re-runs this
+ * reset before re-running the agent, so the read stays deterministic under
+ * retries.
  */
-export async function resetDenialLedger(workspaceRoot: string): Promise<string> {
-  const dir = join(workspaceRoot, STATE_FILE_DIR);
-  await mkdir(dir, { recursive: true });
-  const filePath = denialLedgerPath(workspaceRoot);
+export async function resetDenialLedger(hitlDir: string): Promise<string> {
+  await mkdir(hitlDir, { recursive: true });
+  const filePath = denialLedgerPath(hitlDir);
   await writeFile(filePath, "", "utf-8");
   return filePath;
 }
@@ -276,11 +285,11 @@ export async function resetDenialLedger(workspaceRoot: string): Promise<string>
  * the valid denials before it.
  */
 export async function readDenialLedger(
-  workspaceRoot: string,
+  hitlDir: string,
 ): Promise<DeniedLedgerEntry[]> {
   let raw: string;
   try {
-    raw = await readFile(denialLedgerPath(workspaceRoot), "utf-8");
+    raw = await readFile(denialLedgerPath(hitlDir), "utf-8");
   } catch {
     return [];
   }

package/src/activities/execute-cursor/hook-script.ts

@@ -131,8 +131,27 @@ function buildNodeIdentityScript(): string {
  *
  * The identity token encoding (`base64(key \n salient)`) must stay byte-identical
  * to grantToken() in approval-state.ts.
+ *
+ * Scope guard (the crux of issue #173): the Cursor SDK loads project hooks from
+ * `<workspace>/.cursor/hooks.json`, which is the SAME per-repo surface every
+ * Cursor client reads. When a session runs against the user's real repo, the
+ * user's own interactive Cursor IDE would otherwise load and run this hook too —
+ * gating the IDE, polluting the denial ledger with the IDE's tool calls, and (in
+ * multi-root windows) failing closed. We make the gate apply ONLY to the
+ * runner's own agent by baking in the runner process PID and checking, on every
+ * invocation, whether the runner is an ancestor of the hook process. The SDK
+ * runs hooks in-process via child_process, so the runner's own agent (and its
+ * delegated sub-agents) spawn the hook as a descendant of the runner; any other
+ * Cursor client spawns it under a different process tree. A non-descendant
+ * invocation is allowed immediately and never touches the ledger. This also
+ * makes a leftover hooks.json self-neutralizing: once the runner exits, no
+ * invocation can match its (now-dead) PID, so the gate is inert.
  */
-export function generateHookScript(stateFilePath: string, ledgerFilePath: string): string {
+export function generateHookScript(
+  stateFilePath: string,
+  ledgerFilePath: string,
+  runnerPid: number,
+): string {
   const salientFields = SALIENT_ARG_FIELDS.join(" ");
   const categoryCaseArms = buildCategoryCaseArms();
   const nodeIdentityScript = buildNodeIdentityScript();
@@ -151,6 +170,40 @@ INPUT=$(cat)
 
 STATE_FILE="${stateFilePath}"
 LEDGER_FILE="${ledgerFilePath}"
+RUNNER_PID="${runnerPid}"
+
+# --- Scope guard: gate ONLY the runner's own agent (issue #173) -------------
+# The Cursor SDK runs hooks in-process, so the runner's own agent invocations
+# spawn this script as a DESCENDANT of the runner process (RUNNER_PID); the
+# user's interactive IDE — sharing the same repo .cursor/hooks.json — spawns it
+# under a different process tree. Walk the parent-PID chain: if the runner is an
+# ancestor, apply the gate; otherwise allow immediately and DO NOT write the
+# ledger (so foreign tool calls never appear as phantom approvals). Pure bash so
+# it works even when the Node identity binary below is unavailable.
+__stigmer_ppid() {
+  _p="$1"
+  if [ -r "/proc/$_p/status" ]; then
+    awk '/^PPid:/{print $2; exit}' "/proc/$_p/status" 2>/dev/null || true
+  else
+    ps -o ppid= -p "$_p" 2>/dev/null | tr -d ' ' || true
+  fi
+}
+__stigmer_is_own_agent() {
+  _cur="$$"
+  _i=0
+  while [ "$_i" -lt 64 ]; do
+    if [ -z "$_cur" ]; then return 1; fi
+    if [ "$_cur" = "$RUNNER_PID" ]; then return 0; fi
+    if [ "$_cur" = "1" ] || [ "$_cur" = "0" ]; then return 1; fi
+    _cur="$(__stigmer_ppid "$_cur")"
+    _i=$((_i + 1))
+  done
+  return 1
+}
+if ! __stigmer_is_own_agent; then
+  echo '{"permission":"allow"}'
+  exit 0
+fi
 
 # --- Canonical identity: tool_name / category / identity token / MCP token ---
 # Computed by the same Node.js binary that runs the cursor-runner (absolute path

package/src/activities/execute-cursor/index.ts

@@ -55,10 +55,11 @@ import { backfillMcpServersIfNeeded } from "./connect-backfill.js";
 import { resolveExecutionEnv } from "./env-resolver.js";
 import { resolveBlueprint } from "./blueprint-resolver.js";
 import { buildCursorSubAgentDefinitions } from "./subagent-config.js";
-import { resolveSkills } from "./skill-resolver.js";
+import { resolveSkills, removeStigmerSymlink } from "./skill-resolver.js";
 import { resolveAttachments } from "./attachment-resolver.js";
 import { buildEnhancedPrompt, buildReinvocationPrompt } from "./prompt-builder.js";
-import { writeHooksToWorkspace } from "./workspace-setup.js";
+import { installHitlGate, removeHitlGate } from "./workspace-setup.js";
+import { ensureHitlDir } from "../../shared/workspace/platform-dir.js";
 import { buildApprovalState, buildApprovalGrants, readDenialLedger, reconstructAdjudicatedApprovals } from "./approval-state.js";
 import { provisionCursorWorkspace } from "./workspace-provision.js";
 import { setInterceptorExecutionId, runWithExecutionContext } from "./fetch-interceptor.js";
@@ -131,6 +132,15 @@ async function executeCursorInner(
   let pauseDetected = false;
   let workerShutdownDetected = false;
   let periodicHeartbeat: ReturnType<typeof startHeartbeat> | undefined;
+  // Session HITL directory (runner-owned, outside the workspace) where the hook
+  // script, approval-state file, and denial ledger live. Set once the gate is
+  // installed; the WAITING_FOR_APPROVAL path reads the denial ledger from here.
+  let hitlDir: string | undefined;
+  // Teardown for the HITL gate: restores the workspace's .cursor/hooks.json and
+  // removes the .stigmer symlink so attaching a real repo leaves it untouched
+  // (issue #173). Runs in the finally, covering every success/error/approval
+  // exit path. Undefined until the gate is installed.
+  let hitlCleanup: (() => Promise<void>) | undefined;
   // Carries model/mode/agentId out to the outer catch so a thrown CursorSdkError
   // can be classified with the same context as the run.wait() error path.
   let errorContext = { model: "default", mode: "local", agentId: "" };
@@ -287,7 +297,41 @@ async function executeCursorInner(
     );
     const attachmentPaths = attachmentResults.map((a) => a.relativePath);
 
-    // Phase 5c: Ensure model pricing registry is populated before validation
+    // Phase 5c: Install the HITL approval gate BEFORE resolving the agent.
+    //
+    // The gate's runtime artifacts (hook script, approval-state file, denial
+    // ledger) live in the session HITL directory OUTSIDE the workspace; only a
+    // minimal, merged, transient .cursor/hooks.json is written into the repo,
+    // pointing at the hook script by absolute path. The hook is scoped to this
+    // runner's own process so the user's interactive IDE — sharing the same repo
+    // hooks.json — is never gated (issue #173). Installing here (rather than
+    // after agent create/resume) guarantees the hook is present no matter when
+    // the SDK reads hook config, and the finally restores the repo afterward.
+    //
+    // On reinvocation, turn the user's approvals into tool-identity grants so
+    // the resumed agent's re-attempt (which carries a fresh tool-call id) is
+    // allowed through.
+    hitlDir = await ensureHitlDir(sessionId);
+    const approvalGrants = approvalDecisions
+      ? buildApprovalGrants(adjudicatedApprovals, approvalDecisions)
+      : undefined;
+    const approvalState = buildApprovalState(
+      mergedPolicies,
+      effectiveAutoApproveAll,
+      approvalGrants,
+    );
+    const hitlGate = await installHitlGate({
+      workspaceRoot: primaryWorkspaceDir,
+      hitlDir,
+      approvalState,
+      runnerPid: process.pid,
+    });
+    hitlCleanup = async () => {
+      await removeHitlGate(hitlGate);
+      await removeStigmerSymlink(primaryWorkspaceDir);
+    };
+
+    // Phase 5d: Ensure model pricing registry is populated before validation
     await ensurePricingLoaded();
 
     // Phase 6: Validate model selection
@@ -366,18 +410,7 @@ async function executeCursorInner(
 
     errorContext = { model: validatedModel, mode: agentMode, agentId: resolution.agentId };
 
-    // Phase 8: Write hooks for HITL with policy-aware state. On reinvocation,
-    // turn the user's approvals into tool-identity grants so the resumed agent's
-    // re-attempt (which carries a fresh tool-call id) is allowed through.
-    const approvalGrants = approvalDecisions
-      ? buildApprovalGrants(adjudicatedApprovals, approvalDecisions)
-      : undefined;
-    const approvalState = buildApprovalState(
-      mergedPolicies,
-      effectiveAutoApproveAll,
-      approvalGrants,
-    );
-    await writeHooksToWorkspace(primaryWorkspaceDir, approvalState);
+    // (HITL approval gate already installed in Phase 5c, before agent resolution.)
 
     // Phase 9: Store new agentId as harness_state_id and persist cursor_mode
     if (resolution.isNew && resolution.agentId) {
@@ -714,7 +747,7 @@ async function executeCursorInner(
     // harness — the approval surface is driven entirely by tool-call status. We
     // deliberately do NOT set status.pendingApprovals here: any value would be
     // discarded by the backend's recompute on the next updateStatus.
-    const deniedLedger = await readDenialLedger(primaryWorkspaceDir);
+    const deniedLedger = await readDenialLedger(hitlDir ?? "");
     const deniedToolCalls = reconcileDeniedToolCalls(status.messages, deniedLedger, mergedPolicies);
     if (deniedToolCalls.length > 0) {
       status.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
@@ -1207,6 +1240,22 @@ async function executeCursorInner(
     }
 
     return slimStatus(status);
+  } finally {
+    // Tear down the HITL gate on EVERY exit path (success, error, approval
+    // pause, cancellation) so attaching a real repo leaves the user's
+    // .cursor/hooks.json and workspace untouched between turns (issue #173).
+    // Best-effort: a leftover hooks.json is inert because the scope guard
+    // allows all invocations once this runner PID is gone.
+    if (hitlCleanup) {
+      try {
+        await hitlCleanup();
+      } catch (cleanupErr) {
+        console.warn(
+          `ExecuteCursor HITL gate teardown failed (non-fatal): ` +
+          `execution=${executionId}, error=${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`,
+        );
+      }
+    }
   }
 }
 

package/src/activities/execute-cursor/session-lifecycle.ts

@@ -61,6 +61,12 @@ const CURSOR_SDK_STATE_DIR = ".stigmer/cursor-sdk-state";
  * silently drops the hook and disables the entire approval gate. We must opt
  * in to "project" so the hook loads and tool calls are actually gated.
  *
+ * The hooks.json is the only file written into the workspace — kept minimal,
+ * merged with any user hooks.json, and restored when the turn ends; the gate's
+ * own artifacts live outside the repo and the hook is scoped to this runner's
+ * process, so the user's interactive IDE sharing the repo is never gated (see
+ * workspace-setup.ts / hook-script.ts and issue #173).
+ *
  * Side effect: this also loads other workspace `.cursor/*` config (rules,
  * mcp.json, commands). For runner-provisioned workspaces that is inert; for
  * sessions running on a user's own repo their project config is now honored.

package/src/activities/execute-cursor/skill-resolver.ts

@@ -9,7 +9,7 @@
  * - Returns metadata for prompt injection
  */
 
-import { mkdir, writeFile, symlink, readlink, unlink, rm } from "node:fs/promises";
+import { mkdir, writeFile, symlink, readlink, unlink, rm, lstat } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
@@ -163,6 +163,31 @@ async function ensureStigmerSymlink(
   await symlink(platformDir, linkPath, "dir");
 }
 
+/**
+ * Remove the workspace `.stigmer` symlink created by {@link resolveSkills}.
+ *
+ * Called in the activity's finally so attaching a real repo leaves no Stigmer
+ * symlink behind once the turn ends (issue #173); a multi-turn session recreates
+ * it on the next turn. Only ever removes a SYMLINK — a real `.stigmer` directory
+ * (which would be the user's own, not ours) is left untouched. Best-effort.
+ */
+export async function removeStigmerSymlink(workspaceDir: string): Promise<void> {
+  const linkPath = join(workspaceDir, STIGMER_LOCAL_STATE_DIR);
+  try {
+    const stat = await lstat(linkPath);
+    if (stat.isSymbolicLink()) {
+      await unlink(linkPath);
+    }
+  } catch (err: any) {
+    if (err?.code !== "ENOENT") {
+      console.warn(
+        `removeStigmerSymlink: failed to remove ${linkPath} (non-fatal): ` +
+        `${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+}
+
 /**
  * Clean up platform-managed skill directory for a session.
  */