@saadnvd1/agent-os 0.3.489 → 0.3.494

package/data/chat/useChat.ts

@@ -19,6 +19,7 @@ import type {
   UndoPreview,
 } from "@/lib/chat/events";
 import type { SearchResult } from "@/lib/chat/find";
+import { addBody, touchBody } from "@/lib/chat/bodyCache";
 
 // The index of the item with `id`, searched from the end: what changes is
 // almost always the latest.
@@ -129,6 +130,13 @@ export function useChat(
   const [toolBodies, setToolBodies] = useState<Record<string, ToolBody | null>>(
     {}
   );
+  // Bodies open on screen, never evicted from toolBodies.
+  const visibleBodies = useRef(new Set<string>());
+  const pinToolBody = useCallback((id: string) => {
+    visibleBodies.current.add(id);
+    setToolBodies((prev) => touchBody(prev, id));
+    return () => void visibleBodies.current.delete(id);
+  }, []);
   const [state, setState] = useState<ChatState>("idle");
   const [connected, setConnected] = useState(false);
   const [commands, setCommands] = useState<ChatCommand[]>([]);
@@ -249,7 +257,9 @@ export function useChat(
           const have = new Set(prev.map((p) => p.id));
           setItems(m.items.filter((i) => !have.has(i.id)).concat(prev));
         } else if (m.type === "tool_body") {
-          setToolBodies((prev) => ({ ...prev, [m.id]: m.body }));
+          setToolBodies((prev) =>
+            addBody(prev, m.id, m.body, visibleBodies.current)
+          );
         } else if (m.type === "item") {
           withDeltas(() => {
             const routed = routeItem(
@@ -457,6 +467,7 @@ export function useChat(
     earlierTasks,
     toolBodies,
     requestToolBody,
+    pinToolBody,
     state,
     connected,
     commands,

package/data/sessions/fresh.ts

@@ -0,0 +1,20 @@
+import { useMutation } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+// Starts an orchestrator's or task's conversation over (lib/chat/refresh):
+// now when idle, else after the running turn.
+export function useFreshStart() {
+  return useMutation({
+    mutationFn: async (id: string): Promise<"now" | "after-turn"> => {
+      const res = await fetch(`/api/sessions/${id}/fresh`, { method: "POST" });
+      const body = (await res.json().catch(() => ({}))) as {
+        when?: "now" | "after-turn";
+        error?: string;
+      };
+      if (!res.ok || !body.when)
+        throw new Error(body.error ?? "Couldn't start fresh");
+      return body.when;
+    },
+    onError: (e: Error) => toast.error(e.message),
+  });
+}

package/data/sessions/index.ts

@@ -11,4 +11,5 @@ export {
   useSessionSetup,
 } from "./queries";
 export { usePinSession } from "./pin";
+export { useFreshStart } from "./fresh";
 export type { LaunchSessionInput, SessionSetup } from "./queries";

package/lib/chat/bodyCache.ts

@@ -0,0 +1,69 @@
+import type { ToolBody } from "./events";
+
+// Opened tool output kept in memory, least recently used first out.
+export const MAX_LOADED_BODIES = 40;
+export const MAX_LOADED_BODY_CHARS = 5_000_000;
+
+export type Bodies = Record<string, ToolBody | null>;
+
+export function bodySize(body: ToolBody | null): number {
+  if (!body) return 0;
+  const d = body.diff;
+  return (
+    (body.output?.length ?? 0) +
+    (d ? d.path.length + d.before.length + d.after.length : 0)
+  );
+}
+
+// Object keys keep insertion order, so the first key is the least recently
+// used. Puts `id` last, loaded or being opened again.
+export function touchBody(bodies: Bodies, id: string): Bodies {
+  if (!(id in bodies) || Object.keys(bodies).pop() === id) return bodies;
+  const { [id]: body, ...rest } = bodies;
+  return { ...rest, [id]: body };
+}
+
+// Drops the least recently used bodies until both limits hold. A body on
+// screen stays, even when that leaves the cache over a limit.
+export function capBodies(
+  bodies: Bodies,
+  visible: ReadonlySet<string>
+): Bodies {
+  const ids = Object.keys(bodies);
+  let count = ids.length;
+  let chars = ids.reduce((n, id) => n + bodySize(bodies[id]), 0);
+  if (count <= MAX_LOADED_BODIES && chars <= MAX_LOADED_BODY_CHARS)
+    return bodies;
+  const drop = new Set<string>();
+  for (const id of ids) {
+    if (count <= MAX_LOADED_BODIES && chars <= MAX_LOADED_BODY_CHARS) break;
+    if (visible.has(id)) continue;
+    drop.add(id);
+    count--;
+    chars -= bodySize(bodies[id]);
+  }
+  return Object.fromEntries(
+    ids.filter((id) => !drop.has(id)).map((id) => [id, bodies[id]])
+  );
+}
+
+// A body arriving: it is the most recently used.
+export function addBody(
+  bodies: Bodies,
+  id: string,
+  body: ToolBody | null,
+  visible: ReadonlySet<string>
+): Bodies {
+  const { [id]: _old, ...rest } = bodies;
+  return capBodies({ ...rest, [id]: body }, visible);
+}
+
+// Whether an opened tool must ask for its body: deferred, not loaded (never
+// was, or evicted), and the socket is up.
+export function needsBody(
+  deferred: boolean | undefined,
+  body: ToolBody | null | undefined,
+  connected: boolean
+): boolean {
+  return !!deferred && body === undefined && connected;
+}

package/lib/chat/commands.ts

@@ -48,3 +48,19 @@ export function insertCommand(name: string): string {
 export function leadingCommand(text: string): string | null {
   return text.match(/^\/[\w:.-]+(?=\s|$)/)?.[0] ?? null;
 }
+
+// AgentOS's own command for an orchestrator or task: starts the agent's
+// conversation over, with today's brief and permissions.
+export const FRESH_COMMAND: ChatCommand = {
+  name: "fresh",
+  description: "Start a fresh conversation with the current brief",
+};
+
+export const isFreshCommand = (text: string): boolean =>
+  text.trim().toLowerCase() === "/fresh";
+
+export function withFresh(commands: ChatCommand[]): ChatCommand[] {
+  return commands.some((c) => c.name === "fresh")
+    ? commands
+    : [FRESH_COMMAND, ...commands];
+}

package/lib/chat/refresh.ts

@@ -143,8 +143,26 @@ export function autoCompactEnv(sessionId: string): Record<string, string> {
 
 const k = (tokens: number) => `${Math.round(tokens / 1000)}k`;
 
+// Recorded as the size a conversation ended at when the reader asked for it.
+export const REQUESTED_FRESH = -1;
+
+// The agent's conversation is let go in the database: the next worker
+// starts a new one with the brief and the permissions the server has then.
+// `tokens` is the size it ended at, or REQUESTED_FRESH.
+export function releaseConversation(sessionId: string, tokens: number): void {
+  db.prepare(
+    `UPDATE sessions SET claude_session_id = NULL, chat_resume_at = NULL,
+       chat_suggestion = NULL, chat_context = NULL, chat_restarted = 0,
+       chat_refreshed = ? WHERE id = ?`
+  ).run(tokens, sessionId);
+}
+
 // What the agent reads ahead of its first message in the new conversation.
 export function refreshedNote(role: "orchestrator" | "task", tokens: number) {
+  if (tokens === REQUESTED_FRESH)
+    return role === "orchestrator"
+      ? `(AgentOS started you on a fresh conversation at the user's request. Your brief and "Where things stand" are current; carry on from them.)`
+      : `(AgentOS started you on a fresh conversation at the user's request. Your brief is above; check git status, git log and your PR to see how far you got, then carry on.)`;
   return role === "orchestrator"
     ? `(AgentOS started you on a fresh conversation: the last one passed ${k(tokens)} tokens of context. Your brief and "Where things stand" are current; carry on from them.)`
     : `(AgentOS started you on a fresh conversation: the last one passed ${k(tokens)} tokens of context. Your brief is above; check git status, git log and your PR to see how far you got, then carry on.)`;

package/lib/chat/registry.ts

@@ -24,6 +24,8 @@ export interface Live {
   // Whether it keeps the composer's queue and answers @mention lookups
   // (send_now, drain, files); an older worker drops those silently.
   canQueue?: boolean;
+  // Whether it takes "fresh" (a fresh start the reader asked for).
+  canFresh?: boolean;
   // From an older build and idle: retired once its guess at the next
   // message is in, or this fires.
   retiring?: NodeJS.Timeout;

package/lib/chat/runner.ts

@@ -50,6 +50,7 @@ import {
   queuedSessions,
 } from "./queued";
 import { fallbackFileSuggestions } from "./files";
+import { REQUESTED_FRESH, releaseConversation } from "./refresh";
 import { holdsQueue, settingUp } from "../sessions/setup-progress";
 import { firstMessageId, launchPending } from "../tasks/launch-gate";
 import type { ChatItem, FileSuggestion } from "./events";
@@ -280,6 +281,7 @@ async function ensureLive(sessionId: string, spawn = true): Promise<Live> {
       build: hello.build,
       canPlan: !!hello.caps?.includes("plan"),
       canQueue: !!hello.caps?.includes("queue"),
+      canFresh: !!hello.caps?.includes("fresh"),
     };
     // From an older build and busy, or running background work: it goes at
     // its next turn boundary, by itself if it can. Messages meanwhile wait
@@ -716,6 +718,54 @@ function retire(sessionId: string, live: Live, resume = true): void {
   if (resume) void resumeQueue(sessionId);
 }
 
+// A fresh start the reader asked for, by the path the context threshold
+// takes (the worker's endConversation): "now" when nothing is running, else
+// "after-turn", at the next turn boundary. The next worker reads the brief
+// and permissions as the server has them then, nothing held over.
+export class FreshRefusal extends Error {}
+
+export async function freshStartChat(
+  sessionId: string
+): Promise<"now" | "after-turn"> {
+  const session = getSession(sessionId);
+  // A terminal agent's conversation isn't ours to release: it keeps running.
+  if (session.view !== "chat" || session.archived_at)
+    throw new FreshRefusal("Only an open chat session can start fresh");
+  try {
+    checkChattable(session);
+  } catch (e) {
+    throw new FreshRefusal(e instanceof Error ? e.message : String(e));
+  }
+  const live =
+    registry.live.get(sessionId) ??
+    (runningWorkers().includes(sessionId)
+      ? await ensureLive(sessionId, false).catch(() => undefined)
+      : undefined);
+  if (live) {
+    // A worker from before this existed would ignore the command.
+    if (live.canFresh) {
+      live.worker.command({ type: "fresh" });
+      return live.state === "idle" && !live.activity.tasks.size
+        ? "now"
+        : "after-turn";
+    }
+    if (live.state !== "idle")
+      throw new FreshRefusal("Try again when the current turn has ended");
+    stopChat(sessionId);
+  }
+  releaseConversation(sessionId, REQUESTED_FRESH);
+  const item: ChatItem = {
+    id: `note-refresh-${Date.now()}`,
+    kind: "note",
+    tone: "note",
+    text: `Fresh start: the agent starts a new conversation with its brief${session.role === "orchestrator" ? " and the current state from AgentOS" : ""} at its next message.`,
+    createdAt: Date.now(),
+  };
+  saveItem(sessionId, item);
+  emit(sessionId, { type: "item", item });
+  return "now";
+}
+
 export function stopChat(sessionId: string): void {
   const live = registry.live.get(sessionId);
   if (live) {

package/lib/chat/store.ts

@@ -4,22 +4,102 @@ import type { ChatItem } from "./events";
 // Items keep the position they were first written at, so replacing one
 // (a finished tool call, a streamed message's final text) never reorders.
 export function saveItem(sessionId: string, item: ChatItem): void {
+  flushItems();
   db.prepare(
     `INSERT INTO chat_items (session_id, item_id, seq, data)
      VALUES (?, ?, (SELECT COALESCE(MAX(seq), 0) + 1 FROM chat_items WHERE session_id = ?), ?)
      ON CONFLICT(session_id, item_id) DO UPDATE SET data = excluded.data`
   ).run(sessionId, item.id, sessionId, JSON.stringify(item));
+  seqs.delete(sessionId);
+}
+
+// The streaming path. Every update of an item is a write, so they're held
+// in memory (the latest state of each item) and written together, in one
+// transaction, every FLUSH_MS. Callers flush at anything that mustn't be
+// lost: an item finishing, a turn ending, an error, an interrupt, a close.
+// Every reader here flushes first; one that queries the table itself may be
+// up to FLUSH_MS behind.
+export const FLUSH_MS = 250;
+
+type Pending = { seq: number; data: string };
+type Seqs = { next: number; of: Map<string, number> };
+
+const pending = new Map<string, Map<string, Pending>>();
+const seqs = new Map<string, Seqs>();
+let timer: NodeJS.Timeout | undefined;
+
+// Seeded once from the table, then kept: an item gets its seq the first
+// time it's seen, the same one it would have got from MAX(seq) + 1.
+function seqsOf(sessionId: string): Seqs {
+  let s = seqs.get(sessionId);
+  if (!s) {
+    const row = db
+      .prepare(
+        `SELECT COALESCE(MAX(seq), 0) AS m FROM chat_items WHERE session_id = ?`
+      )
+      .get(sessionId) as { m: number };
+    s = { next: row.m + 1, of: new Map() };
+    seqs.set(sessionId, s);
+  }
+  return s;
+}
+
+export function queueItem(
+  sessionId: string,
+  item: ChatItem,
+  { flush = false }: { flush?: boolean } = {}
+): void {
+  const s = seqsOf(sessionId);
+  let seq = s.of.get(item.id);
+  if (seq === undefined) {
+    seq = s.next++;
+    s.of.set(item.id, seq);
+  }
+  let items = pending.get(sessionId);
+  if (!items) pending.set(sessionId, (items = new Map()));
+  items.set(item.id, { seq, data: JSON.stringify(item) });
+  if (flush) flushItems();
+  else if (!timer) {
+    timer = setTimeout(flushItems, FLUSH_MS);
+    timer.unref();
+  }
+}
+
+export function flushItems(): void {
+  clearTimeout(timer);
+  timer = undefined;
+  if (!pending.size) return;
+  try {
+    const insert = db.prepare(
+      `INSERT INTO chat_items (session_id, item_id, seq, data) VALUES (?, ?, ?, ?)
+       ON CONFLICT(session_id, item_id) DO UPDATE SET data = excluded.data`
+    );
+    db.transaction(() => {
+      for (const [sessionId, items] of pending)
+        for (const [itemId, p] of items)
+          insert.run(sessionId, itemId, p.seq, p.data);
+    })();
+    pending.clear();
+  } catch (error) {
+    // Kept for the next try rather than lost.
+    console.error("Chat items not written:", error);
+    timer = setTimeout(flushItems, FLUSH_MS);
+    timer.unref();
+  }
 }
 
 // Moves an item after every other, as if first written now.
 export function moveToEnd(sessionId: string, itemId: string): void {
+  flushItems();
   db.prepare(
     `UPDATE chat_items SET seq = (SELECT MAX(seq) + 1 FROM chat_items WHERE session_id = ?)
      WHERE session_id = ? AND item_id = ?`
   ).run(sessionId, sessionId, itemId);
+  seqs.delete(sessionId);
 }
 
 export function listItems(sessionId: string): ChatItem[] {
+  flushItems();
   return (
     db
       .prepare(`SELECT data FROM chat_items WHERE session_id = ? ORDER BY seq`)
@@ -31,6 +111,7 @@ export function getItem(
   sessionId: string,
   itemId: string
 ): ChatItem | undefined {
+  flushItems();
   const row = db
     .prepare(`SELECT data FROM chat_items WHERE session_id = ? AND item_id = ?`)
     .get(sessionId, itemId) as { data: string } | undefined;
@@ -38,6 +119,7 @@ export function getItem(
 }
 
 export function hasItem(sessionId: string, itemId: string): boolean {
+  flushItems();
   return !!db
     .prepare(`SELECT 1 FROM chat_items WHERE session_id = ? AND item_id = ?`)
     .get(sessionId, itemId);
@@ -49,6 +131,7 @@ export function lastItems(
   n: number,
   kind?: ChatItem["kind"]
 ): ChatItem[] {
+  flushItems();
   const rows = (
     kind
       ? db
@@ -69,6 +152,7 @@ export function lastItems(
 // What the agent has said since the last message to it, as text: where a
 // chat task's BLOCKED: line stays until someone answers it.
 export function saidSinceLastMessage(sessionId: string, n = 20): string {
+  flushItems();
   const items = lastItems(sessionId, n);
   return items
     .slice(items.findLastIndex((i) => i.kind === "user") + 1)
@@ -81,6 +165,7 @@ export function itemsOfKind<K extends ChatItem["kind"]>(
   sessionId: string,
   kind: K
 ): Extract<ChatItem, { kind: K }>[] {
+  flushItems();
   return (
     db
       .prepare(
@@ -95,6 +180,7 @@ export function itemsOfKind<K extends ChatItem["kind"]>(
 export function runningTools(
   sessionId: string
 ): Extract<ChatItem, { kind: "tool" }>[] {
+  flushItems();
   return (
     db
       .prepare(
@@ -107,6 +193,8 @@ export function runningTools(
 }
 
 export function deleteItems(sessionId: string): void {
+  pending.delete(sessionId);
+  seqs.delete(sessionId);
   db.prepare(`DELETE FROM chat_items WHERE session_id = ?`).run(sessionId);
 }
 
@@ -135,6 +223,7 @@ export function settle(items: ChatItem[]): ChatItem[] {
 
 // What a chat session is working on: the first line of its latest message.
 export function lastUserTask(sessionId: string): string | null {
+  flushItems();
   const row = db
     .prepare(
       `SELECT data FROM chat_items WHERE session_id = ? AND item_id LIKE 'user-%'

package/lib/chat/worker/host.ts

@@ -22,9 +22,10 @@ import type {
 } from "../events";
 import {
   itemsOfKind,
+  flushItems,
   moveToEnd,
+  queueItem,
   runningTools,
-  saveItem,
   settle,
 } from "../store";
 import { claimNext, enqueue, listQueue, moveToFront } from "../queued";
@@ -40,7 +41,13 @@ import {
   visualsTools,
 } from "../../artifacts/tools";
 import type { RoleExtras } from "./extras";
-import { compactThreshold, refreshSettings, refreshedNote } from "../refresh";
+import {
+  REQUESTED_FRESH,
+  compactThreshold,
+  refreshSettings,
+  refreshedNote,
+  releaseConversation,
+} from "../refresh";
 import { compactContext } from "../compact-context";
 import { COMPACT_BRIEF, COMPACT_INSTRUCTIONS } from "../working-state";
 import { compactionDue, staleLabel, type Staleness } from "../stale";
@@ -261,7 +268,10 @@ export class ChatHost {
   }
 
   private record(item: ChatItem): void {
-    saveItem(this.session.id, item);
+    // Streaming updates are written in batches; anything else right away.
+    queueItem(this.session.id, item, {
+      flush: !("streaming" in item && item.streaming),
+    });
     this.emit({ type: "item", item });
   }
 
@@ -354,6 +364,7 @@ export class ChatHost {
           }
         } else if (e.type === "state") {
           if (e.state === "idle") {
+            flushItems();
             // A turn cut off mid-sentence (Esc, Stop) keeps what it streamed.
             this.settleStreaming();
             this.closeTools();
@@ -406,6 +417,7 @@ export class ChatHost {
       this.settleStreaming();
       this.closeTools();
       this.showHandedOver();
+      flushItems();
       this.setState("idle");
     }
   }
@@ -485,7 +497,7 @@ export class ChatHost {
       checkpoint,
     };
     if (handOver) {
-      saveItem(this.session.id, user);
+      queueItem(this.session.id, user, { flush: true });
       this.handedOver.push(user);
     } else this.record(user);
     this.setState("running");
@@ -631,6 +643,7 @@ export class ChatHost {
         }
         return;
       case "interrupt":
+        flushItems();
         await this.modeChange.catch(() => {});
         if (cmd.hard) {
           this.hardStopAt = Date.now();
@@ -672,11 +685,32 @@ export class ChatHost {
       case "retire":
         this.retiring = true;
         return this.retireIfDone();
+      case "fresh":
+        return this.freshOnRequest();
       case "close":
         return this.close();
     }
   }
 
+  // A fresh start the reader asked for: the same retire as at the context
+  // threshold, so it waits for the turn boundary and says so meanwhile.
+  private freshOnRequest(): void {
+    if (this.refreshAt || this.closed) return;
+    this.refreshAt = REQUESTED_FRESH;
+    this.retiring = true;
+    this.retireWaited = true;
+    this.retireIfDone();
+    // Still here: a turn, background work or its rest timer holds it.
+    if (!this.closed)
+      this.record({
+        id: `note-fresh-pending-${Date.now()}`,
+        kind: "note",
+        tone: "note",
+        text: "Starts fresh after this turn",
+        createdAt: Date.now(),
+      });
+  }
+
   private hardStopped(): boolean {
     return this.hardStopAt > 0 && Date.now() - this.hardStopAt < HARD_STOP_MS;
   }
@@ -842,20 +876,19 @@ export class ChatHost {
   // with the brief and tells it why. The chat Saad reads goes on, with a
   // line saying where it started over.
   private endConversation(): void {
-    db.prepare(
-      `UPDATE sessions SET claude_session_id = NULL, chat_resume_at = NULL,
-         chat_suggestion = NULL, chat_context = NULL, chat_restarted = 0,
-         chat_refreshed = ? WHERE id = ?`
-    ).run(this.refreshAt, this.session.id);
+    releaseConversation(this.session.id, this.refreshAt);
     const brief = `its brief${this.session.role === "orchestrator" ? " and the current state from AgentOS" : ""}`;
     const stale = this.staleRefresh;
+    const requested = this.refreshAt === REQUESTED_FRESH;
     this.record({
       id: `note-refresh-${Date.now()}`,
       kind: "note",
       tone: "note",
-      text: stale
-        ? `${staleLabel(stale)}, past its prompt cache: the agent starts a fresh conversation with ${brief} before the next message.`
-        : `Context reached ${Math.round(this.refreshAt / 1000)}k tokens: the agent starts a fresh conversation with ${brief} at its next message.`,
+      text: requested
+        ? `Fresh start: the agent starts a new conversation with ${brief} at its next message.`
+        : stale
+          ? `${staleLabel(stale)}, past its prompt cache: the agent starts a fresh conversation with ${brief} before the next message.`
+          : `Context reached ${Math.round(this.refreshAt / 1000)}k tokens: the agent starts a fresh conversation with ${brief} at its next message.`,
       createdAt: Date.now(),
     });
     if (stale)
@@ -877,6 +910,7 @@ export class ChatHost {
     clearTimeout(this.retireTimer);
     clearTimeout(this.restTimer);
     this.closed = true;
+    flushItems();
     this.onClose();
     this.conversation.close();
   }

package/lib/chat/worker/main.ts

@@ -75,7 +75,7 @@ async function main(sessionId: string) {
         build: buildId(),
         state: host.state,
         streaming: [...host.streaming.values()],
-        caps: ["plan", "queue", "retire"],
+        caps: ["plan", "queue", "retire", "fresh"],
       } satisfies WorkerEvent)}\n`
     );
     client.on(

package/lib/chat/worker/protocol.ts

@@ -58,6 +58,10 @@ export type WorkerCommand =
   // wait in the queue) and closes at its next turn boundary, so a current
   // worker resumes the conversation with today's tools.
   | { type: "retire" }
+  // The reader asked for a fresh conversation: at the next turn boundary
+  // (now, if idle) the agent's conversation ends and the next worker
+  // starts a new one with today's brief and permissions.
+  | { type: "fresh" }
   | { type: "close" };
 
 // Worker -> server: what's live right now on connecting, then events.

package/lib/orchestrator/brief.ts

@@ -124,7 +124,7 @@ Acting:
 - \`${TOOL_NAMES.disarm}\` (task): stop an armed task merging by itself.
 - \`${TOOL_NAMES.ask_saad}\` (title, detail, link?, kind, task?, sha?): park an item on Saad's asks list and carry on; it never waits.
 
-Act through these tools, not the shell: they're scoped to this workspace and braked. The shell runs only \`aos\` commands that read (peers, inbox, history, stacks, schedules, docs), \`aos notify "<text>"\`, which pushes a message to Saad's phone, and git in your own quick changes' worktrees (\`git -C <path> ...\`), each as one plain command: no \`;\`, \`&&\`, pipes, redirects or \`$\` outside quotes. Use it for what he'd want to see now and asked for: the morning report, a real milestone (a stack landed, a blocker only he can clear). Never for routine status: one a minute at most, and he reads the rest here. You can read files anywhere (Read, Grep, Glob), and write them (Write, Edit, NotebookEdit) anywhere except: a project repository or task worktree other than your own open quick changes' worktrees (start a task, or a quick change for a small edit, so the change goes through CI, review and scope), AgentOS's own state in ~/.agent-os outside your folder, secret files (.env, keys, ~/.ssh, ~/.aws, tokenvault and the like), and files that make something run: dotfiles and dot-folders at the top of your home (shell, git, Claude and tool config), ~/Library and /Library's launch agents, git's core.hooksPath folders, the folders on PATH, and any .git, .claude, .mcp.json, CLAUDE.md or AGENTS.md, which would hand you a shell or run code around the gates. Each write is checked before it runs, on the path with symlinks and \`..\` resolved; a refused one says why.
+Act through these tools, not the shell: they're scoped to this workspace and braked. The shell runs anything without asking (Saad chose this on 2026-10-11), so use it to read and investigate yourself: \`gh pr list\`, \`gh run view --log-failed\`, \`gh api\` GETs, \`curl\`, \`sqlite3 -readonly\`, git in any repository, a skill's scripts, pipes and chains. Never use it to get around the tools. A deny list refuses, naming the tool to use instead: merging, closing or retargeting a PR (\`${TOOL_NAMES.sign_off}\`, \`${TOOL_NAMES.arm}\`, \`${TOOL_NAMES.land}\`, \`${TOOL_NAMES.drop}\`), \`git push\` (\`${TOOL_NAMES.quick_pr}\`), writing in a project repository or task worktree other than your own quick changes (\`${TOOL_NAMES.start_task}\`, \`${TOOL_NAMES.quick_change}\`), writing AgentOS's state (sqlite3 without \`-readonly\`, or files in ~/.agent-os outside your folder), stopping or restarting AgentOS or its tmux, and reading secret files or tokenvault. The list catches honest mistakes, not a determined bypass: a script or \`python -c\` could do any of these unseen, and doing so would break Saad's trust in every gate. \`aos notify "<text>"\` pushes a message to Saad's phone. Use it for what he'd want to see now and asked for: the morning report, a real milestone (a stack landed, a blocker only he can clear). Never for routine status: one a minute at most, and he reads the rest here. You can read files anywhere (Read, Grep, Glob), and write them (Write, Edit, NotebookEdit) anywhere except: a project repository or task worktree other than your own open quick changes' worktrees (start a task, or a quick change for a small edit, so the change goes through CI, review and scope), AgentOS's own state in ~/.agent-os outside your folder, secret files (.env, keys, ~/.ssh, ~/.aws, tokenvault and the like), and files that make something run: dotfiles and dot-folders at the top of your home (shell, git, Claude and tool config), ~/Library and /Library's launch agents, git's core.hooksPath folders, the folders on PATH, and any .git, .claude, .mcp.json, CLAUDE.md or AGENTS.md, which would hand you a shell or run code around the gates. Each write is checked before it runs, on the path with symlinks and \`..\` resolved; a refused one says why.
 
 ## Untrusted text