@jpkme/diff-review 0.1.10 → 0.1.13

package/README.md

@@ -1,10 +1,10 @@
 # diff-review
 
-App local para revisar un branch: generás un prompt, lo corrés vos con tu agente
-(Claude, Cursor, Copilot, etc.), soltás el JSON que te devuelve, y la UI completa
-los diffs con `git` y te deja triager hallazgos.
-
-No spawnea agentes ni corre reviews sola: el modelo lo manejás vos a mano.
+App local para revisar un branch con tu agente (Claude, Cursor, Copilot, etc.):
+lanzás la review desde la UI o la CLI, el agente escribe el JSON, la UI completa
+los diffs con `git` y te deja triager hallazgos. Por ACP ves el proceso en vivo y
+después podés preguntarle o pedirle cambios al reporte desde la web. También podés
+copiar el prompt y correrlo en otro agente a mano.
 
 ## Instalación
 
@@ -27,8 +27,8 @@ npx @jpkme/diff-review
 Desde un **repo git**, el default es terminal-first:
 
 1. Elegís **branch** y **base** con prompts en la terminal (`@clack/prompts`; tipeá para filtrar).
-2. Copia el prompt al portapapeles y espera el JSON (`diff-rev_{branchTip}_{baseTip}.json`).
-3. Valida y abre el viewer con el reporte ya importado.
+2. Si hay agentes instalados, el default es lanzar uno (ACP en la web cuando aplica); también podés copiar el prompt al portapapeles.
+3. El agente escribe `diff-rev_{branchTip}_{baseTip}.json`; la CLI valida y abre el viewer.
 
 Si pasás `--branch` y `--base` juntos, saltea los selects. Si quedan iguales (diff vacío), abre la UI.
 
@@ -38,8 +38,8 @@ caso el archivo viejo no cuenta hasta que el agente lo reescriba. Sin terminal i
 
 ### Lanzar el agente (`--agent`)
 
