freeharness 0.4.1

package/canonical/hooks/freeharness-memory-guard.mjs

@@ -0,0 +1,57 @@
+// FreeHarness PreToolUse memory guard.
+// Denies hand-written memory .md files: the free-mem plugin owns persistence, and writing
+// duplicate memory files wastes output tokens. Allows free-mem data, openspec,
+// docs, and the .claude/agent-memory/ and .claude/agent-memory-local/ subtrees (Claude
+// Code's own per-agent memory files); a memory-named basename (MEMORY.md, memory.md,
+// memories.md) is denied everywhere else, a path under .claude/ is never treated as
+// source, and otherwise a .md file under packages/memory/ or vendor/ is allowed as a
+// repository source tree.
+// Reads the hook payload from stdin; emits a deny decision or nothing.
+// The path is normalized (`.`/`..` segments collapsed) before any exemption or deny
+// regex runs, so a traversal segment cannot smuggle a denied path through an exempt one.
+import { posix } from "node:path";
+
+let data = "";
+process.stdin.on("data", (c) => (data += c));
+process.stdin.on("end", () => {
+  let j;
+  try {
+    j = JSON.parse(data);
+  } catch {
+    process.exit(0);
+  }
+  const tool = j.tool_name || "";
+  if (!/^(Write|Edit|MultiEdit)$/.test(tool)) process.exit(0);
+
+  const ti = j.tool_input || {};
+  const raw = ti.file_path || ti.path || "";
+  if (!raw) process.exit(0);
+
+  const p = posix.normalize(String(raw).replace(/\\/g, "/"));
+  const base = p.split("/").pop() || "";
+
+  if (/\/\.claude-mem(\/|$)/.test(p)) process.exit(0);
+  if (/\/(openspec|docs|node_modules)\//.test(p)) process.exit(0);
+  if (/\/\.claude\/agent-memory(-local)?\//.test(p)) process.exit(0);
+
+  const md = /\.md$/i.test(base);
+  const noext = base.replace(/\.md$/i, "");
+  const memName = md && /(^|[._-])(memory|memoria|memories|memorias)([._-]|$)/i.test(noext);
+  const memDir = md && /\/memor(y|ies|ia|ias)\//i.test(p);
+  const claudeDataTree = /\/\.claude\//.test(p);
+  const sourceTree = !claudeDataTree && /\/(packages\/memory|vendor)\//.test(p);
+
+  if (memName || (!sourceTree && memDir)) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason:
+            "FreeHarness: memory is managed exclusively by the free-mem plugin. Do not hand-write memory .md files (it wastes output tokens). Persist context via the free-mem plugin instead.",
+        },
+      }),
+    );
+  }
+  process.exit(0);
+});

package/canonical/hooks/freeharness-output-pruner.mjs

