// tht-gate.js -- Pi extension: the HITL gate for the ThothII NL->SQL workflow.
//
// REWRITE of the reference implementation's tht-gate.js. Two changes vs the source:
//  (1) F2 single source: workflow facts (max_phase, phase names, the schema-linking
//      phase) come from `tht phase meta --json`, NOT from JS-mirrored constants.
//      the reference implementation PHASE_NAMES array (truncated to 7) is gone; F8/datamart can no
//      longer drift out of sync.
//  (2) D2/D4 widget-descriptor: the reviewer interaction is emitted as a
//      widget-descriptor JSON (built by ./gate/builders.js) and awaited by id, instead
//      of rendered by blocking native TUI primitives (ctx.ui.select/custom).
//
// PRESERVED VERBATIM from the source (load-bearing runtime glue, spec D4):
//  - the anti-bypass tool_call hook (FORBIDDEN + PROTECTED_FILES)
//  - the input lock + the `input` hook (entry detection + free-input block + `!` steer)
//  - the kickoff injection (before_agent_start) + the two kickoff payloads
//  - the agent_end prose safety net
//  - the exit-code contracts with the CLI (5 = gate refusal, 6 = needs human /
//    auto-advance not ready -> silent no-op)
//  - textResult / tht() / relayIfThtFails / advanceIfReady helpers
//
// TESTING: the pure builders are L1-tested (./gate/__tests__/). This file is the
// GLUE -- it depends on the Pi runtime (pi.on, pi.registerTool, ctx.sendRaw) and is
// verified end-to-end at L2 (Task D4). It is intentionally NOT unit-tested here; a
// fake-Pi runtime mock (cross-cutting follow-up) would let it run in CI.

import { execFileSync } from "node:child_process";
import { Type } from "typebox";
import {
	buildSelectRequest,
	buildMultiselectRequest,
	buildArtifactGate,
} from "./gate/builders.js";
import { isReserved } from "./reserved-labels.mjs";

// --- prepareArguments: parse stringified arrays (workaround for models that send
//    arrays as JSON strings -- same pattern as pi-core's edit tool prepareEditArguments)
// Coerce a value that may arrive as a JSON-encoded string back into an object/array.
// Models sometimes stringify object params (Type.Object / Type.Any); the parsed value
// is returned only when it is genuinely an object, so plain strings pass through intact.
export function jsonObjectOrSelf(value) {
	if (typeof value !== "string") return value;
	try {
		const parsed = JSON.parse(value);
		return parsed && typeof parsed === "object" ? parsed : value;
	} catch {
		return value;
	}
}

export function prepareReviewerArguments(input) {
	if (!input || typeof input !== "object") return input;
	const args = { ...input };
	// Parse stringified JSON arrays (workaround for models that send arrays as strings)
	if (typeof args.options === "string") {
		try {
			const parsed = JSON.parse(args.options);
			if (Array.isArray(parsed)) args.options = parsed;
		} catch {
			/* not JSON */
		}
	}
	if (typeof args.names === "string") {
		try {
			const parsed = JSON.parse(args.names);
			if (Array.isArray(parsed)) args.names = parsed;
		} catch {
			/* not JSON */
		}
	}
	// reviewer_confirm's `artifact` is a Type.Object; some models send it as a
	// stringified JSON object, which fails validation BEFORE execute() and makes the
	// model loop. Coerce it back to an object so the gate proceeds.
	if (args.artifact !== undefined) args.artifact = jsonObjectOrSelf(args.artifact);
	return args;
}

// --- anti-bypass block lists (spec D4, verbatim from source L169-177) -----------
const FORBIDDEN = [
	/\btht\s+phase\s+(advance|reopen)\b/,
	/\btht\s+decision\s+add\b/,
	/\btht\s+cte\s+plan\b/,
];
const PROTECTED_FILES =
	/(review_decisions\.jsonl|session_manifest\.yaml|cte_plan\.json)/;
// The model orchestrates the workflow; it must never rewrite the gate/extension code
// itself. pi's write/edit tools are otherwise unrestricted, so a confused model can
// (and did) patch tht-gate.js mid-loop. Block any write under the extensions dir.
export const GATE_CODE_FILES = /\.pi[\\/]extensions[\\/]/;

