@staix/agent-hub 0.12.22 → 0.12.24

package/src/cli/console-state.ts

@@ -1,4 +1,7 @@
-import { PERMISSION_MODES } from "../hub/permission-mode.ts";
+import { consoleNeeds, characterAttentionLine, attentionCommand } from "./attention.ts";
+import { CHARACTERS, petFrame, petSize, petFooterRows, type CharacterId, type PetSize, type PetPose } from "../pet/frame.ts";
+import { PEER_PALETTE } from "../ui/peer-palette.ts";
+import { PERMISSION_MODES, permissionBoundary } from "../hub/permission-mode.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import type { ProgressStage } from "../ui/task-progress.ts";
 import { sanitize } from "../hub/envelope.ts";
@@ -10,6 +13,11 @@ export interface Approval {
 export interface PermissionDefault { peer: string; mode: "never-ask"; source: string }
 export interface ConsoleEvent { text: string; peer?: string; kind?: string; tone?: Tone }
 export interface ConsoleState {
+  /** Older embedding callers omit choices and retain the original STAI/off toggle. */
+  petChoices?: readonly CharacterId[]; petCharacter?: CharacterId; petSize?: PetSize; petGlyphs?: "ascii" | "blocks";
+  attentionFacts?: { kind: "review" | "offline"; id: number; peer?: string }[];
+  attentionFingerprint?: string;
+  petEnabled?: boolean; petBlink?: boolean; attentionMessages?: { id?: string; peer?: string; important: boolean; since?: number }[]; storageBlocked?: boolean; recoveryNeed?: { id?: string; running: boolean; since?: number }; attentionSelection?: number;
   mode: "stream" | "panels"; panel: number; selection: number;
   /** The selected request, by id: a, d and v act on it alone, and it is cleared, never moved, when the request closes. */
   approvalId?: string;
@@ -35,12 +43,7 @@ export function initialConsoleState(panels = false): ConsoleState {
   return { mode: panels ? "panels" : "stream", panel: 1, selection: 0,
     input: "", editing: false, history: [], historyIndex: 0, approvals: [], events: [], peers: {}, budget: {}, tasks: [], tasksKnown: false, queue: [], permissionDefaults: [], permissionDefaultsHandled: [], detailOffset: 0, help: false, notice: "" };
 }
-/** Approval frequency does not create a common sandbox across native peers. */
-export function permissionBoundary(peer: string): string {
-  if (peer === "pi" || peer === "local") return `${peer}: inside hub sandbox, path guard and denylist`;
-  if (peer === "claude" || peer === "codex") return `${peer}: native vendor bounds; no hub sandbox`;
-  return `${peer}: runs its own tools; NO hub sandbox`;
-}
+export { permissionBoundary };
 function permissionModeRefusal(peer: string, mode: unknown): string | undefined {
   if (mode === "unmanaged") return `${peer} permission mode is unmanaged; use its native controls`;
   if (mode === "unverified") return `${peer} permission mode is unverified; start with ahub ${peer} and run a tool first`;
@@ -82,9 +85,9 @@ export function terminalText(value: unknown): string {
 export type Tone = "info" | "strong" | "success" | "attention" | "failure" | "muted" | "peerClaude" | "peerCodex" | "taskKeyword" | "number" | "issueRef" | "taskRef";
 export interface Span { text: string; tone?: Tone }
 export const PALETTE: Readonly<Record<Tone, string>> = Object.freeze({
-  info: "\x1b[36m", strong: "\x1b[1;36m", success: "\x1b[32m", attention: "\x1b[33m", failure: "\x1b[31m", muted: "\x1b[90m",
-  peerClaude: "\x1b[94m", peerCodex: "\x1b[96m",
-  taskKeyword: "\x1b[35m", number: "\x1b[1m", issueRef: "\x1b[4m", taskRef: "\x1b[4;35m",
+  info: PEER_PALETTE.hub.ansi, strong: "\x1b[1;36m", success: PEER_PALETTE.local.ansi, attention: PEER_PALETTE.pi.ansi, failure: "\x1b[31m", muted: PEER_PALETTE.other.ansi,
+  peerClaude: PEER_PALETTE.claude.ansi, peerCodex: PEER_PALETTE.codex.ansi,
+  taskKeyword: PEER_PALETTE.kimi.ansi, number: "\x1b[1m", issueRef: "\x1b[4m", taskRef: "\x1b[4;35m",
 });
 export function paint(line: Span[], color: boolean): string {
   return line.map(span => {
@@ -174,7 +177,7 @@ export function resolveColor(flag: string | undefined, env: { isTTY: boolean; TE
   if (flag === "always") return true;
   if (flag === "never") return false;
   if (flag === undefined || flag === "auto") return env.isTTY && env.TERM !== "dumb" && !env.NO_COLOR;
-  return new Error("usage: ahub console [--panels] [--color=auto|always|never]");
+  return new Error("usage: ahub <command> [--color=auto|always|never]");
 }
 export function stateTone(state: string): Tone | undefined {
   if (state === "idle" || state === "approved") return "success";
@@ -184,12 +187,15 @@ export function stateTone(state: string): Tone | undefined {
 }
 const span = (text: unknown, tone?: Tone): Span => ({ text: String(text ?? ""), ...(tone ? { tone } : {}) });
 /** One line of sanitized text: a newline or a tab becomes a space, as wrap() counts a tab (stringWidth("\t") is 0). */
-const flat = (value: unknown) => terminalText(value).replace(/[\n\t]/g, " ");
+const flat = (value: unknown) => {
+  const text = terminalText(value), line = text.replace(/[\n\t]/g, " ");
+  return text.includes("\t") ? terminalText(line) : line;
+};
 /**
  * Clip sanitized plain text to the width and keep the tones of the surviving prefix. Widths are measured as paint()
  * prints them: paint() sanitizes each span again, and a cut that ends a span in `[agent-hub` earns it a `> `.
  */
-function fitLine(line: Span[], columns: number): Span[] {
+export function fitLine(line: Span[], columns: number): Span[] {
   const clean = line.map(s => ({ ...s, text: flat(s.text) }));
   if (Bun.stringWidth(clean.map(s => s.text).join("")) <= columns) return clean;
   const marker = ".".repeat(Math.max(0, Math.min(3, columns)));
@@ -216,7 +222,9 @@ export function fit(value: unknown, columns: number): string {
 export function wrap(value: unknown, columns: number, hang = 4): string[] {
   const lines: string[] = [];
   const half = Math.floor(columns / 2);
-  const width = (text: string) => Bun.stringWidth(sanitize(text));
+  // A bare chunk ending in "--- from" becomes a header marker when table padding follows it.
+  const quoteChunk = (text: string) => sanitize(text + " ").slice(0, -1);
+  const width = (text: string) => Bun.stringWidth(quoteChunk(text));
   for (const part of terminalText(value).replace(/\t/g, " ").split("\n")) {
     const indent = /^\s*/.exec(part)![0];
     const lead = Math.min(Bun.stringWidth(indent), half);
@@ -224,7 +232,7 @@ export function wrap(value: unknown, columns: number, hang = 4): string[] {
     const first = lines.length;
     let start = " ".repeat(lead);
     let line = start;
-    const push = () => { lines.push(sanitize(line.trimEnd())); line = start = pad; };
+    const push = () => { lines.push(quoteChunk(line.trimEnd())); line = start = pad; };
     for (const token of part.slice(indent.length).match(/\s+|\S+/g) ?? []) {
       if (width(line + token) <= columns) { line += token; continue; }
       if (line !== start) push();
@@ -234,7 +242,7 @@ export function wrap(value: unknown, columns: number, hang = 4): string[] {
         line += char;
       }
     }
-    if (line !== start || lines.length === first) lines.push(sanitize(line.trimEnd()));
+    if (line !== start || lines.length === first) lines.push(quoteChunk(line.trimEnd()));
   }
   return lines;
 }
@@ -308,7 +316,7 @@ export function permissionText(a: Pick<Approval, "id" | "peer" | "title" | "opti
 const KEYS: [string, string[]][] = [
   ["Everywhere", ["Tab stream/panels", ": command", "? keys", "Esc back", "q quit"]],
   ["Command", ["Enter run", "Esc cancel", "Up/Down history", "Ctrl-U clear"]],
-  ["Panels", ["1-5 panel", "j/k or arrows move", "Enter view", "j/k scroll a view"]],
+  ["Panels", ["1-5 panel", "Left/Right panel", "j/k or Up/Down move", "Enter view", "j/k scroll a view"]],
   ["Approvals", ["a allow (then y)", "d deny", "v view", "[ ] select"]],
   ["Peers", ["p pause", "r resume", "m permission mode"]],
   ["Tasks", ["a assign (then y)", "r review"]],
@@ -316,9 +324,9 @@ const KEYS: [string, string[]][] = [
   ["Events", ["f peer filter", "g kind filter"]],
 ];
 /** The `?` key table: one group per panel, its keys kept whole and packed into the width after the group column. */
-export function keyTable(columns: number): Span[][] {
+export function keyTable(columns: number, attention = false, characters = false): Span[][] {
   const lines: Span[][] = []; const pad = 12;
-  for (const [group, items] of KEYS) {
+  for (const [group, items] of [...KEYS, ...(attention ? [[characters ? "Pet" : "Attention", ["n next need", characters ? "P next character/off" : "P STAI/off"]] as [string, string[]]] : [])]) {
     let text = ""; let head = group;
     const flush = () => { lines.push([span(head.padEnd(pad), head ? "info" : undefined), span(text)]); head = ""; text = ""; };
     for (const item of items) { if (text && pad + Bun.stringWidth(`${text}   ${item}`) > columns) flush(); text = text ? `${text}   ${item}` : item; }
@@ -344,7 +352,7 @@ function bound(s: ConsoleState): ConsoleState {
   if (s.requestDetail && s.requestDetail !== s.approvalId) { s.requestDetail = s.approvalId; s.detailOffset = 0; }
   return s;
 }
-const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "permission", "ask", "remember", "route", "turns", "undo", "check-path", "report"]);
+const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "permission", "ask", "remember", "route", "sdlc", "turns", "undo", "check-path", "report"]);
 /** A tiny argv parser, never a shell. Quotes group arguments; backslash escapes one character. */
 export function parseConsoleCommand(input: string): string[] {
   const words: string[] = []; let word = ""; let quote = ""; let escaped = false; let started = false;
@@ -380,6 +388,7 @@ export const selectedApproval = (s: ConsoleState) => s.approvals.find(a => a.id
 /** The selected row: the Approvals panel's is the selected request (-1 when none is). */
 const selection = (s: ConsoleState) => s.panel === 2 ? s.approvals.findIndex(a => a.id === s.approvalId) : s.selection;
 export function reduceConsole(state: ConsoleState, key: string, now = Date.now()): { state: ConsoleState; effects: ConsoleEffect[] } {
+  const attentionKeyBlocked = !!(state.confirm || state.optionChoice || state.modeChoice || state.help || state.editing || state.input);
   // A notice answers the key before this one; one that pruning raises now stays.
   let s = pruneApprovals({ ...state, notice: "" }, now); const effects: ConsoleEffect[] = [];
   const done = () => ({ state: bound(s), effects });
@@ -441,10 +450,54 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     } else if (!key.startsWith("\x1b")) s.input += terminalText(key).replace(/\n/g, "");
     return done();
   }
+  if ((key === "n" || key === "P") && attentionKeyBlocked) return done();
   if (key === "q") { effects.push({ type: "exit" }); return done(); }
+  if (key === "P" && !s.optionChoice && !s.help) {
+    const choices = s.petChoices;
+    if (!choices?.length) s.petEnabled = !s.petEnabled;
+    else if (!s.petEnabled) { s.petEnabled = true; s.petCharacter = choices[0]; }
+    else { const next = choices.indexOf(s.petCharacter ?? "stai") + 1; s.petEnabled = next < choices.length; if (s.petEnabled) s.petCharacter = choices[next]; }
+    return done();
+  }
+  if (key === "n" && s.petEnabled && !s.optionChoice && !s.help) {
+    const items = consoleNeeds(s, now).items;
+    if (!items.length) return done();
+    const fingerprint = JSON.stringify(items);
+    const prior = s.attentionFingerprint === fingerprint ? s.attentionSelection ?? -1 : -1;
+    const index = (prior + 1) % items.length;
+    s.attentionFingerprint = fingerprint;
+    s.attentionSelection = index;
+    const item = items[index]!;
+    let navigated = false;
+    if (item.kind === "approval") {
+      s.approvalId = String(item.id);
+      if (s.mode === "panels") { s.panel = 2; s.selection = s.approvals.findIndex(row => row.id === item.id); }
+      navigated = true;
+    } else if (item.kind === "delivery" && s.mode === "panels") {
+      const rows = s.queue.filter(row => row.state === "needs_review" || row.state === "queued");
+      const selected = item.id === undefined ? -1 : rows.findIndex(row => row.id === item.id);
+      if (selected >= 0) { s.panel = 4; s.selection = selected; navigated = true; }
+    } else if (item.kind === "review" && s.mode === "panels") {
+      const rows = panelRows({ ...s, panel: 3 });
+      const selected = rows.findIndex(row => row.id === item.id);
+      if (selected >= 0) { s.panel = 3; s.selection = selected; navigated = true; }
+    }
+    if (navigated) { s.detail = undefined; s.requestDetail = undefined; }
+    else {
+      const command = attentionCommand(item);
+      const text = `${item.kind}${item.peer ? ` ${item.peer}` : ""}${item.id ? ` ${item.id}` : ""}: ${command}`;
+      if (s.mode === "panels") notify(s, text, now, "attention");
+      effects.push({ type: "print", text, kind: "attention", tone: "attention" });
+    }
+    return done();
+  }
   if (key === "\t") { s.mode = s.mode === "panels" ? "stream" : "panels"; s.detail = undefined; s.requestDetail = undefined; return done(); }
   if (key === ":") { s.editing = true; return done(); }
-  if (s.mode === "panels" && /^[1-5]$/.test(key) && !s.optionChoice) { s.panel = Number(key); s.selection = 0; s.detail = undefined; s.requestDetail = undefined; return done(); }
+  const switchPanel = (panel: number) => { s.panel = panel; s.selection = 0; s.detail = undefined; s.requestDetail = undefined; return done(); };
+  if (s.mode === "panels" && /^[1-5]$/.test(key) && !s.optionChoice) return switchPanel(Number(key));
+  // Right and Left are the digit of the next or previous tab, wrapping at both ends (#309); the same guards as the
+  // digits apply (the confirm, mode-choice, key-table and editing branches above returned already).
+  if (s.mode === "panels" && (key === "\x1b[C" || key === "\x1b[D") && !s.optionChoice) return switchPanel((s.panel + (key === "\x1b[C" ? 0 : 3)) % 5 + 1);
   if (key === "?") {
     if (s.mode === "stream") effects.push({ type: "keys" });
     else s.help = !s.help;
@@ -522,7 +575,10 @@ export function renderConsole(s: ConsoleState, columns: number, rows = 24, now =
   return renderConsoleLines(s, columns, rows, now).map(line => paint(line, false));
 }
 const NOTICE_MS = 10_000;
-const TABLES: Record<number, string[]> = {
+export function activeNotice(s: Pick<ConsoleState, "notice" | "noticeAt">, now = Date.now()): boolean {
+  return !!s.notice && now - (s.noticeAt ?? now) < NOTICE_MS;
+}
+export const TABLES: Record<number, string[]> = {
   1: ["PEER", "STATE", "LINK", "Q", "!", "REVIEW", "PAUSE", "QUOTA", "MODEL"],
   2: ["ID", "PEER", "LEFT", "TITLE"],
   3: ["ID", "STATE", "OWNER", "REVIEWER", "CLASS", "AGE", "TITLE", "STAGE"],
@@ -531,16 +587,16 @@ const TABLES: Record<number, string[]> = {
 const showPermissionModes = (s: ConsoleState) => Object.values(s.peers).some(peer => peer.permissionMode && peer.permissionMode !== "ask");
 const count = (n: unknown) => typeof n === "number" && n ? String(n) : "-";
 /** One span per column of a panel row; zero counters and unknown values read `-`. */
-function cells(s: ConsoleState, row: any, selected: boolean, now: number, stages?: Map<number, ProgressStage>): Span[] {
+export function cells(s: ConsoleState, row: any, selected: boolean, now: number, stages?: Map<number, ProgressStage>): Span[] {
   const id = (text: unknown, tone: Tone | undefined) => span(text, tone && (selected ? "strong" : tone));
   if (s.panel === 1) {
     const b = s.budget[row.id];
     const paused = b?.paused ? `budget ${relative(b.paused.resetsAt, now)}` : row.paused && typeof row.paused === "object"
       ? `${row.paused.by ?? "paused"}${typeof row.paused.at === "number" ? ` ${duration(now - row.paused.at)}` : ""}`
       : row.paused === "manual" ? "user" : row.paused ? String(row.paused).split(":")[0] : "-";
-    return [id(row.id, row.state === "offline" ? undefined : "info"), span(row.state, stateTone(row.state)),
+    return [id(row.id, row.state === "offline" ? undefined : "info"), span(row.rostered === false ? `${row.state} off roster` : row.state, stateTone(row.state)),
       ...(showPermissionModes(s) ? [span(row.permissionMode && row.permissionMode !== "ask" ? row.permissionMode : "-", row.permissionMode === "never-ask" ? "attention" : undefined)] : []),
-      span(row.toolsOnly ? "tools-only" : row.attached === false ? "detached" : "attached", row.toolsOnly ? "attention" : undefined),
+      span(row.pullOnly && row.id === "kimi" ? "pull-only" : row.toolsOnly ? "tools-only" : row.attached === false ? "detached" : "attached", row.toolsOnly ? "attention" : undefined),
       span(count(row.queued)), span(count(row.queuedImportant), row.queuedImportant ? "attention" : undefined),
       span(count(row.needsReview), row.needsReview ? "failure" : undefined), span(paused, paused === "-" ? undefined : "attention"),
       span(b?.windows?.length ? b.windows.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%${typeof w.resetsAt === "number" ? ` ${relative(w.resetsAt, now)}` : ""}`).join(", ") : "-"),
@@ -554,23 +610,26 @@ function cells(s: ConsoleState, row: any, selected: boolean, now: number, stages
     const stage = stages?.get(row.id);
     const meter = stage ? "[" + "#".repeat(stage.stage - (stage.changes ? 1 : 0)) + (stage.changes ? "!" : "") + "-".repeat(4 - stage.stage) + "]" : "[----]";
     return [id(`#${row.id}`, "info"), span(`${row.state}${failed && row.state !== last.event ? ` ${last.event}` : ""}${row.ready ? " ready" : ""}${stage?.waiting ? " waiting" : ""}`, failed ? "failure" : row.ready || stage?.waiting ? "attention" : stateTone(row.state)),
-      span(row.owner ?? "-"), span(row.reviewer ?? "-"), span(row.class ?? "-"), span(typeof at === "number" ? duration(now - at) : "-", "muted"), span(row.title), span(meter, stage?.changes ? "failure" : stateTone(row.state))];
+      span(row.owner ?? "-"), span(row.reviewer ?? "-"), span(row.profileClass ? `${row.profileClass} (base ${row.class})` : row.class ?? "-"), span(typeof at === "number" ? duration(now - at) : "-", "muted"), span(row.title), span(row.lifecycle ? `${meter} ${row.lifecycle.workflow ? row.lifecycle.workflow + " " : ""}SDLC ${row.lifecycle.stage}${row.lifecycle.definition ? ` (base ${row.lifecycle.definition.base}) / next: ${row.lifecycle.actor} / entry: ${row.lifecycle.entry?.length ? "blocked" : "ready"} / exit: ${row.lifecycle.exit?.length ? "blocked" : "ready"}` : ""}: ${row.lifecycle.next}` : meter, stage?.changes ? "failure" : stateTone(row.state))];
   }
-  if (s.panel === 4) return [id(row.id, "info"), span(row.peer), span(row.state, stateTone(row.state)), span(row.revision ?? "-"), span(typeof row.createdAt === "number" ? duration(now - row.createdAt) : "-", "muted")];
+  if (s.panel === 4) return [id(row.id, "info"), span(row.peer), span(row.rostered === false ? `${row.state} off roster` : row.state, stateTone(row.state)), span(row.revision ?? "-"), span(typeof row.createdAt === "number" ? duration(now - row.createdAt) : "-", "muted")];
   const [header, ...body] = String(row.text).split("\n");
-  return [span(header, row.tone), ...(body.length ? [span("\n" + body.join("\n"))] : [])];
+  // The header goes through the stream's own tokenizer with the event's tone and kind, on the same tab-flattened
+  // text the stream tokenizes, so an event reads the same in both places (#309); body lines stay plain, as in the
+  // stream. Colour off concatenates to the same bytes.
+  return [...streamTokens((header ?? "").replace(/\t/g, " "), row.tone, row.kind), ...(body.length ? [span("\n" + body.join("\n"))] : [])];
 }
 /**
  * A header row, then the rows, each column starting at the same place on every row: two spaces apart, as wide as its
  * widest cell or header (Bun.stringWidth, at most a third of the width, wider cells cut with the marker); the last column
- * takes the rest.
+ * takes the rest. One-shot callers may supply widths for already-wrapped cells; console defaults stay unchanged.
  */
-function table(head: string[], rows: Span[][], columns: number): Span[][] {
+export function table(head: string[], rows: Span[][], columns: number, explicitWidths?: readonly number[]): Span[][] {
   const cap = Math.max(24, Math.floor(columns / 3));
   const width = (cell: Span | undefined) => Bun.stringWidth(flat(cell?.text));
-  const widths = head.map((h, i) => Math.min(cap, rows.reduce((max, row) => Math.max(max, width(row[i])), Bun.stringWidth(h))));
+  const widths = explicitWidths ? [...explicitWidths] : head.map((h, i) => Math.min(cap, rows.reduce((max, row) => Math.max(max, width(row[i])), Bun.stringWidth(h))));
   const flexible = head.includes("STAGE") ? head.indexOf("TITLE") : head.length - 1;
-  if (head.includes("STAGE")) {
+  if (!explicitWidths && head.includes("STAGE")) {
     // Keep the original columns adjacent; stage meters occupy a fixed right-edge column.
     const room = () => columns - 2 - widths.reduce((sum, value, index) => sum + (index === flexible ? 0 : value), 0) - 2 * (head.length - 1);
     for (const key of ["CLASS", "OWNER", "REVIEWER", "AGE", "STATE"]) {
@@ -579,7 +638,9 @@ function table(head: string[], rows: Span[][], columns: number): Span[][] {
     }
     widths[flexible] = Math.max(0, room());
   }
-  return [head.map(h => span(h, "info")), ...rows].map(row => row.map((cell, i) => {
+  const headerCells = explicitWidths ? head.map((h, i) => wrap(h, Math.max(1, widths[i]!), 0)) : undefined;
+  const headers = headerCells ? Array.from({ length: Math.max(...headerCells.map(cell => cell.length)) }, (_, n) => head.map((_, i) => span(headerCells[i]![n] ?? "", "info"))) : [head.map(h => span(h, "info"))];
+  return [...headers, ...rows].map(row => row.map((cell, i) => {
     if (i === head.length - 1 && flexible === i) return cell;
     const text = fit(cell.text, widths[i]!);
     return { ...cell, text: text + " ".repeat(Math.max(0, widths[i]! - Bun.stringWidth(text)) + (i === head.length - 1 ? 0 : 2)) };
@@ -611,6 +672,35 @@ function header(s: ConsoleState, columns: number): Span[] {
 }
 /** The label column is the hub's own: a cut title or option list is marked `(more)` there; Enter shows it whole. */
 const more = (line: Span[], text?: string): Span[] => [span("(more)".padEnd(Bun.stringWidth(line[0]!.text)), "attention"), ...(text === undefined ? line.slice(1) : [span(text)])];
+export function consoleFooterRows(s: ConsoleState, columns: number, rows: number): number {
+  return s.petEnabled ? petFooterRows(petSize(s.petSize, columns, rows)) : 4;
+}
+function decoratePetFooter(s: ConsoleState, columns: number, rows: number, now: number, rule: Span[], footer: Span[][], noticeShown: boolean): Span[][] {
+  if (!s.petEnabled) return [rule, ...footer];
+  const value = consoleNeeds(s, now), character = s.petCharacter ?? "stai", size = petSize(s.petSize, columns, rows);
+  const tone: Tone = value.state === "blocked" ? "failure" : value.act ? "attention" : "muted";
+  if (size === "line") {
+    const text = characterAttentionLine(value, character, now, s.petBlink, true, s.petGlyphs);
+    return [Bun.stringWidth(text) + 4 <= columns ? [span("-".repeat(columns - Bun.stringWidth(text) - 2) + " ", "muted"), span(text.slice(0, 5)), span(text.slice(5), tone), span("-", "muted")] : rule, ...footer];
+  }
+  const pose: PetPose = s.petBlink && value.items.some(item => item.kind === "approval") && Math.floor(now / 1000) % 2 ? "waitingBlink" : value.state;
+  const frame = petFrame(character, pose, size, s.petGlyphs), width = size === "mini" ? 9 : 12, height = size === "mini" ? 3 : 8;
+  const available = columns - width - 1, caption = characterAttentionLine(value, character, now, false).slice(6);
+  const left: Span[][] = [[span(caption, tone)], footer[0]!, footer[1]!];
+  // Notices and source paths stay in their existing views, never beside an expanded character.
+  if (noticeShown || s.confirm?.type === "permission_default") left[2] = [span(`${s.approvals.length} approvals / ${value.act} action / ${value.watch} watch`, tone)];
+  for (let index = 0; index < height - 3; index++) {
+    const item = value.items[index];
+    left.push(item ? [span([item.kind, item.peer, item.id].filter(part => part !== undefined).join(" "), item.level === "act" ? "attention" : "muted")] : []);
+  }
+  const result = left.map((line, index) => {
+    const fitted = fitLine(line, available), text = fitted.map(cell => cell.text).join("");
+    const body = frame[index] ?? " ".repeat(width), accent = CHARACTERS[character].accent?.[size];
+    const bodySpans = accent?.row === index ? [span(body.slice(0, accent.start)), span(body.slice(accent.start, accent.start + accent.length), "attention"), span(body.slice(accent.start + accent.length))] : [span(body)];
+    return [...fitted, span(" ".repeat(Math.max(0, available - Bun.stringWidth(text)) + 1)), ...bodySpans];
+  });
+  return [...result, footer[2]!]; // The prompt line remains full-width and in its original terminal row.
+}
 export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24, now = Date.now()): Span[][] {
   const permission = selectedApproval(s);
   let prompt = s.editing ? `: ${s.input}` : hint(s, columns);
@@ -626,14 +716,14 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     if (p.permissionMode && p.permissionMode !== "ask") summary.push(span(` ${p.permissionMode}`, "attention"));
     if (p.needsReview) summary.push(span(` review${p.needsReview}`, "failure"));
     if (p.paused) summary.push(span(" paused", "attention"));
-    if (p.toolsOnly) summary.push(span(" tools-only: ahub claude", "attention"));
+    if (p.toolsOnly) summary.push(span(id === "kimi" ? ` pull-only, read ${typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never"}` : " tools-only: ahub claude", "attention"));
   }
   const quotas = Object.entries(s.budget).map(([id, b]) => `${id}:${b.windows?.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%`).join("/") ?? "?"}`).join(" ");
   if (quotas) summary.push(span(`${summary.length ? " | " : ""}${quotas}`));
   const approvals = [span(plural(s.approvals.length, "approval"), s.approvals.length ? "attention" : undefined)];
   if (permission) approvals.push(span(` | ${permission.peer} ${permission.id}`, "attention"), span(` ${duration(permission.expiresAt - now)} left`, "muted"));
   else if (s.approvals.length) approvals.push(span(" | none selected", "muted"));
-  const noticeShown = !!s.notice && now - (s.noticeAt ?? now) < NOTICE_MS;
+  const noticeShown = activeNotice(s, now);
   if (noticeShown) approvals.push(span(" | "), span(s.notice, s.noticeTone ?? "failure"));
   const neverPeer = s.confirm?.type === "permission_default" ? s.confirm.peer : s.confirm?.type === "command" && s.confirm.args[0] === "permission" && s.confirm.args[2] === "never-ask" ? s.confirm.args[1] : undefined;
   const defaultSource = s.confirm?.type === "permission_default" ? s.confirm.source : undefined;
@@ -649,13 +739,15 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     if (!noticeShown && defaultSource === undefined && (counts || !s.approvals.length) && Bun.stringWidth(taskCount.text + " | " + approvals.map(s => s.text).join("")) <= columns) {
       footer[1] = fitLine([taskCount, span(" | "), ...approvals], columns);
     }
-    return [rule, ...footer];
+    return decoratePetFooter(s, columns, rows, now, rule, footer, noticeShown);
   }
   const progress = taskProgress(s.tasks);
-  const height = rows - 6; // header, rule, body, rule, three footer lines
+  const bodyHeight = rows - 2 - consoleFooterRows(s, columns, rows);
+  const noticeLines = noticeShown && s.petEnabled && petSize(s.petSize, columns, rows) !== "line" ? wrap(`Notice: ${s.notice}`, columns).slice(0, Math.max(0, bodyHeight - 6)).map(text => [span(text, s.noticeTone ?? "failure")]) : [];
+  const height = bodyHeight - noticeLines.length;
   const lines: Span[][] = [];
   if (s.confirm?.type === "permission_default") lines.push(...fieldLines([["default", `${s.confirm.peer} never-ask`], ["source", s.confirm.source], ["bounds", permissionBoundary(s.confirm.peer)], ["decision", "y enables; n cancels for this hub; Esc defers; until then ask"]], columns, now).flat());
-  else if (s.help) lines.push(...keyTable(columns));
+  else if (s.help) lines.push(...keyTable(columns, !!s.petEnabled || !!s.petChoices?.length, !!s.petChoices?.length));
   else if (s.detail !== undefined || (s.requestDetail && permission)) {
     const detail = s.detail !== undefined ? detailLines(s.detail, columns, now) : fieldLines(approvalFields(permission!), columns, now).flat();
     lines.push(...detail.slice(Math.min(s.detailOffset, Math.max(0, detail.length - height))));
@@ -696,5 +788,5 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     }
   }
   const body = lines.slice(0, height); while (body.length < height) body.push([]);
-  return [header(s, columns), rule, ...body, rule, ...footer];
+  return [header(s, columns), rule, ...noticeLines, ...body, ...decoratePetFooter(s, columns, rows, now, rule, footer, noticeShown)];
 }

package/src/cli/console.ts

@@ -7,6 +7,11 @@ import { renderTailEvent } from "./tail-render.ts";
 import { syncPermissionDefaults, permissionDefaultText, approvalFrom, initialConsoleState, keyTable, notify, paint, panelRows, permissionText, plural, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, streamTokens, wrapStreamTokens, terminalText, wrap } from "./console-state.ts";
 import type { ConsoleEffect, ConsoleEvent, Detail, Tone } from "./console-state.ts";
 import type { BusEvent } from "../hub/bus.ts";
+import { consoleNeeds, attentionFacts } from "./attention.ts";
+import { loadPetConfig } from "./pet-config.ts";
+import { CHARACTER_IDS, petGlyphs, petSize } from "../pet/frame.ts";
+import { activeNotice, consoleFooterRows } from "./console-state.ts";
+import { characterAttentionLine } from "./attention.ts";
 
 export interface ConsoleTerminal {
   columns: number; rows: number; isTTY: boolean; isRaw?: boolean;
@@ -22,8 +27,9 @@ export interface ConsoleOptions {
   cwd: string; stateDir: string; panels?: boolean; columns?: number; rows?: number;
   terminal?: ConsoleTerminal;
   color?: boolean;
+  noPet?: boolean;
   /** Injected command runner must use argv, closed stdin, and return a cancellation handle. */
-  runCommand?: (args: string[], output: (text: string) => void, done: () => void) => (() => void);
+  runCommand?: (args: string[], output: (text: string) => void, done: () => void, columns?: number) => (() => void);
   pollMs?: number;
 }
 export const RESTORE_CONSOLE = "\x1b[?1049l\x1b[r\x1b[0m\x1b[?25h";
@@ -67,6 +73,11 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   const { client } = options; const terminal = options.terminal ?? nativeTerminal();
   const color = options.color ?? resolveColor(undefined, { isTTY: terminal.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR }) === true;
   let state = initialConsoleState(!!options.panels); state.project = basename(options.cwd);
+  const pet = loadPetConfig(options.cwd);
+  state.petEnabled = pet.enabled && !options.noPet; state.petBlink = pet.blink;
+  state.petChoices = CHARACTER_IDS; state.petCharacter = pet.character ?? "stai";
+  state.petSize = pet.size; state.petGlyphs = petGlyphs(pet.glyphs);
+  let lastAct = 0; let lastBell = -Infinity;
   let columns = options.columns ?? terminal.columns; let rows = options.rows ?? terminal.rows;
   let active = true; let inAlternate = false; let plain = !terminal.isTTY || columns < 80 || rows < 24;
   let polling = false; let childRunning = false; let cancelChild: (() => void) | undefined;
@@ -74,15 +85,22 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   const removers: (() => void)[] = []; const timers: ReturnType<typeof setInterval>[] = [];
   let resolveDone: () => void = () => {}; const done = new Promise<void>(resolve => { resolveDone = resolve; });
   let pendingStream: ConsoleEvent[] = []; let droppedStream = 0;
+  let priorStreamFooterStart: number | undefined;
+  let lastExpandedNotice = "";
   const notice = (text: string) => notify(state, text, Date.now());
   const safeWrite = (text: string) => terminal.write(paint([{ text }], color));
-  const streamLines = (event: ConsoleEvent) => terminalText(event.text).split("\n").flatMap((text, index) => index === 0 ? wrapStreamTokens(text, columns, event.tone, event.kind) : wrap(text, columns).map(line => [{ text: line }]));
+  const streamLines = (event: ConsoleEvent) => terminalText(event.text).replace(/\t/g, " ").split("\n").flatMap((text, index) => {
+    // Tabs are flattened before measuring, as wrap() does; commands already wrap cells at their own offsets.
+    if (event.kind === "command" && Bun.stringWidth(text) <= columns) return [[{ text }]];
+    return index === 0 ? wrapStreamTokens(text, columns, event.tone, event.kind) : wrap(text, columns).map(line => [{ text: line }]);
+  });
   const writeStream = (event: ConsoleEvent) => {
-    terminal.write(`\x1b[${rows - 4};1H`); // the scroll region ends above the rule and the three footer lines
+    terminal.write(`\x1b[${rows - consoleFooterRows(state, columns, rows)};1H`); // the scroll region ends above the rule and the three footer lines
     for (const line of streamLines(event)) { terminal.write(paint(line, color)); terminal.write("\r\n"); }
   };
   /** `record: false` is for the console's own prints (the key table, a request viewed again): not events, so not in Events. */
   const stream = (event: ConsoleEvent, record = true) => {
+    if (event.kind === "command") event = { ...event, text: terminalText(event.text).replace(/\t/g, " ") };
     if (record) state.events = [...state.events, { ...event, text: terminalText(event.text) }].slice(-1000);
     if (plain) {
       const [header, ...body] = terminalText(event.text).split("\n");
@@ -92,15 +110,34 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     else { pendingStream.push(event); if (pendingStream.length > 1000) { pendingStream.shift(); droppedStream++; } }
   };
   const draw = () => {
-    if (!active || plain) return;
+    if (!active) return;
+    if (state.petEnabled) {
+      const attention = consoleNeeds(state, Date.now());
+      if (plain && attention.act !== lastAct) safeWrite(characterAttentionLine(attention, state.petCharacter) + "\n");
+      if (pet.bell && !lastAct && attention.act && attention.items.some(item => item.level === "act" && item.kind !== "message") && Date.now() - lastBell >= 60000) { terminal.write("\x07"); lastBell = Date.now(); }
+      lastAct = attention.act;
+    }
+    if (plain) return;
+    const returningToStream = state.mode === "stream" && inAlternate;
     if (state.mode === "panels" && !inAlternate) { terminal.write("\x1b[r\x1b[?1049h\x1b[2J"); inAlternate = true; }
     else if (state.mode === "stream" && inAlternate) {
-      terminal.write(`\x1b[?1049l\x1b[1;${rows - 4}r`); inAlternate = false;
+      terminal.write(`\x1b[?1049l\x1b[1;${rows - consoleFooterRows(state, columns, rows)}r`); inAlternate = false;
+    }
+    const footerStart = rows - consoleFooterRows(state, columns, rows) + 1;
+    if (state.mode === "stream" && priorStreamFooterStart !== undefined && priorStreamFooterStart < footerStart) {
+      for (let row = priorStreamFooterStart; row < footerStart; row++) terminal.write(`\x1b[${row};1H\x1b[2K`);
+    }
+    if (state.mode === "stream") priorStreamFooterStart = footerStart;
+    terminal.write(state.mode === "stream" ? `\x1b[1;${rows - consoleFooterRows(state, columns, rows)}r` : "\x1b[r");
+    if (returningToStream) {
       if (droppedStream) writeStream({ text: `${plural(droppedStream, "older panel-mode event")} omitted from console memory; inspect hub.log for the full stream.` });
       for (const event of pendingStream) writeStream(event);
       pendingStream = []; droppedStream = 0;
     }
-    terminal.write(state.mode === "stream" ? `\x1b[1;${rows - 4}r` : "\x1b[r");
+    if (state.mode === "stream" && state.petEnabled && petSize(state.petSize, columns, rows) !== "line" && activeNotice(state)) {
+      const key = JSON.stringify([state.noticeAt, state.notice]);
+      if (key !== lastExpandedNotice) { lastExpandedNotice = key; stream({ text: `Notice: ${state.notice}`, kind: "notice", tone: state.noticeTone ?? "failure" }, false); }
+    }
     const lines = renderConsoleLines(state, columns, rows);
     const start = rows - lines.length + 1;
     for (const [index, line] of lines.entries()) { terminal.write(`\x1b[${start + index};1H\x1b[2K`); terminal.write(paint(line, color)); }
@@ -131,7 +168,12 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       if (!active) return;
       const [status, budget, tasks, queue, ready] = replies;
       if (status.status?.tasks && status.ok !== false) state.taskCounts = status.status.tasks;
-      if (status.status?.peers) state.peers = status.status.peers;
+      if (status.status?.peers) state.peers = Object.fromEntries(Object.entries(status.status.peers).map(([peer, value]) => [peer, { ...(value as object), ...status.status.roleInfo?.[peer] }]));
+      if (status.status && status.ok !== false) {
+        state.attentionFacts = attentionFacts(status.status.attentionItems);
+        state.storageBlocked = !!status.status.deliveryError;
+        state.recoveryNeed = status.status.recovery ? { id: status.status.recovery.operationId, running: true } : undefined;
+      }
       if (syncPermissionDefaults(state, status.status?.permissionDefaults) && state.confirm?.type === "permission_default") stream({ text: permissionDefaultText(state.confirm), kind: "permission_default", peer: state.confirm.peer, tone: "attention" });
       if (budget.budget) state.budget = budget.budget;
       if (tasks?.ok) { const parsed = JSON.parse(tasks.text); if (Array.isArray(parsed)) {
@@ -145,9 +187,10 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     } catch (error) { if (active) { notice(String((error as Error).message)); draw(); } }
     finally { polling = false; }
   };
-  const run = options.runCommand ?? ((args, output, finished) => {
+  const run = options.runCommand ?? ((args, output, finished, commandColumns) => {
     const child = Bun.spawn([process.execPath, fileURLToPath(new URL("./main.ts", import.meta.url)), "--project", options.cwd, ...args], {
       cwd: options.cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe",
+      env: { ...process.env, COLUMNS: String(commandColumns), NO_COLOR: "1" },
     });
     const read = async (source: ReadableStream<Uint8Array>) => {
       const decoder = new TextDecoder(); const reader = source.getReader();
@@ -172,7 +215,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       if (!action.option) stream({ text: `  ! denial requested for permission ${action.id}`, kind: "permission", tone: "failure" });
       return;
     }
-    if (action.type === "keys") return stream({ text: keyTable(columns).map(line => paint(line, false)).join("\n"), kind: "console" }, false);
+    if (action.type === "keys") return stream({ text: keyTable(columns, !!state.petEnabled || !!state.petChoices?.length, !!state.petChoices?.length).map(line => paint(line, false)).join("\n"), kind: "console" }, false);
     if (action.type === "print") return stream({ text: action.text, kind: action.kind, ...(action.tone ? { tone: action.tone } : {}) }, false);
     if (action.type === "show") {
       const result = await client.request(action.panel === 3 ? { t: "task", op: "task_show", args: { id: action.id } } : { t: "queue", op: "show", id: action.id }, 3000);
@@ -188,13 +231,14 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     stream({ text: `> ${action.args.join(" ")}`, kind: "command" });
     try {
       // Output lines sit at column 4, as message bodies do: what a command prints can carry peer text, and columns 0 and 2 are the hub's.
-      const output = (text: string) => { if (active) { stream({ text: text.replace(/\n$/, "").replace(/^/gm, "    "), kind: "command" }); draw(); } };
-      cancelChild = run(action.args, output, () => { childRunning = false; cancelChild = undefined; if (active) void refresh(); });
+      const output = (text: string) => { if (active) { stream({ text: terminalText(text).replace(/\t/g, " ").replace(/\n$/, "").replace(/^/gm, "    "), kind: "command" }); draw(); } };
+      cancelChild = run(action.args, output, () => { childRunning = false; cancelChild = undefined; if (active) void refresh(); }, Math.max(1, columns - 4));
     } catch (error) { childRunning = false; notice(String((error as Error).message)); draw(); }
   };
   const handle = (key: string) => {
     if (!active) return;
     const result = reduceConsole(state, key); state = result.state;
+    state.attentionMessages = []; state.attentionSelection = key === "n" ? state.attentionSelection : undefined;
     if (state.mode === "panels" && (plain || columns < 80 || rows < 24)) { state.mode = "stream"; notice("panels need at least 80x24"); }
     for (const action of result.effects) void effect(action).catch(error => stop(`Console error: ${String(error.message)}`));
     draw();
@@ -203,7 +247,10 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   client.onPush = msg => {
     if (!active) return;
     try {
-      if (msg.t === "event") stream({ text: renderTailEvent(msg.e), peer: msg.e.peer ?? msg.e.env?.from, kind: msg.e.env?.kind ?? msg.e.t, tone: eventTone(msg.e) });
+      if (msg.t === "event") {
+        if (state.petEnabled && msg.e.t === "envelope" && !msg.e.dropped && msg.e.env.to?.includes("user")) state.attentionMessages = [...(state.attentionMessages ?? []), { id: msg.e.env.id, peer: msg.e.env.from, important: msg.e.env.priority === "important", since: msg.e.env.ts }].slice(-1000);
+        stream({ text: renderTailEvent(msg.e), peer: msg.e.peer ?? msg.e.env?.from, kind: msg.e.env?.kind ?? msg.e.t, tone: eventTone(msg.e) });
+      }
       else if (msg.t === "context") stream({ text: `  ${msg.peer}: ${contextLine(msg.reading, at => new Date(at).toLocaleTimeString())}`, peer: msg.peer, kind: "context" });
       else if (msg.t === "notice") stream({ text: `  * ${msg.line}`, kind: "notice" });
       else if (msg.t === "permission") {
@@ -224,17 +271,26 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   };
   client.onClose = (_code, reason) => stop(`Hub connection closed${reason ? `: ${reason}` : ""}`);
   try {
+    if (state.petEnabled && pet.notice) {
+      if (state.mode === "panels" && !plain) notify(state, pet.notice, Date.now(), "attention");
+      else stream({ text: pet.notice, kind: "attention", tone: "attention" }, false);
+    }
     if (plain) { state.mode = "stream"; safeWrite("Console panels need a terminal of at least 80x24; showing the plain stream.\n"); }
     if (terminal.isTTY) {
       terminal.raw(true);
       removers.push(terminal.onData(text => {
         // A pasted chunk can only edit text, never approve, confirm or run commands. Bracketed-paste delimiters are stripped.
-        // Under the modal key table it does nothing at all.
+        // Under the modal key table it does nothing at all. A read holding nothing but arrow sequences is that many
+        // key presses (key repeat, a slow link), not a paste (#309): each arrow reaches the reducer on its own.
         if (Array.from(text).length > 1 && !["\x1b[A", "\x1b[B", "\x1b[C", "\x1b[D"].includes(text)) {
-          if (state.help && state.mode === "panels") return;
-          if (state.confirm?.type === "permission_default") { draw(); return; }
-          state.confirm = undefined; state.optionChoice = undefined; state.editing = true;
-          state.input += terminalText(text.replace(/\x1b\[20[01]~/g, "")).replace(/\n/g, " "); draw();
+          if (/^(?:\x1b\[[ABCD])+$/.test(text)) { for (const key of text.match(/\x1b\[[ABCD]/g)!) handle(key); }
+          else {
+            state.attentionMessages = []; state.attentionSelection = undefined;
+            if (state.help && state.mode === "panels") { draw(); return; }
+            if (state.confirm?.type === "permission_default") { draw(); return; }
+            state.confirm = undefined; state.optionChoice = undefined; state.editing = true;
+            state.input += terminalText(text.replace(/\x1b\[20[01]~/g, "")).replace(/\n/g, " "); draw();
+          }
         } else handle(text);
       }));
       removers.push(terminal.onResize(() => {

package/src/cli/facts-hook.ts

@@ -3,8 +3,9 @@
 // PreToolUse preserves facts additionalContext and adds permission decisions; other phases observe only.
 // A failed or timed-out hub decides nothing, leaving Claude's native permission rules in effect.
 import { relative, resolve, isAbsolute } from "node:path";
+import { matchesPolicy } from "../hub/path-policy.ts";
 import { realPath } from "../hub/project.ts";
-import { isAgentConfigPath, isPermissionMode, hardLinked, isHubWritePath } from "../hub/permission-mode.ts";
+import { isAgentConfigPath, isInstructionPath, isPermissionMode, hardLinked, isHubWritePath } from "../hub/permission-mode.ts";
 import { ControlClient } from "../hub/control-client.ts";
 
 /** A library call may target another hub; only the managed command hook inherits that target's native identity. */
@@ -14,7 +15,7 @@ export function nativeHookIdentity(stateDir: string, peer: string, env: NodeJS.P
 }
 
 /** Only resolving project paths outside the hub/native configuration directories receive a file grant. */
-export function projectFileTool(tool: unknown, input: unknown, projectRoot: unknown): boolean {
+export function projectFileTool(tool: unknown, input: unknown, projectRoot: unknown, protectInstructions = false, readOnly: string[] = []): boolean {
   if (typeof projectRoot !== "string" || !isAbsolute(projectRoot) || !input || typeof input !== "object" || Array.isArray(input)) return false;
   const args = input as Record<string, unknown>;
   const key = ["Read", "Edit", "Write", "MultiEdit"].includes(String(tool)) ? "file_path" : tool === "NotebookEdit" ? "notebook_path" : ["LS", "Glob", "Grep"].includes(String(tool)) ? "path" : undefined;
@@ -24,7 +25,8 @@ export function projectFileTool(tool: unknown, input: unknown, projectRoot: unkn
   if (!optional && args[key] === undefined) return false;
   try {
     const root = realPath(projectRoot);
-    const protectedPath = (path: string) => isAgentConfigPath(path) || isHubWritePath(path);
+    const mutates = ["Edit", "Write", "MultiEdit", "NotebookEdit"].includes(String(tool));
+    const protectedPath = (path: string) => isAgentConfigPath(path) || isHubWritePath(path) || (protectInstructions && mutates && isInstructionPath(path));
     const safe = (path: string) => {
       const requested = resolve(root, path), lexical = relative(root, requested);
       if (protectedPath(lexical)) return false;
@@ -34,6 +36,7 @@ export function projectFileTool(tool: unknown, input: unknown, projectRoot: unkn
     };
     const target = typeof args[key] === "string" ? args[key] as string : root;
     if (target.split(/[\\/]/).includes("..") || !safe(target)) return false;
+    if (mutates && matchesPolicy(root, target, readOnly, true)) return false;
     if (tool === "Grep" && args.glob !== undefined) {
       if (typeof args.glob !== "string" || !args.glob || args.glob.split(/[\\/]/).includes("..") || protectedPath(args.glob)) return false;
       if (/[?*[{]/.test(args.glob) || !safe(resolve(root, target, args.glob))) return false;
@@ -48,6 +51,11 @@ export function projectFileTool(tool: unknown, input: unknown, projectRoot: unkn
   } catch { return false; }
 }
 
+/** Only a usable managed scoped-write grant may evaluate filesystem policy. */
+export function scopedWriteBlocked(phase: string, permission: unknown, tool: unknown, evaluate: () => boolean): boolean {
+  return phase === "pre" && permission === "ask-when-needed" && ["Edit", "Write", "MultiEdit", "NotebookEdit"].includes(String(tool)) && !evaluate();
+}
+
 /** The hook's stdout for one Claude Code hook input, or undefined for none. */
 export async function factsHook(stdin: string, stateDir: string, peer: string, timeoutMs = 2000): Promise<string | undefined> {
   const input = JSON.parse(stdin) as { hook_event_name?: unknown; tool_name?: unknown; tool_input?: unknown; tool_use_id?: unknown; session_id?: unknown; transcript_path?: unknown };
@@ -67,7 +75,7 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
     }, timeoutMs);
     if (phase !== "pre" || !res?.ok) return undefined;
     const permission = isPermissionMode(res.permission) ? res.permission : "ask";
-    const fileTool = projectFileTool(input.tool_name, input.tool_input, res.projectRoot);
+    const fileTool = projectFileTool(input.tool_name, input.tool_input, res.projectRoot, res.protectInstructionFiles === true);
     const allow = input.hook_event_name === "PreToolUse" && (permission === "never-ask" || permission === "ask-when-needed" && fileTool);
     const text = typeof res.text === "string" && res.text ? res.text : undefined;
     if (!allow && !text) return undefined;