@hassangameryt/freeflow 0.8.0 → 0.9.0

package/pi-extension/dist/task-memory/tool.js

@@ -0,0 +1,233 @@
+import { autoApproveGroup } from "./config.js";
+import { renderTaskCall, renderTaskResult } from "./render.js";
+import { confirmWithUser } from "../ask-user/ask.js";
+export const TASK_MEMORY_TOOL = "task_memory";
+const DESCRIPTION =
+  "Task memory: the Working Records (Track Work) this session works on, and their projects. Read the task-memory skill before your first proposal; Track Work decides what records say. Reading needs no permission: projects lists every project; list lists this repository's records, or a project's tasks; view reads a record's resume view or one entry by task ID; search finds lines in the focused task, its tree, or its project. Attention: focus switches to an attached record; detach stops working on one. Proposals, each confirmed by the user in a dialog before anything happens: attach a record; create a task in this repository's project and attach it; child or fanout (a child with its own Git worktree) of the focused task for a parallel session; project_new or project_link for this repository; import a repository record into a project; confirm a held record; env to change a task's directories; remove a task with its children, or project_remove a whole project, which moves their records to the trash. Only the user empties the trash, with /freeflow trash empty: when asked to, tell the user to run it. A decline is the user's answer: do not retry it or work around it.";
+const ACTIONS = [
+  "projects",
+  "list",
+  "view",
+  "search",
+  "attach",
+  "focus",
+  "detach",
+  "create",
+  "child",
+  "fanout",
+  "project_new",
+  "project_link",
+  "import",
+  "confirm",
+  "env",
+  "remove",
+  "project_remove",
+];
+// Actions that change which records this session holds; the Runtime State follows them.
+const CHANGES_STATE = new Set(["attach", "focus", "detach", "create", "import", "confirm", "remove", "project_remove"]);
+/** Actions any profile may take: they only read. `env` reads too, unless it changes a directory. */
+const READS = new Set(["projects", "list", "view", "search"]);
+const reads = (params) =>
+  READS.has(params?.action) ||
+  (params?.action === "env" &&
+    !params?.primary?.trim?.() &&
+    !params?.add_dir?.trim?.() &&
+    !params?.remove_dir?.trim?.());
+/** Registered once, declared only while task memory is effective (see applyTaskMemoryTools). */
+export function registerTaskMemoryTool(pi, host) {
+  pi.registerTool({
+    name: TASK_MEMORY_TOOL,
+    label: "Task memory",
+    description: DESCRIPTION,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { type: "string", enum: ACTIONS },
+        record: {
+          type: "string",
+          description: "A task ID such as my-project/task-003, or a record.md path; remove takes a task ID",
+        },
+        project: { type: "string", description: "list: a project's name; import: the project to move the record into" },
+        name: { type: "string", description: "project_new, project_link, project_remove: the project's name" },
+        worktrees: { type: "string", description: "project_new, project_link: where children's worktrees go" },
+        title: { type: "string", description: "create, child, fanout: the new task's title" },
+        goal: {
+          type: "string",
+          description:
+            "create, child, fanout: its goal, one line; omitted, the title is the goal (the dialog shows it)",
+        },
+        entry: { type: "string", description: "view: one entry ID such as S-004" },
+        query: { type: "string", description: "search: text to find" },
+        scope: { type: "string", enum: ["task", "tree", "project"], description: "search: where to look" },
+        primary: { type: "string", description: "env: the task's new primary directory" },
+        add_dir: { type: "string", description: "env: a directory to add" },
+        remove_dir: { type: "string", description: "env: a directory to remove" },
+      },
+      required: ["action"],
+    },
+    // It asks the user, so scripts must not call it (Pi's guidance for such tools); called directly, its own
+    // transcript views apply, which a codemode script's nested call would bypass.
+    exposure: "model-only",
+    defaultActive: false,
+    executionMode: "sequential",
+    renderCall: (args, theme) => renderTaskCall(args, theme),
+    renderResult: (result, options, theme, context) => renderTaskResult(result, options, theme, context),
+    async execute(_id, params, _signal, _update, ctx) {
+      const refused = reads(params) ? undefined : host.refusal?.();
+      const group = reads(params) ? undefined : autoApproveGroup(params?.action);
+      const approved = group !== undefined && host.autoApproved?.(group) === true;
+      const result = refused ? { ok: false, text: refused } : await run(host, params, ctx, approved);
+      if (approved && result.ok)
+        result.text = `Auto-approved by the user's taskMemory.autoApprove setting (${group}); no dialog was shown.\n\n${result.text}`;
+      if (result.ok && CHANGES_STATE.has(params?.action)) host.changed(ctx);
+      let next;
+      if (result.ok && result.snapshot) {
+        const brief = await host.memory.brief(result.snapshot);
+        result.headline ??= `${params.action === "focus" ? "Focus on" : "Attached"} ${brief.label} · ${brief.state}`;
+        next = brief.next || undefined;
+      }
+      return {
+        content: [{ type: "text", text: result.text }],
+        details: {
+          action: params?.action,
+          ...(result.snapshot ? { snapshot: result.snapshot } : {}),
+          ...(result.headline ? { headline: result.headline } : {}),
+          ...(next ? { next } : {}),
+          ...(result.command ? { command: result.command } : {}),
+          ...(result.id ? { id: result.id } : {}),
+        },
+        ...(result.ok ? {} : { isError: true }),
+      };
+    },
+  });
+}
+/** Ask the user before an action taken on their authority; without a UI the proposal cannot be confirmed. */
+async function confirmProposal(ctx, title, message) {
+  if (!ctx.hasUI) return { ok: false, text: `${title} needs the user's confirmation, and no UI is available.` };
+  if (await confirmWithUser(ctx, title, message)) return undefined;
+  return { ok: false, headline: "Declined by the user", text: "The user declined. Do not retry or work around it." };
+}
+const show = (value) => (typeof value === "string" ? value.trim() : "");
+async function run(host, params, ctx, approved = false) {
+  const { memory } = host;
+  // An action the user's auto-approve setting covers runs without asking.
+  const ask = (context, title, message) =>
+    approved ? Promise.resolve(undefined) : confirmProposal(context, title, message);
+  const cwd = ctx.cwd;
+  switch (params?.action) {
+    case "projects":
+      return memory.projects(cwd);
+    case "list":
+      return { ok: true, text: await memory.list(cwd, params.project) };
+    case "view":
+      return memory.view(params.record, params.entry, cwd);
+    case "search":
+      return memory.search(params.query, params.scope, cwd);
+    case "focus":
+      return memory.focus(params.record, cwd);
+    case "detach":
+      return memory.detach(params.record, cwd);
+    case "attach":
+      return (
+        (await ask(
+          ctx,
+          "Attach task record?",
+          `The agent proposes working on ${show(params.record)} in this session.`,
+        )) ?? memory.attach(params.record, cwd)
+      );
+    case "create": {
+      const declined = await ask(
+        ctx,
+        "Create task?",
+        `Create "${show(params.title)}" in this repository's project and attach it to this session? Goal: ${show(params.goal) || show(params.title)}`,
+      );
+      if (declined) return declined;
+      const created = await memory.create(params.title, params.goal, cwd);
+      if (!created.ok || !created.id) return created;
+      const attached = await memory.attach(created.id, cwd);
+      return attached.ok
+        ? {
+            ...attached,
+            headline: `Created and attached ${created.id} — ${show(params.title)}`,
+            text: `Created ${created.id} and attached it to this session.\n\n${attached.text}`,
+          }
+        : { ...attached, text: `Created ${created.id}, but it was not attached: ${attached.text}` };
+    }
+    case "child":
+      return (
+        (await ask(
+          ctx,
+          "Create child task?",
+          `Create "${show(params.title)}" as a child of the focused task, for a parallel session you start?`,
+        )) ?? memory.child(params.title, params.goal)
+      );
+    case "fanout":
+      return (
+        (await ask(
+          ctx,
+          "Fan out a child task?",
+          `Create child "${show(params.title)}" of the focused task with its own Git worktree and branch? You start its session in a new terminal.`,
+        )) ?? memory.fanout(params.title, params.goal)
+      );
+    case "project_new":
+    case "project_link": {
+      const operation = params.action === "project_new" ? "new" : "link";
+      const declined = await ask(
+        ctx,
+        operation === "new" ? "Create project?" : "Link repository?",
+        operation === "new"
+          ? `Create project "${show(params.name)}" and link this repository (${cwd}) to it?${show(params.worktrees) ? ` Child worktrees go in ${show(params.worktrees)}.` : ""}`
+          : `Link this repository (${cwd}) to project "${show(params.name)}"?`,
+      );
+      return declined ?? memory.project(operation, params.name, params.worktrees, cwd);
+    }
+    case "import":
+      return (
+        (await ask(
+          ctx,
+          "Import record?",
+          `Move ${show(params.record)} into the ${show(params.project)} project's store, with a task ID?`,
+        )) ?? memory.importRecord(params.record, params.project, cwd)
+      );
+    case "confirm":
+      return (
+        (await ask(
+          ctx,
+          "Make held record writable?",
+          `Let this session write ${show(params.record) || "its held records"}, taking ownership where another session owns one?`,
+        )) ?? memory.confirm(params.record, cwd)
+      );
+    case "env": {
+      const change = { primary: show(params.primary), add: show(params.add_dir), remove: show(params.remove_dir) };
+      if (change.primary || change.add || change.remove) {
+        const declined = await ask(
+          ctx,
+          "Change task directories?",
+          `For ${show(params.record)}: ${[change.primary && `primary ${change.primary}`, change.add && `add ${change.add}`, change.remove && `remove ${change.remove}`].filter(Boolean).join(", ")}?`,
+        );
+        if (declined) return declined;
+      }
+      return memory.environment(params.record, change, cwd);
+    }
+    case "remove":
+    case "project_remove": {
+      // Removal always asks: no auto-approve setting covers it (Task 006).
+      const target = params.action === "remove" ? { task: params.record } : { project: params.name };
+      const { question, error } = await memory.removalQuestion(target);
+      if (!question) return { ok: false, text: error ?? "Nothing to remove." };
+      const title = params.action === "remove" ? "Remove task?" : "Remove project?";
+      return (await confirmProposal(ctx, title, question)) ?? memory.remove(target);
+    }
+    default:
+      return { ok: false, text: `action must be one of ${ACTIONS.join(", ")}.` };
+  }
+}
+/** Declare or withdraw task_memory when task memory's effective state changes, keeping other tools in place. */
+export function applyTaskMemoryTools(pi, effective) {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const current = pi.getActiveTools();
+  const present = current.includes(TASK_MEMORY_TOOL);
+  if (effective && !present) pi.setActiveTools([...current, TASK_MEMORY_TOOL]);
+  if (!effective && present) pi.setActiveTools(current.filter((name) => name !== TASK_MEMORY_TOOL));
+}

