@estebanforge/pi-antigravity-bridge 1.4.8 → 1.4.10

package/src/approval-detect.ts

@@ -0,0 +1,146 @@
+// Third-party pi permission-extension detection for the approval gate
+// (docs/TODO.md 2.5). The gate defaults to "auto": OFF until one of these
+// extensions is present. Detection reads pi's settings (the packages array
+// is the primary, name-exact signal) plus known on-disk config markers for
+// the audited permission packages (sources: ~/tmp/pi-perm-research/, audit
+// 2026-09-07). Best effort by design: a miss only means the user enables
+// the gate manually; a false positive stages hooks.json, which is inert
+// unless the ACP/CLI server loads it, and observation-only hooks are safe.
+//
+// Run: npm test
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** npm names of the audited pi permission packages (docs/TODO.md 2.4). */
+export const KNOWN_GATE_PACKAGES = [
+	"@gotgenes/pi-permission-system",
+	"@zhushanwen/pi-permission",
+	"pi-permission-system",
+	"@xzzpig/pi-permission-system",
+	"@diegopetrucci/pi-permission-gate",
+	"pi-permission-modes",
+	"@inobit/pi-permission",
+	"@thurstonsand/pi-permissions",
+	"@monroewilliams/pi-permission-system",
+	"@rhedbull/pi-permissions",
+] as const;
+
+export interface GateExtensionHit {
+	/** The known package name matched. */
+	name: string;
+	/** How it was detected: "settings:<path>" or "config:<path>". */
+	evidence: string;
+}
+
+function readJsonIfPresent(file: string): { packages?: unknown } | undefined {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function packagesFrom(settingsFile: string): string[] {
+	const parsed = readJsonIfPresent(settingsFile);
+	const raw = parsed?.packages;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((entry): entry is string => typeof entry === "string");
+}
+
+function nameMatchesPackage(entry: string): string | undefined {
+	// entries look like "npm:@scope/name@1.2.3", "git:...", or a bare path.
+	// Boundary-aware match: the known name must start after :/@ (or the
+	// string start) and must not be a prefix of a longer package name
+	// ("pi-permission-system-clone" must NOT match). Version suffix @x.y is
+	// fine. Peer review 2026-09-07 finding 4.
+	const lower = entry.toLowerCase();
+	let best: string | undefined;
+	for (const name of KNOWN_GATE_PACKAGES) {
+		if (containsName(lower, name) && (best === undefined || name.length > best.length)) best = name;
+	}
+	// Longest match wins: "@xzzpig/pi-permission-system" must resolve to the
+	// scoped name, not to the shorter unscoped fork "pi-permission-system".
+	return best;
+}
+
+function containsName(lower: string, name: string): boolean {
+	let idx = lower.indexOf(name);
+	while (idx >= 0) {
+		const before = idx === 0 ? "" : lower[idx - 1];
+		const after = lower[idx + name.length] ?? "";
+		const okBefore = before === "" || ":/@".includes(before);
+		const okAfter = after === "" || after === "@" || !/[a-z0-9_-]/.test(after);
+		if (okBefore && okAfter) return true;
+		idx = lower.indexOf(name, idx + 1);
+	}
+	return false;
+}
+
+/**
+ * Detect installed third-party permission extensions.
+ *
+ * @param opts.home  HOME override for tests.
+ * @param opts.cwd   project dir override for tests (project settings).
+ * @param opts.settingsFiles  extra settings files to scan (tests).
+ */
+export function detectPermissionGateExtensions(
+	opts: { home?: string; cwd?: string; settingsFiles?: string[] } = {},
+): GateExtensionHit[] {
+	const home = opts.home ?? os.homedir();
+	const cwd = opts.cwd ?? process.cwd();
+	const hits: GateExtensionHit[] = [];
+	const seen = new Set<string>();
+
+	const settingsCandidates = [
+		...(opts.settingsFiles ?? []),
+		path.join(home, ".pi", "agent", "settings.json"),
+		path.join(cwd, ".pi", "settings.json"),
+	];
+	for (const file of settingsCandidates) {
+		for (const entry of packagesFrom(file)) {
+			const name = nameMatchesPackage(entry);
+			if (name && !seen.has(name)) {
+				seen.add(name);
+				hits.push({ name, evidence: `settings:${file}` });
+			}
+		}
+	}
+
+	// Known config-file markers from the audit. Presence of the config does
+	// not prove the extension is installed, but every audited package writes
+	// its config only after install + first run, which is evidence enough for
+	// an opt-in default.
+	const markers: Array<{ file: string; name: string }> = [
+		{ file: path.join(home, ".pi", "agent", "extensions", "pi-permission-system"), name: "@gotgenes/pi-permission-system" },
+		{ file: path.join(home, ".agent", "pi-permissions.jsonc"), name: "@monroewilliams/pi-permission-system" },
+		{ file: path.join(home, ".pi", "agent", "extensions", "permissions.json"), name: "@rhedbull/pi-permissions" },
+		{ file: path.join(cwd, ".pi", "agent", "pi-permissions.jsonc"), name: "@gotgenes/pi-permission-system" },
+	];
+	for (const marker of markers) {
+		if (!seen.has(marker.name)) {
+			try {
+				fs.statSync(marker.file);
+				seen.add(marker.name);
+				hits.push({ name: marker.name, evidence: `config:${marker.file}` });
+			} catch {
+				/* absent - fine */
+			}
+		}
+	}
+
+	return hits;
+}
+
+/** Resolve the effective gate shape from config + detection. "auto" defers
+ *  to detection (shadow when any gate extension is present, else off). */
+export function resolveGateMode(
+	gateMode: "auto" | "shadow" | "dedicated" | "off",
+	hits: GateExtensionHit[],
+): "shadow" | "dedicated" | "off" {
+	if (gateMode === "off") return "off";
+	if (gateMode === "shadow" || gateMode === "dedicated") return gateMode;
+	return hits.length > 0 ? "shadow" : "off";
+}

package/src/approval-gate.ts

@@ -0,0 +1,208 @@
+// Approval-gate shadow tools (docs/TODO.md section 2.5, design v2).
+//
+// When the approval gate is active, the bridge re-registers pi's mutating
+// builtins (bash, write, edit) as SHADOW tools: same name, same schema plus
+// internal __agy* marker fields. Two behaviors, keyed on the marker:
+//
+//   - marker absent: delegate to the captured real builtin. Normal pi
+//     behavior (including the G9 path, where pi tools execute for real) is
+//     untouched.
+//   - marker present: the call is an approval round-trip for an agy NATIVE
+//     tool. NEVER execute locally. Ask the policy for a decision; agy runs
+//     the tool in its own loop either way.
+//
+// Decision mapping (consumed by the provider's /approval park):
+//   resolve (success result)      -> {"decision":"allow"}
+//   throw                         -> {"decision":"deny","reason": message}
+// pi's tool executor converts thrown errors into error tool results with
+// the message as text, matching how builtins report failures (write.js,
+// edit-diff.js). A tool_call handler that blocks the shadow call upstream
+// (any third-party permission extension) produces the same error result
+// without execute() running, so both paths land on the same deny mapping.
+//
+// Run: npm test
+
+import type {
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ExtensionContext,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+/** Marker flag: this shadow-tool call is an approval round-trip, not a real
+ *  invocation. The bridge's provider sets it when composing the toolUse. */
+export const GATE_MARKER = "__agyGate";
+
+/** Internal context fields the provider may attach next to the marker.
+ *  Stripped before delegating to the real builtin. */
+export const MARKER_FIELDS = [GATE_MARKER, "__agyTicket", "__agyTool"] as const;
+
+export type AnyToolDefinition = ToolDefinition<any, any, any>;
+
+export interface GateDecision {
+	allow: boolean;
+	reason?: string;
+}
+
+/** Fallback policy: consulted only when NO extension blocked the shadow
+ *  tool_call. Implementations map approvals.mode: ask -> ctx.ui.confirm
+ *  (guarded by ctx.hasUI), allow -> {allow:true}, deny -> {allow:false}. */
+export type GatePolicy = (call: {
+	tool: string;
+	params: Record<string, unknown>;
+	ctx: unknown;
+}) => Promise<GateDecision> | GateDecision;
+
+/** Marker schemas injected into the shadow parameters. Optional, so the
+ *  model's own calls stay valid; audited permission extensions match only
+ *  their known fields (command/path) and ignore these. */
+const MARKER_SCHEMAS: Record<string, unknown> = {
+	[GATE_MARKER]: {
+		type: "boolean",
+		description:
+			"Internal bridge approval marker. Never set this yourself; calls without local execution intent must not set it.",
+	},
+	__agyTicket: { type: "string" },
+	__agyTool: { type: "string", description: "Native agy tool this approval round-trip is for." },
+};
+
+/** Clone a tool's parameter schema with the marker fields added as optional
+ *  properties. Field-exact for everything the permission extensions match on
+ *  (command, path, edits, ...). Does not mutate the base schema. */
+export function withGateMarkerSchema(base: AnyToolDefinition["parameters"]): AnyToolDefinition["parameters"] {
+	const src = base as { properties?: Record<string, unknown> };
+	return { ...base, properties: { ...src.properties, ...MARKER_SCHEMAS } } as AnyToolDefinition["parameters"];
+}
+
+/** Copy of params without the internal marker fields, for delegation. */
+export function stripMarkerFields(params: Record<string, unknown>): Record<string, unknown> {
+	const out = { ...params };
+	for (const field of MARKER_FIELDS) delete out[field];
+	return out;
+}
+
+export interface ShadowMapping {
+	shadow: "bash" | "write" | "edit";
+	input: Record<string, unknown>;
+}
+
+/** Map an agy native tool call (hook stdin payload) onto the shadow surface.
+ *  Field names follow the TODO 2.5 table: create_file is live-captured (F1);
+ *  the edit-class arg names are docs-attested and degrade gracefully - a
+ *  wrong guess only weakens the confirm-dialog text, never the decision
+ *  (the tool runs in agy's loop either way). Unknown names return null:
+ *  read-only tools are not gated. */
+export function mapNativeToShadow(name: string, args: Record<string, unknown>): ShadowMapping | null {
+	const a = args ?? {};
+	const str = (v: unknown): string => (typeof v === "string" ? v : v === undefined || v === null ? "" : String(v));
+	switch (name) {
+		case "run_command": {
+			const input: Record<string, unknown> = { command: str(a.CommandLine) };
+			if (a.Cwd !== undefined && a.Cwd !== null && a.Cwd !== "") input.cwd = str(a.Cwd);
+			return { shadow: "bash", input };
+		}
+		case "write_to_file":
+		case "create_file":
+			return { shadow: "write", input: { path: str(a.TargetFile), content: str(a.CodeContent) } };
+		case "replace_file_content":
+		case "edit_file":
+			return {
+				shadow: "edit",
+				input: {
+					path: str(a.TargetFile),
+					edits: [{ oldText: str(a.SearchText), newText: str(a.ReplacementContent) }],
+				},
+			};
+		case "multi_replace_file_content": {
+			const chunks = Array.isArray(a.ReplacementChunks) ? a.ReplacementChunks : [];
+			return {
+				shadow: "edit",
+				input: {
+					path: str(a.TargetFile),
+					edits: chunks.map((c) => {
+						const chunk = (c ?? {}) as Record<string, unknown>;
+						return { oldText: str(chunk.SearchText), newText: str(chunk.ReplacementContent) };
+					}),
+				},
+			};
+		}
+		default:
+			return null;
+	}
+}
+
+/** Options for the shadow factory. */
+export interface ShadowOptions {
+	/** Registry lookup for the park's ticket. When set, a marker call whose
+	 *  __agyTicket is missing or unrecognized throws (deny) BEFORE the policy
+	 *  runs: a model that sets __agyGate:true itself can then never produce a
+	 *  fake-approved result, even under approvals.mode "allow". */
+	verifyTicket?: (ticket: string) => boolean;
+}
+
+/** Build the shadow definition for one builtin. `base` MUST be a definition
+ *  of the real builtin - the extension passes factory twins created with
+ *  pi's public createBashToolDefinition/createWriteToolDefinition/
+ *  createEditToolDefinition (pi.getAllTools() returns ToolInfo, which strips
+ *  execute, so the live definition cannot be captured). */
+export function createShadowTool(base: AnyToolDefinition, policy: GatePolicy, opts: ShadowOptions = {}): AnyToolDefinition {
+	const execute = async (
+		toolCallId: string,
+		params: any,
+		signal: AbortSignal | undefined,
+		onUpdate: AgentToolUpdateCallback<any> | undefined,
+		ctx: ExtensionContext,
+	): Promise<AgentToolResult<unknown>> => {
+		const p = (params ?? {}) as Record<string, unknown>;
+		if (p[GATE_MARKER] !== true) {
+			return base.execute(toolCallId, stripMarkerFields(p), signal, onUpdate, ctx);
+		}
+		const native = typeof p.__agyTool === "string" && p.__agyTool.length > 0 ? p.__agyTool : base.name;
+		// Ticket binding (peer review 2026-09-07): only calls the provider parked
+		// carry a live ticket. Anything else with the marker set was forged by
+		// the model (or the park is gone); fail closed without consulting the
+		// policy, so approvals.mode "allow" can never bless it either.
+		const ticket = typeof p.__agyTicket === "string" ? p.__agyTicket : "";
+		if (!ticket || !opts.verifyTicket?.(ticket)) {
+			throw new Error(
+				`approval gate: unrecognized or stale approval ticket; refusing to decide (${native}).`,
+			);
+		}
+		if (signal?.aborted) {
+			throw new Error(`approval gate aborted before a decision was reached (${native}).`);
+		}
+		let decision: GateDecision;
+		// Race the policy against the abort signal: a cancelled turn must
+		// unblock execute() instead of hanging on a human decision.
+		const aborted = new Error(`approval gate aborted before a decision was reached (${native}).`);
+		const abortp = new Promise<never>((_, reject) => {
+			signal?.addEventListener("abort", () => reject(aborted), { once: true });
+		});
+		abortp.catch(() => {}); // late rejection must not become unhandled
+		try {
+			decision = await Promise.race([Promise.resolve(policy({ tool: native, params: p, ctx })), abortp]);
+		} catch (err) {
+			if (signal?.aborted) throw aborted;
+			// Fail closed: a broken policy must never look like an approval.
+			throw new Error(`approval gate policy failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (signal?.aborted) {
+			// Sync-abort inside the policy settles the policy promise BEFORE the
+			// race starts, so the rejection loses the ordering tie. Re-check.
+			throw aborted;
+		}
+		if (!decision.allow) {
+			throw new Error(decision.reason || `blocked by approval gate (${native}).`);
+		}
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Approved by approval gate: ${native}. No local execution happened; the tool runs in the Antigravity agent loop.`,
+				},
+			],
+			details: { gate: "allow", native },
+		};
+	};
+	return { ...base, parameters: withGateMarkerSchema(base.parameters), execute } as AnyToolDefinition;
+}

package/src/approval-hook.ts

@@ -0,0 +1,252 @@
+// Staging for the approval-gate hooks.json (docs/TODO.md 2.5).
+//
+// The ACP server and the agy CLI fire workspace `.agents/hooks.json`
+// PreToolUse hooks (V2: deny honored, reason reaches the model; V3: hook
+// TIMEOUT = soft-pass, agy proceeds ungated). Therefore:
+//   - the staged handler timeout must exceed the whole park budget with
+//     margin (never rely on timeout as a deny), and
+//   - the staged command delegates to the bundled poll script, which
+//     early-acks and polls the bridge for the terminal decision.
+//
+// Merge rules: never clobber a foreign hooks.json. Parse failures abort
+// staging; first-time modification of an existing file writes a
+// timestamped backup next to it (the 2026-09-05 incident rule: every
+// destructive path gets a guard).
+//
+// Run: npm test
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const HOOK_GROUP = "pi-bridge-gate";
+
+/** Group-key namespace. Each pi session stages its OWN group keyed per-pid
+ *  (`pi-bridge-gate-<pid>`): hooks.json lives in the SHARED workspace, and
+ *  two concurrent sessions must never remove or overwrite each other's gate
+ *  (audit 2026-09-07: a single shared key let a gate-off session silently
+ *  strip a gate-on session's PreToolUse matchers). */
+export const GATE_GROUP_PREFIX = "pi-bridge-gate";
+
+/** This session's group key. */
+export function gateGroupKey(pid: number = process.pid): string {
+	return `${GATE_GROUP_PREFIX}-${pid}`;
+}
+
+/** True if the process is running (EPERM counts: alive but not ours). */
+function pidAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Which session a gate group belongs to, parsed from the script path its
+ *  command embeds (`.../approval-hook-<pid>.js`). The pid is the ownership
+ *  proof: the script is per-pid (0600, written by that session). Returns
+ *  null for groups we cannot attribute (foreign/future formats - never
+ *  touched). */
+function gateGroupPid(group: unknown): number | null {
+	const m = /approval-hook-(\d+)\.js/.exec(JSON.stringify(group));
+	return m ? Number(m[1]) : null;
+}
+
+/** agy native tools worth gating: everything that mutates the machine. */
+export const GATED_AGY_TOOLS =
+	"create_file|write_to_file|replace_file_content|multi_replace_file_content|edit_file|run_command";
+
+/** The same list as a set, for the bridge's POST /approval validation: a
+ *  payload for anything else is answered with a direct deny (defense in
+ *  depth - the hooks matcher should never let one through). */
+export const GATED_AGY_TOOL_SET: ReadonlySet<string> = new Set(GATED_AGY_TOOLS.split("|"));
+
+export interface StageOptions {
+	/** Bridge HTTP port (the approval endpoints live on the bridge server). */
+	port: number;
+	/** Bridge shared secret (x-bridge-token). */
+	token: string;
+	/** Path to the bundled poll script (written by the caller). */
+	scriptPath: string;
+	/** Full park budget in ms; the staged hook timeout exceeds it. */
+	parkBudgetMs: number;
+}
+
+/** Source of the staged poll script. Written to disk by the caller (data
+ *  dir), referenced by absolute path from the staged hooks.json. Early-acks
+ *  via POST /approval, then polls GET /approval/<ticket> until a terminal
+ *  decision or the deadline. Terminal: prints the JSON decision on stdout.
+ *  Deadline hit: prints {"decision":"deny", ...} (fail closed) - agy may
+ *  still soft-pass a timed-out hook, but a printed deny is honored (V2). */
+export function hookScriptSource(opts: { port: number; token: string; deadlineMs: number }): string {
+	return `#!/usr/bin/env node
+// Bridge approval hook (generated; do not edit). Polls the pi-antigravity-bridge.
+const PORT = ${opts.port};
+const TOKEN = ${JSON.stringify(opts.token)};
+const DEADLINE = Date.now() + ${opts.deadlineMs};
+let body = "";
+process.stdin.setEncoding("utf8");
+for await (const chunk of process.stdin) body += chunk;
+let ticket = "";
+try {
+	const res = await fetch(\`http://127.0.0.1:\${PORT}/approval\`, {
+		method: "POST",
+		headers: { "content-type": "application/json", "x-bridge-token": TOKEN },
+		body,
+	});
+	const json = await res.json();
+	// Ungated payloads get a terminal decision right on the POST (no park).
+	if (json && typeof json === "object" && "decision" in json) {
+		console.log(JSON.stringify(json.decision));
+		process.exit(0);
+	}
+	ticket = json.ticket ?? "";
+} catch {}
+if (!ticket) {
+	console.log(JSON.stringify({ decision: "deny", reason: "approval gate unreachable (bridge down?)" }));
+	process.exit(0);
+}
+while (Date.now() < DEADLINE) {
+	await new Promise((r) => setTimeout(r, 500));
+	try {
+		const res = await fetch(\`http://127.0.0.1:\${PORT}/approval/\${encodeURIComponent(ticket)}\`, {
+			headers: { "x-bridge-token": TOKEN },
+		});
+		const json = await res.json();
+		if (json.status !== "pending") {
+			console.log(JSON.stringify(json.decision ?? { decision: "deny", reason: "gate returned no decision" }));
+			process.exit(0);
+		}
+	} catch {}
+}
+console.log(JSON.stringify({ decision: "deny", reason: "approval gate deadline exceeded" }));
+`;
+}
+
+/** Hook timeout (seconds) staged for a given park budget: the budget plus a
+ *  60s margin, minimum 60s. V3: a timed-out hook soft-passes, so this must
+ *  never be smaller than the human can plausibly need. */
+export function stagedTimeoutSeconds(parkBudgetMs: number): number {
+	return Math.max(60, Math.ceil(parkBudgetMs / 1000) + 60);
+}
+
+/** Build our hooks.json group for one workspace staging. */
+export function buildGateGroup(opts: StageOptions): Record<string, unknown> {
+	const command = `node ${JSON.stringify(opts.scriptPath)}`;
+	return {
+		enabled: true,
+		PreToolUse: [
+			{
+				matcher: GATED_AGY_TOOLS,
+				hooks: [
+					{
+						type: "command",
+						command,
+						timeout: stagedTimeoutSeconds(opts.parkBudgetMs),
+					},
+				],
+			},
+		],
+	};
+}
+
+export interface StageResult {
+	wrote: boolean;
+	/** Backup file written before first modification of a foreign file. */
+	backup?: string;
+	/** Why nothing was written (parse failure, already current, ...). */
+	reason?: string;
+}
+
+/** Stage the gate group into <workspaceDir>/.agents/hooks.json under THIS
+ *  session's per-pid key. Merge-safe:
+ *  - foreign groups are preserved;
+ *  - gate groups of DEAD sessions are swept (their bridge is gone; the hook
+ *    would fail closed forever), groups of live sessions never touched;
+ *  - a foreign file is backed up before its first modification;
+ *  - unparseable files are never touched. */
+export function stageGateHooks(workspaceDir: string, opts: StageOptions): StageResult {
+	const dir = path.join(workspaceDir, ".agents");
+	const file = path.join(dir, "hooks.json");
+	const group = buildGateGroup(opts);
+	const ownKey = gateGroupKey();
+	let current: Record<string, unknown> = {};
+	const existed = fs.existsSync(file);
+	if (existed) {
+		try {
+			if (fs.lstatSync(file).isSymbolicLink()) {
+				return { wrote: false, reason: "hooks.json is a symlink; refusing to follow it" };
+			}
+		} catch {
+			return { wrote: false, reason: "hooks.json vanished while staging" };
+		}
+		try {
+			const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+				return { wrote: false, reason: "hooks.json is not an object; refusing to touch it" };
+			}
+			current = parsed as Record<string, unknown>;
+		} catch {
+			return { wrote: false, reason: "hooks.json is not valid JSON; refusing to touch it" };
+		}
+		// Sweep gate groups whose owning session is gone. Never touch groups of
+		// live sessions (concurrent pi sessions share this workspace) or groups
+		// we cannot attribute.
+		let swept = 0;
+		for (const key of Object.keys(current)) {
+			if (key === ownKey) continue;
+			const isGateGroup = key === GATE_GROUP_PREFIX || key.startsWith(`${GATE_GROUP_PREFIX}-`);
+			if (!isGateGroup) continue;
+			const pid = gateGroupPid(current[key]);
+			if (pid === null || pidAlive(pid)) continue;
+			delete current[key];
+			swept += 1;
+		}
+		if (swept > 0 && JSON.stringify(current[ownKey]) === JSON.stringify(group)) {
+			// Own group already current; the pass only swept dead peers.
+			fs.writeFileSync(file, JSON.stringify(current, null, 2) + "\n");
+			return { wrote: true, reason: `swept ${swept} dead gate group(s)` };
+		}
+		if (JSON.stringify(current[ownKey]) === JSON.stringify(group)) {
+			return { wrote: false, reason: "already staged" };
+		}
+	}
+	const backup =
+		existed && current[ownKey] === undefined
+			? `${file}.backup-${new Date().toISOString().replace(/[:.]/g, "-")}`
+			: undefined;
+	if (backup) fs.copyFileSync(file, backup);
+	current[ownKey] = group;
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(file, JSON.stringify(current, null, 2) + "\n");
+	return { wrote: true, backup };
+}
+
+/** Remove ONLY this session's gate group (or the given pid's). Other
+ *  sessions' groups - including live ones in a shared workspace - are never
+ *  touched: a gate-off session must not strip a gate-on session's matchers
+ *  (audit 2026-09-07). Foreign content stays; an object file is left in
+ *  place (harmless). */
+export function removeGateHooks(workspaceDir: string, pid: number = process.pid): StageResult {
+	const file = path.join(workspaceDir, ".agents", "hooks.json");
+	if (!fs.existsSync(file)) return { wrote: false, reason: "no hooks.json" };
+	try {
+		if (fs.lstatSync(file).isSymbolicLink()) {
+			return { wrote: false, reason: "hooks.json is a symlink; refusing to follow it" };
+		}
+	} catch {
+		return { wrote: false, reason: "hooks.json vanished while removing" };
+	}
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+		if (!parsed || typeof parsed !== "object") return { wrote: false, reason: "not an object; refusing" };
+		const ownKey = gateGroupKey(pid);
+		if (parsed[ownKey] === undefined) return { wrote: false, reason: "not staged" };
+		delete parsed[ownKey];
+		fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + "\n");
+		return { wrote: true };
+	} catch {
+		return { wrote: false, reason: "not valid JSON; refusing" };
+	}
+}

