@monster-orange/den 0.4.6 → 0.4.8

package/src/shared/agents/guardrails/hooks.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{pretooluse}",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{stop}",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/shared/agents/guardrails/instructions.md

@@ -0,0 +1,39 @@
+## How you work and write (every Den persona)
+
+### Writing to people
+
+- Write plainly. Use short sentences.
+- Never name an issue or an ID without saying what it is. Write "#5 (the
+  hooks issue)" or "the plain-writing rule (R12)", never a bare "#5" or "R12".
+- Ask each decision as a numbered yes/no question. One question per number.
+- No caveat sections. Leave out anything the person doesn't need in order to
+  act.
+
+### Reading and waiting
+
+- Don't read a whole log or a large file into the conversation. Read a slice
+  (`tail -n 100`, `grep -n`), or hand the file to a subagent and ask for the
+  conclusion.
+- Don't poll with `sleep` or `until …; do sleep …; done`. Run long work in the
+  background and wait to be told it ended, or use a wait primitive.
+
+### Handing work back
+
+When you hand work back to a person, end with this, filled in. Den checks it:
+a hand-back with a missing part, an unexplained ID, or a decision that is not
+a numbered yes/no question is sent back to you to fix.
+
+```
+## Hand-back
+- URL: <the full link the person opens, with https://>
+- Machine: <the machine it runs on>
+- Branch: <the branch>
+- What changed: <what is different now, in a sentence or two>
+- What to click: <the steps to see it working>
+- Decisions:
+  1. <a question the person answers yes or no>?
+```
+
+Write "Decisions: none" when there are none, and "URL: none" (with a short
+reason) when the work has no page to open. Every message you end a turn
+with is read by a person, hand-back or not: explain each ID in it.

