@pi-archimedes/sudo 2.13.0 → 2.14.0

package/README.md

@@ -29,6 +29,7 @@ After installing Pi, choose one installation command above, then `cd` into your
 ## What you get
 
 - **`sudo_exec` tool** — runs a privileged command via `sudo -S`, showing the exact command and a human-readable **reason** for confirmation before any credential prompt appears. A declined confirmation means nothing runs and no password is requested.
+- **Optional quieter confirmation** — `confirmWhenCached: false` skips the per-command confirmation while a credential is already cached, so an approved credential window is not interrupted by one dialog per privileged step. Off by default, and a skipped run says so in its own output — the first line of the tool result is `[sudo] confirmation skipped …`, so the terminal, the transcript and the model all see that nobody confirmed it ([ADR 0033](https://github.com/archimedes-codes/pi-archimedes/blob/main/docs/decisions/0033-sudo-confirmation-while-cached.md)).
 - **Masked password prompt** — the password is typed into a masked UI and passed to sudo via stdin only. It is never in argv, environment variables, command logs, or the LLM context.
 - **Defensive output scrubbing** — command output lines that contain the password are redacted before they reach the tool result. That is a literal-substring scrub: it catches common cases, and it is **not** universal leak protection.
 - **Credential cache** — a single in-memory cache with a TTL (15 minutes by default, `ttlMs`); cleared on authentication failure, at `session_start`/`session_shutdown`, and by `/sudo forget`.
@@ -70,13 +71,30 @@ The guard is a **heuristic with accepted residual bypasses** documented in the [
 |---------|------|---------|-------------|
 | `ttlMs` | number | `900000` | Password cache TTL in milliseconds (default 15 minutes) |
 | `defaultTimeoutMs` | number | `120000` | `sudo_exec` default command timeout in milliseconds (default 120 seconds) |
+| `confirmWhenCached` | boolean | `true` | Ask for confirmation before every `sudo_exec`, even with a cached credential. Set to `false` to confirm only when a password will be requested — that is, whenever the credential cache is empty — and skip it for a cached credential; the skipped run then starts its output with the `[sudo] confirmation skipped` marker and sets `confirmationSkipped: true` in the details. Keep `ttlMs` short if you enable this: the cache, not the session, is what bounds unattended privileged runs ([ADR 0033](https://github.com/archimedes-codes/pi-archimedes/blob/main/docs/decisions/0033-sudo-confirmation-while-cached.md)) |
+
+### When the confirmation is skipped
+
+With `confirmWhenCached: false`, a privileged command whose credential is already cached runs without a confirmation dialog. What stays true:
+
+- A **cache miss** still confirms first and then asks for the password, so the run that creates the credential always has both a human click and a human password entry.
+- The **command and reason** stay in the tool call, so the transcript still records exactly what was run and why.
+- The run's own output starts with a line saying the confirmation was skipped, so a quiet run is visibly different from one you approved — in the terminal, in the transcript, and to the model. `details.confirmationSkipped` is the same fact for anything reading the session file.
+- `/sudo forget`, `session_shutdown`, `ttlMs`, and an authentication failure all close the cache and bring the confirmation back.
+- The window is per **process**, not per session: run more than one session in the same process — or a subordinate session inside it — and they share the cached credential, so that is the case to keep `ttlMs` short for ([ADR 0033](https://github.com/archimedes-codes/pi-archimedes/blob/main/docs/decisions/0033-sudo-confirmation-while-cached.md)).
 
 ### Credential handling when sudo retains no verifiable ticket
 
-On sudoers policies that retain no reusable credential ticket (e.g. `timestamp_timeout=0` with strict `Defaults`), an authenticated but failed command is indistinguishable from an authentication failure unless the ticket can be verified with `sudo -n -v`.
+An authenticated but failed command is indistinguishable from an authentication failure unless the credential can be verified independently, so the tool runs two probes after a command-level failure:
+
+1. **`sudo -n -v` (ticket probe)** — validates sudo's ticket, executes no program, needs no password.
+2. **`sudo -S -v` (password probe)** — validates the **cached password** via stdin, executes no program. It runs **only when the ticket probe is non-terminal**, which is exactly the case it answers: hosts where no ticket is ever replayable — `timestamp_timeout=0` / no-reuse `Defaults`, or a tty-keyed timestamp (`timestamp_type=tty`, Ubuntu's default) against a spawn with no controlling terminal. On those hosts the ticket probe fails **even for a correct password**, so without stage 2 every command-level failure would read as an unverifiable credential.
+
+Then:
 
 - A **recognized wrong password** (sudo's `incorrect password` output alongside its prompt) clears the credential **immediately**, on that failure.
-- The **two-strike rule** applies to **ambiguous** failures where the ticket probe cannot verify the credential: the first strike keeps the cached password (with a visible one-more-attempt warning), the second consecutive strike clears it and re-prompts. Success resets the streak, and transport failures don't count as strikes.
+- **Either probe succeeding** means the credential is fine and the command itself failed: the run is reported as an ordinary non-zero exit and any carried strike is reset.
+- The **two-strike rule** applies to **ambiguous** failures, i.e. both probes non-terminal: the first strike keeps the cached password (with a visible one-more-attempt warning), the second consecutive strike clears it and re-prompts. Success resets the streak, and transport failures don't count as strikes. A failed password probe is never treated as proof of a wrong password — only success is terminal — so a transient hiccup cannot discard a good credential.
 
 ## Part of the suite
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/sudo",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/archimedes-codes/pi-archimedes.git"
@@ -19,7 +19,7 @@
     "./guard": "./src/guard.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.13.0"
+    "@pi-archimedes/core": "2.14.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.99.0",

package/src/cache.ts

@@ -1,8 +1,12 @@
 /**
  * In-memory credential cache for sudo_exec (ADR 0010).
  *
- * A single credential at a time, kept ONLY in memory for the active session —
- * never written to disk or the OS keyring. Expired entries return null from
+ * A single credential at a time, kept ONLY in memory for the process — never
+ * written to disk or the OS keyring. pi caches an extension module per process
+ * and re-invokes the factory per session, so the one thing separating two
+ * sessions in a process is the unconditional session_start/session_shutdown
+ * clears in index.ts (ADR 0033's Consequences spell out what that means for a
+ * subordinate in-process session). Expired entries return null from
  * get() (triggering a re-prompt) but are not auto-cleared; clear() is called
  * on session_shutdown, /sudo forget, and auth failure to drop the password
  * from memory entirely. No host/user keying in v1.
@@ -54,5 +58,11 @@ export class CredentialCache {
 	}
 }
 
-/** Module-level singleton, recreated per session via clear() on session_start (Task 3 lifecycle). */
+/**
+ * Module-level singleton, process-scoped: pi caches an extension module per
+ * process, so this object outlives a session and is shared by any session in
+ * the same process. It is cleared — never recreated — by the `session_start` /
+ * `session_shutdown` handlers in index.ts (every session's, not just the one
+ * that filled it), plus `/sudo forget` and auth failure. See ADR 0033.
+ */
 export const credentialCache = new CredentialCache();

package/src/config.test.ts

@@ -27,8 +27,8 @@ describe("sudo config", () => {
 		store.saveCalls.length = 0;
 	});
 
-	it("exposes the shared defaults (15 min TTL, 120 s command timeout)", () => {
-		expect(DEFAULT_SUDO_CONFIG).toEqual({ ttlMs: 900000, defaultTimeoutMs: 120000 });
+	it("exposes the shared defaults (15 min TTL, 120 s command timeout, confirm while cached)", () => {
+		expect(DEFAULT_SUDO_CONFIG).toEqual({ ttlMs: 900000, defaultTimeoutMs: 120000, confirmWhenCached: true });
 	});
 
 	it("returns the defaults when no archimedes.sudo section exists", () => {
@@ -37,11 +37,18 @@ describe("sudo config", () => {
 
 	it("merges a partial archimedes.sudo section over the defaults", () => {
 		store.settings["archimedes.sudo"] = { ttlMs: 5000 };
-		expect(loadSudoConfig()).toEqual({ ttlMs: 5000, defaultTimeoutMs: 120000 });
+		expect(loadSudoConfig()).toEqual({ ttlMs: 5000, defaultTimeoutMs: 120000, confirmWhenCached: true });
+	});
+
+	it("keeps confirming while cached unless the user opts out", () => {
+		store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+		expect(loadSudoConfig().confirmWhenCached).toBe(false);
 	});
 
 	it("saveSudoConfig writes to the archimedes.sudo namespace", () => {
-		saveSudoConfig({ ttlMs: 1234, defaultTimeoutMs: 5678 });
-		expect(store.saveCalls).toEqual([{ namespace: "archimedes.sudo", config: { ttlMs: 1234, defaultTimeoutMs: 5678 } }]);
+		saveSudoConfig({ ttlMs: 1234, defaultTimeoutMs: 5678, confirmWhenCached: true });
+		expect(store.saveCalls).toEqual([
+			{ namespace: "archimedes.sudo", config: { ttlMs: 1234, defaultTimeoutMs: 5678, confirmWhenCached: true } },
+		]);
 	});
 });

package/src/config.ts

@@ -11,11 +11,21 @@ export interface SudoConfig {
 	ttlMs: number;
 	/** sudo_exec default command timeout in ms. Default 120 s. */
 	defaultTimeoutMs: number;
+	/**
+	 * Ask for confirmation before every `sudo_exec`, even when a credential is
+	 * already cached. Default `true` — the confirmation is the last human gate
+	 * once the password is cached (ADR 0010, ADR 0033). Set it to `false` to
+	 * confirm only on the runs that will ask for a password, i.e. the first one
+	 * while the credential cache is empty, and to accept that the agent can then
+	 * run privileged commands unattended for the rest of the cache TTL.
+	 */
+	confirmWhenCached: boolean;
 }
 
 export const DEFAULT_SUDO_CONFIG: SudoConfig = {
 	ttlMs: 900_000,
 	defaultTimeoutMs: 120_000,
+	confirmWhenCached: true,
 };
 
 export function loadSudoConfig(): SudoConfig {

package/src/index.ts

@@ -21,8 +21,10 @@ export function registerSudo(pi: ExtensionAPI, options?: { spawner?: SudoSpawner
 	// direct testing; handleBashToolCall only vets — it never mutates event.input.
 	pi.on("tool_call", (event) => handleBashToolCall(event));
 
-	// Session lifecycle: the credential is a module singleton and must never
-	// outlive a session — cleared at every session boundary (ADR 0010).
+	// Session lifecycle: the credential is a module singleton, so any session
+	// boundary clears it (ADR 0010) — every session's handlers, not just the one
+	// that filled it, which is what keeps an in-process subordinate session from
+	// inheriting it indefinitely (ADR 0033, Consequences).
 	pi.on("session_start", () => {
 		credentialCache.clear();
 	});

package/src/tool-declarations.test.ts

@@ -13,6 +13,7 @@ import { createSudoExecTool } from "./tool.js";
 
 const tool = createSudoExecTool() as unknown as {
   name: string;
+  description?: string;
   annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean };
   exposure?: string;
 };
@@ -37,3 +38,24 @@ describe("sudo_exec annotations", () => {
     expect(tool.exposure ?? "direct").toBe("direct");
   });
 });
+
+describe("sudo_exec description", () => {
+  // The description is handed to the model on every call, and it now carries the
+  // skip contract (ADR 0033): without a pin the wording drifts silently, which is
+  // how bullet 2 kept saying "for the session" after the cache became
+  // process-scoped.
+  const description = tool.description ?? "";
+
+  it("names the setting that skips the gate, so the model can explain the exception", () => {
+    expect(description).toContain("confirmWhenCached");
+  });
+
+  it("scopes the cache to the process, not the session", () => {
+    expect(description).toContain("cached in memory for the process");
+    expect(description).not.toContain("for the session");
+  });
+
+  it("still says the password is never exposed", () => {
+    expect(description).toContain("never exposed");
+  });
+});

package/src/tool.test.ts

@@ -32,7 +32,7 @@ vi.mock("@pi-archimedes/core/bridge", () => ({
 	getBridge: () => bridgeState,
 }));
 
-import { buildSudoArgv, createSudoExecTool, probeSudoTicket, scrubSecret } from "./tool.js";
+import { buildSudoArgv, CONFIRMATION_SKIPPED_MARKER, createSudoExecTool, probeSudoPassword, probeSudoTicket, scrubSecret } from "./tool.js";
 import type { SudoChild, SudoSpawner } from "./tool.js";
 import { credentialCache } from "./cache.js";
 
@@ -333,6 +333,292 @@ describe("sudo_exec tool", () => {
 		});
 	});
 
+	describe("confirmation while a credential is cached (ADR 0033)", () => {
+		// This block installs process.kill spies and turns the bridge on; reset both
+		// so the rest of the file keeps exercising the plain TUI path.
+		afterEach(() => {
+			vi.restoreAllMocks();
+			bridgeState.active = false;
+			bridgeState.confirm.mockReset();
+			bridgeState.password.mockReset();
+		});
+
+		it("confirms on every run by default, even with a cached credential, and the text stays byte-identical", async () => {
+			const { spawner } = makeFakeSpawner({ stdout: "ok\n", code: 0 });
+			const tool = createSudoExecTool({ spawner });
+			credentialCache.set("cachedpw", 60_000);
+			const spies = spiesNoPrompt();
+			const result = await run(tool, tuiCtxWithSpies(true, spies), { command: "id", reason: "whoami" });
+
+			expect(spies.confirmCalls).toHaveLength(1);
+			expect(spies.confirmCalls[0]?.message).toContain("id");
+			// the default path never carries the marker or the flag
+			expect((result.content[0] as { text: string }).text).toBe("ok\n");
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBeUndefined();
+		});
+
+		it("skips the confirmation for a cached credential when confirmWhenCached is false, in both channels", async () => {
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			const { spawner } = makeFakeSpawner({ stdout: "ok\n", code: 0 });
+			const tool = createSudoExecTool({ spawner });
+			credentialCache.set("cachedpw", 60_000);
+			const spies = spiesNoPrompt();
+			const result = await run(tool, tuiCtxWithSpies(true, spies), { command: "id", reason: "whoami" });
+
+			expect(spies.confirmCalls).toHaveLength(0); // no human click for a cached credential
+			expect(result.isError).toBeFalsy();
+			// the text is what the terminal and the model see; details is the session-file record
+			expect((result.content[0] as { text: string }).text).toBe(`${CONFIRMATION_SKIPPED_MARKER}\nok\n`);
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBe(true);
+		});
+
+		it("still confirms when the cache is empty, because that run is what asks for the password", async () => {
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			const { spawner } = makeFakeSpawner({ stdout: "ok\n", code: 0 });
+			const tool = createSudoExecTool({ spawner });
+			const spies = spiesNoPrompt();
+			const ui = {
+				confirm: (title: string, message: string) => {
+					spies.confirmCalls.push({ title, message });
+					return Promise.resolve(true);
+				},
+				// the masked prompt resolves "" = cancelled, so nothing runs
+				custom: (factory: unknown): Promise<string> => {
+					spies.customCalls.push(factory);
+					return Promise.resolve("");
+				},
+			};
+			const ctx = { mode: "tui", hasUI: true, cwd: "/tmp", ui } as unknown as ExtensionContext;
+			const result = await run(tool, ctx, { command: "id", reason: "whoami" });
+
+			expect(spies.confirmCalls).toHaveLength(1); // cache miss → the gate stays
+			expect((result.content[0] as { text: string }).text).toMatch(/password entry cancelled/i);
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBeUndefined();
+		});
+
+		it("marks a failed run that skipped the gate, and keeps the no-output case to the marker alone", async () => {
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			const { spawner } = makeFakeSpawner({ stdout: "", stderr: "boom\n", code: 7 });
+			const { authProbe, passwordProbe } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
+			credentialCache.set("cachedpw", 60_000);
+			const result = await run(tool, tuiCtxWithSpies(true, spiesNoPrompt()), { command: "false", reason: "check" });
+
+			expect(result.isError).toBe(true);
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBe(true);
+			expect((result.content[0] as { text: string }).text).toBe(CONFIRMATION_SKIPPED_MARKER);
+		});
+
+		it("a failing run on the default settings carries neither the marker nor the flag", async () => {
+			const { spawner } = makeFakeSpawner({ stdout: "", stderr: "boom\n", code: 7 });
+			const { authProbe, passwordProbe } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
+			credentialCache.set("cachedpw", 60_000);
+			const result = await run(tool, tuiCtxWithSpies(true, spiesNoPrompt()), { command: "false", reason: "check" });
+
+			expect(result.isError).toBe(true);
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBeUndefined();
+			expect((result.content[0] as { text: string }).text).toBe("");
+		});
+
+		it("marks a timed-out run that skipped the gate (kill path, not the command path)", async () => {
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			const { spawner, last } = makeFakeSpawner({ stderr: "", code: null, exitOn: "kill" });
+			vi.spyOn(process, "kill").mockImplementation((pid?: number) => {
+				if (pid === -4242) last.child.kill("SIGKILL");
+				return true;
+			});
+			const tool = createSudoExecTool({ spawner });
+			credentialCache.set("pw", 60_000);
+
+			const result = await run(tool, tuiCtxWithSpies(true, spiesNoPrompt()), { command: "sleep", reason: "test", timeoutMs: 10 });
+
+			expect(result.isError).toBe(true);
+			expect((result.details as { exitCode: number; confirmationSkipped?: boolean }).confirmationSkipped).toBe(true);
+			expect((result.content[0] as { text: string }).text.startsWith(CONFIRMATION_SKIPPED_MARKER)).toBe(true);
+		});
+
+		it("marks a transport failure that skipped the gate (spawner threw, no command ran)", async () => {
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			const tool = createSudoExecTool({
+				spawner: () => {
+					throw Object.assign(new Error("spawn sudo EACCES"), { code: "EACCES" });
+				},
+			});
+			credentialCache.set("pw", 60_000);
+
+			const result = await run(tool, tuiCtxWithSpies(true, spiesNoPrompt()), { command: "apt update", reason: "maintain" });
+
+			expect(result.isError).toBe(true);
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBe(true);
+			expect((result.content[0] as { text: string }).text.startsWith(CONFIRMATION_SKIPPED_MARKER)).toBe(true);
+		});
+
+		it("marks the ambiguous-credential paths too: strike 1 keeps the warning after the marker, strike 2 clears", async () => {
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			const { spawner } = makeFakeSpawner({ stdout: "", stderr: "boom\n", code: 1 });
+			const { authProbe, passwordProbe } = probeSpy(false, false, false); // both probes non-terminal
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
+			credentialCache.set("pw", 60_000);
+			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
+
+			const first = await run(tool, ctx, { command: "false", reason: "strike one" });
+			const firstText = (first.content[0] as { text: string }).text;
+			expect(firstText.startsWith(`${CONFIRMATION_SKIPPED_MARKER}\n`)).toBe(true);
+			expect(firstText).toMatch(/WARNING/); // the warning keeps its place at the end
+			expect((first.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBe(true);
+
+			const second = await run(tool, ctx, { command: "false", reason: "strike two" });
+			expect(credentialCache.get()).toBeNull(); // the second strike cleared the cache
+			expect((second.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBe(true);
+			expect((second.content[0] as { text: string }).text).toMatch(/authentication failed/i);
+		});
+
+		it("an EXPIRED credential does not authorise a gate-free run — the gate and the prompt come back", async () => {
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			credentialCache.set("stale", 1); // expires immediately
+			await new Promise((resolve) => setTimeout(resolve, 5));
+			const { spawner } = makeFakeSpawner({ stdout: "ok\n", code: 0 });
+			const tool = createSudoExecTool({ spawner });
+			const spies = spiesNoPrompt();
+			const ui = {
+				confirm: (title: string, message: string) => {
+					spies.confirmCalls.push({ title, message });
+					return Promise.resolve(true);
+				},
+				custom: (factory: unknown): Promise<string> => {
+					spies.customCalls.push(factory);
+					return Promise.resolve(""); // cancel the prompt: nothing runs
+				},
+			};
+			const ctx = { mode: "tui", hasUI: true, cwd: "/tmp", ui } as unknown as ExtensionContext;
+
+			const result = await run(tool, ctx, { command: "id", reason: "whoami" });
+
+			// get() is expiry-aware, so an expired entry reads as "no credential"
+			expect(spies.confirmCalls).toHaveLength(1);
+			expect((result.content[0] as { text: string }).text).toMatch(/password entry cancelled/i);
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBeUndefined();
+		});
+
+		it("re-reads the cache after the dialog: a credential cleared while the human was deciding is not used", async () => {
+			// The hoist of the cache read above the gate is ADR 0033's whole structural
+			// change, but the pre-dialog read only decides whether a dialog exists. The
+			// read that arms the run has to happen AFTER the awaited dialog, or whatever
+			// lands during it (`/sudo forget`, another session's `session_start`, the TTL
+			// elapsing) is silently dropped and a revoked password reaches `sudo -S`.
+			const { spawner, last } = makeFakeSpawner({ stdout: "ok\n", code: 0 });
+			const tool = createSudoExecTool({ spawner });
+			credentialCache.set("STALE-PASSWORD", 60_000);
+			const spies = spiesNoPrompt();
+			const ui = {
+				confirm: (title: string, message: string) => {
+					spies.confirmCalls.push({ title, message });
+					credentialCache.clear(); // the human runs /sudo forget while the dialog is open
+					return Promise.resolve(true);
+				},
+				custom: (factory: unknown): Promise<string> => {
+					spies.customCalls.push(factory);
+					return Promise.resolve("FRESH-PASSWORD");
+				},
+			};
+			const ctx = { mode: "tui", hasUI: true, cwd: "/tmp", ui } as unknown as ExtensionContext;
+
+			const result = await run(tool, ctx, { command: "id", reason: "whoami" });
+
+			expect(spies.confirmCalls).toHaveLength(1);
+			expect(spies.customCalls).toHaveLength(1); // re-prompted, exactly as before the hoist
+			expect(last.child.stdin.written.join("")).toBe("FRESH-PASSWORD\n");
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBeUndefined();
+		});
+
+		it("honours the same window when the entry expires during the dialog, not only before the call", async () => {
+			const { spawner, last } = makeFakeSpawner({ stdout: "ok\n", code: 0 });
+			const tool = createSudoExecTool({ spawner });
+			credentialCache.set("STALE-PASSWORD", 20); // live at the pre-dialog read, dead after the wait
+			const spies = spiesNoPrompt();
+			const ui = {
+				confirm: async (title: string, message: string) => {
+					spies.confirmCalls.push({ title, message });
+					await new Promise((resolve) => setTimeout(resolve, 30));
+					return true;
+				},
+				custom: (factory: unknown): Promise<string> => {
+					spies.customCalls.push(factory);
+					return Promise.resolve("FRESH-PASSWORD");
+				},
+			};
+			const ctx = { mode: "tui", hasUI: true, cwd: "/tmp", ui } as unknown as ExtensionContext;
+
+			const result = await run(tool, ctx, { command: "id", reason: "whoami" });
+
+			expect(spies.customCalls).toHaveLength(1);
+			expect(last.child.stdin.written.join("")).toBe("FRESH-PASSWORD\n");
+			expect(result.isError).toBeFalsy();
+		});
+
+		it("marks the English auth-failure fast path too — the one gated() funnel with no skip-path coverage", async () => {
+			// A wrong-password run that skipped the gate is the result a reader most
+			// needs to see was unconfirmed, and the English signature path is the only
+			// gated() return the rest of the suite never reaches with the skip on.
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			const { spawner } = makeFakeSpawner({
+				stderr: "[sudo] password for daniel: \nsorry, try again.\n3 incorrect password attempts\n",
+				code: 1,
+			});
+			const tool = createSudoExecTool({ spawner });
+			credentialCache.set("cachedpw", 60_000);
+			const spies = spiesNoPrompt();
+
+			const result = await run(tool, tuiCtxWithSpies(true, spies), { command: "reboot", reason: "maintain" });
+
+			expect(spies.confirmCalls).toHaveLength(0); // the skip path, not the confirm path
+			expect(result.isError).toBe(true);
+			const text = (result.content[0] as { text: string }).text;
+			expect(text.startsWith(`${CONFIRMATION_SKIPPED_MARKER}\n`)).toBe(true);
+			expect(text).toMatch(/authentication failed \(incorrect password\)/i);
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBe(true);
+		});
+
+		it("keeps the unverified warning AFTER stdout, not merely somewhere in the text", async () => {
+			// With stdout empty, marker-then-warning and warning-then-marker are
+			// byte-identical, so the existing strike-1 case cannot pin the order. One
+			// line of stdout makes the two orderings distinguishable.
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			const { spawner } = makeFakeSpawner({ stdout: "partial\n", stderr: "boom\n", code: 1 });
+			const { authProbe, passwordProbe } = probeSpy(false, false, false); // both probes non-terminal
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
+			credentialCache.set("pw", 60_000);
+
+			const result = await run(tool, tuiCtxWithSpies(true, spiesNoPrompt()), { command: "false", reason: "strike one" });
+
+			const text = (result.content[0] as { text: string }).text;
+			expect(text.startsWith(`${CONFIRMATION_SKIPPED_MARKER}\n`)).toBe(true); // marker first
+			expect(text.indexOf("partial\n")).toBeGreaterThan(text.indexOf(CONFIRMATION_SKIPPED_MARKER));
+			expect(text.indexOf("(WARNING:")).toBeGreaterThan(text.indexOf("partial\n")); // warning last
+			expect((result.details as { error?: string }).error).toMatch(/— WARNING:/);
+		});
+
+		it("applies the same rule in bridge mode: no Client confirm, and both channels still say so", async () => {
+			store.settings["archimedes.sudo"] = { confirmWhenCached: false };
+			bridgeState.active = true;
+			const { spawner } = makeFakeSpawner({ stdout: "ok\n", code: 0 });
+			const tool = createSudoExecTool({ spawner });
+			credentialCache.set("cachedpw", 60_000);
+			const ui = { confirm: vi.fn(), custom: vi.fn() } as unknown as ExtensionContext["ui"];
+
+			const result = await run(tool, { mode: "tui", hasUI: true, cwd: "/tmp", ui } as unknown as ExtensionContext, {
+				command: "id",
+				reason: "whoami",
+			});
+
+			expect(bridgeState.confirm).not.toHaveBeenCalled();
+			expect(result.isError).toBeFalsy();
+			expect((result.content[0] as { text: string }).text).toBe(`${CONFIRMATION_SKIPPED_MARKER}\nok\n`);
+			expect((result.details as { confirmationSkipped?: boolean }).confirmationSkipped).toBe(true);
+		});
+	});
+
 	describe("buildSudoArgv", () => {
 		it("builds sudo -S argv for a plain command", () => {
 			expect(buildSudoArgv("apt install ripgrep")).toEqual(["sudo", "-S", "apt", "install", "ripgrep"]);
@@ -350,8 +636,8 @@ describe("sudo_exec tool", () => {
 	describe("execution", () => {
 		it("runs the command and returns stdout with scrubbed details on success", async () => {
 			const { spawner, last } = makeFakeSpawner({ stdout: "hello\n", stderr: "[sudo] password for daniel: ", code: 0 });
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("cachedpw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -402,8 +688,8 @@ describe("sudo_exec tool", () => {
 
 		it("reports non-zero exit codes as errors", async () => {
 			const { spawner } = makeFakeSpawner({ stderr: "E: not found", code: 100 });
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("pw", 60_000);
 			const spies = spiesNoPrompt();
 			const ctx = tuiCtxWithSpies(true, spies);
@@ -456,8 +742,8 @@ describe("sudo_exec tool", () => {
 			// No automatic exit: only abort's kill ever settles the child.
 			const { spawner, last } = makeFakeSpawner({ stderr: "starting…", code: null, exitOn: "kill" });
 			const killSpy = vi.spyOn(process, "kill").mockImplementation(() => true); // group SIGKILL delivered, no exit echoed here — the settle-guard is the point
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("pw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 			const controller = new AbortController();
@@ -568,8 +854,8 @@ describe("sudo_exec tool", () => {
 			// never produced a process) → the review's crash/hang finding.
 			credentialCache.set("pw", 60_000);
 			const err = Object.assign(new Error("spawn sudo ENOENT"), { code: "ENOENT" });
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner: () => errorChild(err), authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner: () => errorChild(err), authProbe, passwordProbe });
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
 			const result = await run(tool, ctx, { command: "apt update", reason: "maintain" });
@@ -700,8 +986,8 @@ describe("sudo_exec tool", () => {
 			// false-fail this perfectly legitimate fast-exit success.
 			credentialCache.set("nopw", 60_000);
 			const { child, emitStdinError, exit } = streamingChild();
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner: () => child, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner: () => child, authProbe, passwordProbe });
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
 			const promise = run(tool, ctx, { command: "hostname", reason: "test" });
@@ -720,8 +1006,8 @@ describe("sudo_exec tool", () => {
 		it("EPIPE on stdin followed by exit(1) settles as a normal command failure (exit 1), no crash", async () => {
 			credentialCache.set("pw", 60_000);
 			const { child, emitStdinError, exit } = streamingChild();
-			const { authProbe, calls } = probeSpy(true); // gate probes; valid ticket → command failure, not auth
-			const tool = createSudoExecTool({ spawner: () => child, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true); // gate probes; valid ticket → command failure, not auth
+			const tool = createSudoExecTool({ spawner: () => child, authProbe, passwordProbe });
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
 			const promise = run(tool, ctx, { command: "systemctl stop dnsmasq", reason: "test" });
@@ -741,8 +1027,8 @@ describe("sudo_exec tool", () => {
 		it("anomalous stdin error while the child is still running (no exit) settles a clean transport failure — cache RETAINED, no probe", async () => {
 			credentialCache.set("pw", 60_000);
 			const { child, emitStdinError } = streamingChild();
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner: () => child, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner: () => child, authProbe, passwordProbe });
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
 			const promise = run(tool, ctx, { command: "apt update", reason: "maintain" });
@@ -768,8 +1054,8 @@ describe("sudo_exec tool", () => {
 		it("anomalous stdin error AFTER exit(0) already settled success is ignored — result stays success (no double-settle)", async () => {
 			credentialCache.set("pw", 60_000);
 			const { child, emitStdinError, exit } = streamingChild();
-			const { authProbe } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner: () => child, authProbe });
+			const { authProbe, passwordProbe } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner: () => child, authProbe, passwordProbe });
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
 			const promise = run(tool, ctx, { command: "true", reason: "test" });
@@ -842,6 +1128,67 @@ describe("sudo_exec tool", () => {
 		});
 	});
 
+	describe("probeSudoPassword (password-based second-stage credential verification)", () => {
+		it("validates with ['sudo','-S','-v','-p',''] and the password on STDIN — no program, never argv", async () => {
+			const calls: Array<{ command: string; args: string[] }> = [];
+			const { spawner, last } = makeFakeSpawner({ stderr: "", code: 0 });
+			const capturing: SudoSpawner = (command, args) => {
+				calls.push({ command, args });
+				return spawner(command, args);
+			};
+
+			const valid = await probeSudoPassword("hunter2", 5000, undefined, capturing);
+
+			expect(calls).toHaveLength(1);
+			expect(calls[0]).toEqual({ command: "sudo", args: ["-S", "-v", "-p", ""] });
+			expect(calls[0]!.args).not.toContain("hunter2"); // password never in argv
+			expect(last.child.stdin.written).toEqual(["hunter2\n"]); // …only on stdin
+			expect(valid).toBe(true);
+		});
+
+		it("returns false when sudo rejects the credential (non-zero exit)", async () => {
+			const calls: Array<{ command: string; args: string[] }> = [];
+			const { spawner } = makeFakeSpawner({ stderr: "sudo: 1 incorrect password attempt\n", code: 1 });
+			const capturing: SudoSpawner = (command, args) => {
+				calls.push({ command, args });
+				return spawner(command, args);
+			};
+
+			const valid = await probeSudoPassword("wrong", 5000, undefined, capturing);
+
+			expect(calls[0]).toEqual({ command: "sudo", args: ["-S", "-v", "-p", ""] });
+			expect(valid).toBe(false);
+		});
+
+		it("is what the tool runs by DEFAULT after a non-terminal ticket probe (real wiring, fake processes)", async () => {
+			const calls: Array<{ command: string; args: string[] }> = [];
+			const steps = stepSpawner([
+				{ stderr: NON_ENGLISH_STDERR, code: 1 }, // the command run: ambiguous failure
+				{ stderr: "sudo: interactive authentication is required\n", code: 1 }, // stage 1: no reusable ticket
+				{ stderr: "", code: 0 }, // stage 2: the password validates
+			]);
+			const recording: SudoSpawner = (command, args) => {
+				calls.push({ command, args });
+				return steps(command, args);
+			};
+			const tool = createSudoExecTool({ spawner: recording });
+			credentialCache.set("goodpw", 60_000);
+			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
+
+			const result = await run(tool, ctx, { command: "systemctl restart dnsmasq", reason: "flip" });
+
+			expect(calls.map((c) => c.args)).toEqual([
+				["-S", "systemctl", "restart", "dnsmasq"],
+				["-n", "-v"],
+				["-S", "-v", "-p", ""],
+			]);
+			expect(result.isError).toBe(true);
+			const text = (result.content[0] as { text: string }).text;
+			expect(text).not.toMatch(/one more attempt/i);
+			expect(credentialCache.get()?.failStreak).toBe(0);
+		});
+	});
+
 	describe("locale-immune auth-failure invalidation (credential ticket probe)", () => {
 		// The probe gate no longer requires the English prompt: it fires on any
 		// command-level failure (normal non-zero exit) whose stderr did not
@@ -861,8 +1208,8 @@ describe("sudo_exec tool", () => {
 		}
 
 		it("keeps the cache on the FIRST ambiguous failure with a non-terminal probe (strike 1 of two) — with the one-more-attempt warning", async () => {
-			const { authProbe, calls } = probeSpy(false);
-			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(false);
+			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe, passwordProbe });
 			credentialCache.set("badpw-de", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -879,8 +1226,8 @@ describe("sudo_exec tool", () => {
 		});
 
 		it("keeps the cache (and resets a carried streak) when the probe succeeds — valid credential ticket means the command itself failed, NOT the auth", async () => {
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe, passwordProbe });
 			credentialCache.set("goodpw", 60_000);
 			credentialCache.bumpFailStreak(); // carried streak from an earlier ambiguous failure
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
@@ -899,9 +1246,76 @@ describe("sudo_exec tool", () => {
 			expect(calls()).toBe(1);
 		});
 
+		it("verifies the cached PASSWORD when the ticket probe is non-terminal — a correct password is a command failure, not an unverifiable credential", async () => {
+			const { authProbe, passwordProbe, calls, passwordCalls } = probeSpy(false, false, true);
+			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe, passwordProbe });
+			credentialCache.set("goodpw", 60_000);
+			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
+
+			const result = await run(tool, ctx, { command: "sync; echo 3 > /proc/sys/vm/drop_caches", reason: "cache test" });
+
+			// ticket probe non-terminal, password probe terminal → plain command failure
+			expect(result.isError).toBe(true);
+			const text = (result.content[0] as { text: string }).text;
+			expect(text).not.toMatch(/one more attempt/i);
+			expect(text).not.toMatch(/could not be verified/i);
+			expect((result.details as { error?: string }).error).toMatch(/command failed with exit code 1/i);
+			// the credential verified — nothing thrown away, no strike carried
+			expect(credentialCache.get()?.password).toBe("goodpw");
+			expect(credentialCache.get()?.failStreak).toBe(0);
+			expect(calls()).toBe(1);
+			expect(passwordCalls()).toBe(1); // stage 2 ran exactly once
+		});
+
+		it("does NOT run the password probe when the ticket probe is already terminal (stage 1 stays the cheap check)", async () => {
+			const { authProbe, passwordProbe, calls, passwordCalls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe, passwordProbe });
+			credentialCache.set("goodpw", 60_000);
+			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
+
+			const result = await run(tool, ctx, { command: "systemctl restart dnsmasq", reason: "flip" });
+
+			expect(result.isError).toBe(true);
+			expect(calls()).toBe(1);
+			expect(passwordCalls()).toBe(0); // no password spent on a validated ticket
+		});
+
+		it("counts a strike only when BOTH probes are non-terminal — the warning names the credential, not the command", async () => {
+			const { authProbe, passwordProbe, calls, passwordCalls } = probeSpy(false, false, false);
+			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe, passwordProbe });
+			credentialCache.set("pw", 60_000);
+			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
+
+			const result = await run(tool, ctx, { command: "wake lock", reason: "test" });
+
+			expect(result.isError).toBe(true);
+			expect((result.content[0] as { text: string }).text).toMatch(/one more attempt/i);
+			expect(credentialCache.get()?.failStreak).toBe(1);
+			expect(calls()).toBe(1);
+			expect(passwordCalls()).toBe(1);
+		});
+
+		it("treats a stage-2 transport error as non-terminal — strike 1, never a clear", async () => {
+			const { authProbe, calls } = probeSpy(false);
+			const passwordProbe = (): Promise<boolean> => Promise.reject(new Error("probe transport error"));
+			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe, passwordProbe });
+			credentialCache.set("pw", 60_000);
+			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
+
+			const result = await run(tool, ctx, { command: "wake lock", reason: "test" });
+
+			expect(result.isError).toBe(true);
+			const text = (result.content[0] as { text: string }).text;
+			expect(text).not.toMatch(/authentication failed/i);
+			expect(text).toMatch(/one more attempt/i);
+			expect(credentialCache.get()?.password).toBe("pw");
+			expect(credentialCache.get()?.failStreak).toBe(1);
+			expect(calls()).toBe(1);
+		});
+
 		it("keeps the cache on the first ambiguous failure when the probe itself errors — strike 1, not an immediate clear", async () => {
-			const { authProbe, calls } = probeSpy(false, true);
-			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(false, true);
+			const tool = createSudoExecTool({ spawner: ambiguousRunSpawner(), authProbe, passwordProbe });
 			credentialCache.set("pw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -922,8 +1336,8 @@ describe("sudo_exec tool", () => {
 				stderr: "[sudo] password for daniel: \nsorry, try again.\n3 incorrect password attempts\n",
 				code: 1,
 			});
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("badpw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -938,8 +1352,8 @@ describe("sudo_exec tool", () => {
 
 		it("never probes a timed-out run, even when the prompt was seen (124/137 branches stay untouched)", async () => {
 			const { spawner } = makeFakeSpawner({ stderr: "[sudo] password for daniel: ", code: null, exitOn: "kill" });
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("pw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -951,8 +1365,8 @@ describe("sudo_exec tool", () => {
 		});
 
 		it("verifies the probe still runs on a localized-sudo failure with NO English prompt text at all (promptSeen=false — the key regression) — and keeps the cache on strike 1", async () => {
-			const { authProbe, calls } = probeSpy(false);
-			const tool = createSudoExecTool({ spawner: localizedOnlyRunSpawner(), authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(false);
+			const tool = createSudoExecTool({ spawner: localizedOnlyRunSpawner(), authProbe, passwordProbe });
 			credentialCache.set("badpw-de", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -968,8 +1382,8 @@ describe("sudo_exec tool", () => {
 		});
 
 		it("keeps the cache on a no-English-prompt failure when the ticket is valid (probe disambiguates auth from command failure)", async () => {
-			const { authProbe, calls } = probeSpy(true);
-			const tool = createSudoExecTool({ spawner: localizedOnlyRunSpawner(), authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(true);
+			const tool = createSudoExecTool({ spawner: localizedOnlyRunSpawner(), authProbe, passwordProbe });
 			credentialCache.set("goodpw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -989,8 +1403,8 @@ describe("sudo_exec tool", () => {
 				{ stderr: NON_ENGLISH_STDERR, code: 1 }, // strike 1
 				{ stderr: NON_ENGLISH_STDERR, code: 1 }, // strike 2
 			]);
-			const { authProbe, calls } = probeSpy(false);
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(false);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("badpw-de", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -1017,8 +1431,8 @@ describe("sudo_exec tool", () => {
 				{ stdout: "ok\n", code: 0 },           // success → reset
 				{ stderr: NON_ENGLISH_STDERR, code: 1 }, // ambiguous again → must be strike 1, not a clear
 			]);
-			const { authProbe, calls } = probeSpy(false);
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(false);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("pw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -1043,8 +1457,8 @@ describe("sudo_exec tool", () => {
 				{ stderr: NON_ENGLISH_STDERR, code: 1 },                                               // ambiguous → streak 1
 				{ stderr: "[sudo] password for daniel: \nsorry, try again.\n3 incorrect password attempts\n", code: 1 }, // fast path
 			]);
-			const { authProbe, calls } = probeSpy(false); // non-terminal probe → strike 1, not a ticket-valid reset
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe, calls } = probeSpy(false); // non-terminal probe → strike 1, not a ticket-valid reset
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("badpw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -1067,8 +1481,8 @@ describe("sudo_exec tool", () => {
 				if (i === 2) return erroredChild(); // transport failure says nothing about the credential
 				return ambient(command, args);
 			};
-			const { authProbe } = probeSpy(false);
-			const tool = createSudoExecTool({ spawner, authProbe });
+			const { authProbe, passwordProbe } = probeSpy(false);
+			const tool = createSudoExecTool({ spawner, authProbe, passwordProbe });
 			credentialCache.set("pw", 60_000);
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
@@ -1342,9 +1756,9 @@ describe("sudo_exec tool", () => {
 				if (killAttempts === 1) throw Object.assign(new Error("operation not permitted"), { code: "EACCES" });
 				return true;
 			});
-			const { authProbe, calls } = probeSpy(false); // non-terminal probe — any bad entry would bump the streak, VIEWABLE
+			const { authProbe, passwordProbe, calls } = probeSpy(false); // non-terminal probe — any bad entry would bump the streak, VIEWABLE
 			const racing = racingChild();
-			const tool = createSudoExecTool({ spawner: racing.spawner, authProbe });
+			const tool = createSudoExecTool({ spawner: racing.spawner, authProbe, passwordProbe });
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 			const controller = new AbortController();
 
@@ -1378,10 +1792,10 @@ describe("sudo_exec tool", () => {
 				if (killAttempts % 2 === 1) throw Object.assign(new Error("operation not permitted"), { code: "EACCES" });
 				return true; // every odd attempt opens the 50ms retry window; the even one confirms
 			});
-			const { authProbe, calls } = probeSpy(false);
+			const { authProbe, passwordProbe, calls } = probeSpy(false);
 			const races = [racingChild(), racingChild()]; // fresh child per run
 			let next = 0;
-			const tool = createSudoExecTool({ spawner: () => races[next++]!.child, authProbe });
+			const tool = createSudoExecTool({ spawner: () => races[next++]!.child, authProbe, passwordProbe });
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
 			const abortRun = async (reason: string) => {
@@ -1407,9 +1821,9 @@ describe("sudo_exec tool", () => {
 
 		it("a normal (non-aborted) 1–123 exit still probes and bumps exactly as before — the swallow only applies post-abort", async () => {
 			credentialCache.set("pw", 60_000);
-			const { authProbe, calls } = probeSpy(false); // non-terminal probe → strike 1
+			const { authProbe, passwordProbe, calls } = probeSpy(false); // non-terminal probe → strike 1
 			const racing = racingChild();
-			const tool = createSudoExecTool({ spawner: racing.spawner, authProbe });
+			const tool = createSudoExecTool({ spawner: racing.spawner, authProbe, passwordProbe });
 			const ctx = tuiCtxWithSpies(true, spiesNoPrompt());
 
 			const promise = run(tool, ctx, { command: "apt update", reason: "maintain" });
@@ -1436,14 +1850,27 @@ function spiesNoPrompt() {
 	};
 }
 
-function probeSpy(ok: boolean, throws = false) {
+/**
+ * Both credential probes, controllable per test.
+ *
+ * `ok`/`throws` drive stage 1 (the `sudo -n -v` ticket probe). `passwordOk`
+ * drives stage 2 (the `sudo -S -v` password probe), which the tool runs ONLY
+ * when stage 1 is non-terminal — the default there is non-terminal (false),
+ * which keeps the pre-existing two-strike tests meaning what they say.
+ */
+function probeSpy(ok: boolean, throws = false, passwordOk = false) {
 	let calls = 0;
+	let pwCalls = 0;
 	const authProbe: (timeoutMs: number, signal: AbortSignal | undefined) => Promise<boolean> = () => {
 		calls += 1;
 		if (throws) return Promise.reject(new Error("probe transport error"));
 		return Promise.resolve(ok);
 	};
-	return { authProbe, calls: () => calls };
+	const passwordProbe: (password: string, timeoutMs: number, signal: AbortSignal | undefined) => Promise<boolean> = () => {
+		pwCalls += 1;
+		return Promise.resolve(passwordOk);
+	};
+	return { authProbe, passwordProbe, calls: () => calls, passwordCalls: () => pwCalls };
 }
 
 function tuiCtxWithSpies(confirmAnswer: boolean, spies: { confirmCalls: Array<{ title: string; message: string }>; customCalls: unknown[] }): ExtensionContext {

package/src/tool.ts

@@ -30,8 +30,29 @@ export interface SudoExecDetails {
 	stdout: string;
 	stderr: string;
 	error?: string;
+	/**
+	 * Present and `true` only when the confirmation gate was skipped because a
+	 * credential was already cached (`archimedes.sudo.confirmWhenCached: false`,
+	 * ADR 0033). This is the machine-readable record of the skipped gate in the
+	 * session file; `CONFIRMATION_SKIPPED_MARKER` is the same fact in the result
+	 * text, which is the half the terminal and the model actually see.
+	 */
+	confirmationSkipped?: boolean;
 }
 
+/**
+ * First line of a tool result whose confirmation gate was skipped (ADR 0033).
+ *
+ * It belongs in the result **text**, not only in `details`: this tool registers
+ * no result renderer, so the TUI fallback prints `content[].text` alone, and
+ * both provider transforms rebuild a tool result from `content`, dropping
+ * `details`. Without the line, a run nobody approved is word-for-word what an
+ * approved one looks like — to the human reading the transcript, and to the
+ * model deciding whether to issue the next privileged command.
+ */
+export const CONFIRMATION_SKIPPED_MARKER =
+	"[sudo] confirmation skipped — cached credential, archimedes.sudo.confirmWhenCached: false (no human confirmed this command)";
+
 // ── process plumbing ─────────────────────────────────────────────────────────
 
 /** Structural subset of ChildProcess used by runSudo — injectable for tests. */
@@ -284,16 +305,20 @@ export function runSudo(
 	});
 }
 
-/** Timeout for the credential ticket probe (see probeSudoTicket). */
+/** Timeout for the credential probes (see probeSudoTicket / probeSudoPassword). */
 export const AUTH_PROBE_TIMEOUT_MS = 5000;
 
 /**
  * Honest warning surfaced (content + details) on the FIRST ambiguous failure
- * — a non-zero exit without a recognizable failure signature whose
- * credential probe came back non-terminal: the credential is unverified but
- * NOT yet invalidated (a no-reuse sudoers policy makes `sudo -n -v` fail even
- * for a CORRECT password). Kept for one more attempt; a second consecutive
+ * — a non-zero exit without a recognizable failure signature whose BOTH
+ * credential probes came back non-terminal: the credential is unverified but
+ * NOT yet invalidated. Kept for one more attempt; a second consecutive
  * ambiguous failure on the same cached entry clears it and re-prompts.
+ *
+ * Both probes must fail before this warning appears: the ticket probe
+ * (`sudo -n -v`) cannot see a ticket under a no-reuse sudoers policy or a
+ * tty-keyed timestamp with no controlling terminal, and the password probe
+ * (`sudo -S -v`, second stage) covers exactly that case.
  */
 const AMBIGUOUS_CREDENTIAL_WARNING =
 	"the command failed and the cached credential could not be verified (no recognizable authentication failure, and the credential check did not confirm it) — the cached password is kept for one more attempt; if the password itself was wrong it will be cleared and re-prompted after one more such failure.";
@@ -318,6 +343,40 @@ export async function probeSudoTicket(
 	return !run.timedOut && run.error === undefined && run.exitCode === 0;
 }
 
+/**
+ * Second-stage credential check: validate the CACHED PASSWORD itself by
+ * running `sudo -S -v`, which executes no program and returns 0 iff sudo
+ * accepts the credential supplied on stdin. That is what the ticket probe
+ * cannot answer, and the difference matters on hosts where a ticket is never
+ * reusable:
+ *
+ * - `timestamp_type=tty` (Ubuntu's compile-time default) against a spawn
+ *   with no controlling terminal produces a ticket no later invocation can
+ *   replay, so `sudo -n -v` fails for a CORRECT password.
+ * - `timestamp_timeout=0` / `!timestamp` sudoers policies have the same
+ *   effect by design (the ticket is gone the moment the command ends).
+ *
+ * Without this stage every command-level failure on such a host reads as an
+ * unverifiable credential: a misleading warning on the first, a cache wipe
+ * and a fresh password prompt on the second.
+ *
+ * No `-k`: when a ticket IS reusable this returns immediately and reports an
+ * otherwise-usable credential, and revoking the user's own ticket as a side
+ * effect of a diagnostic would be rude. The password reaches sudo over stdin
+ * only, never argv or env (ADR 0010), and a failed validation is NOT treated
+ * as evidence of a wrong password here — only success is terminal, so the
+ * two-strike rule keeps its existing margin.
+ */
+export async function probeSudoPassword(
+	password: string,
+	timeoutMs: number,
+	signal: AbortSignal | undefined,
+	spawner: SudoSpawner,
+): Promise<boolean> {
+	const run = await runSudo(["sudo", "-S", "-v", "-p", ""], password, timeoutMs, signal, spawner);
+	return !run.timedOut && run.error === undefined && run.exitCode === 0;
+}
+
 /**
  * Belt-and-braces: drop any line that contains the raw password so it can
  * never appear in tool details/result content (normally stderr is clean —
@@ -346,15 +405,15 @@ export function buildSudoArgv(command: string): string[] {
 
 const SUDO_EXEC_DESCRIPTION = `Run a command with elevated privileges using sudo.
 
-- BEFORE any credential is requested, the exact command and its reason are shown to the user for confirmation.
-- The password is entered only through a masked UI, passed to sudo via stdin, cached in memory for the session, and never exposed.
+- BEFORE any credential is requested, the exact command and its reason are shown to the user for confirmation. The one exception is user configuration: with \`archimedes.sudo.confirmWhenCached: false\`, a command whose credential is already cached runs without that confirmation, and the result text starts with a line saying so.
+- The password is entered only through a masked UI, passed to sudo via stdin, cached in memory for the process, and never exposed.
 - Use this instead of sudo in bash — interactive sudo in bash is blocked.
 - The command is executed as argv, NOT through a shell: no pipes, redirects, &&, ;, or env assignments; pass args space-separated, quote only literal args.`;
 
 /**
  * Create the sudo_exec tool definition. Options are a test seam: pass a
- * custom spawner to exercise execution paths without real processes, and a
- * custom authProbe to control the ticket probe without spawning `sudo -n`.
+ * custom spawner to exercise execution paths without real processes, and
+ * custom probes to control the credential checks without spawning `sudo -v`.
  */
 export function createSudoExecTool(options: {
 	spawner?: SudoSpawner;
@@ -367,12 +426,26 @@ export function createSudoExecTool(options: {
 	 * password-free credential validation that executes no program)
 	 * is safe to run after any command-level failure. Default: a
 	 * spawner-based `sudo -n -v` ticket probe (probeSudoTicket). It
-	 * never receives the password, by design.
+	 * never receives the password, by design — the second stage below
+	 * is what asks the credential itself.
 	 */
 	authProbe?: (timeoutMs: number, signal: AbortSignal | undefined) => Promise<boolean>;
+	/**
+	 * Second-stage credential check, run only when the ticket probe is
+	 * non-terminal: validate the CACHED PASSWORD with `sudo -S -v` (no
+	 * program executed, password over stdin). This is the check that
+	 * separates "the password is bad" from "this host never has a
+	 * reusable ticket" (tty-keyed timestamps without a controlling
+	 * terminal, `timestamp_timeout=0`, no-reuse sudoers). Default:
+	 * probeSudoPassword.
+	 */
+	passwordProbe?: (password: string, timeoutMs: number, signal: AbortSignal | undefined) => Promise<boolean>;
 } = {}) {
 	const spawner = options.spawner ?? defaultSpawner;
 	const authProbe = options.authProbe ?? ((timeoutMs: number, signal: AbortSignal | undefined) => probeSudoTicket(timeoutMs, signal, spawner));
+	const passwordProbe =
+		options.passwordProbe ??
+		((password: string, timeoutMs: number, signal: AbortSignal | undefined) => probeSudoPassword(password, timeoutMs, signal, spawner));
 
 	const fail = (text: string, details: SudoExecDetails) => ({
 		content: [{ type: "text" as const, text }],
@@ -436,20 +509,54 @@ export function createSudoExecTool(options: {
 			}
 
 			// Display the exact command + reason and require confirmation
-			// BEFORE any credential is acquired.
-			const confirmed = await confirmCommand(ctx, command, reason);
-			if (!confirmed) {
-				return fail("Command not confirmed — not executed, and no password was requested.", {
-					command,
-					reason,
-					exitCode: -1,
-					stdout: "",
-					stderr: "",
-					error: "command not confirmed",
-				});
-			}
-
+			// BEFORE any credential is acquired (ADR 0010). The one exception is
+			// opt-in and narrow — `confirmWhenCached: false` with a credential
+			// already cached: the password prompt already showed this user the
+			// command and reason it was cached for, and the run is recorded with
+			// `confirmationSkipped` (ADR 0033). Nothing about the credential is
+			// changed here, and a cache miss still confirms and prompts.
 			let credential = credentialCache.get();
+			const confirmationSkipped = credential !== null && config.confirmWhenCached === false;
+			/**
+			 * Attach the gate provenance to a result produced after the gate: the
+			 * flag for the session file, and the marker line in front of the text —
+			 * which is the half a human in the terminal and the model actually see.
+			 * Prefixing keeps every existing suffix (the unverified-credential
+			 * warning) exactly where it read before.
+			 */
+			const gated = <T extends { content: Array<{ type: "text"; text: string }>; details: SudoExecDetails }>(result: T): T => {
+				if (!confirmationSkipped) return result;
+				const text = result.content[0]?.text ?? "";
+				return {
+					...result,
+					// A failed command with no stdout gets the marker alone — not a
+					// marker plus an empty line the terminal then renders as a gap.
+					content: [
+						{ type: "text" as const, text: text ? `${CONFIRMATION_SKIPPED_MARKER}\n${text}` : CONFIRMATION_SKIPPED_MARKER },
+					],
+					details: { ...result.details, confirmationSkipped: true },
+				};
+			};
+			if (!confirmationSkipped) {
+				const confirmed = await confirmCommand(ctx, command, reason);
+				if (!confirmed) {
+					return fail("Command not confirmed — not executed, and no password was requested.", {
+						command,
+						reason,
+						exitCode: -1,
+						stdout: "",
+						stderr: "",
+						error: "command not confirmed",
+					});
+				}
+				// The dialog is awaited, so the entry above may have been cleared or have
+				// expired while the human decided (`/sudo forget`, another session's
+				// `session_start`, the TTL elapsing). Re-read it rather than running on
+				// the retained object: a revoked credential must be re-prompted for.
+				// The read above stays where it is — `confirmationSkipped` is computed
+				// from it and decides whether a dialog exists at all.
+				credential = credentialCache.get();
+			}
 			if (!credential) {
 				const password = await promptForPassword(ctx, command, reason);
 				if (!password) {
@@ -489,26 +596,26 @@ export function createSudoExecTool(options: {
 			// auth failure, and never drop the password: a transport glitch is
 			// transient relative to the credential itself.
 			if (run.error) {
-				return fail(`failed to run privileged command: ${run.error}`, {
+				return gated(fail(`failed to run privileged command: ${run.error}`, {
 					command,
 					reason,
 					exitCode: run.exitCode,
 					stdout,
 					stderr,
 					error: run.error,
-				});
+				}));
 			}
 
 			if (run.authFailed) {
 				credentialCache.clear();
-				return fail(
+				return gated(fail(
 					`sudo authentication failed (incorrect password) — exit code ${run.exitCode}. The in-memory credential cache was cleared; the user will be re-prompted on the next attempt.`,
 					{ command, reason, exitCode: run.exitCode, stdout, stderr, error: "authentication failed" },
-				);
+				));
 			}
 
 			if (run.timedOut) {
-				return {
+				return gated({
 					content: [{ type: "text" as const, text: stdout }],
 					details: {
 						command,
@@ -519,28 +626,39 @@ export function createSudoExecTool(options: {
 						error: `timed out after ${timeoutMs}ms — command was killed`,
 					} satisfies SudoExecDetails,
 					isError: true,
-				};
+				});
 			}
 
 			// Locale-immune auth-failure disambiguation: the run exited
 			// non-zero WITHOUT the English "incorrect password" fast-path
 			// signature — a wrong password is indistinguishable from a
 			// localized message (or a genuine command failure) on the
-			// signature path alone. Probe the credential with `sudo -n -v`
-			// (validates the ticket, executes no program, no password):
-			// the probe succeeding means the credential is fine and the
-			// command itself failed → normal result; the probe failing means
-			// the credential is unverified. Two-strike rule on the AMBIGUOUS
-			// path only: a no-reuse sudoers policy makes `sudo -n -v` fail
-			// even for a CORRECT password (no reusable ticket), so the first
-			// such failure keeps the credential with a visible one-more-attempt
+			// signature path alone. Two credential probes, cheapest first:
+			//
+			//   1. `sudo -n -v` (probeSudoTicket) validates the TICKET,
+			//      executes no program, needs no password.
+			//   2. `sudo -S -v` (probeSudoPassword) validates the CACHED
+			//      PASSWORD, executes no program, password over stdin only.
+			//      Runs only when stage 1 is non-terminal, because stage 1
+			//      failing is exactly the case stage 2 answers: a no-reuse
+			//      sudoers policy, or `timestamp_type=tty` against a spawn
+			//      with no controlling terminal (Ubuntu's default), leaves
+			//      no replayable ticket EVEN FOR A CORRECT PASSWORD. With
+			//      stage 1 alone, every command-level failure on such a host
+			//      reads as an unverifiable credential.
+			//
+			// Either probe succeeding means the credential is fine and the
+			// command itself failed → normal result. Two-strike rule on the
+			// AMBIGUOUS path only (both probes non-terminal): the first such
+			// failure keeps the credential with a visible one-more-attempt
 			// warning; the SECOND consecutive ambiguous failure on the same
 			// cached entry clears it and re-prompts. The English fast path
 			// (above) still clears immediately, and success / run / /timeout
 			// /abort outcomes reset (or leave untouched) the streak.
 			// NOT gated on the prompt text — localized sudo emits a prompt in
-			// the user's language, and after ANY command-level failure the
-			// probe is safe (valid ticket → keep, no ticket → re-prompt).
+			// the user's language, and after ANY command-level failure both
+			// probes are safe (the password one validates only, and a wrong
+			// password still costs nothing beyond a failed `sudo -v`).
 			// Control/kill exits are excluded: -1 process error (handled
 			// above), 124 timeout (handled above), 130 abort, 137 SIGKILL —
 			// those aren't auth evidence and must not count as strikes.
@@ -551,20 +669,34 @@ export function createSudoExecTool(options: {
 				} catch {
 					ticketValid = false; // probe transport error → non-terminal probe
 				}
-				if (ticketValid) {
-					// Ticket terminal: the credential verified — drop any carried
+
+				// Stage 2. Only success is terminal: a failed `sudo -v` keeps the
+				// existing margin (no immediate clear on a single ambiguous
+				// failure), so a transport hiccup or an over-restrictive sudoers
+				// cannot throw away a good credential.
+				let passwordValid = false;
+				if (!ticketValid) {
+					try {
+						passwordValid = await passwordProbe(credential.password, AUTH_PROBE_TIMEOUT_MS, signal);
+					} catch {
+						passwordValid = false; // probe transport error → non-terminal probe
+					}
+				}
+
+				if (ticketValid || passwordValid) {
+					// Terminal: the credential verified — drop any carried
 					// streak; this is a straightforward command failure.
 					credentialCache.resetFailStreak();
 				} else {
-					// Non-terminal probe: unverifiable credential — count a strike
+					// Non-terminal probes: unverifiable credential — count a strike
 					// on the CURRENT cached entry.
 					credentialCache.bumpFailStreak();
 					if ((credentialCache.get()?.failStreak ?? 0) >= 2) {
 						credentialCache.clear();
-						return fail(
+						return gated(fail(
 							`sudo authentication failed — exit code ${run.exitCode}. The cached password produced two consecutive failures without a verifiable credential — the credential cache was cleared; you will be re-prompted for the password on the next sudo_exec.`,
 							{ command, reason, exitCode: run.exitCode, stdout, stderr, error: "authentication failed" },
-						);
+						));
 					}
 					unverifiedCredentialWarning = true; // strike 1: keep, warn, and fall through to the normal failure result
 				}
@@ -573,12 +705,12 @@ export function createSudoExecTool(options: {
 			const isError = run.exitCode !== 0;
 			if (!isError) {
 				credentialCache.resetFailStreak();
-				return {
+				return gated({
 					content: [{ type: "text" as const, text: stdout }],
 					details: { command, reason, exitCode: run.exitCode, stdout, stderr } satisfies SudoExecDetails,
-				};
+				});
 			}
-			return {
+			return gated({
 				content: [{ type: "text" as const, text: unverifiedCredentialWarning ? `${stdout}\n(WARNING: ${AMBIGUOUS_CREDENTIAL_WARNING})` : stdout }],
 				details: {
 					command,
@@ -591,7 +723,7 @@ export function createSudoExecTool(options: {
 						: `command failed with exit code ${run.exitCode}`,
 				} satisfies SudoExecDetails,
 				isError: true,
-			};
+			});
 		},
 	};
 }