@andromarces/agent-loops 0.2.2 → 0.3.0

package/src/install/manifest.mjs

@@ -0,0 +1,222 @@
+// The install manifest (#139). One record per touched target, at
+// `<home>/.agent-loops/install.json`, so `agent-loop uninstall` can restore the
+// pre-install bytes and remove only entries it inserted. The baseline recorded
+// by the first install is immutable: later installs carry it forward untouched
+// and only uninstall consumes it.
+import { createHash } from "node:crypto";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import {
+  ensureDir,
+  readTextOrNull,
+  removeDirQuiet,
+  removeFileQuiet,
+  writeTextAtomic,
+} from "./fsutil.mjs";
+
+export const MANIFEST_VERSION = 1;
+
+/**
+ * The install home. `AGENT_LOOP_HOME` overrides it so tests never touch the
+ * developer's real home directory.
+ */
+export function resolveHome() {
+  const override = process.env.AGENT_LOOP_HOME;
+  return override ? resolve(override) : homedir();
+}
+
+export function installRoot(home = resolveHome()) {
+  return join(home, ".agent-loops");
+}
+
+export function manifestPath(home = resolveHome()) {
+  return join(installRoot(home), "install.json");
+}
+
+/**
+ * The lock file that serializes `install` and `uninstall` for one install home.
+ * It lives under the OS temp root, not under the home, so `removeManifest` can
+ * delete `<home>/.agent-loops` while the lock is held. The key is a hash of the
+ * canonical home: the resolved path, lowercased on Windows, where paths compare
+ * case-insensitively, so equivalent spellings share one lock. The temp root is
+ * `tmpdir()`: two processes with different `TMPDIR`/`TEMP` values compute
+ * different lock paths and do not contend, so callers that must serialize
+ * across a sandbox must share one temp root.
+ */
+export function manifestLockFile(home = resolveHome()) {
+  const resolved = resolve(home);
+  const canonical = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  const key = createHash("sha256").update(canonical).digest("hex").slice(0, 12);
+  return join(tmpdir(), "agent-loops", `install-${key}.lock`);
+}
+
+export function emptyManifest() {
+  return { version: MANIFEST_VERSION, harnesses: {} };
+}
+
+/** True for a JSON object, which excludes null and an array. */
+function isJsonObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** True for a settings locator, so a record's `locator` cannot crash the merge. */
+function isLocator(value) {
+  if (!isJsonObject(value)) {
+    return false;
+  }
+  if (value.kind === "key") {
+    return typeof value.key === "string";
+  }
+  return (
+    value.kind === "array" &&
+    Array.isArray(value.path) &&
+    value.path.length > 0 &&
+    value.path.every((key) => typeof key === "string")
+  );
+}
+
+/** True for a value a record holds as a hash or a backup path. */
+function isStringOrNull(value) {
+  return value === null || typeof value === "string";
+}
+
+/** The error for a record whose named field cannot be acted on. */
+function unexpectedHarnessRecord(harness, detail, path) {
+  return new Error(
+    `Install manifest has an unexpected record for harness "${harness}" (${detail}): ${path}`,
+  );
+}
+
+/**
+ * Rejects a `files` entry install or uninstall cannot act on. Uninstall reads
+ * `shaAfter`, `existedBefore`, and `backupPath` before any write, so a wrong
+ * type there would leave a partial uninstall.
+ */
+function assertFileRecord(harness, entry, where, path) {
+  if (!isJsonObject(entry)) {
+    throw unexpectedHarnessRecord(harness, where, path);
+  }
+  if (typeof entry.path !== "string") {
+    throw unexpectedHarnessRecord(harness, `${where}.path`, path);
+  }
+  if (typeof entry.shaAfter !== "string") {
+    throw unexpectedHarnessRecord(harness, `${where}.shaAfter`, path);
+  }
+  if (!isStringOrNull(entry.shaBefore)) {
+    throw unexpectedHarnessRecord(harness, `${where}.shaBefore`, path);
+  }
+  if (typeof entry.existedBefore !== "boolean") {
+    throw unexpectedHarnessRecord(harness, `${where}.existedBefore`, path);
+  }
+  if (!isStringOrNull(entry.backupPath)) {
+    throw unexpectedHarnessRecord(harness, `${where}.backupPath`, path);
+  }
+}
+
+/** Rejects a `settings` entry, which carries the file fields plus its merge metadata. */
+function assertSettingsRecord(harness, entry, where, path) {
+  assertFileRecord(harness, entry, where, path);
+  if (!isLocator(entry.locator)) {
+    throw unexpectedHarnessRecord(harness, `${where}.locator`, path);
+  }
+  if (!Object.hasOwn(entry, "entry")) {
+    throw unexpectedHarnessRecord(harness, `${where}.entry`, path);
+  }
+  if (typeof entry.userEdited !== "boolean") {
+    throw unexpectedHarnessRecord(harness, `${where}.userEdited`, path);
+  }
+  if (!Number.isInteger(entry.createdFrom)) {
+    throw unexpectedHarnessRecord(harness, `${where}.createdFrom`, path);
+  }
+}
+
+/**
+ * Rejects a harness record that install or uninstall cannot act on, naming the
+ * first bad field. `files` and `settings` may be absent, but when present every
+ * entry must carry the fields uninstall reads; `dirs` may be absent, but when
+ * present it must be an array of strings. Every field is checked before any
+ * caller writes, so a corrupt field cannot leave a partial install or uninstall.
+ */
+function assertHarnessRecord(harness, record, path) {
+  if (!isJsonObject(record)) {
+    throw unexpectedHarnessRecord(harness, "record", path);
+  }
+  if (record.files !== undefined) {
+    if (!Array.isArray(record.files)) {
+      throw unexpectedHarnessRecord(harness, "files", path);
+    }
+    record.files.forEach((entry, index) =>
+      assertFileRecord(harness, entry, `files[${index}]`, path),
+    );
+  }
+  if (record.settings !== undefined) {
+    if (!Array.isArray(record.settings)) {
+      throw unexpectedHarnessRecord(harness, "settings", path);
+    }
+    record.settings.forEach((entry, index) =>
+      assertSettingsRecord(harness, entry, `settings[${index}]`, path),
+    );
+  }
+  if (record.dirs !== undefined) {
+    if (!Array.isArray(record.dirs)) {
+      throw unexpectedHarnessRecord(harness, "dirs", path);
+    }
+    record.dirs.forEach((dir, index) => {
+      if (typeof dir !== "string") {
+        throw unexpectedHarnessRecord(harness, `dirs[${index}]`, path);
+      }
+    });
+  }
+}
+
+export async function readManifest(home = resolveHome()) {
+  const path = manifestPath(home);
+  const text = await readTextOrNull(path);
+  if (text === null) {
+    return emptyManifest();
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error(`Install manifest is not valid JSON: ${path}`);
+  }
+  if (!isJsonObject(value)) {
+    throw new Error(`Install manifest has an unexpected shape: ${path}`);
+  }
+  if (value.version !== MANIFEST_VERSION) {
+    throw new Error(
+      `Install manifest has an unsupported version (${JSON.stringify(value.version)}): ${path}`,
+    );
+  }
+  if (!isJsonObject(value.harnesses)) {
+    throw new Error(`Install manifest has an unexpected shape: ${path}`);
+  }
+  for (const [harness, record] of Object.entries(value.harnesses)) {
+    assertHarnessRecord(harness, record, path);
+  }
+  return { version: MANIFEST_VERSION, harnesses: value.harnesses };
+}
+
+export async function writeManifest(home, manifest) {
+  const path = manifestPath(home);
+  await ensureDir(dirname(path), new Set());
+  await writeTextAtomic(path, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+/** Deletes the manifest and its now-empty directory once no harness is recorded. */
+export async function removeManifest(home) {
+  const root = installRoot(home);
+  await removeFileQuiet(manifestPath(home));
+  try {
+    await removeDirQuiet(root);
+  } catch (err) {
+    // The manifest is already gone, so no later uninstall can retry this
+    // directory. Name it and ask for a manual cleanup instead of hiding it.
+    throw new Error(
+      `Install directory ${root} could not be removed (${err.code}). ` +
+        "The manifest was already deleted; remove the directory manually.",
+      { cause: err },
+    );
+  }
+}

package/src/install/settings.mjs

@@ -0,0 +1,217 @@
+// Settings-file merge for the installer (#139). A settings target records where
+// its one entry lives with a locator:
+//   - `{ kind: "array", path: ["hooks", "PreToolUse"], matcher, matcherKey }`
+//     inserts one element into the array at `path` (for example a Claude or
+//     Codex hook entry).
+//   - `{ kind: "key", key }` sets one top-level key (the Antigravity named hook
+//     group in `~/.gemini/config/hooks.json`).
+// The visible entry is the only ownership key: find and remove compare the
+// recorded entry by deep equality, so a package move or an upgrade that changes
+// a path still finds the old record.
+import { deepEqual } from "./fsutil.mjs";
+
+export function parseSettings(text, path) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`Settings file does not parse: ${path} (${err.message})`);
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Settings file is not a JSON object: ${path}`);
+  }
+  return value;
+}
+
+export function serializeSettings(value, originalText) {
+  const newline =
+    originalText === null || originalText === undefined || originalText.endsWith("\n") ? "\n" : "";
+  return `${JSON.stringify(value, null, 2)}${newline}`;
+}
+
+function existingArray(settings, locator) {
+  let node = settings;
+  for (const key of locator.path) {
+    if (node === null || typeof node !== "object" || !Object.hasOwn(node, key)) {
+      return null;
+    }
+    node = node[key];
+  }
+  return Array.isArray(node) ? node : null;
+}
+
+/** Returns the array a target writes into, creating missing objects if asked. */
+export function arrayAt(settings, locator, { create = false } = {}) {
+  const existing = existingArray(settings, locator);
+  if (existing || !create) {
+    return existing;
+  }
+  let node = settings;
+  for (const key of locator.path) {
+    if (node[key] === null || typeof node[key] !== "object") {
+      node[key] = key === locator.path[locator.path.length - 1] ? [] : {};
+    }
+    node = node[key];
+  }
+  return node;
+}
+
+/**
+ * Checks the shape along an array locator path before a merge. A wrong-typed
+ * container (`"hooks": []`, `"PreToolUse": {}`) is invalid settings, so the
+ * caller refuses with the manual snippet instead of writing a dropped or
+ * crashing entry.
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function validateLocator(settings, locator) {
+  if (locator.kind === "key") {
+    return { ok: true };
+  }
+  let node = settings;
+  for (let index = 0; index < locator.path.length; index++) {
+    const key = locator.path[index];
+    if (node === null || typeof node !== "object" || Array.isArray(node)) {
+      const where = locator.path.slice(0, index).join(".") || "(root)";
+      return { ok: false, reason: `expected an object at ${where}` };
+    }
+    if (!Object.hasOwn(node, key)) {
+      return { ok: true };
+    }
+    const value = node[key];
+    const last = index === locator.path.length - 1;
+    if (last) {
+      if (!Array.isArray(value)) {
+        return { ok: false, reason: `expected an array at ${locator.path.join(".")}` };
+      }
+    } else if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return {
+        ok: false,
+        reason: `expected an object at ${locator.path.slice(0, index + 1).join(".")}`,
+      };
+    }
+    node = value;
+  }
+  return { ok: true };
+}
+
+export function findEntryIndex(settings, locator, entry) {
+  if (locator.kind === "key") {
+    return Object.hasOwn(settings, locator.key) && deepEqual(settings[locator.key], entry) ? 0 : -1;
+  }
+  const array = existingArray(settings, locator);
+  return array ? array.findIndex((candidate) => deepEqual(candidate, entry)) : -1;
+}
+
+/**
+ * Inserts the entry. Returns `{ status: "inserted" | "conflict" | "duplicate" }`.
+ * An array locator appends a new entry even when another entry shares its
+ * matcher, because harnesses such as Claude Code allow several entries per
+ * matcher and a same-matcher user entry is never replaced. A key locator owns
+ * exactly one key, so a key occupied by different content is a conflict.
+ */
+export function insertEntry(settings, locator, entry) {
+  if (locator.kind === "key") {
+    if (Object.hasOwn(settings, locator.key)) {
+      return deepEqual(settings[locator.key], entry)
+        ? { status: "duplicate" }
+        : { status: "conflict" };
+    }
+    settings[locator.key] = entry;
+    return { status: "inserted" };
+  }
+  const array = arrayAt(settings, locator, { create: true });
+  if (findEntryIndex(settings, locator, entry) !== -1) {
+    return { status: "duplicate" };
+  }
+  array.push(entry);
+  return { status: "inserted" };
+}
+
+/** Replaces `current` with `next` in place. Returns true when `current` was found. */
+export function replaceEntry(settings, locator, current, next) {
+  const index = findEntryIndex(settings, locator, current);
+  if (index === -1) {
+    return false;
+  }
+  if (locator.kind === "key") {
+    settings[locator.key] = next;
+  } else {
+    existingArray(settings, locator)[index] = next;
+  }
+  return true;
+}
+
+/** Removes the recorded entry by deep equality. Returns true when it was found. */
+export function removeEntry(settings, locator, entry) {
+  const index = findEntryIndex(settings, locator, entry);
+  if (index === -1) {
+    return false;
+  }
+  if (locator.kind === "key") {
+    delete settings[locator.key];
+  } else {
+    existingArray(settings, locator).splice(index, 1);
+  }
+  return true;
+}
+
+/**
+ * Deletes empty containers along an array locator path, deepest key first, after
+ * the entry is removed. `createdFrom` is the index of the first path key that
+ * install created; a container the user already had is kept even when it is
+ * empty. A container that holds anything is kept.
+ */
+export function pruneEmptyLocator(settings, locator, createdFrom = 0) {
+  if (locator.kind === "key") {
+    return;
+  }
+  const chain = [];
+  let node = settings;
+  for (const key of locator.path) {
+    if (node === null || typeof node !== "object" || !Object.hasOwn(node, key)) {
+      return;
+    }
+    chain.push({ parent: node, key });
+    node = node[key];
+  }
+  for (let i = chain.length - 1; i >= createdFrom; i--) {
+    const { parent, key } = chain[i];
+    const value = parent[key];
+    const empty = Array.isArray(value)
+      ? value.length === 0
+      : value !== null && typeof value === "object" && Object.keys(value).length === 0;
+    if (!empty) {
+      return;
+    }
+    delete parent[key];
+  }
+}
+
+/**
+ * The index of the first key along an array locator path that is absent, or the
+ * path length when every key exists. Install records it so uninstall prunes only
+ * the containers install created.
+ */
+export function missingLocatorIndex(settings, locator) {
+  if (locator.kind === "key") {
+    return Object.hasOwn(settings, locator.key) ? 1 : 0;
+  }
+  let node = settings;
+  for (let index = 0; index < locator.path.length; index++) {
+    const key = locator.path[index];
+    if (node === null || typeof node !== "object" || !Object.hasOwn(node, key)) {
+      return index;
+    }
+    node = node[key];
+  }
+  return locator.path.length;
+}
+
+/** The fragment a maintainer can paste by hand when the installer refuses to merge. */
+export function manualSnippet(path, locator, entry) {
+  const where =
+    locator.kind === "key"
+      ? `under the top-level key "${locator.key}"`
+      : `under ${locator.path.join(".")}`;
+  return [`Add to ${path} ${where}:`, JSON.stringify(entry, null, 2)].join("\n");
+}

package/src/install/templates/antigravity/agent-loop-antigravity-parent-guard.mjs

@@ -0,0 +1,14 @@
+// Agent-loop Antigravity parent-guard hook shim (#88). Install copies this file
+// beside `hooks.json` in the global `~/.gemini/config/` folder, and the named
+// `agent-loop-parent-guard` `PreToolUse` group runs it by relative path.
+// Antigravity runs the hook command without a shell and resolves it against
+// that folder, so a quoted or spaced absolute script path fails. The shim
+// loads the guard from the installed package, whose path may contain spaces,
+// through a file URL. Install renders the import below to that absolute URL.
+try {
+  await import("__AGENT_LOOP_GUARD_URL__");
+} catch {
+  // A stale or unreachable guard URL denies nothing. A thrown import exits
+  // non-zero, and Antigravity blocks the tool call on a non-zero exit, so the
+  // failure is swallowed to keep the permission flow intact for every session.
+}

package/src/install/templates/antigravity/hooks.json

@@ -0,0 +1,16 @@
+{
+  "agent-loop-parent-guard": {
+    "PreToolUse": [
+      {
+        "matcher": "write_to_file|replace_file_content|multi_replace_file_content|sed_file|notebook_edit|invoke_subagent|send_message",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./agent-loop-antigravity-parent-guard.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/install/templates/antigravity/skills/agent-loop/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: agent-loop
+description: Run a delegated agent-loop role orchestration through the agent-loop CLI. Invoke only with /agent-loop.
+---
+
+Read `{{AGENT_LOOP_INSTRUCTIONS}}` and follow it for this request. Run every
+`agent-loop` command in the instructions as `__AGENT_LOOP_CLI__` instead, so the
+run does not depend on the `agent-loop` command resolving on PATH.
+
+Before the init dispatch call, run `__AGENT_LOOP_CLI__ harness-check antigravity`.
+It exits 0 only when the nearest harness process above this shell is Antigravity
+CLI. If it exits 3, stop and report that another harness owns the session; do
+not start a run. If it exits with any other non-zero code, stop and report that
+the check could not run or found no harness ancestor, which is distinct from a
+harness refusal. Do not use `ANTIGRAVITY_CONVERSATION_ID` to make this
+decision, because a nested harness inherits it.
+
+Use the invocation text as the task and role settings. Before the init dispatch
+call, verify that the active shell has `ANTIGRAVITY_CONVERSATION_ID`. Do not
+print its value. In PowerShell, pass `$env:ANTIGRAVITY_CONVERSATION_ID` as
+`--parent-session`. Set `$worktree = (Get-Location).Path` and pass
+`--cwd $worktree`. Do not embed `$PWD` in POSIX-style quotes. In POSIX shells,
+pass `--cwd "$PWD"` and `$ANTIGRAVITY_CONVERSATION_ID`. If the variable is
+absent, report the missing session channel and do not start the run.

package/src/install/templates/claude/skills/agent-loop/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: agent-loop
+description: Run a delegated agent-loop role orchestration through the agent-loop CLI. Invoke only with /agent-loop.
+disable-model-invocation: true
+argument-hint: <task and role settings>
+# OpenCode also discovers ~/.claude/skills, lists this skill to the model, and
+# the model auto-invokes it for an /agent-loop request. Hide it from OpenCode's
+# model list so the installed OpenCode plugin command owns /agent-loop and
+# supplies the session id.
+metadata:
+  opencode/autoinvoke: false
+---
+
+@{{AGENT_LOOP_INSTRUCTIONS}}
+
+Follow the attached instructions for this invocation. If the file is not
+attached, read `{{AGENT_LOOP_INSTRUCTIONS}}` before acting. Run every
+`agent-loop` command in the instructions as `__AGENT_LOOP_CLI__` instead, so the
+run does not depend on the `agent-loop` command resolving on PATH. The task and
+role settings from the invocation are:
+
+$ARGUMENTS
+
+Before the init dispatch call, run `__AGENT_LOOP_CLI__ harness-check claude`. It
+exits 0 only when the nearest harness process above this shell is Claude Code.
+If it exits 3, stop and report that another harness owns the session; do not
+start a run. If it exits with any other non-zero code, stop and report that the
+check could not run or found no harness ancestor, which is distinct from a
+harness refusal. Do not use `${CLAUDE_SESSION_ID}` to make this decision,
+because a foreign harness leaves the literal in place and a nested harness
+inherits the value.
+
+On the init dispatch call, pass ${CLAUDE_SESSION_ID} as `--parent-session`.

package/src/install/templates/codex/skills/agent-loop/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: agent-loop
+description: Run a delegated agent-loop role orchestration when the user explicitly invokes $agent-loop.
+# OpenCode also discovers ~/.agents/skills, lists this skill to the model, and
+# the model auto-invokes it for an /agent-loop request. Hide it from OpenCode's
+# model list so the installed OpenCode plugin command owns /agent-loop and
+# supplies the session id.
+metadata:
+  opencode/autoinvoke: false
+---
+
+Read `{{AGENT_LOOP_INSTRUCTIONS}}` and follow it for this request. Run every
+`agent-loop` command in the instructions as `__AGENT_LOOP_CLI__` instead, so the
+run does not depend on the `agent-loop` command resolving on PATH.
+
+Before the init dispatch call, run `__AGENT_LOOP_CLI__ harness-check codex`. It
+exits 0 only when the nearest harness process above this shell is Codex CLI. If
+it exits 3, stop and report that another harness owns the session; do not start a
+run. If it exits with any other non-zero code, stop and report that the check
+could not run or found no harness ancestor, which is distinct from a harness
+refusal. Do not use `CODEX_THREAD_ID` to make this decision, because a nested
+harness inherits it.
+
+Use the invocation text as the task and role settings. Before the init dispatch
+call, verify that the active shell has `CODEX_THREAD_ID`. Do not print its value.
+In PowerShell, pass `$env:CODEX_THREAD_ID` as `--parent-session`. Set
+`$worktree = (Get-Location).Path` and pass `--cwd $worktree`. Do not embed
+`$PWD` in POSIX-style quotes. In POSIX shells, pass `--cwd "$PWD"`. In POSIX
+shells, pass `$CODEX_THREAD_ID`. If it is absent, report the missing session
+channel and do not start the run.

package/src/install/templates/codex/skills/agent-loop/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/src/install/templates/copilot/hooks/parent-guard.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "matcher": "Edit|Write",
+        "exec": "node",
+        "args": [],
+        "cwd": ".",
+        "timeoutSec": 10
+      }
+    ]
+  }
+}

package/src/install/templates/opencode/plugins/parent-guard.ts

@@ -0,0 +1,11 @@
+// Agent-loop OpenCode parent-guard plugin (#75), installed at user scope by
+// `agent-loop install`. The factory and its rationale live in
+// `src/hook/opencode-plugin.mjs`; this template only wires that factory to the
+// shipped decision logic and the installed orchestrator instructions.
+import { createParentGuardPlugin } from "__AGENT_LOOP_PLUGIN_URL__";
+import { decideParentGuard } from "__AGENT_LOOP_GUARD_URL__";
+
+export default createParentGuardPlugin({
+  decideParentGuard,
+  instructionsPath: "{{AGENT_LOOP_INSTRUCTIONS}}",
+});

package/src/lib/args.mjs

@@ -26,6 +26,29 @@ export function readNonNegativeInt(flag, value) {
   return val;
 }
 
+// Defaults shared by the headless CLI, the role subcommand, and the loop runtime.
+export const DEFAULT_MAX_STEPS = 20;
+export const DEFAULT_TIMEOUT = 3600;
+
+// Role flags: `--<role>[-model|-effort]` to option key. The headless CLI reads
+// all three roles, the role subcommand reads the child roles.
+export const CHILD_ROLE_KINDS = ["worker", "reviewer"];
+export const ROLE_KINDS = ["orchestrator", ...CHILD_ROLE_KINDS];
+
+export function roleFlags(roles) {
+  return Object.fromEntries(
+    roles.flatMap((role) => [
+      [`--${role}`, role],
+      [`--${role}-model`, `${role}Model`],
+      [`--${role}-effort`, `${role}Effort`],
+    ]),
+  );
+}
+
+export const ROLE_FLAG_BY_OPTION = Object.fromEntries(
+  Object.entries(roleFlags(ROLE_KINDS)).map(([flag, option]) => [option, flag]),
+);
+
 export function assertOpenCodeOptions(role, kind, model, effort) {
   if (kind && normalizeAgent(kind) !== "opencode") {
     return;

package/src/lib/hash.mjs

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+
+/**
+ * SHA-256 hex digest. Accepts a string (hashed as UTF-8) or a Buffer, so text
+ * and file bytes hash through one helper.
+ */
+export function sha256(data) {
+  return createHash("sha256").update(data).digest("hex");
+}

package/src/lib/log.mjs

@@ -1,8 +1,9 @@
 // Lifecycle logging at operational boundaries (AGENTS.md logging guideline).
 // Every line is tagged with its level: "[agent-loop] <level>: <message>".
 // info and debug go to stdout, warn and error to stderr; debug is shown only when
-// the --verbose gate is on. Warn and error lines are length-bounded so untrusted
-// content (for example a model echo in a validation error) cannot flood a line.
+// the --verbose gate is on. Every line is length-bounded so untrusted content
+// (for example a model echo in a validation error) cannot flood a line; logInfoFull
+// prints a trusted, user-facing note in full instead.
 const MAX_LENGTH = 300;
 
 let verbose = false;
@@ -31,8 +32,22 @@ export function logDebug(message) {
   }
 }
 
+function writeInfo(message) {
+  (stderrOnly ? console.error : console.log)(`[agent-loop] info: ${message}`);
+}
+
 export function logInfo(message) {
-  (stderrOnly ? console.error : console.log)(`[agent-loop] info: ${truncate(message)}`);
+  writeInfo(truncate(message));
+}
+
+/**
+ * Prints an info line in full, without the 300-character bound. A post-install
+ * note is trusted guidance the user must read to its last sentence, so the
+ * bound that keeps untrusted content from flooding an ordinary line does not
+ * apply.
+ */
+export function logInfoFull(message) {
+  writeInfo(message);
 }
 
 export function logWarn(message) {