-Si hay agentes instalados, después de branch y base un solo select lista copiar el prompt al portapapeles (primera
-opción) y cada agente detectado. Con `--agent` saltea esa lista y va directo a elegir agente y modelo:
+Si hay agentes instalados, después de branch y base un solo select lista cada agente detectado (default el primero)
+y, al final, copiar el prompt al portapapeles. Con `--agent` saltea esa lista y va directo a elegir agente y modelo:
 
 ```bash
 diff-review --agent
@@ -63,13 +63,38 @@ instalados, sigue con el portapapeles. Sin terminal interactiva usa el primer ag
 
 El agente tiene que estar logueado (p. ej. `claude /login` una vez).
 
+#### Por ACP, con la web (Claude Code, Cursor CLI, GitHub Copilot CLI)
+
+Si el agente elegido habla ACP, la CLI abre la UI enseguida y el agente corre dentro del server local. Claude Code
+va por el adaptador `@agentclientprotocol/claude-agent-acp` (se baja con `npx` la primera vez); Cursor
+(`cursor-agent acp`) y Copilot (`copilot --acp`) lo traen de fábrica. Codex y Gemini siguen por la terminal.
+
+- El select de modelo muestra los que ofrece cada agente (se consultan por ACP la primera vez).
+- La web muestra lo que va haciendo (comandos, archivos que lee, plan). La terminal solo avisa fallos duros o JSON válido.
+- Al terminar cada turno, el server valida el JSON; si falta algo se lo pide al agente hasta dos veces y, cuando valida,
+  la web abre el reporte.
+- Cada pedido de permiso pasa por una política fija: leer dentro del repo, escribir únicamente el JSON del review
+  y comandos de solo lectura: `git` (diff, log, show, blame…), `cat`, `head`, `tail`, `grep`, `rg`, `find`, `ls`,
+  `wc`, `sed -n 'N,Mp'` y sus equivalentes de PowerShell, encadenados con `|`, `&&`, `||` o `;`, con los paths
+  dentro del repo. Se rechazan redirecciones a archivos (salvo `/dev/null`), `$(…)`, red, instalaciones y todo lo
+  demás; el agente recibe las reglas en el prompt para no intentarlo.
+- La allowlist propia de cada agente no se usa en estas sesiones (aprobaría por nombre de comando, p. ej.
+  `echo x > archivo`): Claude corre sin cargar `~/.claude/settings.json` ni el `.claude/` del repo, y Cursor con
+  una copia de su configuración sin `permissions.allow` (en el temp del sistema; el login se conserva).
+- La sesión queda viva: en el reporte, el botón **Agente** abre un chat para preguntarle sobre la review
+  (no puede escribir nada) o pedirle cambios al JSON (el reporte se actualiza y el triage de los hallazgos que
+  siguen se conserva). Si el server se reinició, la sesión se retoma con `session/load`.
+
+También se puede lanzar desde la UI, en "2. Generar review" → **Lanzar agente**. Con `--headless` corre en la
+terminal como el resto de los agentes.
+
 Para abrir la UI primero (sin esperar el JSON):
 
 ```bash
 diff-review --ui
 ```
 
-Opciones: `--port` (si está ocupado, usa el siguiente libre), `--host`, `--base`, `--branch`, `--agent`, `--no-open`.
+Opciones: `--port` (si está ocupado, usa el siguiente libre), `--host`, `--base`, `--branch`, `--agent`, `--headless`, `--no-open`.
 
 Si lo lanzás desde un repositorio git, la UI precarga esa ruta y el branch actual.
 
@@ -85,11 +110,9 @@ npm start                # mismo que el bin global
 ## Flujo (UI)
 
 1. Pegá la ruta (o URL) del repo y elegí branch / base — o lanzá `diff-review` / `diff-review --ui` desde el repo.
-2. Copiá el prompt (o el comando de skill `/diff-review`).
-3. Corrélo en tu agente; que escriba `diff-rev_{branchTip}_{baseTip}.json` y lo valide con `npx --yes @jpkme/diff-review validate <archivo>` (también acepta nombres legacy).
-4. Arrastrá ese JSON a la dropzone (o dejá que el CLI lo importe solo). La UI hidrata los diffs con git.
-
-"Ver ejemplo" carga un reporte de muestra sin tocar un repo.
+2. Si hay agentes ACP, el default es **Lanzar agente**; si no, usá **Copiar prompt** y pegalo en tu agente.
+3. El agente escribe `.diff-review/diff-rev_{branchTip}_{baseTip}.json` (en sesiones ACP el server valida solo; si corriste el prompt a mano, `npx --yes @jpkme/diff-review validate <archivo>`).
+4. Con agente integrado o CLI el reporte se abre solo; si no, arrastrá el JSON a la dropzone. La UI hidrata los diffs con git (reusa el companion `.diff` si existe).
 
 ## Qué hace git (en tu máquina)
 

package/bin/diff-review.mjs

@@ -7,28 +7,40 @@
  *   diff-review --port 5191
  *   diff-review --branch x --base y   → saltea selects de Clack
  *   diff-review --agent      → elegir agente + modelo y lanzarlo con el prompt (sin portapapeles)
+ *   diff-review --headless   → con agente: correrlo en la terminal en vez de por ACP con la web
  *   diff-review --no-open
  */
 
 import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
-import { AGENTS, detectAgents, modelChoices, OTHER_MODEL, resolvedRunModel, runAgent } from '../lib/agents.mjs';
+import { AGENTS, detectAgents, modelChoices, resolvedRunModel, runAgent } from '../lib/agents.mjs';
+import { listAcpModelsCached, supportsAcp } from '../lib/acp.mjs';
+import { buildAcpModelSelectOptions, sortModelSelectOptions } from '../lib/model-label.mjs';
 import { autocompleteEs } from '../lib/autocomplete-es.mjs';
 import { copyTextToClipboard } from '../lib/clipboard.mjs';
 import { branchTips, getRemoteUrl, listBranches, tryResolveGitRoot } from '../lib/git.mjs';
 import { makeOutputFilename } from '../lib/output-name.mjs';
-import { buildPrompt } from '../lib/prompt.mjs';
+import { buildPrompt, outputRelPath } from '../lib/prompt.mjs';
+import { prepareReviewPromptOpts } from '../lib/review-prep.mjs';
+import { ensureReviewDir, writeDiffCache } from '../lib/review-dir.mjs';
 import { existingReviewOutput, waitForReviewOutput } from '../lib/wait-output.mjs';
 import { stampReviewProvenance } from '../lib/review-meta.mjs';
 import { runValidateCli } from '../lib/check-report.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(here, '..');
-const buildDir = join(packageRoot, 'web', 'build');
+// `DIFF_REVIEW_OUT=build-next` cuando `web/build` está bloqueado por un server en marcha (EBUSY en Windows).
+const buildDir = (() => {
+	const primary = join(packageRoot, 'web', 'build');
+	const overlay = join(packageRoot, 'web', 'build-next');
+	if (existsSync(join(overlay, 'index.js'))) return overlay;
+	return primary;
+})();
 const entry = join(buildDir, 'index.js');
 
 const DEFAULT_HOST = '127.0.0.1';
@@ -63,6 +75,9 @@ un solo select lista el portapapeles y cada agente detectado.
 Si pasás --branch y --base juntos, saltea los selects.
 Con --agent: saltea esa lista; elegís un agente instalado y el modelo,
 y diff-review lo lanza con el prompt.
+Si el agente habla ACP (Claude Code), corre desde la UI web: ves el
+proceso en vivo y después podés preguntarle o pedirle cambios al reporte.
+Con --headless corre en la terminal como antes.
 Con --ui: abre la UI de inmediato (web-first).
 
 Options:
@@ -72,6 +87,7 @@ Options:
       --base <b>   Base del merge-base (salta el select de base)
       --branch <b> Branch a revisar (salta el select de branch)
       --agent      Lanzar un agente instalado (${AGENTS.map((a) => a.bins[0]).join(', ')}) con el prompt
+      --headless   Con agente: correrlo en la terminal (sin ACP ni chat en la web)
       --no-open    No abrir el navegador
   -h, --help       Esta ayuda
 
@@ -87,6 +103,7 @@ function parseArgs(argv) {
 		help: false,
 		ui: false,
 		agent: false,
+		headless: false,
 		base: '',
 		branch: ''
 	};
@@ -96,6 +113,7 @@ function parseArgs(argv) {
 		else if (a === '--no-open') opts.open = false;
 		else if (a === '--ui') opts.ui = true;
 		else if (a === '--agent') opts.agent = true;
+		else if (a === '--headless') opts.headless = true;
 		else if (a === '--host') opts.host = argv[++i] || opts.host;
 		else if (a === '--base') opts.base = argv[++i] || opts.base;
 		else if (a === '--branch') opts.branch = argv[++i] || opts.branch;
@@ -308,28 +326,55 @@ function copyPromptOrWarn(prompt) {
 }
 
 /**
- * Modelo del agente: select con TTY; sin TTY, el modelo por defecto (string vacío).
+ * Opciones de modelo: las que ofrece el agente por ACP (si va a correr así) o, si no, la lista fija.
  * @param {import('../lib/agents.mjs').DetectedAgent} agent
+ * @param {{ acpCwd?: string }} opts
  */
-async function pickModel(agent) {
-	if (!isInteractive()) return '';
-
-	const { options, initialValue } = modelChoices(agent.def);
-	const choice = await p.select({ message: 'Modelo', options, initialValue });
-	if (p.isCancel(choice)) {
-		p.cancel('Cancelado.');
-		process.exit(0);
+async function modelOptions(agent, { acpCwd }) {
+	const fixed = modelChoices(agent.def);
+	const sortedFixed = {
+		...fixed,
+		options: sortModelSelectOptions(fixed.options)
+	};
+	if (!acpCwd) return sortedFixed;
+	const spin = p.spinner();
+	spin.start(`Consultando los modelos de ${agent.def.label}`);
+	try {
+		const { models, currentModel, fromCache } = await listAcpModelsCached(agent, { cwd: acpCwd });
+		spin.stop(
+			fromCache
+				? `Modelos de ${agent.def.label} (caché)`
+				: `Modelos de ${agent.def.label}`
+		);
+		if (!models.length) return sortedFixed;
+		// Misma fusión/labels/orden que la UI.
+		return buildAcpModelSelectOptions({ models, currentModel }, fixed);
+	} catch (err) {
+		spin.stop(`No pude consultar los modelos (${err instanceof Error ? err.message.split('\n')[0] : err}).`);
+		return sortedFixed;
 	}
-	if (choice !== OTHER_MODEL) return /** @type {string} */ (choice);
+}
 
-	const typed = ensureValue(
-		await p.text({
-			message: 'Id del modelo',
-			validate: (v) => (String(v ?? '').trim() ? undefined : 'Escribí el id del modelo.')
-		}),
-		'modelo'
+/**
+ * Modelo del agente: autocomplete con búsqueda; sin TTY, el default (string vacío).
+ * @param {import('../lib/agents.mjs').DetectedAgent} agent
+ * @param {{ acpCwd?: string }} [opts] con `acpCwd`, la lista sale del agente por ACP
+ */
+async function pickModel(agent, opts = {}) {
+	if (!isInteractive()) return '';
+
+	const { options, initialValue } = await modelOptions(agent, opts);
+	return /** @type {string} */ (
+		ensureValue(
+			await autocompleteEs({
+				message: 'Modelo',
+				options,
+				initialValue,
+				placeholder: 'opus, sonnet, gpt…'
+			}),
+			'modelo'
+		)
 	);
-	return typed.trim();
 }
 
 /**
@@ -337,8 +382,9 @@ async function pickModel(agent) {
  * Si `preset` ya viene elegido, solo pregunta el modelo.
  * @param {import('../lib/agents.mjs').DetectedAgent[]} detected
  * @param {import('../lib/agents.mjs').DetectedAgent} [preset]
+ * @param {{ repo: string, headless: boolean }} [run] para consultar los modelos por ACP
  */
-async function pickAgentAndModel(detected, preset) {
+async function pickAgentAndModel(detected, preset, run) {
 	if (!isInteractive()) return { agent: preset ?? detected[0], model: '' };
 
 	let agent = preset;
@@ -354,11 +400,12 @@ async function pickAgentAndModel(detected, preset) {
 		agent = detected.find((a) => a.def.id === id) ?? detected[0];
 	}
 
-	return { agent, model: await pickModel(agent) };
+	const acpCwd = run && !run.headless && supportsAcp(agent) ? run.repo : undefined;
+	return { agent, model: await pickModel(agent, { acpCwd }) };
 }
 
 /**
- * Portapapeles primero y después cada agente detectado.
+ * Agentes detectados primero (default el primero); portapapeles como opción secundaria.
  * @param {import('../lib/agents.mjs').DetectedAgent[]} detected
  * @returns {Promise<import('../lib/agents.mjs').DetectedAgent | null>} `null` = portapapeles
  */
@@ -367,10 +414,10 @@ async function pickDelivery(detected) {
 		await p.select({
 			message: '¿Cómo generás el review?',
 			options: [
-				{ value: 'clipboard', label: 'Copiar el prompt al portapapeles', hint: 'lo pegás en tu agente' },
-				...detected.map((a) => ({ value: a.def.id, label: a.def.label, hint: a.path }))
+				...detected.map((a) => ({ value: a.def.id, label: a.def.label, hint: a.path })),
+				{ value: 'clipboard', label: 'Copiar el prompt al portapapeles', hint: 'lo pegás en tu agente' }
 			],
-			initialValue: 'clipboard'
+			initialValue: detected[0].def.id
 		}),
 		'modo'
 	);
@@ -407,7 +454,7 @@ async function reuseExistingReview(existing, outputFilename) {
  */
 async function runAgentAndWait(agent, { repo, prompt, model, outputFilename, useClack }) {
 	const what = `${agent.def.label} (${model || 'modelo por defecto'})`;
-	const msg = `Lanzando ${what}. Espera ${outputFilename} en la raíz del repo; Ctrl+C cancela.`;
+	const msg = `Lanzando ${what}. Espera ${outputRelPath(outputFilename)}; Ctrl+C cancela.`;
 	if (useClack) p.outro(msg);
 	else console.log(msg);
 
@@ -447,11 +494,33 @@ async function runAgentAndWait(agent, { repo, prompt, model, outputFilename, use
 	return /** @type {{ path: string }} */ (result);
 }
 
+/**
+ * El agente corre dentro del server de la UI (ACP): la web muestra el proceso y abre el reporte; la terminal ve un
+ * resumen. La sesión queda viva para preguntas y cambios desde el reporte.
+ * @param {import('../lib/agents.mjs').DetectedAgent} agent
+ * @param {{ repo: string, branch: string, base: string, model: string, outputFilename: string, useClack: boolean }} run
+ * @param {{ host: string, port: number, open: boolean }} opts
+ */
+async function runAgentInUi(agent, { repo, branch, base, model, outputFilename, useClack }, opts) {
+	const id = randomUUID();
+	const msg = `Lanzando ${agent.def.label} (${model || 'modelo por defecto'}). El progreso se ve en la web; Ctrl+C corta.`;
+	if (useClack) p.outro(msg);
+	else console.log(msg);
+	await startServer({
+		host: opts.host,
+		port: opts.port,
+		open: opts.open,
+		launchCwd: repo,
+		openPath: `/?agent=${encodeURIComponent(id)}`,
+		agentRun: { id, repo, branch, base, outputFilename, agentId: agent.def.id, ...(model ? { model } : {}) }
+	});
+}
+
 function explainWaitingForAgent(outputFilename, { copied, useClack }) {
 	const copyMsg = copied
 		? 'Se copió un prompt al portapapeles: pegalo en el chat de tu agente de IA para generar el contenido de la review.'
 		: 'Generá el JSON con tu agente de IA usando el prompt de esta sesión (no se pudo copiar solo al portapapeles).';
-	const waitMsg = `Aguardando el resultado del agente (${outputFilename} en la raíz del repo). La UI web se abre cuando ese archivo esté listo.`;
+	const waitMsg = `Aguardando el resultado del agente (${outputRelPath(outputFilename)}). La UI web se abre cuando ese archivo esté listo.`;
 
 	if (useClack) {
 		p.log.success(copyMsg);
@@ -465,7 +534,8 @@ function explainWaitingForAgent(outputFilename, { copied, useClack }) {
 }
 
 /**
- * @param {{ host: string, port: number, open: boolean, launchCwd: string, importFile?: string, openPath?: string }} cfg
+ * @typedef {{ id: string, repo: string, branch: string, base: string, outputFilename: string, agentId: string, model?: string }} AgentRun
+ * @param {{ host: string, port: number, open: boolean, launchCwd: string, importFile?: string, openPath?: string, agentRun?: AgentRun }} cfg
  */
 async function startServer(cfg) {
 	if (!existsSync(entry)) {
@@ -495,8 +565,11 @@ O reinstalá el paquete (el tarball de npm incluye el build).`);
 			HOST: cfg.host,
 			PORT: String(port),
 			ORIGIN: origin,