@@ -0,0 +1,333 @@
+// FreeHarness output pruner (Claude Code PostToolUse hook, matcher Bash).
+// Replaces stdout via `updatedToolOutput`; the command, exit codes and on-disk effects stay
+// untouched (a PreToolUse `updatedInput` pipe rewrite would change what `Bash(...)` allow
+// rules match and hide the real exit status). Oversize stdout is written in full to
+// ~/.claude/freeharness/tool-output/<session>/<n>.txt; the model gets head + tail with
+// `[freeharness: N lines pruned ...]` markers, and a `{kind:"pruned"}` record lands in the
+// cost log. Allowlisted commands and test-runner failure blocks pass through whole. Never
+// blocks; exit 0 always. Optional --digest <url> summarizes a marker via a local model on a
+// loopback host only (a pruned region can carry secrets); credential-shaped lines are dropped.
+// Disable: FREEHARNESS_HOOK_OUTPUT_PRUNER=off.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Defaults; overridden with --max-bytes / --max-lines. */
+export const DEFAULTS = Object.freeze({ maxBytes: 8 * 1024, maxLines: 200, headShare: 0.6, blockCap: 120, digestMs: 1500 });
+
+/** System prompt for every digest request: facts only, bounded, no chatter. */
+const DIGEST_SYSTEM_PROMPT =
+  "Produce a factual digest of the following tool output in at most 12 lines. No commentary, no preamble: facts only.";
+
+/** Preview commands the model must see whole. */
+const ALLOWLIST = /\bgit\s+(diff|show|apply|format-patch|log\s+-p)\b|(^|[\s;|&])(diff|patch|colordiff)\b|--dry-run\b/;
+
+/** Test runners kept whole. */
+const TEST_RUNNERS = /\bpytest\b|\bpython3?\s+-m\s+pytest\b|\bnode\s+(--import\s+\S+\s+)?--test\b|\bvitest\b|\bnpm\s+(run\s+)?test\b|\bnpx\s+vitest\b|\bjest\b/;
+
+/** Failure-block grammars: `start` opens, `end` closes; `blockCap` bounds a runaway block. */
+const BLOCKS = [
+  // pytest: FAILURES / ERRORS sections, each `____ test_x ____` block, summary/result lines.
+  { start: /^={3,}\s+(FAILURES|ERRORS|short test summary info)\s+={3,}$|^_{3,}\s.+\s_{3,}$/, end: /^={3,}.*={3,}$|^_{3,}\s.+\s_{3,}$/ },
+  { start: /^(FAILED|ERROR)\s/, end: /^(?!(FAILED|ERROR)\s)/ },
+  { start: /^={3,}\s+\d+\s+(failed|passed|error|errors|skipped|warnings?)\b.*={3,}$/, end: /^/ },
+  // node --test (TAP) and vitest/jest FAIL blocks.
+  { start: /^\s*not ok\b/, end: /^\s*(ok|not ok|#|1\.\.)/ },
+  { start: /^\s*(FAIL|×|✗|✕)\s|^\s*(AssertionError|Error):|^\s*Traceback \(most recent call last\)/, end: /^\s*(PASS|✓|√|Test Files|Tests|Snapshots|Time:|Ran all)\b/ },
+];
+
+/** Parses CLI options with env fallbacks for the byte/line limits. */
+export function parseOptions(argv) {
+  const opts = { maxBytes: DEFAULTS.maxBytes, maxLines: DEFAULTS.maxLines, digestUrl: null, digestMs: DEFAULTS.digestMs };
+  const env = (k) => process.env[k];
+  const num = (v, fallback) => {
+    const n = Number.parseInt(String(v), 10);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+  };
+  if (env("FREEHARNESS_PRUNER_MAX_BYTES")) opts.maxBytes = num(env("FREEHARNESS_PRUNER_MAX_BYTES"), opts.maxBytes);
+  if (env("FREEHARNESS_PRUNER_MAX_LINES")) opts.maxLines = num(env("FREEHARNESS_PRUNER_MAX_LINES"), opts.maxLines);
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--max-bytes") opts.maxBytes = num(argv[++i], opts.maxBytes);
+    else if (argv[i] === "--max-lines") opts.maxLines = num(argv[++i], opts.maxLines);
+    else if (argv[i] === "--digest") opts.digestUrl = argv[++i] || null;
+    else if (argv[i] === "--digest-ms") opts.digestMs = num(argv[++i], opts.digestMs);
+  }
+  return opts;
+}
+
+/** Splits text into lines without a trailing empty element. */
+function splitLines(text) {
+  if (text.length === 0) return [];
+  const lines = text.split("\n");
+  if (text.endsWith("\n")) lines.pop();
+  return lines;
+}
+
+/** Failure blocks as [start, end] ranges, bounded by DEFAULTS.blockCap lines each. */
+export function failureBlocks(lines) {
+  const ranges = [];
+  let i = 0;
+  while (i < lines.length) {
+    const g = BLOCKS.find((b) => b.start.test(lines[i]));
+    if (!g) {
+      i += 1;
+      continue;
+    }
+    let j = i + 1;
+    while (j < lines.length && j - i < DEFAULTS.blockCap && !g.end.test(lines[j])) j += 1;
+    ranges.push([i, j - 1]);
+    i = j;
+  }
+  return ranges;
+}
+
+/** Prunes to the dual limit: head + tail kept, failure blocks kept whole, each gap replaced by a marker. Null when within both limits. */
+export function prune(text, limits, keepFailures, copyPath) {
+  const totalBytes = Buffer.byteLength(text, "utf8");
+  const lines = splitLines(text);
+  const totalLines = lines.length;
+  if (totalBytes <= limits.maxBytes && totalLines <= limits.maxLines) return null;
+
+  const keep = new Uint8Array(lines.length);
+  const budgetLines = Math.max(4, limits.maxLines);
+  let head = Math.floor(budgetLines * DEFAULTS.headShare);
+  let tail = budgetLines - head;
+  const mark = (from, to) => {
+    for (let k = Math.max(0, from); k <= Math.min(lines.length - 1, to); k++) keep[k] = 1;
+  };
+  const protectedIdx = new Uint8Array(lines.length);
+  if (keepFailures) {
+    for (const [a, b] of failureBlocks(lines)) {
+      mark(a, b);
+      for (let k = a; k <= b; k++) protectedIdx[k] = 1;
+    }
+  }
+  mark(0, head - 1);
+  mark(lines.length - tail, lines.length - 1);
+
+  // Byte limit: shrink head then tail, never a protected line, until under budget.
+  const bytesOf = () => {
+    let n = 0;
+    for (let k = 0; k < lines.length; k++) if (keep[k]) n += Buffer.byteLength(lines[k], "utf8") + 1;
+    return n;
+  };
+  const budgetBytes = Math.max(512, limits.maxBytes);
+  while (bytesOf() > budgetBytes && (head > 2 || tail > 2)) {
+    if (head > 2) {
+      head -= 1;
+      if (!protectedIdx[head]) keep[head] = 0;
+    }
+    if (bytesOf() > budgetBytes && tail > 2) {
+      tail -= 1;
+      const idx = lines.length - tail - 1;
+      if (idx >= 0 && !protectedIdx[idx]) keep[idx] = 0;
+    }
+  }
+
+  const out = [];
+  const regions = [];
+  let prunedLines = 0;
+  let prunedBytes = 0;
+  let k = 0;
+  while (k < lines.length) {
+    if (keep[k]) {
+      const line = lines[k];
+      out.push(line.length > budgetBytes ? `${line.slice(0, budgetBytes)} …[line truncated]` : line);
+      k += 1;
+      continue;
+    }
+    const from = k;
+    let gapBytes = 0;
+    const gapLines = [];
+    while (k < lines.length && !keep[k]) {
+      gapLines.push(lines[k]);
+      gapBytes += Buffer.byteLength(lines[k], "utf8") + 1;
+      k += 1;
+    }
+    const n = k - from;
+    prunedLines += n;
+    prunedBytes += gapBytes;
+    const marker = `[freeharness: ${n} lines pruned (${from + 1}-${k})]`;
+    regions.push({ marker, gapText: gapLines.join("\n"), n, from: from + 1, to: k });
+    out.push(marker);
+  }
+  out.push(`[freeharness: ${prunedLines} lines pruned, full output at ${copyPath}]`);
+  return { text: `${out.join("\n")}\n`, prunedLines, prunedBytes, totalLines, totalBytes, regions };
+}
+
+/** Per-session copy directory (FREEHARNESS_TOOL_OUTPUT_DIR overrides). */
+function copyDir(sessionId) {
+  const root = process.env.FREEHARNESS_TOOL_OUTPUT_DIR || path.join(os.homedir(), ".claude", "freeharness", "tool-output");
+  return path.join(root, sessionId.replace(/[^\w.-]/g, "_") || "unknown");
+}
+
+/** Writes output as the next numbered file; throws on failure. */
+function writeCopy(dir, text) {
+  fs.mkdirSync(dir, { recursive: true });
+  const n = fs.readdirSync(dir).filter((f) => /^\d+\.txt$/.test(f)).length + 1;
+  const file = path.join(dir, `${n}.txt`);
+  fs.writeFileSync(file, text, "utf8");
+  return file;
+}
+
+/** Appends the pruned-bytes record; failures report on stderr only. */
+function appendCostRecord(record) {
+  try {
+    const file = process.env.FREEHARNESS_COST_LOG || path.join(os.homedir(), ".claude", "freeharness", "cost", "usage.jsonl");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(record)}\n`, "utf8");
+  } catch (e) {
+    process.stderr.write(`freeharness-output-pruner: cost log not written: ${e instanceof Error ? e.message : String(e)}\n`);
+  }
+}
+
+/** Loopback hosts a digest request may target. */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+
+/** True when `url`'s host is loopback. */
+function isLoopbackUrl(url) {
+  try {
+    return LOOPBACK_HOSTS.has(new URL(url).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Drops lines shaped like a credential. */
+function redactSecrets(text) {
+  return text
+    .split("\n")
+    .filter((line) => !/(KEY|SECRET|TOKEN|PASSWORD)\s*[=:]/i.test(line))
+    .join("\n");
+}
+
+/** Asks the local model server for a digest of one region (secrets redacted); failure resolves to null, named on stderr. */
+export async function requestDigest(url, timeoutMs, text) {
+  if (!isLoopbackUrl(url)) {
+    process.stderr.write(`freeharness-output-pruner: digest request refused: non-loopback host in ${url}\n`);
+    return null;
+  }
+  try {
+    const res = await fetch(`${url.replace(/\/+$/, "")}/v1/chat/completions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        model: "local",
+        temperature: 0,
+        max_tokens: 400,
+        stream: false,
+        messages: [
+          { role: "system", content: DIGEST_SYSTEM_PROMPT },
+          { role: "user", content: redactSecrets(text) },
+        ],
+      }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) {
+      process.stderr.write(`freeharness-output-pruner: digest request failed: HTTP ${res.status}\n`);
+      return null;
+    }
+    const body = await res.json();
+    const content = body && body.choices && body.choices[0] && body.choices[0].message && body.choices[0].message.content;
+    if (typeof content !== "string" || !content.trim()) {
+      process.stderr.write("freeharness-output-pruner: digest request failed: no digest in response\n");
+      return null;
+    }
+    return content.trim();
+  } catch (e) {
+    process.stderr.write(`freeharness-output-pruner: digest request failed: ${e instanceof Error ? e.message : String(e)}\n`);
+    return null;
+  }
+}
+
+/** Regions digested per output, and the pass deadline as a multiple of --digest-ms. */
+const MAX_DIGESTED_REGIONS = 3;
+const OVERALL_DEADLINE_MULTIPLE = 2;
+
+/** Replaces each marker with a digest no longer than the region; failure keeps the marker. Bounded to `MAX_DIGESTED_REGIONS` attempts, one deadline. */
+export async function digestResult(result, url, timeoutMs) {
+  let text = result.text;
+  const deadline = Date.now() + timeoutMs * OVERALL_DEADLINE_MULTIPLE;
+  let attempts = 0;
+  for (const region of result.regions) {
+    if (attempts >= MAX_DIGESTED_REGIONS) break;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    attempts += 1;
+    const digest = await requestDigest(url, Math.min(timeoutMs, remaining), region.gapText);
+    if (!digest || digest.length > region.gapText.length) continue;
+    text = text.replace(region.marker, () => `[freeharness: ${region.n} lines digested (${region.from}-${region.to})] ${digest}`);
+  }
+  return text;
+}
+
+/** Builds the hook response for one PostToolUse payload, or null for pass-through. */
+export async function respond(payload, opts) {
+  if (payload.tool_name !== "Bash") return null;
+  const input = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
+  const command = typeof input.command === "string" ? input.command : "";
+  if (ALLOWLIST.test(command)) return null;
+  const response = payload.tool_response;
+  if (!response || typeof response !== "object" || typeof response.stdout !== "string") return null;
+  const keepFailures = TEST_RUNNERS.test(command);
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+  const dir = copyDir(sessionId);
+  const probe = prune(response.stdout, opts, keepFailures, "<pending>");
+  if (!probe) return null;
+  let copyPath;
+  try {
+    copyPath = writeCopy(dir, response.stdout);
+  } catch (e) {
+    process.stderr.write(`freeharness-output-pruner: disk copy failed, output passed through unpruned: ${e instanceof Error ? e.message : String(e)}\n`);
+    return null;
+  }
+  const result = prune(response.stdout, opts, keepFailures, copyPath);
+  if (!result) return null;
+  const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  // Digest runs before the cost record is appended: a failure never leaves a cost line
+  // pointing at a run that did not finish.
+  const stdout = opts.digestUrl ? await digestResult(result, opts.digestUrl, opts.digestMs) : result.text;
+  appendCostRecord({
+    kind: "pruned",
+    ts: new Date().toISOString(),
+    session_id: sessionId,
+    project: path.basename(cwd),
+    cwd,
+    bytes: result.prunedBytes,
+    lines: result.prunedLines,
+    total_bytes: result.totalBytes,
+    total_lines: result.totalLines,
+    path: copyPath,
+    command: command.slice(0, 160),
+  });
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      updatedToolOutput: { ...response, stdout },
+    },
+  };
+}
+
+/** Entry point: read stdin, respond or stay silent. */
+async function main() {
+  if ((process.env.FREEHARNESS_HOOK_OUTPUT_PRUNER || "").toLowerCase() === "off") return;
+  let payload = {};
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    if (raw.trim()) payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (!payload || typeof payload !== "object") return;
+  try {
+    const out = await respond(payload, parseOptions(process.argv.slice(2)));
+    if (out) process.stdout.write(JSON.stringify(out));
+  } catch (e) {
+    process.stderr.write(`freeharness-output-pruner: ${e instanceof Error ? e.message : String(e)}\n`);
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  main().finally(() => process.exit(0));
+}