// --- kickoff payloads (verbatim from source L184-212, load-bearing model prose) -
const NUOVA_DOMANDA_KICKOFF =
	"Istruzioni operative — nuova sessione ThothII (workflow human-in-the-middle: tu " +
	"orchestri, il reviewer decide, la CLI `tht` persiste; NON sei in modalita' autonoma).\n" +
	'1. Esegui `tht session new "<la domanda dell\'utente nel messaggio sopra>"` e annota ' +
	"l'id stampato nell'ultima riga.\n" +
	"2. Carica la skill leggendo il file con il tool `read`: `.pi/skills/tht-sessione/SKILL.md` " +
	"(NON come comando di shell ne' come `/skill:...`). Poi segui il suo workflow dalla Fase 1 " +
	"(Chiarimento), usando l'id di sessione in ogni comando `tht`.\n" +
	"Se la skill non si carica (per qualsiasi motivo): FERMATI. Non proseguire da solo, non " +
	"improvvisare analisi o query. Comunica al reviewer che la skill tht-sessione non e' " +
	"disponibile e attendi istruzioni.\n" +
	"Regole non negoziabili (valgono SEMPRE, anche senza la skill):\n" +
	"- Una domanda al reviewer per volta; attendi la sua risposta prima di proseguire.\n" +
	"- MAI promuovere, escludere, correggere o applicare alcunche' senza conferma esplicita.\n" +
	"- Le interazioni col reviewer passano dai tool reviewer_select/reviewer_decide/" +
	"reviewer_confirm (widget-descriptor); il reviewer invia testo libero prefissando '!'. " +
	"NON eseguire mai `tht phase advance|reopen` ne' `tht decision add` da shell.\n" +
	"- Procedi una fase alla volta: a fine fase cedi il turno al reviewer, non incatenare le fasi.";

const NUOVA_DOMANDA_KICKOFF_PROVIDED = (sessionId) =>
	"Istruzioni operative — sessione ThothII (workflow human-in-the-middle). " +
	`La sessione è GIÀ creata con id \`${sessionId}\`: usalo in OGNI comando \`tht\`. ` +
	"NON creare una nuova sessione.\n" +
	"1. Carica la skill leggendo `.pi/skills/tht-sessione/SKILL.md` con il tool `read`, " +
	`poi segui il workflow dalla Fase 1 usando l'id \`${sessionId}\`.\n` +
	"Regole non negoziabili: una domanda al reviewer per volta; mai promuovere/escludere/" +
	"correggere senza conferma; le interazioni passano dai tool reviewer_*; testo libero col prefisso '!'. " +
	"MAI `tht phase advance|reopen` né `tht decision add` da shell.";

const RIPRENDI_KICKOFF =
	"Istruzioni operative — ripresa di una sessione ThothII esistente (id nel messaggio sopra).\n" +
	"1. Esegui `tht session show <id>` e leggi: stato, domanda, decisioni registrate, presenza " +
	"di schema_linking.json.\n" +
	"2. Carica la skill leggendo `.pi/skills/tht-sessione/SKILL.md` con il tool `read` (non come " +
	"comando di shell ne' `/skill:...`).\n" +
	"3. Determina l'ultima fase completata dai fatti persistiti (le decisioni sono la verita': " +
	"cio' che non e' registrato non e' avvenuto) e riprendi da li'.\n" +
	"Esegui i passi 1-2 ORA, in QUESTO stesso turno, chiamando subito i tool (`bash` per " +
	"`tht session show`, `read` per la skill): NON limitarti a dichiarare l'intenzione e NON " +
	"terminare il turno prima di aver chiamato i tool.\n" +
	"Valgono le stesse regole non negoziabili: una domanda per volta, conferma esplicita, tool " +
	"reviewer_*, niente phase advance/reopen o decision add da shell, una fase alla volta.";

// Recovery hint shown when `tht phase advance` refuses with exit 5 (gate not satisfied).
const PHASE_RECOVERY =
	"Completa i prerequisiti della fase (decisioni/artefatti) e riprova.";

// --- helpers (verbatim from source) -------------------------------------------

function textResult(text) {
	return { content: [{ type: "text", text }], details: {} };
}

// Load THT_* env vars from .env (project root = ctx.cwd).
function loadEnvFromDotenv(ctx) {
	const fs = require("node:fs");
	const path = require("node:path");
	const envPath = path.join(ctx.cwd, ".env");
	try {
		const raw = fs.readFileSync(envPath, "utf8");
		for (const line of raw.split("\n")) {
			const trimmed = line.trim();
			if (!trimmed || trimmed.startsWith("#")) continue;
			const idx = trimmed.indexOf("=");
			if (idx === -1) continue;
			const key = trimmed.slice(0, idx).trim();
			const value = trimmed.slice(idx + 1).trim();
			if (key.startsWith("THT_") || key.startsWith("PSD_")) {
				process.env[key] = value;
			}
		}
	} catch {
		// .env not found or unreadable — proceed with existing env.
	}
}