package/src/config.ts

@@ -44,6 +44,29 @@ export type AgyMode = "accept-edits" | "plan";
 export type ThinkingTier = "low" | "medium" | "high";
 export type BridgeTools = "none" | "mcp" | "all";
 
+/** How the approval gate activates (docs/TODO.md section 2.5).
+ *
+ *  "auto" (default): OFF until a third-party pi permission extension is
+ *  detected (src/approval-detect.ts). When one is found, the gate runs in
+ *  "shadow" mode so that extension gates agy's native tool calls with zero
+ *  configuration on its side.
+ *
+ *  "shadow" / "dedicated": force the gate on in that shape. "off": never
+ *  gate, even when a permission extension is installed. NOTE: "dedicated"
+ *  currently stages the same shadow tools as "shadow" (warn-logged remap);
+ *  the explicit antigravity_approve variant is planned - see docs/TODO.md. */
+export type GateMode = "auto" | "shadow" | "dedicated" | "off";
+
+/** Fallback decision when no extension blocked a gated call: "ask" uses
+ *  ctx.ui.confirm (headless = deny, fail-closed), "allow" auto-approves,
+ *  "deny" auto-rejects. */
+export type GateAskMode = "ask" | "allow" | "deny";
+
+export interface GateConfig {
+	gateMode: GateMode;
+	mode: GateAskMode;
+}
+
 export interface AcpConfig {
 	/** Path to agy_acp_server.par. Empty = env AGY_ACP_BIN > PATH. */
 	bin: string;
@@ -108,6 +131,11 @@ export interface AgyConfig {
 	 *  digest (per-turn) is not. Turn off for agy-native behavior (agy's own
 	 *  system prompt only). */
 	systemPrompt: boolean;
+	/** Approval gate over agy NATIVE tool calls (create_file, run_command,
+	 *  ...). pi tools agy calls already pass through pi's gates via the G9
+	 *  round-trip; this covers the rest. Default auto (off until a
+	 *  third-party permission extension is detected). See docs/TODO.md 2.5. */
+	approvals: GateConfig;
 }
 
 const DEFAULTS: AgyConfig = {
@@ -120,6 +148,7 @@ const DEFAULTS: AgyConfig = {
 	bridgeTools: "all",
 	digest: false,
 	systemPrompt: true,
+	approvals: { gateMode: "auto", mode: "ask" },
 	acp: { bin: "", permissions: "auto" },
 };
 
@@ -189,6 +218,19 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		? ["1", "true", "on"].includes(envSys.toLowerCase())
 		: file.systemPrompt ?? DEFAULTS.systemPrompt;
 
+	// Approval gate (docs/TODO.md 2.5). Unknown values fall back to "auto"
+	// so a typo can never silently force the gate on.
+	const gateRaw = (process.env.AGY_APPROVALS ?? file.approvals?.gateMode ?? DEFAULTS.approvals.gateMode).toLowerCase();
+	const gateMode: GateMode =
+		gateRaw === "shadow" || gateRaw === "dedicated" || gateRaw === "off"
+			? gateRaw
+			: "auto";
+	const askRaw = (process.env.AGY_APPROVALS_MODE ?? file.approvals?.mode ?? DEFAULTS.approvals.mode).toLowerCase();
+	const gateAskMode: GateAskMode =
+		askRaw === "allow" || askRaw === "deny"
+			? askRaw
+			: "ask";
+
 	const fileAcp = (typeof file.acp === "object" && file.acp !== null ? file.acp : {}) as Partial<AcpConfig>;
 	const acp: AcpConfig = {
 		bin:
@@ -208,6 +250,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		bridgeTools,
 		digest,
 		systemPrompt,
+		approvals: { gateMode, mode: gateAskMode },
 		patchCleanupNotified: file.patchCleanupNotified === true,
 	};
 }