privateer-agent 0.12.58 → 0.13.0

package/README.md

@@ -126,6 +126,9 @@ silently. The moat is swappable; the floor under it holds.
   and the mic closes when you stop talking. Your OS voice by default — nothing leaves the
   machine — or your account's confidential-compute TTS/STT once you sign in. `/talk loop on`
   makes it hands-free. See [Talk to it](#talk-to-it--voice-both-directions).
+- **Named terminals.** The agent can open windows you watch — a dev server, a REPL, a second
+  agent — give each a name, and bring any of them to the front; `/term api` switches you there
+  yourself. macOS Terminal, iTerm2, and tmux anywhere. See [Named terminals](#named-terminals).
 - **MCP servers, sub-agents & skills.** Connect Model Context Protocol servers (local stdio
   or remote HTTP with OAuth) with [`/connect`](#connectors--mcp), delegate work to bounded
   parallel sub-agents, and drop in skills — all gated like everything else.
@@ -359,8 +362,9 @@ One caveat while the account endpoints catch up: `/speak rate` and `/talk vocab`
 by the local and OpenAI-compatible engines, not yet by the account's TTS/STT.
 
 Voice is **off by default and interactive-only** — harbor, ACP and channel sessions never
-speak. The mic opens only on something you did (`/talk`, the push-to-talk key, or a
-conversation turn you switched on); there is no wake word, capture is hard-capped, audio is
+speak. The mic opens only on something you did (`/talk`, the push-to-talk key, a
+conversation turn you switched on, or switching to a window while dictation or conversation
+mode is on); there is no wake word, capture is hard-capped, audio is
 held in memory and never written to disk, and a mis-heard transcript is still just a prompt —
 every tool call it leads to hits the same permission gate as anything you type. Recording
 needs a capture tool on PATH: `sox` anywhere, or `arecord`/`parecord`/`ffmpeg` on Linux,
@@ -368,6 +372,37 @@ needs a capture tool on PATH: `sox` anywhere, or `arecord`/`parecord`/`ffmpeg` o
 standalone [`privateer-speak`](https://www.npmjs.com/package/privateer-speak) package, usable
 in any Pi agent.
 
+## Named terminals
+
+Ask for "a terminal running the dev server" and the agent opens a new window, names it, and
+puts it in front of you. Every Privateer window names itself too (after its folder, or the
+name the agent gave it), so you and the agent can hop between them by name:
+
+```
+/term                  pick a terminal to switch to
+/term api              switch to "api"
+/term open api npm run dev    open one yourself
+/term name backend     rename this window
+/term close api        close it, ending what runs there
+/term list             every named terminal (← marks this one)
+```
+
+The agent does the same through its `terminal` tool. Opening a window with a command goes
+through the permission gate exactly like running that command in bash; switching and listing
+don't ask. The agent can't read what a window prints: that's what bash and background tasks
+are for. These windows are for you.
+
+Voice follows you between windows. Every window shares one voice setup, so with
+dictation or conversation mode on, the window you switch to listens for your next prompt,
+including a new agent the moment its window opens in front. The window you left pauses
+its mic. (That's [privateer-speak](https://www.npmjs.com/package/privateer-speak)'s focus
+awareness; it needs a terminal that reports focus.)
+
+Works in **macOS Terminal**, **iTerm2**, and inside **tmux** on any platform; other terminals
+get told so. macOS may ask once for permission to let the terminal control itself. Names are
+shared across every Privateer on the machine (`~/.privateer/terminals.json`), and a window
+that's been closed drops off the list on its own.
+
 ## The Privateer app
 
 The same account drives Privateer from **iOS, Android, [the web app](https://privateer.pro),

package/extensions/privateer-brand.ts

@@ -285,10 +285,10 @@ function contextLine(p: Palette): string {
 // or three things a returning user should notice. `cmd`, when present, is rendered in the
 // accent color so the actionable bit stands out from the prose. Trim this as it ages.
 const WHATS_NEW: Array<{ text: string; cmd?: string }> = [
+  { text: "Open and switch named terminals —", cmd: "/term" },
+  { text: "Voice follows the window you're in" },
   { text: "Searchable model picker —", cmd: "/models" },
   { text: "Start over with a new agent —", cmd: "/fresh" },
-  { text: "Text-only models can read images now" },
-  { text: "Live crypto prices and Solana wallets" },
 ];
 
 function whatsNewRows(p: Palette): string[] {

package/extensions/privateer-speak.ts

@@ -61,6 +61,7 @@ import {
 } from "privateer-speak";
 import { apiRequest, hasCredentials } from "../src/auth/privateer.ts";
 import { globalDir } from "../src/config/paths.ts";
+import { thisTerminalIsFront } from "../src/terminals/index.ts";
 import { VOICE_DESCRIPTIONS } from "./speak-voices.data.ts";
 
 const QWEN3_TTS_VOICES = ["serena", "aiden", "dylan", "eric", "ono_anna", "ryan", "sohee", "uncle_fu", "vivian"];
@@ -358,7 +359,14 @@ export default function privateerSpeak(pi: any): void {
   // voiceCommands: saying one of these AS THE WHOLE UTTERANCE runs /fresh (see
   // extensions/privateer-fresh.ts) instead of sending the words to the model. Whole
   // utterance only, so "why did the fresh start fail" is still a question.
-  makePiSpeakExtension({ configFile: join(globalDir(), "speak.json"), voiceCommands: VOICE_COMMANDS })(pi);
+  // isFocused: a window that has just started (say, one the agent opened with the
+  // terminal tool) asks Terminal/iTerm2 whether it's in front, so a hands-free mode
+  // carries on in the new agent without a keypress — see src/terminals/.
+  makePiSpeakExtension({
+    configFile: join(globalDir(), "speak.json"),
+    voiceCommands: VOICE_COMMANDS,
+    isFocused: thisTerminalIsFront,
+  })(pi);
 }
 
 const VOICE_COMMANDS: Record<string, string> = {

package/extensions/privateer-terminals.ts

@@ -0,0 +1,73 @@
+// Named terminals — the `terminal` tool and /term, so the agent can open windows the
+// user watches (a dev server, a REPL, a second agent) and either of them can switch
+// between those windows by name. See src/terminals/ for how windows are found and why
+// only tmux, macOS Terminal and iTerm2 are driven.
+//
+// Interactive only: the window registers itself at session start, which a harbor or ACP
+// host has no window to do, and the tool refuses without a UI.
+
+import { closeTerminal, describeListing, focusTerminal, openTerminal, renameSelf, terminalListing, backend, claimSelf } from "../src/terminals/index.ts";
+import { terminalToolDefinition } from "../src/tools/terminal.ts";
+
+const USAGE =
+  "/term — pick a terminal to switch to · /term <name> — switch · /term open <name> [command] · " +
+  "/term name <name> — rename this one · /term close <name> · /term list";
+
+export default function privateerTerminals(pi: any): void {
+  pi.registerTool?.(terminalToolDefinition);
+
+  // Name this window as soon as the session starts, so it can be switched back to from
+  // any other — not only after its first /term.
+  pi.on?.("session_start", (_e: any, ctx: any) => {
+    if (!ctx?.hasUI) return;
+    const b = backend();
+    if ("unsupported" in b) return;
+    void claimSelf(b, ctx.cwd ?? process.cwd()).catch(() => undefined);
+  });
+
+  pi.registerCommand?.("term", {
+    description: "Switch between named terminals, or open one",
+    handler: async (args: string, ctx: any) => {
+      const notify = (m: string, kind: "info" | "warning" | "error" = "info") => ctx?.ui?.notify?.(m, kind);
+      const cwd = ctx?.cwd ?? process.cwd();
+      const [sub = "", ...rest] = String(args ?? "").trim().split(/\s+/).filter(Boolean);
+      const report = (o: { ok: boolean; message: string }) => notify(o.message, o.ok ? "info" : "warning");
+
+      switch (sub.toLowerCase()) {
+        case "": {
+          const l = await terminalListing(cwd);
+          if ("unsupported" in l) return notify(l.unsupported, "warning");
+          const others = l.records.filter((r) => r.id !== l.selfId);
+          if (!others.length) return notify(`No other named terminals. ${USAGE}`);
+          if (typeof ctx?.ui?.select !== "function") return notify(describeListing(l));
+          const labels = others.map((r) => `${r.name}  ${r.command ?? r.cwd}`);
+          const picked = await ctx.ui.select("Switch to terminal", labels);
+          const rec = picked ? others[labels.indexOf(picked)] : undefined;
+          if (rec) report(await focusTerminal(rec.name, cwd));
+          return;
+        }
+        case "list": {
+          const l = await terminalListing(cwd);
+          return notify("unsupported" in l ? l.unsupported : describeListing(l), "unsupported" in l ? "warning" : "info");
+        }
+        case "open": {
+          const [name, ...cmd] = rest;
+          if (!name) return notify("Usage: /term open <name> [command]", "warning");
+          return report(await openTerminal({ name, cwd, ...(cmd.length ? { command: cmd.join(" ") } : {}) }));
+        }
+        case "name":
+        case "rename":
+          if (!rest.length) return notify("Usage: /term name <name>", "warning");
+          return report(await renameSelf(rest.join(" "), cwd));
+        case "close":
+          if (!rest.length) return notify("Usage: /term close <name>", "warning");
+          return report(await closeTerminal(rest.join(" "), cwd));
+        case "help":
+          return notify(USAGE);
+        default:
+          // Anything else is a name: /term api, /term "dev server".
+          return report(await focusTerminal([sub, ...rest].join(" "), cwd));
+      }
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.58",
+  "version": "0.13.0",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",
@@ -86,7 +86,7 @@
     "pi-privacy": "0.14.1",
     "pi-subagents": "0.70.0",
     "picomatch": "4.0.5",
-    "privateer-speak": "0.6.0",
+    "privateer-speak": "0.7.0",
     "privateer-workflow": "0.1.0",
     "tinfoil": "1.1.11",
     "tsx": "4.23.0",

package/src/config/moatManifest.json

@@ -20,6 +20,7 @@
     { "entry": "extensions/privateer-media.ts", "name": "privateer-media", "note": "image/video/speech/music + ffmpeg compose" },
     { "entry": "extensions/privateer-computer.ts", "name": "privateer-computer", "note": "screen control — screenshots, mouse and keyboard (off unless armed with --allow-computer-control)" },
     { "entry": "extensions/privateer-desktop.ts", "name": "privateer-desktop", "note": "/desktop — open the Privateer desktop app" },
+    { "entry": "extensions/privateer-terminals.ts", "name": "privateer-terminals", "note": "named terminal windows — the terminal tool + /term to switch between them" },
     { "entry": "extensions/privateer-hints.ts", "name": "privateer-hints", "note": "rotating tips in the working line + /hints" },
     { "entry": "extensions/privateer-update.ts", "name": "privateer-update", "note": "tool pack updates in place — banner flag + /update" },
     { "entry": "extensions/privateer-fresh.ts", "name": "privateer-fresh", "note": "/fresh — replace the agent with a new one and stop everything it started" },

package/src/permissions/classify.ts

@@ -648,6 +648,28 @@ export function classifyToolCall(
     };
   }
 
+  // terminal (src/tools/terminal.ts) — named windows the user watches. Opening one
+  // with a command RUNS that command, so it is bash-kind with the command as the
+  // detail: the same danger list, allowlist and plan-mode refusal as typing it into
+  // bash. A bare shell is bash-kind too (it puts a new window on the user's screen),
+  // and so is close, which ends whatever runs in the window. Focus and list only move
+  // a window to the front or read names: no gate, in any mode.
+  if (name === "terminal") {
+    const action = str(obj.action) || "list";
+    if (action === "focus" || action === "list") return null;
+    const label = str(obj.name);
+    if (action === "close") {
+      return { tool: toolName, kind: "bash", title: `Close terminal "${label}"`, detail: `close terminal ${label}` };
+    }
+    const command = str(obj.command).trim();
+    return {
+      tool: toolName,
+      kind: "bash",
+      title: command ? `Open terminal "${label}" running a command` : `Open terminal "${label}"`,
+      detail: command || `open a shell${obj.cwd ? ` in ${str(obj.cwd)}` : ""}`,
+    };
+  }
+
   // Network reads (web fetch / search / http).
   if (name.includes("fetch") || name.includes("web") || name.includes("http") || name.includes("url")) {
     return {

package/src/terminals/backends.ts

@@ -0,0 +1,376 @@
+// Named terminals: the part that talks to the terminal program itself.
+//
+// A "terminal" here is a window (or tab, or tmux window) the user can SEE: the agent
+// opens one for a dev server, a REPL or a second agent, gives it a name, and either
+// of them can bring it to the front by that name later. Output is not read back:
+// that is what bash and background tasks are for. These are for the person at the
+// keyboard.
+//
+// IDENTITY IS THE TTY. Every backend can tell us which pseudo-terminal a window owns,
+// and the same tty is what a process running inside it sees as its controlling
+// terminal. So a Privateer started in a window we opened finds its own name by asking
+// `ps` for its tty, and a window the user opened by hand can still be named and
+// focused once a session inside it has registered it. Window titles would have been
+// easier to match and are worthless as identity: the shell rewrites them on every
+// prompt.
+//
+// THREE BACKENDS, ONE ON PURPOSE PER PLACE. tmux wins whenever we are inside it,
+// because there the "window" the user sees is tmux's, whatever app draws it. Outside
+// tmux: macOS Terminal and iTerm2 through AppleScript. Everything else (Ghostty,
+// kitty, WezTerm, Linux and Windows terminals with no tmux) gets a clear "not here"
+// rather than a guess: focusing a window by name on X11/Wayland/Windows needs a
+// window manager contract we can't count on, and tmux runs everywhere.
+//
+// AppleScript runs as the terminal app controlling ITSELF (Privateer is a child of the
+// window it draws in). Terminal does this without an Automation prompt (verified);
+// iTerm2 is untested here and may ask once.
+
+import { execFile } from "node:child_process";
+
+export type TerminalApp = "tmux" | "Apple_Terminal" | "iTerm.app";
+
+export interface OpenRequest {
+  name: string;
+  cwd: string;
+  /** Typed into the new shell, so it runs with the user's own PATH and rc files. */
+  command?: string;
+  /** Bring it to the front (default). False leaves focus where it was. */
+  focus: boolean;
+}
+
+export interface TerminalBackend {
+  app: TerminalApp;
+  /** Human name for messages. */
+  label: string;
+  /** Open a window and return its id (a tty path, or a tmux pane id). */
+  open(req: OpenRequest): Promise<string>;
+  /** Bring the window with this id to the front. False when it no longer exists. */
+  focus(id: string): Promise<boolean>;
+  /** Close it, ending what runs inside. False when it no longer exists. */
+  close(id: string): Promise<boolean>;
+  /** Ids of every window that exists right now, for pruning the registry. */
+  live(): Promise<Set<string>>;
+  /** The id of the window this process runs in, if it can tell. */
+  selfId(): Promise<string | undefined>;
+  /** Is this window the one in front, app and all? undefined when it can't tell. */
+  isFront(id: string): Promise<boolean | undefined>;
+}
+
+/** Run a program and hand back stdout; injectable so tests can see the exact calls. */
+export type Exec = (file: string, args: string[]) => Promise<string>;
+
+export const execProgram: Exec = (file, args) =>
+  new Promise((resolve, reject) => {
+    execFile(file, args, { timeout: 10_000, encoding: "utf8" }, (err, stdout, stderr) => {
+      if (err) reject(new Error(String(stderr || err.message).trim()));
+      else resolve(String(stdout));
+    });
+  });
+
+/** Single-quote for POSIX sh: the one quoting that has no special characters inside. */
+export function shQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** An AppleScript string literal. */
+export function asString(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** What gets typed into a new shell: change to the folder, then run the command if any. */
+export function shellLine(cwd: string, command?: string): string {
+  const cd = `cd ${shQuote(cwd)}`;
+  return command?.trim() ? `${cd} && ${command.trim()}` : cd;
+}
+
+const TTY = /\/dev\/tty[\w.]+/g;
+
+/** This process's controlling tty as a /dev path, from ps (the one tool both Unixes ship). */
+export async function ttyOf(pid: number, exec: Exec = execProgram): Promise<string | undefined> {
+  try {
+    const out = (await exec("ps", ["-o", "tty=", "-p", String(pid)])).trim();
+    if (!out || out.startsWith("?")) return undefined;
+    return out.startsWith("/dev/") ? out : `/dev/${out}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Hang up everything running on a tty — what closing the window by hand does — so the
+ * close that follows has nothing to ask about. Without this, Terminal answers a close
+ * of a busy window with a "terminate running processes?" sheet, the window stays, and
+ * every later close of it is swallowed by that sheet. (macOS `pkill -t` matches
+ * nothing here, hence ps + kill.) Processes we may not signal (login) are skipped.
+ */
+export async function hangUp(tty: string, exec: Exec = execProgram): Promise<void> {
+  const name = tty.replace(/^\/dev\//, "");
+  let pids: string[];
+  try {
+    pids = (await exec("ps", ["-t", name, "-o", "pid="])).split(/\s+/).filter((p) => /^\d+$/.test(p));
+  } catch {
+    return; // nothing on it
+  }
+  for (const pid of pids) {
+    if (Number(pid) === process.pid) continue;
+    await exec("kill", ["-HUP", pid]).catch(() => undefined);
+  }
+}
+
+const pause = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Hang up, close, and confirm the window is really gone. The window is pinned by the
+ * app's own id BEFORE the hang-up: once nothing runs on the tty, a lookup by tty no
+ * longer finds it (see findTab), and a tty is reused the moment it's free.
+ */
+async function closeChecked(
+  tty: string,
+  exec: Exec,
+  label: string,
+  steps: { handle: () => Promise<string>; close: (handle: string) => Promise<unknown>; exists: (handle: string) => Promise<boolean> },
+): Promise<boolean> {
+  const handle = (await steps.handle()).trim();
+  if (!handle || handle === "missing") return false;
+  await hangUp(tty, exec);
+  await pause(300);
+  await steps.close(handle);
+  for (let i = 0; i < 10; i++) {
+    if (!(await steps.exists(handle))) return true;
+    await pause(200);
+  }
+  throw new Error(`${label} kept the window open — it may be asking you to confirm. Close it by hand.`);
+}
+
+// ── macOS Terminal ──────────────────────────────────────────────────────────
+
+// Every lookup walks windows → tabs and matches on tty. `return` inside the loops
+// matters: closing a window mid-iteration invalidates the list being walked.
+//
+// Only tabs with something still running count. A window whose shell has exited stays
+// on screen ("[Process completed]") still reporting its old tty, and macOS hands that
+// tty to the next window opened — so without this, the dead window and the new one
+// would answer to the same id.
+const findTab = (tty: string, body: string): string => `
+if application "Terminal" is not running then return "missing"
+tell application "Terminal"
+  repeat with w in windows
+    repeat with t in tabs of w
+      if tty of t is ${asString(tty)} and (count of processes of t) > 0 then
+        ${body}
+        return "ok"
+      end if
+    end repeat
+  end repeat
+end tell
+return "missing"`;
+
+export function appleTerminal(exec: Exec = execProgram): TerminalBackend {
+  const osa = (script: string) => exec("osascript", ["-e", script]);
+  return {
+    app: "Apple_Terminal",
+    label: "Terminal",
+    async open(req) {
+      // `do script` with no target opens a new window and returns its tab.
+      const out = await osa(`
+tell application "Terminal"
+  set t to do script ${asString(shellLine(req.cwd, req.command))}
+  set custom title of t to ${asString(req.name)}
+  set title displays custom title of t to true
+  ${req.focus ? "activate" : ""}
+  return tty of t
+end tell`);
+      const tty = out.match(TTY)?.[0];
+      if (!tty) throw new Error(`Terminal opened a window but did not say which (${out.trim() || "no output"})`);
+      return tty;
+    },
+    async focus(id) {
+      // index 1 is "frontmost among Terminal's windows"; activate brings Terminal forward.
+      return (await osa(findTab(id, "set selected of t to true\n        set index of w to 1\n        activate"))).trim() === "ok";
+    },
+    async close(id) {
+      return closeChecked(id, exec, "Terminal", {
+        handle: () => osa(findTab(id, "return id of w")),
+        close: (wid) => osa(`tell application "Terminal" to close (window id ${Number(wid)})`),
+        exists: async (wid) =>
+          (await osa(`tell application "Terminal" to return exists window id ${Number(wid)}`)).trim() === "true",
+      });
+    },
+    async live() {
+      const out = await osa(`
+if application "Terminal" is not running then return ""
+set out to ""
+tell application "Terminal"
+  repeat with w in windows
+    repeat with t in tabs of w
+      if (count of processes of t) > 0 then set out to out & (tty of t) & linefeed
+    end repeat
+  end repeat
+end tell
+return out`);
+      return new Set(out.match(TTY) ?? []);
+    },
+    selfId: () => ttyOf(process.pid, exec),
+    async isFront(id) {
+      const out = await osa(`
+if application "Terminal" is not running then return "false"
+tell application "Terminal"
+  if not frontmost then return "false"
+  return ((tty of selected tab of front window) is ${asString(id)}) as text
+end tell`);
+      return out.trim() === "true";
+    },
+  };
+}
+
+// ── iTerm2 ──────────────────────────────────────────────────────────────────
+
+const findSession = (tty: string, body: string): string => `
+if application id "com.googlecode.iterm2" is not running then return "missing"
+tell application "iTerm2"
+  repeat with w in windows
+    repeat with t in tabs of w
+      repeat with s in sessions of t
+        if tty of s is ${asString(tty)} then
+          ${body}
+          return "ok"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell
+return "missing"`;
+
+export function iTerm(exec: Exec = execProgram): TerminalBackend {
+  const osa = (script: string) => exec("osascript", ["-e", script]);
+  return {
+    app: "iTerm.app",
+    label: "iTerm2",
+    async open(req) {
+      const out = await osa(`
+tell application "iTerm2"
+  set w to (create window with default profile)
+  tell current session of w
+    set name to ${asString(req.name)}
+    write text ${asString(shellLine(req.cwd, req.command))}
+    set theTty to tty
+  end tell
+  ${req.focus ? "activate" : ""}
+  return theTty
+end tell`);
+      const tty = out.match(TTY)?.[0];
+      if (!tty) throw new Error(`iTerm2 opened a window but did not say which (${out.trim() || "no output"})`);
+      return tty;
+    },
+    async focus(id) {
+      return (await osa(findSession(id, "select w\n          tell t to select\n          tell s to select\n          activate"))).trim() === "ok";
+    },
+    async close(id) {
+      // A session's `id` is iTerm2's own unique identifier for it.
+      const bySession = (sid: string, body: string) => `
+if application id "com.googlecode.iterm2" is not running then return "missing"
+tell application "iTerm2"
+  repeat with w in windows
+    repeat with t in tabs of w
+      repeat with s in sessions of t
+        if id of s is ${asString(sid)} then
+          ${body}
+          return "ok"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell
+return "missing"`;
+      return closeChecked(id, exec, "iTerm2", {
+        handle: () => osa(findSession(id, "return id of s")),
+        close: (sid) => osa(bySession(sid, "tell s to close")),
+        exists: async (sid) => (await osa(bySession(sid, ""))).trim() === "ok",
+      });
+    },
+    async live() {
+      const out = await osa(`
+if application id "com.googlecode.iterm2" is not running then return ""
+tell application "iTerm2" to return tty of every session of every tab of every window`);
+      return new Set(out.match(TTY) ?? []);
+    },
+    selfId: () => ttyOf(process.pid, exec),
+    async isFront(id) {
+      const out = await osa(`
+if application id "com.googlecode.iterm2" is not running then return "false"
+tell application "iTerm2"
+  if not frontmost then return "false"
+  return ((tty of current session of current window) is ${asString(id)}) as text
+end tell`);
+      return out.trim() === "true";
+    },
+  };
+}
+
+// ── tmux ────────────────────────────────────────────────────────────────────
+
+// Ids are pane ids (%12): stable for the pane's life and unique across sessions, where
+// window indexes renumber. The command is typed into a shell rather than given to
+// new-window, so the window outlives the command exactly as it does on macOS.
+export function tmux(exec: Exec = execProgram, env: NodeJS.ProcessEnv = process.env): TerminalBackend {
+  const run = (...args: string[]) => exec("tmux", args);
+  const exists = async (id: string) => (await run("list-panes", "-a", "-F", "#{pane_id}")).split(/\s+/).includes(id);
+  return {
+    app: "tmux",
+    label: "tmux",
+    async open(req) {
+      const id = (
+        await run("new-window", ...(req.focus ? [] : ["-d"]), "-P", "-F", "#{pane_id}", "-n", req.name, "-c", req.cwd)
+      ).trim();
+      if (!/^%\d+$/.test(id)) throw new Error(`tmux opened a window but did not say which (${id || "no output"})`);
+      if (req.command?.trim()) {
+        await run("send-keys", "-t", id, "-l", req.command.trim());
+        await run("send-keys", "-t", id, "Enter");
+      }
+      return id;
+    },
+    async focus(id) {
+      if (!(await exists(id))) return false;
+      // A pane in another session needs the client moved there first.
+      await run("switch-client", "-t", id).catch(() => undefined);
+      await run("select-window", "-t", id);
+      await run("select-pane", "-t", id);
+      return true;
+    },
+    async close(id) {
+      if (!(await exists(id))) return false;
+      await run("kill-window", "-t", id);
+      return true;
+    },
+    async live() {
+      return new Set((await run("list-panes", "-a", "-F", "#{pane_id}")).split(/\s+/).filter(Boolean));
+    },
+    selfId: async () => env.TMUX_PANE || undefined,
+    // tmux knows whether the pane is the one showing, not whether the app drawing it is
+    // in front: a pane that isn't showing is behind, one that is can't be sure.
+    async isFront(id) {
+      const out = (await run("display-message", "-p", "-t", id, "#{pane_active}#{window_active}")).trim();
+      return out === "11" ? undefined : false;
+    },
+  };
+}
+
+/**
+ * The backend for the window this process is in, or why there isn't one. tmux first:
+ * inside it, TERM_PROGRAM names the app that draws tmux, not the thing we can drive.
+ */
+export function detectBackend(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  exec: Exec = execProgram,
+): TerminalBackend | { unsupported: string } {
+  if (env.TMUX) return tmux(exec, env);
+  if (platform === "darwin" && env.TERM_PROGRAM === "Apple_Terminal") return appleTerminal(exec);
+  if (platform === "darwin" && env.TERM_PROGRAM === "iTerm.app") return iTerm(exec);
+  const where = env.TERM_PROGRAM ? `${env.TERM_PROGRAM}` : platform === "win32" ? "this Windows terminal" : "this terminal";
+  return {
+    unsupported:
+      `Named terminals work inside tmux, macOS Terminal and iTerm2 — not in ${where}. ` +
+      `Run privateer inside tmux to use them here.`,
+  };
+}

package/src/terminals/index.ts

@@ -0,0 +1,200 @@
+// Named terminals: what the `terminal` tool and /term both do, so the agent and the
+// person at the keyboard share one vocabulary — "open api", "go to api", "close api".
+//
+// The window a Privateer runs in names itself on first use (see claimSelf): its folder's
+// name, or the name the agent gave it when it opened it. That is what makes "go back to
+// main" possible from a window the agent opened, and what lets the user hop between
+// windows they opened by hand once a session in each has started.
+
+import { basename } from "node:path";
+import { detectBackend, type TerminalBackend } from "./backends.ts";
+import {
+  checkName,
+  findTerminal,
+  forgetTerminal,
+  freeName,
+  listTerminals,
+  saveTerminal,
+  type TerminalRecord,
+} from "./registry.ts";
+
+export type Outcome = { ok: true; message: string } | { ok: false; message: string };
+
+const fail = (message: string): Outcome => ({ ok: false, message });
+const done = (message: string): Outcome => ({ ok: true, message });
+
+let cachedBackend: TerminalBackend | { unsupported: string } | undefined;
+/** Fixed for the life of the process: the window we were started in doesn't change. */
+export function backend(): TerminalBackend | { unsupported: string } {
+  return (cachedBackend ??= detectBackend());
+}
+/** Tests only. */
+export function setBackendForTests(b: TerminalBackend | { unsupported: string } | undefined): void {
+  cachedBackend = b;
+}
+
+const errorText = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+/**
+ * This process's own window, registered if it isn't yet. A window the agent opened
+ * already has a record under its tty, so a Privateer started there keeps that name.
+ */
+export async function claimSelf(b: TerminalBackend, cwd: string): Promise<TerminalRecord | undefined> {
+  const id = await b.selfId();
+  if (!id) return undefined;
+  const records = await listTerminals(b);
+  const mine = records.find((r) => r.id === id);
+  if (mine) return mine;
+  const base = checkName(basename(cwd));
+  const rec: TerminalRecord = {
+    name: freeName("name" in base ? base.name : "main", records),
+    app: b.app,
+    id,
+    cwd,
+    createdAt: Date.now(),
+  };
+  saveTerminal(rec);
+  return rec;
+}
+
+export async function openTerminal(opts: {
+  name: string;
+  cwd: string;
+  command?: string;
+  focus?: boolean;
+}): Promise<Outcome> {
+  const b = backend();
+  if ("unsupported" in b) return fail(b.unsupported);
+  const checked = checkName(opts.name);
+  if ("error" in checked) return fail(checked.error);
+  const records = await listTerminals(b);
+  const clash = findTerminal(records, checked.name);
+  if (clash) {
+    return fail(
+      `There is already a terminal named "${clash.name}". Focus it, close it first, or pick another name.`,
+    );
+  }
+  // Register where we are first, so the new window can be left for this one by name.
+  await claimSelf(b, opts.cwd).catch(() => undefined);
+  const focus = opts.focus !== false;
+  let id: string;
+  try {
+    id = await b.open({ name: checked.name, cwd: opts.cwd, ...(opts.command ? { command: opts.command } : {}), focus });
+  } catch (e) {
+    return fail(`Could not open a ${b.label} window: ${errorText(e)}`);
+  }
+  saveTerminal({
+    name: checked.name,
+    app: b.app,
+    id,
+    cwd: opts.cwd,
+    ...(opts.command?.trim() ? { command: opts.command.trim() } : {}),
+    createdAt: Date.now(),
+  });
+  // macOS puts a new Terminal window in front whatever we ask; put ours back.
+  if (!focus) {
+    const self = await b.selfId().catch(() => undefined);
+    if (self) await b.focus(self).catch(() => undefined);
+  }
+  const what = opts.command?.trim() ? `running \`${opts.command.trim()}\`` : "with a shell";
+  return done(`Opened "${checked.name}" ${what} in ${opts.cwd}${focus ? " — it has focus now" : " in the background"}.`);
+}
+
+export async function focusTerminal(name: string, cwd: string): Promise<Outcome> {
+  const b = backend();
+  if ("unsupported" in b) return fail(b.unsupported);
+  await claimSelf(b, cwd).catch(() => undefined);
+  const records = await listTerminals(b);
+  const rec = findTerminal(records, name);
+  if (!rec) return fail(unknownName(name, records));
+  let ok: boolean;
+  try {
+    ok = await b.focus(rec.id);
+  } catch (e) {
+    return fail(`Could not focus "${rec.name}": ${errorText(e)}`);
+  }
+  if (!ok) {
+    forgetTerminal(rec.app, rec.id);
+    return fail(`"${rec.name}" has been closed.`);
+  }
+  return done(`Switched to "${rec.name}".`);
+}
+
+export async function closeTerminal(name: string, cwd: string): Promise<Outcome> {
+  const b = backend();
+  if ("unsupported" in b) return fail(b.unsupported);
+  const self = await claimSelf(b, cwd).catch(() => undefined);
+  const records = await listTerminals(b);
+  const rec = findTerminal(records, name);
+  if (!rec) return fail(unknownName(name, records));
+  if (self && rec.id === self.id) return fail(`"${rec.name}" is this terminal — it can't close itself.`);
+  try {
+    if (!(await b.close(rec.id))) {
+      forgetTerminal(rec.app, rec.id);
+      return fail(`"${rec.name}" was already closed.`);
+    }
+  } catch (e) {
+    return fail(`Could not close "${rec.name}": ${errorText(e)}`);
+  }
+  forgetTerminal(rec.app, rec.id);
+  return done(`Closed "${rec.name}".`);
+}
+
+export async function renameSelf(name: string, cwd: string): Promise<Outcome> {
+  const b = backend();
+  if ("unsupported" in b) return fail(b.unsupported);
+  const checked = checkName(name);
+  if ("error" in checked) return fail(checked.error);
+  const self = await claimSelf(b, cwd);
+  if (!self) return fail("Can't tell which window this is, so it can't be named.");
+  const clash = findTerminal(await listTerminals(b), checked.name);
+  if (clash && clash.id !== self.id) return fail(`"${clash.name}" is already another terminal's name.`);
+  saveTerminal({ ...self, name: checked.name });
+  return done(`This terminal is "${checked.name}" now.`);
+}
+
+/**
+ * Is the window this process runs in the one in front? For voice (privateer-speak): a
+ * new window can't learn that from the terminal until focus next changes. undefined
+ * when it can't tell — an unsupported terminal, or no tty.
+ */
+export async function thisTerminalIsFront(): Promise<boolean | undefined> {
+  const b = backend();
+  if ("unsupported" in b) return undefined;
+  try {
+    const id = await b.selfId();
+    return id ? await b.isFront(id) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface TerminalListing {
+  records: TerminalRecord[];
+  selfId?: string;
+}
+
+export async function terminalListing(cwd: string): Promise<TerminalListing | { unsupported: string }> {
+  const b = backend();
+  if ("unsupported" in b) return b;
+  const self = await claimSelf(b, cwd).catch(() => undefined);
+  return { records: await listTerminals(b), ...(self ? { selfId: self.id } : {}) };
+}
+
+export function describeListing(l: TerminalListing): string {
+  if (!l.records.length) return "No named terminals yet.";
+  return l.records
+    .map((r) => {
+      const here = r.id === l.selfId ? "  ← this one" : "";
+      const what = r.command ? ` — ${r.command}` : "";
+      return `${r.name}: ${r.cwd}${what}${here}`;
+    })
+    .join("\n");
+}
+
+function unknownName(name: string, records: readonly TerminalRecord[]): string {
+  const names = records.map((r) => r.name);
+  return names.length
+    ? `No terminal named "${name}". Named terminals: ${names.join(", ")}.`
+    : `No terminal named "${name}", and none are open yet.`;
+}

package/src/terminals/registry.ts

@@ -0,0 +1,107 @@
+// Named terminals: which name means which window, shared by every Privateer on this
+// machine. One agent opens "api"; a second agent, or the user's /term in any window,
+// can bring "api" to the front. So the record lives in the global dir, not in the
+// session.
+//
+// A record is (app, id) → name. Ids are ttys or tmux pane ids, and both get reused once
+// their window is gone, so records are pruned against what the backend says exists
+// before they are trusted (see listTerminals) — a stale "api" must not focus whatever
+// unrelated window inherited its tty.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "../config/paths.ts";
+import type { TerminalApp, TerminalBackend } from "./backends.ts";
+
+export interface TerminalRecord {
+  name: string;
+  app: TerminalApp;
+  /** The window's tty (/dev/ttys004) or tmux pane id (%12). */
+  id: string;
+  /** The folder it was opened in. */
+  cwd: string;
+  /** What the agent started in it, if anything. */
+  command?: string;
+  /** Epoch ms. */
+  createdAt: number;
+}
+
+export function registryPath(): string {
+  return join(globalDir(), "terminals.json");
+}
+
+export function readRegistry(): TerminalRecord[] {
+  try {
+    const parsed = JSON.parse(readFileSync(registryPath(), "utf8"));
+    const list = Array.isArray(parsed?.terminals) ? parsed.terminals : [];
+    return list.filter(
+      (r: any) => r && typeof r.name === "string" && typeof r.id === "string" && typeof r.app === "string",
+    );
+  } catch {
+    return [];
+  }
+}
+
+function writeRegistry(records: TerminalRecord[]): void {
+  const dir = globalDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // Rename over the old file so a second Privateer reading at the same moment sees the
+  // old list or the new one, never half of each.
+  const tmp = `${registryPath()}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ terminals: records }, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  renameSync(tmp, registryPath());
+}
+
+const MAX_NAME = 40;
+
+/** A usable name, or why not. Names are matched without regard to case. */
+export function checkName(raw: string): { name: string } | { error: string } {
+  const name = raw.trim().replace(/\s+/g, " ");
+  if (!name) return { error: "A terminal needs a name." };
+  if (name.length > MAX_NAME) return { error: `Keep terminal names to ${MAX_NAME} characters.` };
+  if (!/^[\p{L}\p{N}][\p{L}\p{N} ._-]*$/u.test(name)) {
+    return { error: "Terminal names are letters, digits, spaces, dots, dashes and underscores." };
+  }
+  return { name };
+}
+
+export const sameName = (a: string, b: string): boolean => a.toLowerCase() === b.toLowerCase();
+
+/** `base`, or `base-2`, `base-3`… — the first not already taken. */
+export function freeName(base: string, taken: readonly TerminalRecord[]): string {
+  const used = (n: string) => taken.some((r) => sameName(r.name, n));
+  if (!used(base)) return base;
+  for (let i = 2; ; i++) if (!used(`${base}-${i}`)) return `${base}-${i}`;
+}
+
+/** Records for windows that still exist on this backend. Others' records are kept. */
+export async function listTerminals(backend: TerminalBackend): Promise<TerminalRecord[]> {
+  const all = readRegistry();
+  let live: Set<string>;
+  try {
+    live = await backend.live();
+  } catch {
+    return all.filter((r) => r.app === backend.app); // can't check: trust, don't prune
+  }
+  const kept = all.filter((r) => r.app !== backend.app || live.has(r.id));
+  if (kept.length !== all.length) writeRegistry(kept);
+  return kept.filter((r) => r.app === backend.app);
+}
+
+export function findTerminal(records: readonly TerminalRecord[], name: string): TerminalRecord | undefined {
+  return records.find((r) => sameName(r.name, name));
+}
+
+/** Add or replace: one record per window, one window per name. */
+export function saveTerminal(rec: TerminalRecord): void {
+  const others = readRegistry().filter(
+    (r) => !(r.app === rec.app && r.id === rec.id) && !(r.app === rec.app && sameName(r.name, rec.name)),
+  );
+  writeRegistry([...others, rec]);
+}
+
+export function forgetTerminal(app: TerminalApp, id: string): void {
+  const all = readRegistry();
+  const kept = all.filter((r) => !(r.app === app && r.id === id));
+  if (kept.length !== all.length) writeRegistry(kept);
+}

package/src/tools/terminal.ts

@@ -0,0 +1,80 @@
+// `terminal` — open, focus, list and close named terminal windows the user can see.
+// The machinery and its limits are in src/terminals/; this is the model-facing surface.
+//
+// The gate (permissions/classify.ts) treats `open` with a command exactly like bash —
+// it IS running that command, just in a window the user watches — and `close` as
+// bash-kind too, since it ends whatever runs there. `focus` and `list` are not gated:
+// they change which window is in front and read a list of names.
+
+import { Type } from "typebox";
+import {
+  closeTerminal,
+  describeListing,
+  focusTerminal,
+  openTerminal,
+  terminalListing,
+} from "../terminals/index.ts";
+
+function text(t: string) {
+  return { content: [{ type: "text", text: t }], details: {} };
+}
+
+const ACTIONS = ["open", "focus", "list", "close"] as const;
+type Action = (typeof ACTIONS)[number];
+
+export const terminalToolDefinition = {
+  name: "terminal",
+  label: "Terminal",
+  description:
+    "Open, switch between, list and close named terminal windows on the user's screen. " +
+    "`open` starts a new window with a name (and optionally a command, typed into its shell — a dev server, " +
+    "a REPL, a log tail, another `privateer`), and gives it focus unless focus is false. `focus` brings a named " +
+    "terminal to the front — including the one you are running in (see `list`), so you can send the user back. " +
+    "`list` shows every named terminal and marks this one. `close` closes a window and ends what runs in it. " +
+    "You can NOT read a terminal's output: for commands whose output you need, use bash or a background task. " +
+    "Use this when the user wants to watch or use something themselves, or asks to switch terminals. " +
+    "Works in macOS Terminal, iTerm2, and inside tmux.",
+  parameters: Type.Object({
+    action: Type.Union(ACTIONS.map((a) => Type.Literal(a)), { description: "What to do." }),
+    name: Type.Optional(
+      Type.String({ description: "The terminal's name — required for open, focus and close. Short: \"api\", \"tests\"." }),
+    ),
+    command: Type.Optional(Type.String({ description: "open: a shell command to run in the new window." })),
+    cwd: Type.Optional(Type.String({ description: "open: the folder to start in. Defaults to the current one." })),
+    focus: Type.Optional(Type.Boolean({ description: "open: bring the new window to the front (default true)." })),
+  }),
+  async execute(
+    _id: string,
+    params: { action: Action; name?: string; command?: string; cwd?: string; focus?: boolean },
+    _signal?: AbortSignal,
+    _onUpdate?: unknown,
+    ctx?: any,
+  ) {
+    if (ctx && ctx.hasUI === false) return text("Terminal windows need an interactive session on the user's machine.");
+    const cwd = String(ctx?.cwd ?? process.cwd());
+    const name = String(params.name ?? "").trim();
+    const action: Action = ACTIONS.includes(params.action) ? params.action : "list";
+    if (action !== "list" && !name) return text(`Error: name is required for ${action}.`);
+    switch (action) {
+      case "open":
+        return text(
+          (
+            await openTerminal({
+              name,
+              cwd: params.cwd?.trim() || cwd,
+              ...(params.command?.trim() ? { command: params.command } : {}),
+              ...(params.focus === false ? { focus: false } : {}),
+            })
+          ).message,
+        );
+      case "focus":
+        return text((await focusTerminal(name, cwd)).message);
+      case "close":
+        return text((await closeTerminal(name, cwd)).message);
+      case "list": {
+        const l = await terminalListing(cwd);
+        return text("unsupported" in l ? l.unsupported : describeListing(l));
+      }
+    }
+  },
+};