// Single chokepoint for all CLI calls. cwd is the Pi project root (harness/).
function tht(ctx, args, input) {
	loadEnvFromDotenv(ctx);
	return execFileSync("tht", args, { cwd: ctx.cwd, encoding: "utf8", input });
}

// Runs a privileged tht call; converts any failure into an actionable textResult
// (never propagates a raw "Command failed" to the model).
function relayIfThtFails(ctx, args, recovery) {
	try {
		tht(ctx, args);
		return null;
	} catch (e) {
		const cliMsg = (e.stderr || e.message || String(e)).toString().trim();
		return textResult(`${cliMsg} ${recovery}`);
	}
}

// F2 single-source: workflow facts from `tht phase meta --json`. Cached per session.
// Replaces the source's mirrored PHASE_NAMES constant (which drifted to 7 entries)
// and the regex-parse of `tht phase show` text.
let _phaseMetaCache = null;
function phaseMeta(ctx) {
	if (_phaseMetaCache) return _phaseMetaCache;
	const raw = tht(ctx, ["phase", "meta", "--json"]);
	const meta = JSON.parse(raw);
	_phaseMetaCache = meta;
	return meta;
}
// Returns the workflow.yaml phase id (e.g. "F1"), not the descriptive name — this is
// what feeds the widget's `phase` field, which the frontend WorkflowBar matches against
// its own "F1".."F8" ids to light up the stepper pills.
function phaseId(ctx, num) {
	const meta = phaseMeta(ctx);
	const p = meta.phases.find((x) => x.num === num);
	return p ? p.id : "?";
}
function currentPhase(ctx, session) {
	const out = tht(ctx, ["phase", "show", "--session", session]);
	const m = out.match(/Fase corrente:\s*(\d+)/);
	return m ? parseInt(m[1], 10) : 1;
}

// tht phase advance --auto: exit 6 = not ready / needs human (silent no-op), others propagated.
// Used for the fire-and-forget auto-advance of the auto phases (F2 memory, F6 cte) after a
// reviewer_decide: it only advances when the phase is auto-eligible (zero substantive
// decisions + prerequisites met), otherwise the CLI exits 6 and we no-op.
function advanceIfReady(ctx, session) {
	try {
		tht(ctx, ["phase", "advance", "--auto", "--session", session]);
		return { advanced: true };
	} catch (e) {
		if (e.status === 6) return { advanced: false };
		return {
			advanced: false,
			error: (e.stderr || e.message || String(e)).toString().trim(),
		};
	}
}

// --- widget emission + wait — usa l'API UI NATIVA di Pi (ctx.ui.input) --------
//
// emitAndWait(ctx, descriptor) sends the widget-descriptor as JSON in the `title`
// of ctx.ui.input and awaits the response as a parsed string value. No ctx.sendRaw,
// no pi.on("extension_ui_response"): Pi routes the response via pendingExtensionRequests.
//
// The no-limbo invariant: undefined/null/invalid-JSON/control:"cancel" are NEVER
// accepted as a final answer — the widget is re-presented. Real escapes (Back/Exit/Other)
// are always present as selectable options in the descriptor, so cancel has no
// legitimate meaning.
// The frontend's reviewer widgets always carry the picked option(s) in a `choices`
// ARRAY (SelectWidget/ArtifactGateWidget send `choices: [optionId]`). Single-pick
// handlers read the first element; `choice` (singular) is accepted as a legacy form.
export function selectedChoice(resp) {
	if (Array.isArray(resp?.choices)) return resp.choices[0];
	return resp?.choice;
}

// Builds the `tht decision add` argv for one decision payload {type, subject, detail?,
// rationale?}. Shared by reviewer_decide (multiselect) and reviewer_select (auto-confirm).
export function decisionAddArgs(session, d) {
	const args = [
		"decision",
		"add",
		"--session",
		session,
		"--type",
		d.type,
		"--subject",
		d.subject,
	];
	if (d.detail) args.push("--detail", d.detail);
	if (d.rationale) args.push("--rationale", d.rationale);
	return args;
}