+			// Reviews con seed/diff o import JSON suelen pasar los 512K por defecto del adapter-node.
+			BODY_SIZE_LIMIT: process.env.BODY_SIZE_LIMIT || '16M',
 			DIFF_REVIEW_LAUNCH_CWD: cfg.launchCwd,
-			...(cfg.importFile ? { DIFF_REVIEW_IMPORT_FILE: cfg.importFile } : {})
+			...(cfg.importFile ? { DIFF_REVIEW_IMPORT_FILE: cfg.importFile } : {}),
+			...(cfg.agentRun ? { DIFF_REVIEW_AGENT_RUN: JSON.stringify(cfg.agentRun), DIFF_REVIEW_MIRROR: '1' } : {})
 		},
 		stdio: ['ignore', 'pipe', 'inherit'],
 		windowsHide: false
@@ -514,6 +587,7 @@ O reinstalá el paquete (el tarball de npm incluye el build).`);
 					ready = true;
 					console.log(`diff-review listo en ${terminalLink(origin)} — Ctrl+C para salir.`);
 					if (cfg.open) openBrowser(openUrl);
+					else if (cfg.agentRun) console.log(`Progreso del agente: ${terminalLink(openUrl)}`);
 				}
 				continue;
 			}
@@ -548,6 +622,22 @@ async function runUiMode(opts, launch, launchCwd) {
 	if (launch) {
 		console.log(`Repo:   ${launch.repo}`);
 		console.log(`Branch: ${branch}  (base: ${base})`);
+		let promptOpts = { outputFilename };
+		try {
+			promptOpts = prepareReviewPromptOpts({
+				repo: launch.repo,
+				branch,
+				base,
+				outputFilename
+			});
+		} catch (err) {
+			console.warn(
+				'No pude precomputar el diff:',
+				err instanceof Error ? err.message : err
+			);
+			ensureReviewDir(launch.repo);
+			writeDiffCache(launch.repo, outputFilename, { branch, base });
+		}
 		const prompt = buildPrompt(
 			{
 				source: 'local',
@@ -556,7 +646,7 @@ async function runUiMode(opts, launch, launchCwd) {
 				base,
 				remoteUrl: launch.remoteUrl
 			},
-			{ outputFilename }
+			promptOpts
 		);
 		if (copyTextToClipboard(prompt)) {
 			console.log('Prompt copiado al portapapeles.');
@@ -623,12 +713,28 @@ async function main() {
 	}
 
 	const outputFilename = buildOutputFilename(launch.repo, branch, base);
+	// El agente escribe en .diff-review/ (que se ignora sola) y lee de ahí el diff ya calculado.
+	let promptOpts = { outputFilename };
+	try {
+		promptOpts = prepareReviewPromptOpts({
+			repo: launch.repo,
+			branch,
+			base,
+			outputFilename
+		});
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (prompted) p.log.warn(`No pude precomputar el diff: ${msg}`);
+		else console.warn('No pude precomputar el diff:', msg);
+		ensureReviewDir(launch.repo);
+		writeDiffCache(launch.repo, outputFilename, { branch, base });
+	}
 
 	if (!prompted) {
 		console.log(`Repo:   ${launch.repo}`);
 		console.log(`Branch: ${branch}  (base: ${base})`);
 	} else {
-		p.note(`${branch}  →  ${base}\n${outputFilename}`, 'Review');
+		p.note(`${branch}  →  ${base}\n${outputRelPath(outputFilename)}`, 'Review');
 	}
 
 	const prompt = buildPrompt(
@@ -639,7 +745,7 @@ async function main() {
 			base,
 			remoteUrl: launch.remoteUrl
 		},
-		{ outputFilename }
+		promptOpts
 	);
 
 	// Sin --agent también se detectan (con terminal interactiva) para ofrecer lanzar uno en vez del portapapeles.
@@ -665,7 +771,18 @@ async function main() {
 	}
 	const useAgent = !result && detected.length > 0 && (opts.agent || chosen != null);
 	if (useAgent) {
-		const { agent, model } = await pickAgentAndModel(detected, chosen ?? undefined);
+		const { agent, model } = await pickAgentAndModel(detected, chosen ?? undefined, {
+			repo: launch.repo,
+			headless: opts.headless
+		});
+		if (supportsAcp(agent) && !opts.headless) {
+			await runAgentInUi(
+				agent,
+				{ repo: launch.repo, branch, base, model, outputFilename, useClack },
+				opts
+			);
+			return;
+		}
 		result = await runAgentAndWait(agent, {
 			repo: launch.repo,
 			prompt,

package/lib/acp-policy.mjs

@@ -0,0 +1,223 @@
+/**
+ * Qué puede hacer el agente cuando corre por ACP. Cada `session/request_permission` pasa por acá: no hay nadie
+ * mirando la terminal para aprobar, así que la política es una allowlist (leer, comandos de solo lectura y escribir
+ * el JSON de salida en `.diff-review/`) y todo lo demás se rechaza.
+ *
+ * Ojo: el agente solo pide permiso para lo que *su* configuración no aprueba sola (p. ej. Claude Code aplica la
+ * allowlist de `~/.claude/settings.json` antes de preguntar). Esto acota lo que pide, no lo que el usuario ya
+ * habilitó en su agente.
+ */
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, normalize, resolve } from "node:path";
+import { checkShell } from "./acp-shell.mjs";
+import { outputRelPath } from "./output-name.mjs";
+
+/**
+ * @typedef {"review" | "ask" | "edit"} PolicyMode
+ *   review = generar el JSON; ask = preguntas (no puede escribir nada); edit = modificar el JSON.
+ * @typedef {{ repo: string, outputFilename: string, mode: PolicyMode }} PolicyContext
+ * @typedef {{
+ *   kind?: string | null,
+ *   title?: string | null,
+ *   rawInput?: unknown,
+ *   locations?: { path: string }[] | null,
+ *   content?: { type: string, path?: string }[] | null,
+ * }} ToolCallLike
+ * @typedef {{ allow: boolean, reason: string }} Decision
+ */
+
+/** @param {string} a @param {string} b */
+function samePath(a, b, platform = process.platform) {
+  const na = normalize(a);
+  const nb = normalize(b);
+  return platform === "win32" ? na.toLowerCase() === nb.toLowerCase() : na === nb;
+}
+
+/**
+ * Resuelve symlinks cuando el path (o un ancestro) existe. Sin eso, un link dentro del repo
+ * puede apuntar fuera y pasar `isInside` con solo `resolve`.
+ * @param {string} path
+ */
+function canonicalPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    const parts = [];
+    let cur = normalize(path);
+    for (;;) {
+      const parent = dirname(cur);
+      if (!parent || parent === cur) return normalize(path);
+      parts.unshift(basename(cur));
+      try {
+        return resolve(realpathSync(parent), ...parts);
+      } catch {
+        cur = parent;
+      }
+    }
+  }
+}
+
+/** @param {string} child @param {string} root */
+function isInside(child, root, platform = process.platform) {
+  const c = normalize(canonicalPath(child));
+  const r = normalize(canonicalPath(root)).replace(/[\\/]+$/, "");
+  const [cc, rr] = platform === "win32" ? [c.toLowerCase(), r.toLowerCase()] : [c, r];
+  return cc === rr || cc.startsWith(`${rr}\\`) || cc.startsWith(`${rr}/`);
+}
+
+/** Paths que toca la tool call (`locations`, diffs de `content` y los campos típicos de `rawInput`). */
+export function toolCallPaths(toolCall, repo) {
+  const raw = toolCall.rawInput && typeof toolCall.rawInput === "object" ? /** @type {Record<string, unknown>} */ (toolCall.rawInput) : {};
+  const candidates = [
+    ...(toolCall.locations ?? []).map((l) => l?.path),
+    ...(toolCall.content ?? []).map((c) => (c?.type === "diff" ? c.path : undefined)),
+    raw.file_path,
+    raw.path,
+    raw.filePath,
+    raw.notebook_path,
+  ];
+  const out = [];
+  for (const c of candidates) {
+    if (typeof c !== "string" || !c.trim()) continue;
+    const abs = isAbsolute(c) ? c : resolve(repo, c);
+    if (!out.some((p) => samePath(p, abs))) out.push(abs);
+  }
+  return out;
+}
+
+/** @param {unknown} rawInput */
+function commandOf(rawInput) {
+  if (!rawInput || typeof rawInput !== "object") return "";
+  const cmd = /** @type {Record<string, unknown>} */ (rawInput).command;
+  if (Array.isArray(cmd)) return cmd.map(String).join(" ");
+  return typeof cmd === "string" ? cmd : "";
+}
+
+/**
+ * Comando de shell que la política evalúa (rawInput, backticks o título entero).
+ * Cursor a veces envuelve el script con `@…@` en el título.
+ * @param {ToolCallLike} toolCall
+ */
+export function toolCallCommand(toolCall) {
+  const fromRaw = commandOf(toolCall.rawInput).trim();
+  if (fromRaw) return fromRaw;
+  const title = String(toolCall.title ?? "").trim();
+  const tick = /^`([\s\S]+)`$/.exec(title);
+  if (tick) return tick[1].trim();
+  const at = /^@\s*([\s\S]*?)\s*@$/.exec(title);
+  if (at) return at[1].trim();
+  return title;
+}
+
+/**
+ * Etiqueta corta del agente si el título no es el comando mismo.
+ * @param {ToolCallLike} toolCall
+ * @param {string} [command]
+ */
+export function toolCallLabel(toolCall, command = toolCallCommand(toolCall)) {
+  const title = String(toolCall.title ?? "").trim();
+  if (!title) return "";
+  if (/^`[\s\S]+`$/.test(title) || /^@\s*[\s\S]*?\s*@$/.test(title)) return "";
+  const norm = (s) => s.replace(/\s+/g, " ").trim();
+  if (command && norm(title) === norm(command)) return "";
+  if (command && command.length >= 24 && title.includes(command.slice(0, 24))) return "";
+  return title;
+}
+
+/**
+ * Motivo de denegación legible en la UI de permisos.
+ * @param {string} reason
+ */
+export function humanizePolicyReason(reason) {
+  const r = String(reason || "").trim();
+  if (!r) return "La política bloqueó este pedido.";
+  let m;
+  if ((m = /^(.+?) no está permitido$/.exec(r))) {
+    return `La política bloqueó «${m[1]}» (no está en la allowlist de comandos).`;
+  }
+  if ((m = /^variables de entorno en el comando:\s*(.*)$/s.exec(r))) {
+    const token = String(m[1] || "?").trim().slice(0, 40);
+    return `La política interpretó parte del comando como variable de entorno (${token}) y lo bloqueó.`;
+  }
+  if ((m = /^path fuera del repo:\s*(.*)$/s.exec(r))) {
+    return `El path queda fuera del repo: ${m[1]}`;
+  }
+  if ((m = /^lectura fuera del repo:\s*(.*)$/s.exec(r))) {
+    return `Lectura fuera del repo: ${m[1]}`;
+  }
+  if ((m = /^opción global de git no permitida:\s*(.*)$/s.exec(r))) {
+    return `Opción de git no permitida: ${m[1]}`;
+  }
+  if (r.startsWith("git ")) return `Comando git no permitido por la política: ${r}`;
+  if (r.startsWith("solo se puede escribir") || r.includes("sin path") || r.startsWith("modo pregunta")) return r;
+  return `La política bloqueó el pedido: ${r}`;
+}
+
+/**
+ * ¿El comando de shell solo lee? Ver `checkShell` en `acp-shell.mjs`.
+ * @param {string} command
+ * @param {{ repo?: string }} [opts]
+ */
+export function isAllowedShell(command, opts) {
+  return checkShell(command, opts).ok;
+}
+
+/**
+ * @param {ToolCallLike} toolCall
+ * @param {PolicyContext} ctx
+ * @returns {Decision}
+ */
+export function decidePermission(toolCall, { repo, outputFilename, mode }) {
+  const kind = toolCall.kind ?? "other";
+  const paths = toolCallPaths(toolCall, repo);
+
+  if (kind === "read" || kind === "search") {
+    if (!paths.length) {
+      return { allow: false, reason: `${kind === "search" ? "búsqueda" : "lectura"} sin path` };
+    }
+    const outside = paths.find((p) => !isInside(p, repo));
+    return outside ? { allow: false, reason: `lectura fuera del repo: ${outside}` } : { allow: true, reason: "lectura" };
+  }
+  if (kind === "think") return { allow: true, reason: "pensar" };
+
+  if (kind === "execute") {
+    // Cursor no manda `rawInput`: el comando viene en el título (backticks / @…@ / texto).
+    const cmd = toolCallCommand(toolCall);
+    const check = checkShell(cmd, { repo });
+    return check.ok ? { allow: true, reason: "comando de solo lectura" } : { allow: false, reason: check.reason };
+  }
+
+  if (kind === "edit" || kind === "delete") {
+    if (mode === "ask") return { allow: false, reason: "modo pregunta: no se edita nada" };
+    if (!paths.length) return { allow: false, reason: `${kind === "delete" ? "borrado" : "edición"} sin path` };
+    const target = resolve(repo, outputRelPath(outputFilename));
+    const outside = paths.find((p) => !samePath(canonicalPath(p), canonicalPath(target)));
+    return outside
+      ? {
+          allow: false,
+          reason: `solo se puede escribir ${outputRelPath(outputFilename)} (no ${outside})`
+        }
+      : { allow: true, reason: `escritura de ${outputRelPath(outputFilename)}` };
+  }
+
+  return { allow: false, reason: `${kind} no permitido: ${toolCall.title ?? "?"}` };
+}
+
+/**
+ * Respuesta ACP para una decisión del usuario / política.
+ * - allow + once → `allow_once` (la política se vuelve a evaluar en el próximo pedido).
+ * - allow + always → `allow_always` si el agente la ofrece; si no, cae a `allow_once`.
+ * @param {{ optionId: string, kind: string }[]} options
+ * @param {boolean} allow
+ * @param {{ always?: boolean }} [opts]
+ */
+export function permissionOutcome(options, allow, opts = {}) {
+  const always = Boolean(opts.always);
+  const kinds = allow
+    ? always
+      ? ["allow_always", "allow_once"]
+      : ["allow_once"]
+    : ["reject_once", "reject_always"];
+  const option = kinds.map((kind) => options.find((o) => o.kind === kind)).find(Boolean);
+  return option ? { outcome: { outcome: "selected", optionId: option.optionId } } : { outcome: { outcome: "cancelled" } };
+}