package/src/shared/agents/guardrails/pretooluse.mjs

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+/**
+ * Den's PreToolUse hook for Claude Code sessions it launches (den-claude).
+ * Den passes it in the agent's own settings file (--settings); it never
+ * touches the user's ~/.claude. Plain Node with no imports beyond node:*,
+ * so it starts in a few tens of milliseconds on every Bash and Read call.
+ *
+ * Hook contract (https://code.claude.com/docs/en/hooks, "PreToolUse" and
+ * "Exit code output"): the tool call arrives as JSON on stdin
+ * ({ tool_name, tool_input, cwd, ... }). Exit 2 blocks the call, and Claude
+ * gets stderr as the reason. Exit 0 with no output lets the normal
+ * permission flow decide. Any error here exits 0: a broken hook never
+ * blocks anything.
+ *
+ * It blocks exactly two things, and nothing else:
+ *
+ *   1. Whole-file reads of a log or a large file into the conversation:
+ *      - Read with no `limit`;
+ *      - Bash `cat` or `less` of it, when its output reaches the
+ *        conversation (the last stage of a pipeline, stdout not redirected);
+ *      - Bash `tail` from a line or byte (`tail +1`, `-n +1`, `--lines=+1`),
+ *        which prints the whole rest of the file, likewise. A plain `tail`
+ *        prints 10 lines, a slice, and passes.
+ *      A log is `*.log` (or `*.log.<N>`), a `.jsonl` under `.dev-metrics/`,
+ *      or a `.jsonl` under a `.claude/projects/` directory (a transcript).
+ *      Large is over LARGE_BYTES.
+ *   2. Foreground `sleep` in Bash: `sleep N` on its own or inside an
+ *      `until ...; do sleep N; done` (or while/for) polling loop. A Bash call
+ *      with run_in_background, or a `sleep ... &`, is not blocked.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Over this many bytes, a file is large (Claude Code's own Read cap). */
+export const LARGE_BYTES = 256 * 1024;
+
+const READ_HINT =
+  "Read a slice instead: `tail -n 100 <file>`, `grep -n <pattern> <file>`, " +
+  "or a Read with offset and limit. To go through all of it, hand it to a " +
+  "subagent and ask it for the conclusion.";
+
+const SLEEP_HINT =
+  "Waiting with sleep is polling. Run the long command with " +
+  "run_in_background (you are told when it ends), or use a wait primitive " +
+  "(the Monitor tool with an until-condition, or the command's own --wait). " +
+  "Do not loop on sleep.";
+
+/** Is this path a log: *.log, .dev-metrics/*.jsonl, or a transcript? */
+export function isLogPath(p) {
+  const s = String(p).replace(/\\/g, "/");
+  const base = s.slice(s.lastIndexOf("/") + 1);
+  if (/\.log(\.\d+)?$/i.test(base)) return true;
+  if (!/\.jsonl$/i.test(base)) return false;
+  if (/(^|\/)\.dev-metrics\//.test(s)) return true;
+  return /(^|\/)\.claude\/projects\//.test(s);
+}
+
+/** The file's size, or -1 when it can't be read (a glob, a variable). */
+function sizeOf(p, cwd, home) {
+  try {
+    let f = String(p);
+    if (home && (f === "~" || f.startsWith("~/")))
+      f = path.join(home, f.slice(1));
+    const st = fs.statSync(path.resolve(cwd || ".", f));
+    return st.isFile() ? st.size : -1;
+  } catch {
+    return -1;
+  }
+}
+
+/** Why reading all of this file is blocked, or null. */
+export function wholeReadReason(p, cwd, home) {
+  if (isLogPath(p)) return "a log";
+  const n = sizeOf(p, cwd, home);
+  if (n > LARGE_BYTES) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return null;
+}
+
+/**
+ * Split a shell command into pipelines of stages. Each stage is
+ * { words, stdoutRedirected, background }. Quotes and backslashes are
+ * honoured, `$( … )` stays inside its word, comments and heredoc bodies are
+ * skipped. Not a full shell parser: anything it can't read is left alone.
+ */
+export function parseShell(src) {
+  const pipelines = [];
+  let stages = [];
+  let words = [];
+  let word = "";
+  let inWord = false;
+  const heredocs = [];
+
+  const endWord = () => {
+    if (inWord) words.push(word);
+    word = "";
+    inWord = false;
+  };
+  const endStage = () => {
+    endWord();
+    if (words.length) stages.push(stage(words));
+    words = [];
+  };
+  const endPipeline = (background = false) => {
+    endStage();
+    if (stages.length) {
+      if (background) stages[stages.length - 1].background = true;
+      pipelines.push(stages);
+    }
+    stages = [];
+  };
+
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "\\" && i + 1 < src.length) {
+      if (src[i + 1] !== "\n") word += src[i + 1];
+      inWord = inWord || src[i + 1] !== "\n";
+      i += 2;
+      continue;
+    }
+    if (c === "'") {
+      const j = src.indexOf("'", i + 1);
+      const end = j < 0 ? src.length : j;
+      word += src.slice(i + 1, end);
+      inWord = true;
+      i = end + 1;
+      continue;
+    }
+    if (c === '"') {
+      let j = i + 1;
+      while (j < src.length && src[j] !== '"') {
+        if (src[j] === "\\" && j + 1 < src.length) {
+          word += src[j + 1];
+          j += 2;
+        } else word += src[j++];
+      }
+      inWord = true;
+      i = j + 1;
+      continue;
+    }
+    if (c === "$" && src[i + 1] === "(") {
+      let depth = 0;
+      let j = i + 1;
+      for (; j < src.length; j++) {
+        if (src[j] === "(") depth++;
+        else if (src[j] === ")" && --depth === 0) break;
+      }
+      word += src.slice(i, j + 1);
+      inWord = true;
+      i = j + 1;
+      continue;
+    }
+    if (c === "`") {
+      const j = src.indexOf("`", i + 1);
+      const end = j < 0 ? src.length : j;
+      word += src.slice(i, end + 1);
+      inWord = true;
+      i = end + 1;
+      continue;
+    }
+    if (c === "#" && !inWord) {
+      while (i < src.length && src[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "\n") {
+      endPipeline();
+      i++;
+      // Skip heredoc bodies that start on this line.
+      while (heredocs.length) {
+        const delim = heredocs.shift();
+        for (;;) {
+          if (i >= src.length) break;
+          const nl = src.indexOf("\n", i);
+          const line = src.slice(i, nl < 0 ? src.length : nl);
+          i = nl < 0 ? src.length : nl + 1;
+          if (line.replace(/^\t+/, "") === delim) break;
+        }
+      }
+      continue;
+    }
+    if (c === " " || c === "\t") {
+      endWord();
+      i++;
+      continue;
+    }
+    if (c === "<" && src[i + 1] === "<" && src[i + 2] !== "<") {
+      endWord();
+      let j = i + 2;
+      if (src[j] === "-") j++;
+      while (src[j] === " " || src[j] === "\t") j++;
+      let d = "";
+      while (j < src.length && !/[\s;&|<>()]/.test(src[j])) d += src[j++];
+      heredocs.push(d.replace(/['"\\]/g, ""));
+      words.push("<<");
+      i = j;
+      continue;
+    }
+    if (c === "&" && src[i + 1] === "&") {
+      endPipeline();
+      i += 2;
+      continue;
+    }
+    if (c === "|" && src[i + 1] === "|") {
+      endPipeline();
+      i += 2;
+      continue;
+    }
+    if (c === "&" && src[i + 1] === ">") {
+      endWord();
+      words.push(src[i + 2] === ">" ? "&>>" : "&>");
+      i += src[i + 2] === ">" ? 3 : 2;
+      continue;
+    }
+    if (c === "|") {
+      endStage();
+      i += src[i + 1] === "&" ? 2 : 1;
+      continue;
+    }
+    if (c === "&") {
+      endPipeline(true);
+      i++;
+      continue;
+    }
+    if (c === ";" || c === "(" || c === ")") {
+      endPipeline();
+      i++;
+      continue;
+    }
+    if (c === ">" || c === "<") {
+      // A redirection operator: its own word, with any fd before it.
+      const fd = inWord && /^\d+$/.test(word) ? word : "";
+      if (fd) {
+        word = "";
+        inWord = false;
+      } else endWord();
+      let op = fd + c;
+      let j = i + 1;
+      if (src[j] === ">" || src[j] === "&") op += src[j++];
+      words.push(op);
+      i = j;
+      continue;
+    }
+    word += c;
+    inWord = true;
+    i++;
+  }
+  endPipeline();
+  return pipelines;
+}
+
+const PREFIX = new Set([
+  "do",
+  "then",
+  "else",
+  "elif",
+  "while",
+  "until",
+  "if",
+  "!",
+  "{",
+  "}",
+  "time",
+  "exec",
+  "command",
+  "nohup",
+]);
+
+/** One stage: its command and arguments, with redirections taken out. */
+function stage(raw) {
+  let k = 0;
+  while (
+    k < raw.length &&
+    (PREFIX.has(raw[k]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(raw[k]))
+  )
+    k++;
+  const words = [];
+  const inputs = [];
+  let stdoutRedirected = false;
+  for (let j = k; j < raw.length; j++) {
+    const w = raw[j];
+    const r = /^(\d*|&)>>?(&?)$/.exec(w);
+    if (r) {
+      // Claude Code shows stdout and stderr both, so only stdout sent to a
+      // file leaves the chat: `>f`, `1>f`, `&>f`. `2>f`, `2>&1`, `>&2` don't.
+      const toFd = r[2] === "&" && /^\d+$/.test(raw[j + 1] ?? "");
+      if ((r[1] === "" || r[1] === "1" || r[1] === "&") && !toFd)
+        stdoutRedirected = true;
+      j++;
+      continue;
+    }
+    if (w === "<") {
+      if (raw[j + 1] !== undefined) inputs.push(raw[j + 1]);
+      j++;
+      continue;
+    }
+    if (w === "<<") {
+      j++;
+      continue;
+    }
+    words.push(w);
+  }
+  return { words, inputs, stdoutRedirected, background: false };
+}
+
+const base = (w) => String(w).slice(String(w).lastIndexOf("/") + 1);
+
+/**
+ * tail reads the whole rest of the file only when it starts from a line or
+ * byte (`+N`, `-n +N`, `-n+N`, `--lines=+N`, the same for -c/--bytes); a
+ * plain tail prints 10 lines, and a count or a follow is a slice.
+ */
+function tailReadsAll(args) {
+  for (let j = 0; j < args.length; j++) {
+    const a = args[j];
+    if (/^\+\d+$/.test(a)) return true;
+    if (/^-[nc]\+\d+$/.test(a) || /^--(lines|bytes)=\+\d+$/.test(a))
+      return true;
+    if (
+      (a === "-n" || a === "-c" || a === "--lines" || a === "--bytes") &&
+      /^\+\d+$/.test(args[j + 1] ?? "")
+    )
+      return true;
+  }
+  return false;
+}
+
+/** The file arguments of cat, less or tail (options and their values out). */
+function fileArgs(cmd, args) {
+  const out = [];
+  for (let j = 0; j < args.length; j++) {
+    const a = args[j];
+    if (a === "--") {
+      out.push(...args.slice(j + 1));
+      break;
+    }
+    if (a === "-") continue;
+    if (a.startsWith("-") || (cmd === "tail" && /^\+\d+$/.test(a))) {
+      if (cmd === "tail" && (a === "-n" || a === "-c")) j++;
+      continue;
+    }
+    out.push(a);
+  }
+  return out;
+}
+
+/** The reason to block this Bash command, or null. */
+export function bashDecision(command, opts = {}) {
+  const { cwd, home, background } = opts;
+  let pipelines;
+  try {
+    pipelines = parseShell(String(command ?? ""));
+  } catch {
+    return null;
+  }
+  for (const stages of pipelines)
+    for (let s = 0; s < stages.length; s++) {
+      const st = stages[s];
+      const cmd = base(st.words[0] ?? "");
+      const args = st.words.slice(1);
+      if (cmd === "sleep" && args.length && !background && !st.background)
+        return `Den blocked \`sleep ${args.join(" ")}\`. ${SLEEP_HINT}`;
+      if (cmd !== "cat" && cmd !== "less" && cmd !== "tail") continue;
+      // Output that goes on to another command or a file never reaches the chat.
+      if (s < stages.length - 1 || st.stdoutRedirected) continue;
+      if (cmd === "tail" && !tailReadsAll(args)) continue;
+      for (const f of [...fileArgs(cmd, args), ...st.inputs]) {
+        const why = wholeReadReason(f, cwd, home);
+        if (why)
+          return `Den blocked \`${[cmd, ...args].join(" ")}\`: it reads all of ${f} (${why}) into the conversation. ${READ_HINT}`;
+      }
+    }
+  return null;
+}
+
+/** The reason to block this tool call, or null. */
+export function decide(input, env = process.env) {
+  if (!input || typeof input !== "object") return null;
+  const ti =
+    input.tool_input && typeof input.tool_input === "object"
+      ? input.tool_input
+      : {};
+  const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
+  const home = env.HOME;
+  if (input.tool_name === "Read") {
+    if (ti.limit !== undefined && ti.limit !== null) return null;
+    if (typeof ti.file_path !== "string") return null;
+    const why = wholeReadReason(ti.file_path, cwd, home);
+    return why
+      ? `Den blocked a Read of all of ${ti.file_path} (${why}). ${READ_HINT}`
+      : null;
+  }
+  if (input.tool_name === "Bash")
+    return bashDecision(ti.command, {
+      cwd,
+      home,
+      background: ti.run_in_background === true,
+    });
+  return null;
+}
+
+async function main() {
+  let text = "";
+  for await (const chunk of process.stdin) text += chunk;
+  let reason = null;
+  try {
+    reason = decide(JSON.parse(text));
+  } catch {
+    reason = null;
+  }
+  if (reason) {
+    process.stderr.write(`${reason}\n`);
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+/** Run as a script (the hook), not imported. */
+function isMain() {
+  try {
+    return (
+      !!process.argv[1] &&
+      fs.realpathSync(process.argv[1]) ===
+        fs.realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+}
+if (isMain()) main().catch(() => process.exit(0));

package/src/shared/agents/guardrails/stop-hook.ts

@@ -0,0 +1,66 @@
+/**
+ * Den's Stop hook for Claude Code sessions it launches (den-claude): the
+ * hand-back check (handback.ts) on the turn's last message.
+ *
+ * Hook contract (https://code.claude.com/docs/en/hooks, "Stop input" and
+ * "Stop decision control"): JSON on stdin with `last_assistant_message`
+ * and `stop_hook_active`. Printing `{"decision":"block","reason":…}` keeps
+ * Claude going with the reason; printing nothing lets it stop.
+ *
+ * A message with the "Hand-back" heading (the template's) gets the whole
+ * hand-back check. Any other last message is still what the person reads,
+ * so it gets the plain-writing part only: every ID explained (R12).
+ * When Claude is already continuing because of a stop hook
+ * (stop_hook_active), it lets the turn end, so it never loops. Any error
+ * lets the turn end too.
+ */
+import { bareIds, checkHandback, looksLikeHandback } from "../handback.js";
+
+/** The hook's stdout for one Stop input ("" lets the turn end). */
+export function stopDecision(input: unknown): string {
+  if (!input || typeof input !== "object") return "";
+  const i = input as {
+    stop_hook_active?: unknown;
+    last_assistant_message?: unknown;
+  };
+  if (i.stop_hook_active === true) return "";
+  const msg = i.last_assistant_message;
+  if (typeof msg !== "string") return "";
+  // A hand-back is checked whole. Any other final message is what the
+  // person reads too, so it gets the plain-writing check: no bare IDs.
+  const handback = looksLikeHandback(msg);
+  const problems = handback
+    ? checkHandback(msg).problems
+    : bareIds(msg).map(
+        (id) =>
+          `"${id}" is not explained. Say what it is, e.g. "${id} (what it is)".`,
+      );
+  if (problems.length === 0) return "";
+  return JSON.stringify({
+    decision: "block",
+    reason: [
+      handback
+        ? "Den checked your hand-back and it is not ready. Fix these, then send it again:"
+        : "Den checked your message to the person and it is not plain yet. Fix these, then send it again:",
+      ...problems.map((p) => `- ${p}`),
+    ].join("\n"),
+  });
+}
+
+async function main(): Promise<void> {
+  let text = "";
+  for await (const chunk of process.stdin) text += String(chunk);
+  let out = "";
+  try {
+    out = stopDecision(JSON.parse(text));
+  } catch {
+    out = "";
+  }
+  if (out) process.stdout.write(`${out}\n`);
+}
+
+if (process.argv[1] && /stop-hook\.[jt]s$/.test(process.argv[1]))
+  main().then(
+    () => process.exit(0),
+    () => process.exit(0),
+  );

package/src/shared/agents/guardrails.ts

@@ -0,0 +1,114 @@
+/**
+ * Guardrails (den#5): what Den adds to a launch of a default-pack persona,
+ * from Den-owned files in guardrails/:
+ *
+ *   instructions.md  the shared persona instructions (plain writing, reading
+ *                    and waiting, the hand-back template). Appended to the
+ *                    role prompt (personas.ts rolePrompt), so every runtime
+ *                    gets them.
+ *   hooks.json       a Claude Code settings fragment: a PreToolUse hook on
+ *                    Bash and Read (pretooluse.mjs) and a Stop hook
+ *                    (stop-hook.ts, the hand-back check). den-claude merges
+ *                    it into the agent's own --settings file; Den never
+ *                    writes the user's ~/.claude.
+ *
+ * On by default for Den's default pack, off for a distribution's packs.
+ * A distribution turns them off or on per pack (agents.default_pack, a
+ * persona_packs entry's `hooks` / `instructions`) and per persona (front
+ * matter `den_hooks` / `den_instructions`), the persona winning.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { enginePath, scriptEntrypoint, type EngineCommand } from "../engine.js";
+
+export interface Guardrails {
+  /** Den's Claude Code hooks (PreToolUse reads and sleeps, Stop hand-back). */
+  hooks: boolean;
+  /** The shared persona instructions in the role prompt. */
+  instructions: boolean;
+}
+
+/** Den's default pack: both on. */
+export const DEFAULT_PACK_GUARDRAILS: Guardrails = {
+  hooks: true,
+  instructions: true,
+};
+
+/** A distribution's pack: both off unless it opts in. */
+export const PACK_GUARDRAILS: Guardrails = {
+  hooks: false,
+  instructions: false,
+};
+
+/** Where the guardrail files ship (src/ ships whole). */
+export const GUARDRAILS_DIR = enginePath(
+  "src",
+  "shared",
+  "agents",
+  "guardrails",
+);
+
+/** The shared persona instructions, as Den ships them. */
+export function sharedInstructions(dir: string = GUARDRAILS_DIR): string {
+  return fs.readFileSync(path.join(dir, "instructions.md"), "utf-8").trim();
+}
+
+/** One argument for a POSIX shell, single-quoted when it needs it. */
+export function shellQuote(s: string): string {
+  return /^[A-Za-z0-9_./:@%+=,-]+$/.test(s)
+    ? s
+    : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+const commandLine = (c: EngineCommand): string =>
+  [c.command, ...c.args].map(shellQuote).join(" ");
+
+export interface HookCommands {
+  /** The PreToolUse hook's command line. */
+  pretooluse: string;
+  /** The Stop hook's command line. */
+  stop: string;
+}
+
+/** The command lines Den's hooks run: this node, Den's own scripts. */
+export function hookCommands(
+  dir: string = GUARDRAILS_DIR,
+  node: string = process.execPath,
+): HookCommands {
+  return {
+    pretooluse: commandLine({
+      command: node,
+      args: [path.join(dir, "pretooluse.mjs")],
+    }),
+    stop: commandLine(
+      scriptEntrypoint("src/shared/agents/guardrails/stop-hook.ts"),
+    ),
+  };
+}
+
+/**
+ * The `hooks` block of the agent's settings file: hooks.json with each
+ * `{pretooluse}` / `{stop}` placeholder replaced by its command line.
+ */
+export function guardrailHooks(
+  dir: string = GUARDRAILS_DIR,
+  cmds: HookCommands = hookCommands(dir),
+): Record<string, unknown> {
+  const fragment = JSON.parse(
+    fs.readFileSync(path.join(dir, "hooks.json"), "utf-8"),
+  ) as { hooks: Record<string, unknown> };
+  const fill = (v: unknown): unknown => {
+    if (typeof v === "string")
+      return v.replace(
+        /\{(pretooluse|stop)\}/g,
+        (_, k: keyof HookCommands) => cmds[k],
+      );
+    if (Array.isArray(v)) return v.map(fill);
+    if (v && typeof v === "object")
+      return Object.fromEntries(
+        Object.entries(v).map(([k, x]) => [k, fill(x)]),
+      );
+    return v;
+  };
+  return fill(fragment.hooks) as Record<string, unknown>;
+}