// Workstream F: classifies a reviewer_select response into the action the gate takes.
// A concrete choice that carries a `decision` payload auto-confirms (persist directly,
// no second gate); a bare choice stays ask-only; back/exit/Other never persist.
export function resolveSelectOutcome(opts, resp) {
	if (resp?.control === "freetext") return { kind: "freetext", text: resp.text };
	if (resp?.control === "back") return { kind: "back" };
	if (resp?.control === "exit") return { kind: "exit" };
	const choice = selectedChoice(resp);
	const option = (opts || []).find((o) => o.id === choice) || null;
	if (option && option.decision)
		return { kind: "decision", option, decision: option.decision };
	return { kind: "choice", option, choice };
}

// Classifies a reviewer_confirm response. Advance happens ONLY on an explicit
// "approve" choice; a bare/unknown response resolves to {kind:"unknown"} and is
// re-presented (never an accidental approve). freetext is actionable feedback,
// distinct from an explicit "reject".
export function resolveConfirmOutcome(resp) {
	if (resp?.control === "freetext") return { kind: "freetext", text: resp.text };
	if (resp?.control === "back") return { kind: "back" };
	if (resp?.control === "exit") return { kind: "exit" };
	const choice = selectedChoice(resp);
	if (choice === "approve") return { kind: "approve" };
	if (choice === "reject") return { kind: "reject" };
	return { kind: "unknown", choice };
}

// True when a reviewer_decide has no merito options but is allowed to close empty
// and advance (the empty memory phase F2). The gate then shows an info notice and
// auto-advances instead of presenting an empty checklist.
export function shouldSkipEmptyDecide({ meritCount, allowEmpty, advance }) {
	return meritCount === 0 && !!allowEmpty && !!advance;
}

export async function emitAndWait(ctx, descriptor) {
	for (;;) {
		const value = await ctx.ui.input(JSON.stringify(descriptor), "");
		if (value === undefined || value === null) {
			await reLoop(ctx);
			continue;
		}
		let resp;
		try {
			resp = JSON.parse(value);
		} catch {
			await reLoop(ctx);
			continue;
		}
		if (resp && resp.control !== "cancel" && resp.id === descriptor.id)
			return resp;
		await reLoop(ctx);
	}
}

async function reLoop(ctx) {
	// TUI-only: "Esc"/terminal navigation has no meaning in RPC (the browser
	// renders widget buttons). Guard on ctx.mode, NOT ctx.hasUI — on pi >=0.80
	// hasUI is true in RPC too, so this warning would leak to the frontend.
	if (ctx.mode === "tui")
		await ctx.ui.notify(
			"Esc non chiude il gate: usa Torna indietro / Esci / Altro dalle opzioni.",
			"warning",
		);
}

// --- the extension ------------------------------------------------------------