package/pi-extension/dist/tool-execution/apply-patch/tool.js

@@ -2,7 +2,7 @@ import { APPLY_PATCH_LARK_GRAMMAR } from "./grammar.js";
 import { applyPatch } from "./plan.js";
 export const APPLY_PATCH = "apply_patch";
 const DESCRIPTION =
-  "Use the apply_patch tool to edit files. Its input is a patch: *** Begin Patch, then *** Add File:, *** Update File: (optionally followed by *** Move to:) or *** Delete File: sections, then *** End Patch. In update sections, @@ lines anchor a hunk and every other line starts with space (context), - (remove) or + (add). Include enough context lines for each hunk to match one place.";
+  "Use apply_patch to change several files in one call, or to add, delete or move files together with other changes; to change one existing file, use edit. The input is a patch: *** Begin Patch, then *** Add File:, *** Update File: (optionally followed by *** Move to:) or *** Delete File: sections, then *** End Patch. In update sections, @@ lines anchor a hunk and every other line starts with space (context), - (remove) or + (add). Copy context lines from your latest view of the file, enough for each hunk to match one place.";
 const CODES = { add: "A", update: "M", move: "M", delete: "D" };
 /** Codex's summary on success, so GPT models read the result they were trained on. */
 export function resultText(result) {

package/pi-extension/dist/tool-execution/background.js

@@ -3,14 +3,27 @@ import { createWriteStream } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
 import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
 export const BASH_BACKGROUND = "bash_background";
+export const MONITOR = "monitor";
 export const STOP_BACKGROUND = "stop_background";
 export const NOTICE_TYPE = "freeflow-background";
+export const MONITOR_TYPE = "freeflow-monitor";
+/** Background commands and monitors together. */
 export const MAX_RUNNING = 16;
+export const MONITOR_DEFAULT_MS = 5 * 60_000;
+export const MONITOR_MAX_MS = 30 * 60_000;
+/** Event notices a monitor may send per minute before it is stopped; each one can start a model turn. */
+export const MONITOR_PER_MINUTE = 20;
+/** Lines one event notice shows; the rest stay in the output file. */
+export const MONITOR_MAX_LINES = 40;
+const MAX_LINE_CHARS = 1_000;
 /** Marks harness messages, which arrive on their own schedule, as not written by the user. */
-export const NOTICE_PREFIX = "[Freeflow notice, not from the user]";
-const newId = () => `bg${randomBytes(6).readUIntBE(0, 6).toString(36).slice(-6).padStart(6, "0")}`;
+import { freeflowNotice } from "../host/inbound.js";
+export { freeflowNotice };
+const newId = (prefix) => `${prefix}${randomBytes(6).readUIntBE(0, 6).toString(36).slice(-6).padStart(6, "0")}`;
+const shellQuote = (text) => `'${text.replace(/'/g, `'\\''`)}'`;
 function labelFor(command, description) {
   const text = description?.trim() || command.trim().split("\n")[0];
   return text.length > 80 ? `${text.slice(0, 77)}...` : text;
@@ -28,6 +41,10 @@ function close(stream, trailer) {
 export class BackgroundJobs {
   host;
   jobs = new Map();
+  /** Launches between their check of MAX_RUNNING and their job's registration. */
+  starting = 0;
+  /** Changes when the session ends, so a launch that was still starting then does not run. */
+  generation = 0;
   constructor(host) {
     this.host = host;
   }
@@ -35,39 +52,101 @@ export class BackgroundJobs {
     return [...this.jobs.values()].filter((job) => job.status === "running");
   }
   async start(command, description, cwd, sessionId) {
-    const running = this.running();
-    if (running.length >= MAX_RUNNING)
+    return this.launch("command", command, description, cwd, sessionId);
+  }
+  /**
+   * Claude Code's Monitor: each line the command prints to stdout is an event for the model, batched by the host;
+   * stderr goes to the output file only. One notice when the command exits, expires, or is stopped for sending too
+   * much.
+   */
+  async monitor(command, description, timeoutMs, cwd, sessionId) {
+    const ms = Math.min(Math.max(Math.round(timeoutMs) || MONITOR_DEFAULT_MS, 1_000), MONITOR_MAX_MS);
+    return this.launch("monitor", command, description, cwd, sessionId, ms);
+  }
+  async launch(kind, command, description, cwd, sessionId, timeoutMs) {
+    if (this.running().length + this.starting >= MAX_RUNNING)
       throw new Error(`${MAX_RUNNING} background commands are running. Stop one with stop_background, then retry.`);
-    let id = newId();
-    while (this.jobs.has(id)) id = newId();
+    const prefix = kind === "monitor" ? "mon" : "bg";
+    let id = newId(prefix);
+    while (this.jobs.has(id)) id = newId(prefix);
+    const generation = this.generation;
     const folder = join(tmpdir(), "freeflow", sessionId.replace(/[^A-Za-z0-9._-]/g, "_"), "background");
-    await mkdir(folder, { recursive: true, mode: 0o700 });
     const outputPath = join(folder, `${id}.output`);
-    const stream = createWriteStream(outputPath, { flags: "w", mode: 0o600 });
-    await new Promise((resolve, reject) => {
-      stream.once("open", () => resolve());
-      stream.once("error", reject);
-    });
+    // A monitor's stderr is appended to the same file by the shell, so both writers append.
+    let stream;
+    this.starting++;
+    try {
+      await mkdir(folder, { recursive: true, mode: 0o700 });
+      stream = createWriteStream(outputPath, { flags: kind === "monitor" ? "a" : "w", mode: 0o600 });
+      await new Promise((resolve, reject) => {
+        stream.once("open", () => resolve());
+        stream.once("error", reject);
+      });
+    } finally {
+      this.starting--;
+    }
+    if (generation !== this.generation) {
+      await close(stream, "[not started: the session ended]\n");
+      throw new Error("The session ended before the command started.");
+    }
     const controller = new AbortController();
     let endsWithNewline = true;
     const job = {
       id,
+      kind,
       label: labelFor(command, description),
       outputPath,
       controller,
       status: "running",
+      events: 0,
       done: Promise.resolve(),
     };
-    const run = createLocalBashOperations({ shellPath: this.host.shellPath() }).exec(command, cwd, {
+    let partial = "";
+    // One decoder per job, so a character split across two reads is decoded whole.
+    const decoder = new StringDecoder("utf8");
+    const event = (line) => {
+      job.events++;
+      const text = line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}... (line cut)` : line;
+      this.host.event(
+        id,
+        text,
+        (lines) => this.eventText(job, lines),
+        () => this.halt(job, "limit"),
+      );
+    };
+    const script = kind === "monitor" ? `{\n${command}\n} 2>>${shellQuote(outputPath)}` : command;
+    const run = createLocalBashOperations({ shellPath: this.host.shellPath() }).exec(script, cwd, {
       onData: (data) => {
         if (data.length === 0) return;
         endsWithNewline = data[data.length - 1] === 10;
         stream.write(data);
+        if (kind !== "monitor" || job.stopping) return;
+        const lines = (partial + decoder.write(data)).split("\n");
+        // An unfinished line keeps only what a terminal would show (the text after its last carriage return), so a
+        // progress bar redrawn with \r does not grow it without bound; the output file has everything.
+        partial = (lines.pop() ?? "")
+          .split("\r")
+          .at(-1)
+          .slice(-4 * MAX_LINE_CHARS);
+        for (const line of lines) if (line.trim() !== "") event(line.replace(/\r$/, ""));
       },
       signal: controller.signal,
     });
