@nanhara/hara 0.121.1 → 0.122.1

package/dist/org/review-chain.js

@@ -4,6 +4,191 @@
 // (it needs runAgent + providers); these are the pure, testable pieces: verdict parsing, change capture,
 // and the prompts. Used by `hara org --review`.
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { verifyOpenedRegularFileSync } from "../fs-read.js";
+import { sensitiveFileReason } from "../security/sensitive-files.js";
+import { redactToolSubprocessOutput, toolSubprocessEnv } from "../security/subprocess-env.js";
+const MAX_CHANGED_PATHS = 4096;
+const GIT_CAPTURE_TIMEOUT_MS = 10_000;
+const MAX_STAGED_VERIFY_BYTES = 64 * 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+function gitBytes(cwd, args) {
+    return execFileSync("git", args, {
+        cwd,
+        env: toolSubprocessEnv(),
+        encoding: "buffer",
+        maxBuffer: 50_000_000,
+        timeout: GIT_CAPTURE_TIMEOUT_MS,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+}
+function nulPaths(bytes) {
+    const text = bytes.toString("utf8");
+    // A replacement character means a POSIX byte filename could not be represented safely as a JS path.
+    // Fail closed instead of accidentally diffing a path other than the one Git named.
+    if (text.includes("\uFFFD"))
+        throw new Error("git returned a filename that is not valid UTF-8");
+    return text.split("\0").filter(Boolean);
+}
+function pathInside(cwd, path) {
+    const rel = relative(resolve(cwd), resolve(cwd, path));
+    return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function safePathLabel(path) {
+    return redactToolSubprocessOutput(path);
+}
+function safePathLabels(paths) {
+    return [...new Set(paths.map(safePathLabel))];
+}
+function classifyPaths(cwd, paths) {
+    const classified = { protected: [], missing: [] };
+    for (const path of paths) {
+        if (!pathInside(cwd, path)) {
+            classified.protected.push(path);
+            continue;
+        }
+        const absolute = join(cwd, path);
+        if (sensitiveFileReason(absolute) !== null) {
+            classified.protected.push(path);
+            continue;
+        }
+        try {
+            const info = lstatSync(absolute);
+            // A tracked directory is a submodule gitlink (Git emits only its object id). Every other non-regular
+            // inode is excluded so FIFOs/devices/symlinks and hard-link aliases cannot enter model context.
+            if (!info.isDirectory() && (!info.isFile() || info.nlink > 1))
+                classified.protected.push(path);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                classified.missing.push(path);
+            else
+                classified.protected.push(path);
+        }
+    }
+    return classified;
+}
+function diffArgs(options, format) {
+    const args = ["diff", "--no-ext-diff", "--no-textconv", "--no-renames"];
+    if (format === "name-status")
+        args.push("--name-status", "-z");
+    if (options.staged)
+        args.push("--staged");
+    else if (options.base) {
+        if (options.base.startsWith("-") || options.base.includes("\0"))
+            throw new Error("invalid base ref");
+        args.push(options.base);
+    }
+    else
+        args.push("HEAD");
+    return args;
+}
+function changedPathStatuses(cwd, options) {
+    const fields = nulPaths(gitBytes(cwd, [...diffArgs(options, "name-status"), "--"]));
+    const statuses = new Map();
+    for (let i = 0; i < fields.length;) {
+        const rawStatus = fields[i++];
+        if (!/^[ACDMRTUXB][0-9]*$/u.test(rawStatus))
+            throw new Error("git returned an invalid name-status record");
+        const status = rawStatus[0];
+        // --no-renames keeps C/R out of ordinary output, but consume both paths defensively if a Git variant
+        // still reports one so a source name can never be mistaken for a status token.
+        if (status === "C" || status === "R") {
+            const source = fields[i++];
+            const destination = fields[i++];
+            if (source === undefined || destination === undefined)
+                throw new Error("git returned a truncated name-status record");
+            statuses.set(destination, status);
+            continue;
+        }
+        const path = fields[i++];
+        if (path === undefined)
+            throw new Error("git returned a truncated name-status record");
+        statuses.set(path, status);
+    }
+    return statuses;
+}
+function stagedIndexEntry(cwd, path) {
+    const records = nulPaths(gitBytes(cwd, ["ls-files", "--stage", "-z", "--", path]));
+    if (records.length !== 1)
+        return null;
+    const record = records[0];
+    const tab = record.indexOf("\t");
+    if (tab < 0 || record.slice(tab + 1) !== path)
+        return null;
+    const fields = record.slice(0, tab).split(" ");
+    if (fields.length !== 3 || fields[2] !== "0" || !/^[0-9a-f]+$/u.test(fields[1]))
+        return null;
+    return { mode: fields[0], oid: fields[1] };
+}
+function verifiedWorktreeBlobOid(cwd, path, algorithm, maxBytes) {
+    const absolute = join(cwd, path);
+    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+    const fd = openSync(absolute, constants.O_RDONLY | constants.O_NONBLOCK | noFollow);
+    try {
+        const before = fstatSync(fd);
+        verifyOpenedRegularFileSync(absolute, before, {
+            action: "verify staged commit content",
+            rejectHardLinks: true,
+            protectSensitive: true,
+        });
+        if (before.size > maxBytes)
+            throw new Error("staged file exceeds verification limit");
+        const chunks = [];
+        let total = 0;
+        while (total <= maxBytes) {
+            const want = Math.min(READ_CHUNK_BYTES, maxBytes + 1 - total);
+            const buffer = Buffer.allocUnsafe(want);
+            const bytesRead = readSync(fd, buffer, 0, want, total);
+            if (!bytesRead)
+                break;
+            chunks.push(buffer.subarray(0, bytesRead));
+            total += bytesRead;
+        }
+        if (total > maxBytes)
+            throw new Error("staged file exceeds verification limit");
+        const after = fstatSync(fd);
+        verifyOpenedRegularFileSync(absolute, after, {
+            action: "verify staged commit content",
+            rejectHardLinks: true,
+            protectSensitive: true,
+        });
+        if (before.dev !== after.dev
+            || before.ino !== after.ino
+            || before.size !== after.size
+            || before.mtimeMs !== after.mtimeMs
+            || before.ctimeMs !== after.ctimeMs
+            || total !== before.size)
+            throw new Error("staged worktree file changed during verification");
+        const hash = createHash(algorithm);
+        hash.update(`blob ${total}\0`);
+        for (const chunk of chunks)
+            hash.update(chunk);
+        return hash.digest("hex");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function stagedBlobMatchesWorktree(cwd, path, maxBytes) {
+    try {
+        const entry = stagedIndexEntry(cwd, path);
+        if (!entry || (entry.mode !== "100644" && entry.mode !== "100755"))
+            return false;
+        const algorithm = entry.oid.length === 40 ? "sha1" : entry.oid.length === 64 ? "sha256" : null;
+        if (!algorithm)
+            return false;
+        return verifiedWorktreeBlobOid(cwd, path, algorithm, maxBytes) === entry.oid;
+    }
+    catch {
+        return false;
+    }
+}
+function untrackedPaths(cwd) {
+    return nulPaths(gitBytes(cwd, ["ls-files", "--others", "--exclude-standard", "-z", "--"]));
+}
 /** Fallback reviewer persona when the project has no `reviewer` role. Read-only by intent. */
 export const REVIEWER_SYSTEM = `You are a senior code reviewer reviewing changes made to accomplish a task.
 Inspect them for: correctness and bugs, security, missing edge cases, and whether they actually accomplish
@@ -37,33 +222,142 @@ export function parseVerdict(text) {
     const approved = !CHANGES_RE.test(after) && APPROVE_RE.test(after); // changes-signal vetoes; ambiguous = not approved
     return { approved, issues: text.slice(0, idx).trim() };
 }
-/** Capture the working-tree changes vs HEAD (what to review). Non-destructive; empty for a non-git dir
- *  or a repo with no commits. New (untracked) files are listed by name — the reviewer can read_file them. */
-export function captureChanges(cwd, cap = 100_000) {
-    const git = (args) => {
-        try {
-            return execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 50_000_000 });
+/** Capture model-safe change metadata. Git patches are deliberately excluded because their old side is
+ * historical content with no trustworthy current filesystem identity. Reviewers can read current files. */
+export function captureChanges(cwd, cap = 100_000, options = {}) {
+    try {
+        const statuses = changedPathStatuses(cwd, options);
+        const paths = [...statuses.keys()];
+        const deleted = new Set(paths.filter((path) => statuses.get(path) === "D"));
+        const includeUntracked = options.includeUntracked ?? (!options.staged && !options.base);
+        const untracked = includeUntracked ? untrackedPaths(cwd) : [];
+        if (paths.length + untracked.length > MAX_CHANGED_PATHS) {
+            return { diff: "", newFiles: [], skippedFiles: [], omittedDeletions: [], error: `too many changed paths (>${MAX_CHANGED_PATHS})` };
         }
-        catch {
-            return "";
+        const tracked = classifyPaths(cwd, paths);
+        const untrackedClass = classifyPaths(cwd, untracked);
+        const skippedRaw = new Set([...tracked.protected, ...untrackedClass.protected]);
+        // A token-shaped untracked pathname is itself unsafe model input. Once staged, its diff header is
+        // redacted like every other subprocess output; before then, omit it rather than advertise a false path.
+        for (const path of untracked)
+            if (safePathLabel(path) !== path)
+                skippedRaw.add(path);
+        // Missing is not synonymous with deleted: a staged AD entry has an added blob in the index while the
+        // worktree path is absent. Only Git's exact D status is an omitted deletion; every other missing tracked
+        // entry is unverifiable and remains protected.
+        for (const path of tracked.missing)
+            if (!deleted.has(path))
+                skippedRaw.add(path);
+        const omittedRaw = paths.filter((path) => !skippedRaw.has(path) && deleted.has(path));
+        const safePaths = paths.filter((path) => !skippedRaw.has(path) && !deleted.has(path));
+        const missingUntracked = new Set(untrackedClass.missing);
+        const newFiles = untracked
+            .filter((path) => !skippedRaw.has(path) && !missingUntracked.has(path))
+            .slice(0, 50);
+        // Never provide a Git patch to a model: even an ordinary modification's old side can be a historical
+        // hard-link alias of a credential, and a staged index blob can diverge from today's verified worktree.
+        // Status + redacted path metadata is sufficient for reviewers to inspect the current file via read_file.
+        let diff = safePaths.map((path) => `${statuses.get(path)}\t${safePathLabel(path)}`).join("\n");
+        if (diff.length > cap)
+            diff = diff.slice(0, cap) + "\n…[diff truncated]";
+        return {
+            diff,
+            newFiles,
+            skippedFiles: safePathLabels([...skippedRaw]),
+            omittedDeletions: safePathLabels(omittedRaw),
+        };
+    }
+    catch (error) {
+        return {
+            diff: "",
+            newFiles: [],
+            skippedFiles: [],
+            omittedDeletions: [],
+            error: redactToolSubprocessOutput(error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+/** Protected files currently staged for commit. Commit-message generation and commit both fail closed. */
+export function protectedStagedPaths(cwd) {
+    try {
+        const statuses = changedPathStatuses(cwd, { staged: true });
+        if (statuses.size > MAX_CHANGED_PATHS)
+            return ["(too many staged paths to verify)"];
+        const classified = classifyPaths(cwd, [...statuses.keys()]);
+        const unverifiable = new Set(classified.missing.filter((path) => statuses.get(path) !== "D"));
+        const protectedSet = new Set(classified.protected);
+        let remainingBytes = MAX_STAGED_VERIFY_BYTES;
+        for (const [path, status] of statuses) {
+            if (status === "D" || protectedSet.has(path) || unverifiable.has(path))
+                continue;
+            let size = remainingBytes + 1;
+            try {
+                size = lstatSync(join(cwd, path)).size;
+            }
+            catch { /* verification below fails closed */ }
+            if (!["A", "M", "T"].includes(status)
+                || size > remainingBytes
+                || !stagedBlobMatchesWorktree(cwd, path, remainingBytes)) {
+                unverifiable.add(path);
+            }
+            else {
+                remainingBytes -= size;
+            }
         }
-    };
-    let diff = git(["diff", "HEAD"]).trim();
-    if (diff.length > cap)
-        diff = diff.slice(0, cap) + "\n…[diff truncated]";
-    const newFiles = git(["ls-files", "--others", "--exclude-standard"])
-        .split("\n")
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .slice(0, 50);
-    return { diff, newFiles };
+        return safePathLabels([...classified.protected, ...unverifiable]);
+    }
+    catch {
+        // An unreadable/ambiguous Git index cannot be declared safe to send to a model or commit automatically.
+        return ["(unable to verify staged paths)"];
+    }
+}
+/** Protected tracked/untracked changes that `git add -A` would stage. */
+export function protectedWorkingTreePaths(cwd) {
+    try {
+        // Compare HEAD directly with the final worktree. Combining cached + unstaged lists misclassifies an AD
+        // entry that `git add -A` will collapse to no net change.
+        const statuses = changedPathStatuses(cwd, {});
+        const tracked = [...statuses.keys()];
+        const untracked = untrackedPaths(cwd);
+        if (tracked.length + untracked.length > MAX_CHANGED_PATHS)
+            return ["(too many changed paths to verify)"];
+        const trackedClass = classifyPaths(cwd, tracked);
+        const untrackedClass = classifyPaths(cwd, untracked);
+        const unverifiable = trackedClass.missing.filter((path) => statuses.get(path) !== "D");
+        return safePathLabels([...trackedClass.protected, ...unverifiable, ...untrackedClass.protected]);
+    }
+    catch {
+        return ["(unable to verify working-tree paths)"];
+    }
+}
+/** Protected tracked changes that `git add -u` would stage (untracked files are intentionally excluded). */
+export function protectedTrackedWorkingTreePaths(cwd) {
+    try {
+        const statuses = changedPathStatuses(cwd, {});
+        const tracked = [...statuses.keys()];
+        if (tracked.length > MAX_CHANGED_PATHS)
+            return ["(too many changed paths to verify)"];
+        const classified = classifyPaths(cwd, tracked);
+        const unverifiable = classified.missing.filter((path) => statuses.get(path) !== "D");
+        return safePathLabels([...classified.protected, ...unverifiable]);
+    }
+    catch {
+        return ["(unable to verify tracked working-tree paths)"];
+    }
 }
 /** True only if the working tree is fully clean — no uncommitted changes. The `--commit` capstone uses
  *  this as a guard: `git add -A` + commit is only safe to run when the tree was clean before the org ran,
  *  so it captures THIS run's work and never sweeps up pre-existing WIP. False for a non-git dir. */
 export function isTreeClean(cwd) {
     try {
-        return execFileSync("git", ["status", "--porcelain"], { cwd, encoding: "utf8", maxBuffer: 50_000_000 }).trim() === "";
+        return execFileSync("git", ["status", "--porcelain"], {
+            cwd,
+            env: toolSubprocessEnv(),
+            encoding: "utf8",
+            maxBuffer: 50_000_000,
+            timeout: GIT_CAPTURE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim() === "";
     }
     catch {
         return false; // not a git repo / git error → treat as "not clean" so we never auto-commit blindly
@@ -73,15 +367,57 @@ export function isTreeClean(cwd) {
 export function stripCommitFence(text) {
     return text.trim().replace(/^```[a-z]*\n?/i, "").replace(/\n?```$/i, "").trim();
 }
+function displayPathList(paths, cap = 12_000) {
+    const shown = [];
+    let length = 0;
+    for (const path of paths) {
+        const label = JSON.stringify(safePathLabel(path));
+        if (length + label.length + (shown.length ? 2 : 0) > cap)
+            break;
+        shown.push(label);
+        length += label.length + (shown.length > 1 ? 2 : 0);
+    }
+    const remaining = paths.length - shown.length;
+    if (!shown.length)
+        return `${paths.length} path(s) (names omitted for length)`;
+    return shown.join(", ") + (remaining ? `, … and ${remaining} more` : "");
+}
+/** Model-safe input for commit-message generation. A deletion-only commit still has useful metadata, but
+ * never receives the unverifiable historical blob that Git's ordinary deletion diff would expose. */
+export function commitMessageInput(changes) {
+    const omittedDeletions = changes.omittedDeletions ?? [];
+    const parts = [];
+    if (changes.diff.trim())
+        parts.push(changes.diff);
+    if (omittedDeletions.length) {
+        parts.push("Tracked deletions (historical file contents intentionally omitted for safety): " +
+            displayPathList(omittedDeletions));
+    }
+    return parts.join("\n\n");
+}
 /** The reviewer's input: the task + the changes to review. */
 export function reviewPrompt(task, changes) {
+    const skippedFiles = changes.skippedFiles ?? [];
+    const omittedDeletions = changes.omittedDeletions ?? [];
     const parts = [`Task that was implemented:\n${task}`, ""];
-    if (changes.diff)
-        parts.push("Changes (working tree vs HEAD):\n```diff\n" + changes.diff + "\n```");
+    if (changes.diff) {
+        parts.push("Change metadata only (status + path; historical patch contents are intentionally omitted):\n```text\n" +
+            changes.diff + "\n```");
+    }
     if (changes.newFiles.length)
-        parts.push(`New files (use read_file to inspect): ${changes.newFiles.join(", ")}`);
-    if (!changes.diff && !changes.newFiles.length)
-        parts.push("(no diff captured — inspect the working tree with git / read_file)");
+        parts.push(`New files (use read_file to inspect): ${displayPathList(changes.newFiles)}`);
+    if (skippedFiles.length) {
+        parts.push("Protected paths were omitted from review context and MUST NOT be opened by the reviewer: " +
+            displayPathList(skippedFiles));
+    }
+    if (omittedDeletions.length) {
+        parts.push("Tracked deletions were detected, but their historical contents were omitted because old filesystem " +
+            "identity cannot be verified safely: " + displayPathList(omittedDeletions));
+    }
+    if (changes.error)
+        parts.push(`(change capture failed closed: ${changes.error})`);
+    if (!changes.diff && !changes.newFiles.length && !omittedDeletions.length)
+        parts.push("(no reviewable diff was captured)");
     parts.push("\nReview these changes against the task. Finish with your VERDICT line.");
     return parts.join("\n");
 }

package/dist/org/roles.js

@@ -1,10 +1,12 @@
 // Org roles — markdown agent definitions in <project>/.hara/roles/*.md.
-// Frontmatter: name, description, owns[], rejects[], model?, allowTools[], denyTools[]. Body = persona/system.
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+// Frontmatter: name, description, owns[], rejects[], model?, allowTools[], denyTools[], readOnly?. Body = persona/system.
+import { writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { findProjectRoot } from "../context/agents-md.js";
 import { pluginRoleDirs } from "../plugins/plugins.js";
+import { readModelContextFileSync } from "../fs-read.js";
+const MAX_ROLE_BYTES = 512 * 1024;
 export function rolesDir(cwd) {
     return join(findProjectRoot(cwd), ".hara", "roles");
 }
@@ -83,25 +85,49 @@ function parseFrontmatter(text) {
  *  parallel), with a role allowed to narrow further but never to grant write/exec. `isReadonly` is the
  *  read-kind predicate. This is the guard that keeps the `agent` tool from bypassing the approval gate. */
 export function subagentToolFilter(role, isReadonly) {
-    const roleFilter = role?.allowTools
-        ? (n) => role.allowTools.includes(n)
-        : role?.denyTools
-            ? (n) => !role.denyTools.includes(n)
-            : null;
+    // Treat allow + deny as an intersection when both are present. A deny must never disappear merely
+    // because an allow-list was also declared (mixed policies are common in generated role bundles).
+    const roleFilter = role?.allowTools || role?.denyTools
+        ? (n) => (!role.allowTools || role.allowTools.includes(n)) && (!role.denyTools || !role.denyTools.includes(n))
+        : null;
     return (n) => isReadonly(n) && (roleFilter ? roleFilter(n) : true);
 }
+/** Apply a role's declared tool policy to a normal (approval-gated) run. Undefined means unrestricted. */
+export function roleToolFilter(role) {
+    if (!role)
+        return undefined;
+    const declared = (name) => (!role.allowTools || role.allowTools.includes(name)) && (!role.denyTools || !role.denyTools.includes(name));
+    if (role.readOnly) {
+        // Raw bash is intentionally absent: even commands that look read-only can hide redirection, command
+        // substitution, hooks, or an executable with side effects. Reviewers get dedicated read/search tools.
+        const safe = new Set(["read_file", "grep", "glob", "ls", "web_fetch", "web_search", "codebase_search", "todo_write"]);
+        return (name) => safe.has(name) && declared(name);
+    }
+    return role.allowTools || role.denyTools ? declared : undefined;
+}
 export function loadRoles(cwd) {
-    const byId = new Map();
     // lowest→highest precedence: plugins < org(B-end push) < global < .claude/agents < .hara/roles (project wins)
-    for (const dir of [...pluginRoleDirs(), orgRolesDir(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]) {
+    return [...rolesFromDirs([...pluginRoleDirs(), orgRolesDir(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]).values()];
+}
+/** The project-independent layers only (plugins + org-pushed + ~/.hara/roles) — what the global agent
+ *  index lists as "runs anywhere". Excludes cwd-derived layers by construction. */
+export function loadGlobalRoles() {
+    return [...rolesFromDirs([...pluginRoleDirs(), orgRolesDir(), globalRolesDir()]).values()];
+}
+function rolesFromDirs(dirs) {
+    const byId = new Map();
+    for (const dir of dirs) {
         if (!existsSync(dir))
             continue;
         for (const f of readdirSync(dir)) {
             if (!f.endsWith(".md") || f === "README.md")
                 continue;
             try {
-                const { fm, body } = parseFrontmatter(readFileSync(join(dir, f), "utf8"));
+                const { fm, body } = parseFrontmatter(readModelContextFileSync(join(dir, f), MAX_ROLE_BYTES));
                 const id = fm.name || f.replace(/\.md$/, "");
+                const explicitReadOnly = /^(true|false)$/i.test(String(fm.readOnly ?? ""))
+                    ? String(fm.readOnly).toLowerCase() === "true"
+                    : undefined;
                 byId.set(id, {
                     id,
                     description: fm.description || "",
@@ -112,6 +138,7 @@ export function loadRoles(cwd) {
                     model: fm.model && !/^(sonnet|opus|haiku|inherit)$/i.test(String(fm.model)) ? fm.model : undefined,
                     allowTools: Array.isArray(fm.allowTools) ? fm.allowTools : claudeTools(fm.tools),
                     denyTools: Array.isArray(fm.denyTools) ? fm.denyTools : undefined,
+                    readOnly: explicitReadOnly ?? (id.toLowerCase() === "reviewer" ? true : undefined),
                     system: body,
                 });
             }
@@ -120,7 +147,7 @@ export function loadRoles(cwd) {
             }
         }
     }
-    return [...byId.values()];
+    return byId;
 }
 export function hasRoles(cwd) {
     return loadRoles(cwd).length > 0;
@@ -140,10 +167,11 @@ End with a one-line summary of what changed.
 name: reviewer
 description: Reviews code for bugs, correctness, security, and style. Does not modify code.
 owns: [review, audit, check, correctness, security, vulnerability, lint, quality]
-allowTools: [read_file, bash]
+allowTools: [read_file, grep, glob, ls, codebase_search]
+readOnly: true
 ---
 You are the **reviewer**. Read the relevant code and report concrete issues (bug / correctness /
-security / style) with file:line and a suggested fix. Do NOT edit files — you have read-only tools.
+security / style) with file:line and a suggested fix. Do NOT edit files — your tool surface is enforced read-only.
 Be specific; skip nitpicks unless asked.
 `,
     "docs.md": `---
@@ -164,6 +192,7 @@ Each \`*.md\` here is a role-agent. Frontmatter:
 - \`rejects\` — keywords that exclude this role (REJECT)
 - \`model\` — optional model override
 - \`allowTools\` / \`denyTools\` — restrict the role's tools
+- \`readOnly\` — enforce read/search-only tools (defaults on for a role named \`reviewer\`)
 
 Run \`hara org "<task>"\` to dispatch a task to the owning role, or \`hara org --role <id> "<task>"\`.
 `,