export default function (pi) {
	let lockActive = false;
	let lastSteered = false;
	let pendingKickoff = null;
	let activeSessionId = null;

	// 1) ANTI-BYPASS tool_call hook (spec D4, verbatim). Blocks direct phase/decision
	//    calls and writes to protected files so the reviewer cannot bypass the gate.
	pi.on("tool_call", (event) => {
		if (event.toolName === "bash") {
			const cmd = event.input?.command ?? "";
			// tht session finalize: legit session-close path -- unlock and let through.
			if (/\btht\s+session\s+finalize\b/.test(cmd)) {
				lockActive = false;
				lastSteered = false;
				return;
			}
			if (FORBIDDEN.some((re) => re.test(cmd))) {
				return {
					block: true,
					reason:
						"Avanzamento/ritorno di fase e registrazione decisioni passano dal " +
						"reviewer: usa i tool reviewer_confirm / reviewer_select.",
				};
			}
		}
		if (event.toolName === "write" || event.toolName === "edit") {
			const path = event.input?.path ?? event.input?.file_path ?? "";
			if (GATE_CODE_FILES.test(path)) {
				return {
					block: true,
					reason:
						"Il codice del gate (.pi/extensions) non va modificato: sei l'orchestratore " +
						"del workflow, non uno sviluppatore del gate. Usa i tool del gate.",
				};
			}
			if (PROTECTED_FILES.test(path)) {
				return {
					block: true,
					reason:
						"Questo file di stato e' gestito dal gate: non scriverlo direttamente.",
				};
			}
		}
	});

	// 2) INPUT hook: workflow entry detection + free-input block + `!` steer channel.
	pi.on("input", async (event, ctx) => {
		const raw = (event.text ?? "").trimStart();
		// entry detection: workflow-start funziona sia da TUI sia da comando RPC `prompt`.
		if (/^\/(nuova-domanda|riprendi-sessione)\b/.test(raw)) {
			// NOTE: the source runs an ollama preflight here; ThothII defers embeddings
			// readiness to the session's first vector op. Entry detection only:
			lockActive = true;
			lastSteered = false;
			pendingKickoff = /^\/nuova-domanda\b/.test(raw)
				? process.env.THT_SESSION
					? NUOVA_DOMANDA_KICKOFF_PROVIDED(process.env.THT_SESSION)
					: NUOVA_DOMANDA_KICKOFF
				: RIPRENDI_KICKOFF;
		}
		// free-input block: attivo quando il lock è su, per qualsiasi input utente (non solo interattivo).
		if (!lockActive) return { action: "continue" };
		const trimmed = (event.text ?? "").trimStart();
		if (trimmed.length === 0) return { action: "continue" };
		if (trimmed.startsWith("/")) return { action: "continue" };
		// `!`-prefixed free text -> forward to the model (the one sanctioned steer channel).
		if (trimmed.startsWith("!"))
			return { action: "transform", text: trimmed.slice(1).trimStart() };
		if (ctx.mode === "tui") {
			await ctx.ui.notify(
				"Durante la sessione rispondi con i widget del gate. " +
					"Per inviare testo libero al modello inizia la riga con '!'.",
				"warning",
			);
		}
		return { action: "handled" };
	});

	// 3) BEFORE_AGENT_START: one-shot kickoff injection (appends the operational
	//    instructions to the system prompt on the turn that starts/resumes a session).
	pi.on("before_agent_start", (event) => {
		if (!pendingKickoff) return undefined;
		const inject = pendingKickoff;
		pendingKickoff = null;
		return { systemPrompt: `${event.systemPrompt}\n\n${inject}` };
	});

	// 4) SESSION_START: reset all session-scoped state.
	pi.on("session_start", (_event, _ctx) => {
		lockActive = false;
		lastSteered = false;
		pendingKickoff = null;
		activeSessionId = null;
		_phaseMetaCache = null;
	});

	// 5) AGENT_END prose safety net: if the model emits prose instead of a reviewer_*
	//    tool call (and the lock is active), nudge it back to the gate tools.
	pi.on("agent_end", async (event) => {
		if (!lockActive) return;
		const msgs = event.messages ?? [];
		const last = msgs[msgs.length - 1];
		const isProse =
			last &&
			last.role === "assistant" &&
			Array.isArray(last.content) &&
			last.content.some(
				(b) => b.type === "text" && (b.text ?? "").trim().length > 0,
			) &&
			!last.content.some((b) => b.type === "toolCall");
		if (isProse && !lastSteered) {
			lastSteered = true;
			await pi.sendUserMessage(
				"Le risposte del reviewer arrivano solo dai widget del gate. Riproponi la " +
					"richiesta come reviewer_select (opzioni + 'Altro'), non in chat.",
				{ deliverAs: "followUp" },
			);
		}
	});

	// --- the four reviewer tools (widget-descriptor emit + await) ---------------

	pi.registerTool({
		name: "reviewer_select",
		label: "Domanda a scelta (reviewer)",
		description:
			"Pone una domanda a scelta singola al reviewer via un widget select. Le opzioni di " +
			"controllo (Altro/Torna indietro/Esci) sono sempre presenti. La scelta su un'opzione " +
			"concreta È la conferma: se quell'opzione porta un payload `decision` {type, subject, " +
			"detail?, rationale?}, la decisione viene PERSISTITA direttamente (tht decision add) " +
			"senza un secondo gate di conferma; se p.advance è vero, tenta tht phase advance --if-ready. " +
			"Un'opzione SENZA `decision` resta solo-richiesta (non persiste). Altro/Torna indietro/Esci " +
			"non persistono mai e tornano come testo da gestire.",
		parameters: Type.Object({
			session: Type.String({
				description: "Id sessione (per determinare la fase).",
			}),
			title: Type.String(),
			options: Type.Array(
				Type.Object({
					id: Type.String(),
					label: Type.String(),
					decision: Type.Optional(
						Type.Object({
							type: Type.String(),
							subject: Type.String(),
							detail: Type.Optional(Type.String()),
							rationale: Type.Optional(Type.String()),
						}),
					),
					recommended: Type.Optional(Type.Boolean()),
				}),
			),
			intro: Type.Optional(Type.String()),
			advance: Type.Optional(Type.Boolean()),
		}),
		prepareArguments: prepareReviewerArguments,
		async execute(_id, params, _signal, _onUpdate, ctx) {
			lockActive = true;
			const { session, title, options: opts, intro, advance } = params;
			const phase = phaseId(ctx, currentPhase(ctx, session));
			const recommended = opts.find((o) => o.recommended)?.id ?? null;

			const widget = buildSelectRequest({
				id: `u${Date.now()}`,
				phase,
				title,
				intro: intro ?? null,
				recommended,
				options: opts
					.filter((o) => !isReserved(o.label))
					.map((o) => ({ id: o.id, label: o.label })),
			});
			const resp = await emitAndWait(ctx, widget);
			const outcome = resolveSelectOutcome(opts, resp);
			// control responses (back/exit/other) are surfaced as text for the model to act on.
			if (outcome.kind === "freetext")
				return textResult(`Altro (reviewer): ${outcome.text}`);
			if (outcome.kind === "back")
				return textResult("Il reviewer vuole tornare indietro.");
			if (outcome.kind === "exit")
				return textResult("Il reviewer vuole uscire.");
			// concrete choice carrying a decision -> auto-confirm: persist directly, no second gate.
			if (outcome.kind === "decision") {
				const err = relayIfThtFails(
					ctx,
					decisionAddArgs(session, outcome.decision),
					"",
				);
				if (err) return err;
				if (advance) advanceIfReady(ctx, session);
				return textResult(
					`Decisione registrata (${outcome.decision.type}): ${outcome.option.label}.`,
				);
			}
			// bare choice (no decision payload) -> ask-only, non-persisting.
			return textResult(
				`Scelta del reviewer: ${outcome.option ? outcome.option.label : outcome.choice}`,
			);
		},
	});

	pi.registerTool({
		name: "reviewer_decide",
		label: "Decisione di merito (reviewer)",
		description:
			"Pone una decisione di merito al reviewer via widget multiselect e PERSISTE le " +
			"scelte (tht decision add). Ogni opzione porta un payload decision {type, subject, " +
			"detail, rationale}. Dopo la conferma, se p.advance e' vero tenta tht phase advance --if-ready.",
		parameters: Type.Object({
			session: Type.String(),
			title: Type.String(),
			options: Type.Array(
				Type.Object({
					id: Type.String(),
					label: Type.String(),
					decision: Type.Object({
						type: Type.String(),
						subject: Type.String(),
						detail: Type.Optional(Type.String()),
						rationale: Type.Optional(Type.String()),
					}),
					recommended: Type.Optional(Type.Boolean()),
				}),
			),
			allow_empty: Type.Optional(Type.Boolean()),
			advance: Type.Optional(Type.Boolean()),
		}),
		prepareArguments: prepareReviewerArguments,
		async execute(_id, params, _signal, _onUpdate, ctx) {
			lockActive = true;
			const { session, title, options: opts, advance } = params;
			const phase = phaseId(ctx, currentPhase(ctx, session));
			const toAdd = [];
			const meritOptions = opts
				.filter((o) => !isReserved(o.label))
				.map((o) => ({ id: o.id, label: o.label }));
			if (shouldSkipEmptyDecide({ meritCount: meritOptions.length, allowEmpty: params.allow_empty ?? false, advance })) {
				await ctx.ui.notify(
					"Nessuna memory riutilizzabile per questa domanda — passo alla fase successiva.",
					"info",
				);
				advanceIfReady(ctx, session);
				return textResult(
					"Fase memoria vuota: nessuna decisione da registrare, avanzamento automatico alla fase successiva.",
				);
			}
			const widget = buildMultiselectRequest({
				id: `u${Date.now()}`,
				phase,
				title,
				allowEmpty: params.allow_empty ?? false,
				options: meritOptions,
				recommended: opts.find((o) => o.recommended)?.id ?? null,
			});
			const resp = await emitAndWait(ctx, widget);
			if (resp.control === "freetext") {
				return textResult(
					`Altro (reviewer): ${resp.text}. Riformula la proposta tenendo conto.`,
				);
			}
			if (resp.control === "back")
				return textResult("Il reviewer vuole tornare indietro.");
			if (resp.control === "exit")
				return textResult("Il reviewer vuole uscire.");
			const chosen = opts.filter((o) => (resp.choices ?? []).includes(o.id));
			for (const c of chosen) {
				const d = c.decision;
				const err = relayIfThtFails(ctx, decisionAddArgs(session, d), "");
				if (err) return err;
				toAdd.push(d);
			}
			if (advance) advanceIfReady(ctx, session);
			return textResult(
				toAdd.length
					? `Registrate ${toAdd.length} decisioni: ${toAdd.map((d) => d.type).join(", ")}.`
					: "Nessuna decisione registrata (il reviewer non ha selezionato opzioni di merito).",
			);
		},
	});

	pi.registerTool({
		name: "reviewer_confirm",
		label: "Gate di avanzamento (reviewer)",
		description:
			"Checkpoint di fase/CTE/SQL: presenta un widget artifact-gate (artefatto + " +
			"Approva/Rifiuta/Altro) ed esegue l'azione privilegiata (tht phase advance, cte plan, " +
			"decision add sql_approved) solo su approvazione. kind: phase | cte_plan | cte_result | sql.",
		parameters: Type.Object({
			session: Type.String(),
			kind: Type.Union([
				Type.Literal("phase"),
				Type.Literal("cte_plan"),
				Type.Literal("cte_result"),
				Type.Literal("sql"),
			]),
			title: Type.String(),
			artifact: Type.Object({
				kind: Type.String(),
				data: Type.Any(),
				version: Type.Optional(Type.Number()),
			}),
			// kind:"cte_plan" only -- ordered list of CTE names to persist (tht cte plan --name).
			names: Type.Optional(Type.Array(Type.String())),
		}),
		prepareArguments: prepareReviewerArguments,
		async execute(_id, params, _signal, _onUpdate, ctx) {
			lockActive = true;
			const { session, kind, title, artifact } = params;
			const phase = phaseId(ctx, currentPhase(ctx, session));
			const widget = buildArtifactGate({
				id: `u${Date.now()}`,
				phase,
				title,
				artifact,
				action: { kind: "approve_reject", prompt: "Approvi o rifiuti?" },
			});
			let outcome;
			for (;;) {
				const resp = await emitAndWait(ctx, widget);
				outcome = resolveConfirmOutcome(resp);
				if (outcome.kind !== "unknown") break;
				await ctx.ui.notify("Scegli «Salva e procedi» o «Rifiuta».", "warning");
			}
			if (outcome.kind === "freetext")
				return textResult(
					`Altro (reviewer): ${outcome.text}. Valuta e agisci, poi ri-presenta il gate.`,
				);
			if (outcome.kind === "reject")
				return textResult("Rifiutato: rivedi e riprova.");
			if (outcome.kind === "back")
				return textResult("Il reviewer vuole tornare indietro.");
			if (outcome.kind === "exit")
				return textResult("Il reviewer vuole uscire.");
			// outcome.kind === "approve" -> execute the privileged action via the CLI.
			if (kind === "phase") {
				// Explicit human approval: advance unconditionally except for unmet
				// prerequisites. Plain `phase advance` (no --auto) enforces advance_problems
				// and exits 6 with the missing items, which relayIfThtFails surfaces.
				const err = relayIfThtFails(
					ctx,
					["phase", "advance", "--session", session],
					PHASE_RECOVERY,
				);
				if (err) return err;
				return textResult(`Fase approvata (sessione ${session}).`);
			}
			if (kind === "cte_plan") {
				// The CTE plan is the ordered list of CTE names; the model passes them in
				// params.names (tht cte plan requires at least one --name).
				const names = Array.isArray(params.names) ? params.names : [];
				if (names.length === 0) {
					return textResult(
						"Nessun nome CTE fornito: il piano CTE richiede l'elenco ordinato dei CTE " +
							"(parametro names di reviewer_confirm).",
					);
				}
				const planArgs = ["cte", "plan", "--session", session];
				for (const n of names) planArgs.push("--name", n);
				const err = relayIfThtFails(ctx, planArgs, "");
				if (err) return err;
				return textResult(
					`CTE plan approvato (${names.length} CTE, sessione ${session}).`,
				);
			}
			if (kind === "cte_result") {
				// The CTE under review is always next_cte (plan order is enforced by
				// `tht cte test`). Approve it BY NAME: `cte_approved` keys on the CTE
				// name (phase.approved_ctes / next_cte); a `phase:N` subject is rejected
				// by `decision add` (exit 5) and never satisfies F6's advance prereq.
				const cteName = tht(ctx, [
					"cte",
					"next",
					"--session",
					session,
				]).trim();
				if (!cteName) {
					return textResult(
						`Nessun CTE in attesa di approvazione (sessione ${session}).`,
					);
				}
				const err = relayIfThtFails(
					ctx,
					["decision", "add", "--session", session, "--type", "cte_approved", "--subject", cteName],
					"",
				);
				if (err) return err;
				return textResult(`CTE '${cteName}' approvato (sessione ${session}).`);
			}
			if (kind === "sql") {
				const err = relayIfThtFails(
					ctx,
					[
						"decision",
						"add",
						"--session",
						session,
						"--type",
						"sql_approved",
						"--subject",
						`phase:${currentPhase(ctx, session)}`,
					],
					"",
				);
				if (err) return err;
				return textResult(`SQL approvato (sessione ${session}).`);
			}
			return textResult(`Approvato (kind=${kind}, sessione ${session}).`);
		},
	});

	pi.registerTool({
		name: "rewrite_question",
		label: "Riscrittura domanda (deterministica)",
		description:
			"Scrive deterministicamente question.md via tht session set-question (evita il tool " +
			"di edit unreliable). assumptions puo' essere array o stringa JSON.",
		parameters: Type.Object({
			session: Type.String(),
			question: Type.String(),
			assumptions: Type.Optional(Type.Any()),
		}),
		async execute(_id, params, _signal, _onUpdate, ctx) {
			lockActive = true;
			const { session, question, assumptions } = params;
			let assumps = assumptions;
			if (typeof assumps === "string") {
				try {
					assumps = JSON.parse(assumps);
				} catch {
					assumps = [assumps];
				}
			}
			// `tht session set-question` takes the session id as a positional argument
			// (the `session` command group uses positional ids, unlike phase/cte/decision
			// which use --session).
			const args = ["session", "set-question", session, "--question", question];
			if (Array.isArray(assumps)) {
				for (const a of assumps) args.push("--assumption", String(a));
			}
			const err = relayIfThtFails(ctx, args, "");
			if (err) return err;
			return textResult(`Domanda riscritta per la sessione ${session}.`);
		},
	});

	pi.registerTool({
		name: "write_schema_linking",
		label: "Scrittura schema_linking.json (validata)",
		description:
			"Scrive deterministicamente schema_linking.json validandolo contro il modello " +
			"SchemaLinking via tht session set-schema-linking (evita edit a mano e la " +
			"validazione manuale). schema_linking e' l'oggetto JSON completo: {question, " +
			"candidates:[{kind:'table'|'column', name, evidence?, decision?}], joins:[{from, " +
			"to, source?}], excluded:[{kind, name}], open_questions:[], concept_formulas:[]}.",
		parameters: Type.Object({
			session: Type.String(),
			schema_linking: Type.Any(),
		}),
		async execute(_id, params, _signal, _onUpdate, ctx) {
			lockActive = true;
			const { session } = params;
			// schema_linking is Type.Any(): a stringified JSON object passes validation
			// but would be double-encoded here and rejected by the CLI. Normalize first.
			const schema_linking = jsonObjectOrSelf(params.schema_linking);
			try {
				tht(
					ctx,
					["session", "set-schema-linking", session, "--file", "-"],
					JSON.stringify(schema_linking),
				);
				return textResult(
					`schema_linking.json scritto e validato per la sessione ${session}.`,
				);
			} catch (e) {
				const cliMsg = (e.stderr || e.message || String(e)).toString().trim();
				return textResult(`${cliMsg} Correggi schema_linking e riprova.`);
			}
		},
	});

	// --- slash command: /torna [session_id] [N] (rollback to a previous phase) --
	pi.registerCommand("torna", {
		description:
			"Torna a una fase precedente: /torna <session_id> [N] (default: un passo).",
		handler: async (args, ctx) => {
			const parts = args.trim().split(/\s+/).filter(Boolean);
			const sessionId =
				parts.length >= 2
					? parts[0]
					: parts.length === 1 && /^\d/.test(parts[0])
						? undefined
						: parts[0];
			const sid = sessionId ?? activeSessionId ?? process.env.THT_SESSION;
			if (!sid) {
				await ctx.ui.notify("Uso: /torna <session_id> [N]", "warning");
				return;
			}
			const cur = currentPhase(ctx, sid);
			const targetArg = parts.find((x) => /^\d+$/.test(x));
			const target = targetArg ? parseInt(targetArg, 10) : cur - 1;
			if (target < 1 || target >= cur) {
				await ctx.ui.notify(
					`Target non valido (fase corrente ${cur}).`,
					"warning",
				);
				return;
			}
			tht(ctx, [
				"phase",
				"reopen",
				"--session",
				sid,
				"--phase",
				String(target),
			]);
			await pi.sendUserMessage(
				`Ho riaperto la Fase ${target} della sessione ${sid}. Riprendi il protocollo da quella fase.`,
				{ deliverAs: "followUp" },
			);
		},
	});
}