+    const timer =
+      timeoutMs === undefined ? undefined : setTimeout(() => this.halt(job, "expired"), timeoutMs).unref?.();
+    const finish = () => {
+      if (timer) clearTimeout(timer);
+      job.ended = true;
+      if (kind !== "monitor") return;
+      partial += decoder.end();
+      if (partial.trim() !== "" && !job.stopping) event(partial);
+      partial = "";
+      if (job.stopping === "shutdown" && this.host.discardEvents) this.host.discardEvents(id);
+      else this.host.endEvents(id);
+    };
     job.done = run.then(
       async ({ exitCode }) => {
+        finish();
         const code = exitCode ?? 1;
         job.exitCode = code;
         job.status = code === 0 ? "completed" : "failed";
@@ -75,10 +154,20 @@ export class BackgroundJobs {
         this.notify(job);
       },
       async (error) => {
+        finish();
         const lead = endsWithNewline ? "" : "\n";
         if (job.stopping) {
           job.status = "stopped";
-          await close(stream, `${lead}${job.stopping === "tool" ? "[stopped]" : "[stopped at session end]"}\n`);
+          const trailer =
+            job.stopping === "tool"
+              ? "[stopped]"
+              : job.stopping === "shutdown"
+                ? "[stopped at session end]"
+                : job.stopping === "expired"
+                  ? "[stopped: timeout]"
+                  : "[stopped: too many events]";
+          await close(stream, `${lead}${trailer}\n`);
+          if (job.stopping === "expired" || job.stopping === "limit") this.notify(job);
           return;
         }
         // The command could not run (for example, the working directory is gone).
@@ -89,7 +178,25 @@ export class BackgroundJobs {
       },
     );
     this.jobs.set(id, job);
-    return { id, outputPath };
+    return { id, outputPath, ...(timeoutMs === undefined ? {} : { timeoutMs }) };
+  }
+  /** Stop a monitor on its own account: its timeout passed, or it sent more than its rate limit allows. */
+  halt(job, reason) {
+    if (job.status !== "running" || job.stopping || job.ended) return;
+    job.stopping = reason;
+    job.controller.abort();
+  }
+  eventText(job, lines) {
+    const shown = lines.slice(0, MONITOR_MAX_LINES);
+    const more = lines.length - shown.length;
+    return freeflowNotice(
+      "monitor",
+      [
+        `Monitor ${job.id} (${job.label}):`,
+        ...shown,
+        ...(more > 0 ? [`... ${more} more lines in ${job.outputPath}`] : []),
+      ].join("\n"),
+    );
   }
   async stop(id) {
     const job = this.jobs.get(id);
@@ -117,6 +224,7 @@ export class BackgroundJobs {
   }
   /** Session end: stop every running job, wait for the processes to exit, forget them. No notice is sent. */
   async stopAll() {
+    this.generation++;
     const running = this.running();
     for (const job of running) {
       job.stopping = "shutdown";
@@ -129,15 +237,45 @@ export class BackgroundJobs {
   restate() {
     const running = this.running();
     if (running.length === 0) return;
-    const list = running.map((job) => `${job.id} (${job.label}), output ${job.outputPath}`).join("; ");
+    const list = running
+      .map((job) => `${job.kind === "monitor" ? "monitor " : ""}${job.id} (${job.label}), output ${job.outputPath}`)
+      .join("; ");
     this.host.send(
-      `${NOTICE_PREFIX} Still running: ${list}. Do not start them again; stop one with stop_background before restarting it.`,
+      freeflowNotice(
+        "background",
+        `Still running: ${list}. Do not start them again; stop one with stop_background before restarting it.`,
+      ),
       { running: running.map((job) => ({ id: job.id, outputPath: job.outputPath })) },
       false,
     );
   }
   notify(job, runError) {
-    if (job.stopping) return;
+    if (job.stopping === "tool" || job.stopping === "shutdown") return;
+    const details = {
+      id: job.id,
+      ...(job.kind === "monitor" ? { kind: job.kind } : {}),
+      status: job.status,
+      ...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
+      ...(job.kind === "monitor" ? { events: job.events } : {}),
+      outputPath: job.outputPath,
+    };
+    if (job.kind === "monitor") {
+      const events = `${job.events} ${job.events === 1 ? "event" : "events"}`;
+      const outcome =
+        job.stopping === "expired"
+          ? `reached its timeout after ${events} and was stopped. Start it again to keep watching.`
+          : job.stopping === "limit"
+            ? `was stopped after ${events}: it sent more than ${MONITOR_PER_MINUTE} notices in a minute. Filter its output to the lines you would act on, then start it again.`
+            : runError !== undefined
+              ? `failed to run: ${runError}.`
+              : `exited with code ${job.exitCode} after ${events}.`;
+      this.host.send(
+        freeflowNotice("monitor", `Monitor ${job.id} (${job.label}) ${outcome} Output: ${job.outputPath}.`),
+        details,
+        true,
+      );
+      return;
+    }
     const outcome =
       runError !== undefined
         ? `failed to run: ${runError}`
@@ -145,23 +283,29 @@ export class BackgroundJobs {
           ? "completed"
           : `failed with exit code ${job.exitCode}`;
     this.host.send(
-      `${NOTICE_PREFIX} Background command ${job.id} (${job.label}) ${outcome}. Output: ${job.outputPath}.`,
-      {
-        id: job.id,
-        status: job.status,
-        ...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
-        outputPath: job.outputPath,
-      },
+      freeflowNotice(
+        "background",
+        `Background command ${job.id} (${job.label}) ${outcome}. Output: ${job.outputPath}.`,
+      ),
+      details,
       true,
     );
   }
 }
 const START_DESCRIPTION = [
-  "Run a shell command in the background. Use it for servers, watchers and commands expected to run longer than two minutes. Returns an ID and an output file at once; you are notified once, when the command exits. Read the output file for output so far.",
+  "Run a shell command in the background; it returns at once with an ID and an output file. Use it for servers, watchers, and builds, test runs or installs expected to take over two minutes; run shorter commands with bash.",
+  "You are notified once, when the command exits; if you are idle then, the notice starts a new turn. Meanwhile do other work, and read the output file only for output so far; do not poll it.",
   "To be notified when something becomes ready, run a command that exits when it is: until grep -qE 'Listening|Error|Traceback' server.log; do sleep 1; done. Match the failure lines too: a check that waits only for success stays silent when the process crashes.",
+  "Commands stop when the session ends; their output files stay readable.",
+].join("\n\n");
+const MONITOR_DESCRIPTION = [
+  "Use monitor to act on a running command's lines as they appear: errors in a log while you test, failures in a long test run. For one signal (a server is ready, a build finished), use bash_background with a command that exits when the condition holds.",
+  "Each line the command prints to stdout reaches you as a notice (lines within 200 ms join one notice); stderr goes only to the output file. You also get one notice when the command exits or when timeout_ms passes (default 5 minutes, at most 30); start it again to keep watching. A notice that arrives while you are idle starts a model turn, so make the command print only lines you would act on; one that prints too much is stopped.",
+  "Every stage of a pipe must flush each line (grep --line-buffered, awk with fflush()), or lines wait in a buffer; head cannot.",
+  "Silence is not success: match every outcome you would act on, failures as well as success, for example tail -f app.log | grep -E --line-buffered 'ready|ERROR|Traceback|FAILED'.",
 ].join("\n\n");
 const STOP_DESCRIPTION =
-  "Stop a background command started with bash_background. Returns after the command has exited.";
+  "Stop a background command or monitor once neither you nor the user needs it, such as a server after the checks that used it. Returns after it has exited.";
 /** Registered once, inactive until Tool Execution is effective (see tool-execution/tools.ts). */
 export function registerBackgroundTools(pi, jobs, host) {
   const guard = () => {
@@ -208,6 +352,54 @@ export function registerBackgroundTools(pi, jobs, host) {
       };
     },
   });
+  pi.registerTool({
+    name: MONITOR,
+    label: MONITOR,
+    description: MONITOR_DESCRIPTION,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        command: { type: "string", description: "Shell command whose stdout lines are the events" },
+        description: { type: "string", description: "A few words saying what is watched; shown with every event" },
+        timeout_ms: {
+          type: "number",
+          minimum: 1_000,
+          maximum: MONITOR_MAX_MS,
+          description: `Stop watching after this long (default ${MONITOR_DEFAULT_MS}, at most ${MONITOR_MAX_MS})`,
+        },
+      },
+      required: ["command", "description"],
+    },
+    outputSchema: {
+      type: "object",
+      properties: { id: { type: "string" }, outputPath: { type: "string" }, timeoutMs: { type: "number" } },
+      required: ["id", "outputPath", "timeoutMs"],
+    },
+    exposure: "direct",
+    defaultActive: false,
+    async execute(_id, params, _signal, _u, ctx) {
+      guard();
+      const started = await jobs.monitor(
+        String(params?.command ?? ""),
+        String(params?.description ?? ""),
+        Number(params?.timeout_ms ?? MONITOR_DEFAULT_MS),
+        ctx.cwd,
+        ctx.sessionManager?.getSessionId?.() ?? "session",
+      );
+      const minutes = Math.round(((started.timeoutMs ?? MONITOR_DEFAULT_MS) / 60_000) * 10) / 10;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Monitor ${started.id} started. Each line it prints reaches you as a notice; it stops when the command exits, after ${minutes} min, or with stop_background. When you tell the user you are watching, say it stops after ${minutes} min unless restarted. Output: ${started.outputPath}.`,
+          },
+        ],
+        details: started,
+        structuredContent: started,
+      };
+    },
+  });
   pi.registerTool({
     name: STOP_BACKGROUND,
     label: STOP_BACKGROUND,
@@ -215,7 +407,7 @@ export function registerBackgroundTools(pi, jobs, host) {
     parameters: {
       type: "object",
       additionalProperties: false,
-      properties: { id: { type: "string", description: "The ID bash_background returned" } },
+      properties: { id: { type: "string", description: "The ID bash_background or monitor returned" } },
       required: ["id"],
     },
     outputSchema: {

package/pi-extension/dist/tool-execution/config.js

@@ -1,4 +1,9 @@
-export const DEFAULT_TOOL_EXECUTION_CONFIG = Object.freeze({ enabled: false });
+export const DEFAULT_TOOL_EXECUTION_CONFIG = Object.freeze({
+  enabled: true,
+  guidanceNotices: true,
+});
+/** The keys `toolExecution` acts on; the settings test checks each has a /freeflow settings row. */
+export const TOOL_EXECUTION_KEYS = ["enabled", "guidanceNotices"];
 // Settings of the retired v2 runtime (.deprecated/tool-execution-v2). Existing configuration files keep loading;
 // the values no longer do anything.
 const RETIRED_KEYS = ["capture", "programs", "workspace", "discovery", "adapters", "accounting"];
@@ -7,10 +12,12 @@ function record(value) {
 }
 export function validateToolExecutionConfig(value) {
   if (!record(value)) return "toolExecution must be an object";
-  const unknown = Object.keys(value).find((key) => key !== "enabled" && !RETIRED_KEYS.includes(key));
+  const unknown = Object.keys(value).find((key) => !TOOL_EXECUTION_KEYS.includes(key) && !RETIRED_KEYS.includes(key));
   if (unknown) return `toolExecution has unsupported key: ${unknown}`;
   if (value.enabled !== undefined && typeof value.enabled !== "boolean")
     return "toolExecution.enabled must be a boolean";
+  if (value.guidanceNotices !== undefined && typeof value.guidanceNotices !== "boolean")
+    return "toolExecution.guidanceNotices must be a boolean";
   return null;
 }
 export function resolveToolExecutionConfig(repository, local, freeflowEnabled) {
@@ -18,5 +25,9 @@ export function resolveToolExecutionConfig(repository, local, freeflowEnabled) {
   const localTool = record(local.toolExecution) ? local.toolExecution : {};
   const setting = Object.hasOwn(localTool, "enabled") ? localTool.enabled : repositoryTool.enabled;
   const enabled = setting === undefined ? DEFAULT_TOOL_EXECUTION_CONFIG.enabled : setting === true;
-  return { enabled, effective: freeflowEnabled && enabled };
+  const notices = Object.hasOwn(localTool, "guidanceNotices")
+    ? localTool.guidanceNotices
+    : repositoryTool.guidanceNotices;
+  const guidanceNotices = notices === undefined ? DEFAULT_TOOL_EXECUTION_CONFIG.guidanceNotices : notices === true;
+  return { enabled, guidanceNotices, effective: freeflowEnabled && enabled };
 }