@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/dist/tool-execution/edit-messages.js

@@ -0,0 +1,120 @@
+// Messages Freeflow gives around Pi's edit and write. Every error ends in one literal next action; results carry no
+// reassurance. The wording was reviewed against the Beyond the Weights findings (Task 006 evidence).
+const MAX_SHOWN_LINES = 20;
+const MAX_LINE_CHARS = 300;
+const MIN_SIMILARITY = 0.5;
+/** Pi's edit fuzzy normalization (core/tools/edit-diff.ts normalizeForFuzzyMatch, not exported). */
+export function normalizeForMatch(text) {
+  return text
+    .normalize("NFKC")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .replace(/[‘’‚‛]/g, "'")
+    .replace(/[“”„‟]/g, '"')
+    .replace(/[‐‑‒–—―−]/g, "-")
+    .replace(/[  -   　]/g, " ");
+}
+/** File text as Pi's edit matches it: without a BOM and with LF line endings. */
+export function editableText(raw) {
+  return raw.replace(/^/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function bigrams(text) {
+  const counts = new Map();
+  for (let i = 0; i < text.length - 1; i++) {
+    const pair = text.slice(i, i + 2);
+    counts.set(pair, (counts.get(pair) ?? 0) + 1);
+  }
+  return counts;
+}
+function lineSimilarity(a, b) {
+  const x = a.trim(),
+    y = b.trim();
+  if (x === y) return 1;
+  if (x.length < 2 || y.length < 2) return 0;
+  const left = bigrams(x),
+    right = bigrams(y);
+  let shared = 0;
+  for (const [pair, count] of left) shared += Math.min(count, right.get(pair) ?? 0);
+  return (2 * shared) / (x.length - 1 + (y.length - 1));
+}
+/** The window of the file most similar to the old text, as 1-based inclusive lines, or undefined when none is close. */
+export function closestMatch(fileText, oldText) {
+  const lines = fileText.split("\n");
+  const wanted = oldText.replace(/\n+$/, "").split("\n");
+  const size = Math.min(wanted.length, lines.length);
+  if (size === 0) return undefined;
+  let best;
+  for (let start = 0; start + size <= lines.length; start++) {
+    let total = 0;
+    for (let i = 0; i < size; i++) total += lineSimilarity(lines[start + i], wanted[i]);
+    const score = total / wanted.length;
+    if (!best || score > best.score) best = { start, score };
+  }
+  return best && best.score >= MIN_SIMILARITY ? { start: best.start + 1, end: best.start + size } : undefined;
+}
+/** 1-based start lines of every place the old text matches, compared as Pi's edit compares it. */
+export function matchingLines(fileText, oldText) {
+  const haystack = normalizeForMatch(fileText),
+    needle = normalizeForMatch(oldText);
+  const found = [];
+  if (!needle) return found;
+  for (let index = haystack.indexOf(needle); index >= 0; index = haystack.indexOf(needle, index + 1))
+    found.push(haystack.slice(0, index).split("\n").length);
+  return found;
+}
+function shownLines(fileText, start, end) {
+  return fileText
+    .split("\n")
+    .slice(start - 1, Math.min(end, start - 1 + MAX_SHOWN_LINES))
+    .map((line) => (line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}…` : line))
+    .join("\n");
+}
+const NOT_FOUND = /^Could not find (?:the exact text|edits\[(\d+)\]) in (.+?)\. The old ?[tT]ext must match exactly/;
+const NOT_UNIQUE = /^Found (\d+) occurrences of (?:the text|edits\[(\d+)\]) in (.+?)\. /;
+/**
+ * Replace Pi's not-found or not-unique edit error with one literal next action. Returns undefined when the error is
+ * another kind (overlap, empty, no change) or Pi worded it differently, so the result stays exactly as Pi wrote it.
+ */
+export function rewriteEditError(error, path, edits, fileText) {
+  const notFound = NOT_FOUND.exec(error);
+  if (notFound) {
+    const index = notFound[1] === undefined ? 0 : Number(notFound[1]);
+    const subject = notFound[1] === undefined ? path : `${path} edits[${index}]`;
+    const oldText = editableText(String(edits[index]?.oldText ?? ""));
+    const match = closestMatch(fileText, oldText);
+    if (!match)
+      return `${subject}: old text not found and no similar lines exist in the current file. Read the region you meant, then retry.`;
+    return [
+      `${subject}: old text not found. Closest match, lines ${match.start}–${match.end} (current file contents):`,
+      shownLines(fileText, match.start, match.end),
+      "If these are the lines you meant, retry with old text copied exactly from them. If not, read the region you meant, then retry.",
+    ].join("\n");
+  }
+  const notUnique = NOT_UNIQUE.exec(error);
+  if (notUnique) {
+    const index = notUnique[2] === undefined ? 0 : Number(notUnique[2]);
+    const subject = notUnique[2] === undefined ? path : `${path} edits[${index}]`;
+    const lines = matchingLines(fileText, editableText(String(edits[index]?.oldText ?? "")));
+    const places = lines.length > 0 ? lines.length : Number(notUnique[1]);
+    const where = lines.length > 0 ? ` (lines ${lines.join(", ")})` : "";
+    return `${subject}: old text matches ${places} places${where}. To change one place, add surrounding lines until it matches only that place. To change every place, give one edits[] entry per place, each with enough surrounding lines to match only that place.`;
+  }
+  return undefined;
+}
+export const writeRefusal = (path) =>
+  `${path} exists and has not been read in this session. Read ${path}, then retry the write.`;
+export const changedAfterEdit = (path) => `${path} changed since you read it; the edit applied to the current text.`;
+export const changedAfterWrite = (path) =>
+  `${path} changed since you read it; the write replaced the current contents.`;
+export const noNeedToReread = (path) => `No need to re-read ${path} to confirm this edit.`;
+/** Files the model read that changed or disappeared outside its own edits, as a fact and one next action. */
+export function changedFilesNotice(changed, deleted) {
+  const lines = [];
+  if (changed.length > 0)
+    lines.push(
+      `Files you read earlier changed since you read them: ${changed.join(", ")}. Read what you need from them again before editing them.`,
+    );
+  if (deleted.length > 0) lines.push(`Files you read earlier no longer exist: ${deleted.join(", ")}.`);
+  return lines.length > 0 ? lines.join("\n") : undefined;
+}

package/pi-extension/dist/tool-execution/file-state.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+// Files above this size are identified by size and modification time instead of a content hash.
+export const HASH_LIMIT_BYTES = 8 * 1024 * 1024;
+const UNICODE_SPACES = /[  -   　]/g;
+/** Resolve a tool path the way Pi's tools do: strip `@`, normalize odd spaces, expand `~`, resolve against cwd. */
+export function resolveToolPath(path, cwd) {
+  let candidate = path.replace(UNICODE_SPACES, " ");
+  if (candidate.startsWith("@")) candidate = candidate.slice(1);
+  if (candidate === "~") candidate = homedir();
+  else if (candidate.startsWith("~/")) candidate = `${homedir()}${candidate.slice(1)}`;
+  const resolved = isAbsolute(candidate) ? resolve(candidate) : resolve(cwd, candidate);
+  if (existsSync(resolved)) return resolved;
+  // Pi's read also finds macOS names typed differently: narrow space before AM/PM, NFD, curly apostrophe.
+  for (const variant of [
+    resolved.replace(/ (AM|PM)\./gi, " $1."),
+    resolved.normalize("NFD"),
+    resolved.replace(/'/g, "’"),
+  ])
+    if (variant !== resolved && existsSync(variant)) return variant;
+  return resolved;
+}
+function fileKey(path, cwd) {
+  const resolved = resolveToolPath(path, cwd);
+  try {
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+async function fingerprint(file) {
+  let info;
+  try {
+    info = await stat(file);
+  } catch {
+    return "absent";
+  }
+  if (!info.isFile()) return "absent";
+  if (info.size > HASH_LIMIT_BYTES) return { size: info.size, mtimeMs: info.mtimeMs };
+  const bytes = await readFile(file);
+  return { sha256: createHash("sha256").update(bytes).digest("hex"), size: bytes.length };
+}
+async function statOf(file) {
+  try {
+    const info = await stat(file);
+    return info.isFile() ? { size: info.size, mtimeMs: info.mtimeMs } : "absent";
+  } catch {
+    return "absent";
+  }
+}
+const sameStat = (a, b) =>
+  a !== undefined && (a === "absent" || b === "absent" ? a === b : a.size === b.size && a.mtimeMs === b.mtimeMs);
+function sameFingerprint(a, b) {
+  if (a === "absent" || b === "absent") return a === b;
+  if ("sha256" in a && "sha256" in b) return a.sha256 === b.sha256;
+  if ("mtimeMs" in a && "mtimeMs" in b) return a.size === b.size && a.mtimeMs === b.mtimeMs;
+  return false;
+}
+/** The files a successful tool call read or changed, from a tool call's name and arguments. */
+export function touchedPaths(toolName, input) {
+  if (["read", "edit", "write"].includes(toolName)) return typeof input?.path === "string" ? [input.path] : [];
+  if (toolName === "apply_patch" && typeof input?.input === "string")
+    return [...input.input.matchAll(/^\s*\*\*\* (?:Add File|Update File|Delete File|Move to): (.+?)\s*$/gm)].map(
+      (match) => match[1],
+    );
+  return [];
+}
+/**
+ * Which files the model has read or written on the current branch, and their content at that moment. Held in memory
+ * and rebuilt from the branch after navigation or resume; never persisted and never consulted on the request path.
+ */
+export class FileState {
+  files = new Map();
+  async observe(path, cwd, via) {
+    const key = fileKey(path, cwd);
+    const at = await statOf(key);
+    this.files.set(key, { fingerprint: await fingerprint(key), via, stat: at });
+  }
+  wasRead(path, cwd) {
+    return this.files.has(fileKey(path, cwd));
+  }
+  /** Whether the file differs from its last observation; false when it was never observed. */
+  async changedSinceObserved(path, cwd) {
+    const key = fileKey(path, cwd);
+    const known = this.files.get(key);
+    if (!known) return false;
+    return !sameFingerprint(known.fingerprint, await fingerprint(key));
+  }
+  /**
+   * Observed files whose content changed since the model last read or wrote them, each reported once per change.
+   * Costs one stat per observed file; a file is hashed only when its size or modification time moved.
+   */
+  async changedSinceNoticed() {
+    const changed = [];
+    for (const [key, known] of this.files) {
+      const at = await statOf(key);
+      if (sameStat(known.stat, at)) continue;
+      known.stat = at;
+      const now = await fingerprint(key);
+      if (sameFingerprint(known.fingerprint, now)) continue;
+      if (known.noticed !== undefined && sameFingerprint(known.noticed, now)) continue;
+      known.noticed = now;
+      changed.push({ path: key, deleted: now === "absent" });
+    }
+    return changed;
+  }
+  /**
+   * Mark every file a successful read, edit, write or patch on the branch touched, with today's content. A Freeflow
+   * compaction starts over: the model then holds only the files it carried.
+   */
+  async rebuild(branch, cwd) {
+    this.files.clear();
+    const calls = new Map();
+    const touched = new Set();
+    for (const entry of branch) {
+      if (entry?.type === "compaction" && entry.details?.freeflow) {
+        touched.clear();
+        for (const item of entry.details.freeflow.carried ?? [])
+          if (item?.kind === "file" && typeof item.path === "string" && !item.error) touched.add(item.path);
+      }
+      const message = entry?.type === "message" ? entry.message : undefined;
+      if (message?.role === "assistant")
+        for (const block of message.content ?? [])
+          if (block?.type === "toolCall") calls.set(block.id, { name: block.name, input: block.arguments });
+      if (message?.role === "toolResult" && message.isError !== true) {
+        const call = calls.get(message.toolCallId);
+        if (call) for (const path of touchedPaths(call.name, call.input)) touched.add(path);
+      }
+    }
+    for (const path of touched) await this.observe(path, cwd, "rebuilt");
+  }
+  reset() {
+    this.files.clear();
+  }
+}

package/pi-extension/dist/tool-execution/file-tracking.js

@@ -0,0 +1,163 @@
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+import { readFile } from "node:fs/promises";
+import { FileState, resolveToolPath } from "./file-state.js";
+import {
+  changedAfterEdit,
+  changedAfterWrite,
+  changedFilesNotice,
+  editableText,
+  noNeedToReread,
+  rewriteEditError,
+  writeRefusal,
+} from "./edit-messages.js";
+import { SkillReads } from "./skill-reads.js";
+import { cachedBranch } from "../host/branch.js";
+function existingFile(path, cwd) {
+  try {
+    return statSync(resolveToolPath(path, cwd)).isFile();
+  } catch {
+    return false;
+  }
+}
+// Tools whose own targets are observed after they run; any other tool may change files behind the model's back.
+const TRACKED_TOOLS = ["read", "edit", "write", "apply_patch"];
+/** A tracked file (keyed by real path) as the model would name it: relative to the working directory when inside. */
+function shown(path, cwd) {
+  let real = cwd;
+  try {
+    real = realpathSync(cwd);
+  } catch {}
+  for (const base of [real, cwd]) {
+    const inside = relative(base, path);
+    if (inside && !inside.startsWith("..") && !isAbsolute(inside)) return inside;
+  }
+  return path;
+}
+/** A tool result's content with lines appended to its text (before delivery: nothing already sent changes). */
+export function withLines(content, lines) {
+  const text = content.map((part) => (part?.type === "text" ? part.text : "")).join("");
+  return [
+    { type: "text", text: [text, ...lines].filter(Boolean).join("\n") },
+    ...content.filter((part) => part?.type !== "text"),
+  ];
+}
+/**
+ * Claude Code's file awareness around Pi's read, edit and write: refuse a whole-file write over a file never read,
+ * say when an edited file changed since it was read, turn edit errors into one next action, and answer a repeat
+ * read of a Freeflow instruction file the model already holds with one line. Nested calls (codemode) are handled like
+ * direct ones, except that a nested read is never answered for the model: the script consumes its text.
+ */
+export class FileTracking {
+  state = new FileState();
+  changed = new Map();
+  skillReads = new SkillReads();
+  built = false;
+  reset() {
+    this.state.reset();
+    this.changed.clear();
+    this.skillReads.reset();
+    this.built = false;
+  }
+  /** Forget the branch's files; they are rebuilt from the new branch before the next tool call. */
+  invalidate() {
+    this.built = false;
+    this.skillReads.invalidate();
+  }
+  /** After Pi's own compaction the files are unchanged, but the instruction files read before it are out of view. */
+  piCompacted() {
+    this.skillReads.clear();
+  }
+  clearPending() {
+    this.changed.clear();
+  }
+  /** After a Freeflow compaction the model holds only the carried files, read at compaction time. */
+  async compacted(carried, ctx) {
+    this.state.reset();
+    this.changed.clear();
+    for (const path of carried) await this.state.observe(path, ctx.cwd, "read");
+    this.built = true;
+    this.skillReads.clear();
+  }
+  /** Freeflow skills the model holds in this context, by name; reads are rebuilt from the branch when needed. */
+  loadedSkills(ctx) {
+    if (!this.skillReads.built) this.skillReads.rebuild(cachedBranch(ctx.sessionManager) ?? [], ctx.cwd);
+    return this.skillReads.skills();
+  }
+  /** The branch's file state for apply_patch, built when needed. */
+  async forPatch(ctx) {
+    await this.ensureBuilt(ctx);
+    return this.state;
+  }
+  /** Record files a successful apply_patch wrote or moved, as a successful write records them. */
+  async written(paths, ctx) {
+    await this.ensureBuilt(ctx);
+    for (const path of paths) await this.state.observe(path, ctx.cwd, "apply_patch");
+  }
+  async ensureBuilt(ctx) {
+    if (!this.skillReads.built) this.skillReads.rebuild(cachedBranch(ctx.sessionManager) ?? [], ctx.cwd);
+    if (this.built) return;
+    await this.state.rebuild(cachedBranch(ctx.sessionManager) ?? [], ctx.cwd);
+    this.built = true;
+  }
+  async toolCall(event, ctx) {
+    const name = event.toolName;
+    const path = event.input?.path;
+    if (!["edit", "write"].includes(name) || typeof path !== "string") return undefined;
+    await this.ensureBuilt(ctx);
+    if (name === "write" && existingFile(path, ctx.cwd) && !this.state.wasRead(path, ctx.cwd))
+      return { block: true, reason: writeRefusal(path) };
+    if (await this.state.changedSinceObserved(path, ctx.cwd)) this.changed.set(event.toolCallId, path);
+    return undefined;
+  }
+  /** Files the model read that changed since, not yet reported; undefined when there are none. */
+  async changedNotice(ctx, build = true) {
+    // Before a prompt nothing is rebuilt: a branch not yet rebuilt has no baseline to compare against.
+    if (!build && !this.built) return undefined;
+    await this.ensureBuilt(ctx);
+    const found = await this.state.changedSinceNoticed();
+    return changedFilesNotice(
+      found.filter((file) => !file.deleted).map((file) => shown(file.path, ctx.cwd)),
+      found.filter((file) => file.deleted).map((file) => shown(file.path, ctx.cwd)),
+    );
+  }
+  async toolResult(event, ctx) {
+    const name = event.toolName;
+    // A command (or any other tool) may have changed files the model read. Nested calls are reported on the
+    // result of the script that made them, which is what the model sees.
+    if (!TRACKED_TOOLS.includes(name)) {
+      if (event.parentToolCallId) return undefined;
+      const notice = await this.changedNotice(ctx);
+      return notice === undefined ? undefined : { content: withLines(event.content ?? [], [notice]) };
+    }
+    const path = event.input?.path;
+    if (!["read", "edit", "write"].includes(name) || typeof path !== "string") return undefined;
+    await this.ensureBuilt(ctx);
+    const changed = this.changed.get(event.toolCallId);
+    this.changed.delete(event.toolCallId);
+    if (event.isError) {
+      if (name !== "edit") return undefined;
+      let fileText;
+      try {
+        fileText = editableText(await readFile(resolveToolPath(path, ctx.cwd), "utf8"));
+      } catch {
+        return undefined;
+      }
+      const error = (event.content ?? []).map((part) => (part?.type === "text" ? part.text : "")).join("");
+      const rewritten = rewriteEditError(error, path, event.input?.edits ?? [], fileText);
+      return rewritten === undefined ? undefined : { content: [{ type: "text", text: rewritten }] };
+    }
+    await this.state.observe(path, ctx.cwd, name);
+    if (name === "read") {
+      this.skillReads.observe(event, ctx.cwd);
+      return undefined;
+    }
+    const lines =
+      name === "edit"
+        ? [...(changed ? [changedAfterEdit(path)] : []), noNeedToReread(path)]
+        : changed
+          ? [changedAfterWrite(path)]
+          : [];
+    return lines.length > 0 ? { content: withLines(event.content ?? [], lines) } : undefined;
+  }
+}

package/pi-extension/dist/tool-execution/guidance-notices.js

@@ -0,0 +1,124 @@
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { freeflowNotice } from "../host/inbound.js";
+import { isFreeflowInstruction } from "./skill-reads.js";
+/**
+ * Guidance pushed at the moment it is needed (the push retriever, Task 004 D-003): a short Freeflow notice appended to
+ * the result of the tool call that makes it relevant, so it reaches the agent whether or not it read the skill that
+ * owns it.
+ *
+ * - A `git commit` result: Deliver Work's commit essentials, plus Write Skill's loss check when the commit staged
+ *   model-facing instruction text (read from Git at that result). Once per run.
+ * - The second failure of the same test command: diagnose's two key lines. Once per command until it passes.
+ * - A test command that passes after the run changed a file: run Execute Work's self-review before the final report.
+ *   Once per run, and not after self-review ran.
+ * - Any tool result while Execute Work's body is not in the model's context (never read, or dropped by a compaction):
+ *   read it before more tool calls. Once per run, and not on a read of Freeflow's own instruction files, so reading
+ *   Discuss Work first is not interrupted.
+ *
+ * Cache: a notice is part of a tool result that has not been delivered yet, the same path as Tool Execution's
+ * changed-files line; nothing already sent changes. Request path: none of this runs per request. State is in memory,
+ * O(1) per tool result, bounded (at most FAILURE_KEYS test commands), and reset per run where it says so.
+ */
+const FAILURE_KEYS = 32;
+const TEST_COMMAND =
+  /(^|[\s;&|(])((npm|pnpm|yarn|bun)\b[^;&|]*\btest(:[\w:-]+)?\b|node\s+(\S+\s+)*--test\b|(pytest|jest|vitest|mocha|rspec|phpunit|ctest|tox)\b|go\s+test\b|cargo\s+(test|nextest)\b|(mvn|gradle|\.\/gradlew)\b[^;&|]*\btest\b|make\s+(test|check)\b|dotnet\s+test\b|bundle\s+exec\s+rspec\b|python3?\s+-m\s+(pytest|unittest)\b)/;
+const GIT_COMMIT = /(^|[\s;&|(])git(\s+(-C|-c)\s+\S+)*\s+commit\b(?![^;&|]*--help)/;
+const CHANGES_FILES = new Set(["edit", "write", "apply_patch"]);
+// Model-facing instruction text, as Write Skill's loss check reads it: skill packages, capabilities, runtime prompts
+// and instruction files.
+const INSTRUCTION_TEXT =
+  /(^|\/)(SKILL\.md|AGENTS\.md|CLAUDE\.md)$|^(skills|capabilities)\/.+\.md$|(^|\/)prompts\/[^/]+\.md$/;
+export const COMMIT_NOTICE =
+  "Committing (Deliver Work): check what the commit holds with `git show --stat --oneline HEAD` and `git status --short --branch`: only the paths this claim needs, staged explicitly, since staged does not mean yours. Never commit Working Records (`.freeflow/tasks/`), secrets or local environment files. No --amend, --no-verify, --allow-empty or push unless the user asked for exactly that; after a failed commit or hook, inspect what changed before retrying.";
+export const INSTRUCTION_TEXT_NOTICE =
+  "This commit stages model-facing instruction text: for a substantial revision (a merge, split, move or rewrite), run Write Skill's `skill-author compare --all-units` and settle every unmatched unit before it goes further.";
+export const DIAGNOSE_NOTICE =
+  "This test command failed twice (Execute Work's Diagnose Before Fixing; its diagnose reference has the full loop): two failed fixes mean the diagnosis is wrong. Before the next change, find an observation that would come out differently if your explanation were wrong: change the question, change the kind of observation, or check the cheapest assumption (did it build; does the test import what you think?).";
+export const executeWorkNotice = (skill) =>
+  `Read Execute Work (${skill}) before more tool calls: it holds how to read the request, find what a change touches and diagnose a failure.`;
+/** Text without the guidance notices joined to it: moment guidance, not evidence, so it is not carried on. */
+export const withoutGuidanceNotices = (text) =>
+  text.replace(/\n?<freeflow-notice type="guidance">\n[\s\S]*?\n<\/freeflow-notice>/g, "");
+export const selfReviewNotice = (script) =>
+  `Before your final report (Execute Work's step before reporting; read Execute Work if its body is not in your context): run \`node ${script} --base <ref>\` and read its report: changed tests and fixtures with their hunks, new tests and whether they fail on the base, and whether each requirement's check ran after the last edit.`;
+const textOf = (content) => (content ?? []).map((part) => (part?.type === "text" ? part.text : "")).join("");
+/**
+ * The paths a commit command dealt with, read once at its result: what the new commit holds when it succeeded, what is
+ * still staged when it failed. Null when Git cannot tell.
+ */
+function committedPaths(cwd, failed) {
+  const args = failed
+    ? ["diff", "--cached", "--name-only"]
+    : ["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", "HEAD"];
+  return new Promise((resolve) =>
+    execFile("git", args, { cwd, timeout: 2000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) =>
+      resolve(error ? null : stdout.split("\n").filter(Boolean)),
+    ),
+  );
+}
+export class GuidanceNotices {
+  run = { committed: false, changed: false, reviewed: false, reminded: false, executeWork: false };
+  failures = new Map();
+  selfReview;
+  executeWork;
+  constructor(packageRoot) {
+    this.selfReview = join(packageRoot, "skills", "execute-work", "scripts", "self-review.mjs");
+    this.executeWork = join(packageRoot, "skills", "execute-work", "SKILL.md");
+  }
+  /** A new agent run: per-run notices may come again. */
+  runStarted() {
+    this.run = { committed: false, changed: false, reviewed: false, reminded: false, executeWork: false };
+  }
+  /**
+   * The notice lines to append to a tool result; empty when none applies. `executeWorkUnread` says whether Execute
+   * Work is a skill this session lists and its body is not in the model's context; omitted, the notice never shows.
+   */
+  async toolResult(event, cwd, executeWorkUnread) {
+    if (event?.parentToolCallId) return [];
+    const name = event?.toolName;
+    const lines = [];
+    if (
+      !this.run.executeWork &&
+      executeWorkUnread !== undefined &&
+      !isFreeflowInstruction(name, event.input, cwd) &&
+      executeWorkUnread()
+    ) {
+      this.run.executeWork = true;
+      lines.push(freeflowNotice("guidance", executeWorkNotice(this.executeWork)));
+    }
+    if (CHANGES_FILES.has(name)) {
+      if (!event.isError) this.run.changed = true;
+      return lines;
+    }
+    if (name !== "bash") return lines;
+    const command = String(event.input?.command ?? "").trim();
+    if (command.includes("self-review.mjs")) this.run.reviewed = true;
+    if (GIT_COMMIT.test(command) && !this.run.committed) {
+      this.run.committed = true;
+      const paths = await committedPaths(cwd, event.isError === true);
+      const body = [COMMIT_NOTICE];
+      if (paths?.some((path) => INSTRUCTION_TEXT.test(path))) body.push(INSTRUCTION_TEXT_NOTICE);
+      lines.push(freeflowNotice("guidance", body.join("\n")));
+    }
+    if (TEST_COMMAND.test(command)) {
+      const key = command.replace(/\s+/g, " ");
+      // Pi's bash reports a nonzero exit as an error result ("Command exited with code N").
+      const failed = event.isError === true || /Command exited with code [1-9]\d*\s*$/.test(textOf(event.content));
+      if (failed) {
+        const count = (this.failures.get(key) ?? 0) + 1;
+        this.failures.delete(key);
+        this.failures.set(key, count);
+        while (this.failures.size > FAILURE_KEYS) this.failures.delete(this.failures.keys().next().value);
+        if (count === 2) lines.push(freeflowNotice("guidance", DIAGNOSE_NOTICE));
+      } else {
+        this.failures.delete(key);
+        if (this.run.changed && !this.run.reviewed && !this.run.reminded) {
+          this.run.reminded = true;
+          lines.push(freeflowNotice("guidance", selfReviewNotice(this.selfReview)));
+        }
+      }
+    }
+    return lines;
+  }
+}

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

@@ -0,0 +1,54 @@
+import { homedir, platform, release } from "node:os";
+import { getShellConfig } from "@earendil-works/pi-coding-agent";
+// Pi's generic rule lines that contradict the taught bash-first working style or repeat Freeflow's interaction
+// contract. Every other rule, including each tool's and extension's guidelines, stays as Pi renders it.
+const REMOVED_RULES = new Set([
+  "- Use read to examine files instead of cat or sed.",
+  "- Be concise in your responses",
+  "- Show file paths clearly when working with files",
+]);
+function renderedSection(systemPrompt, name) {
+  const match = new RegExp(`<${name}>\\n([\\s\\S]*?)\\n</${name}>`).exec(systemPrompt);
+  return match?.[1];
+}
+function rules(systemPrompt) {
+  const rendered = renderedSection(systemPrompt, "rules");
+  if (rendered === undefined) return undefined;
+  const lines = rendered.split("\n");
+  const kept = lines.filter((line) => !REMOVED_RULES.has(line));
+  return kept.length === lines.length || kept.length === 0 ? undefined : kept.join("\n");
+}
+function docs(systemPrompt) {
+  const rendered = renderedSection(systemPrompt, "docs");
+  if (rendered === undefined) return undefined;
+  const path = (label) => new RegExp(`^- ${label}: (.+?)(?: \\(|$)`, "m").exec(rendered)?.[1];
+  const [readme, docsPath, examples] = [path("Main documentation"), path("Additional docs"), path("Examples")];
+  if (!readme || !docsPath || !examples) return undefined;
+  return `Pi documentation (read only when the user asks about pi itself): ${readme}, ${docsPath}, ${examples}.`;
+}
+function environment(shellPath) {
+  let shell;
+  try {
+    shell = getShellConfig(shellPath?.startsWith("~/") ? `${homedir()}${shellPath.slice(1)}` : shellPath).shell;
+  } catch {
+    shell = "unavailable";
+  }
+  return `Platform: ${platform()} ${release()}. Shell for bash: ${shell}.`;
+}
+/**
+ * Pi prompt sections Freeflow owns while Tool Execution is effective. Every value derives from inputs fixed for the
+ * configuration and machine, so the system prompt stays identical across requests and sessions. Pi's preamble is
+ * never touched: the Claude subscription plugin shapes it only when Pi's own preamble is present.
+ */
+export function toolExecutionSections(systemPrompt, shellPath) {
+  const sections = {};
+  const ownRules = rules(systemPrompt);
+  if (ownRules !== undefined) sections.rules = ownRules;
+  const ownDocs = docs(systemPrompt);
+  if (ownDocs !== undefined) sections.docs = ownDocs;
+  return sections;
+}
+/** Sections Tool Execution adds after Freeflow's guidance: the environment facts, then its guidance when available. */
+export function toolExecutionTail(shellPath, guidance) {
+  return { environment: environment(shellPath), ...(guidance ? { tool_execution: guidance } : {}) };
+}