@lucascouts/claude-agent-tui 0.1.0

package/dist/gate/settings-writer.js

@@ -0,0 +1,349 @@
+// Story 032 — safe settings.local.json hook writer (Degrau-2 §9 BLOCKER c).
+//
+// The Degrau-2 permission gate (HYBRID prototype, story 007 / GATE_FINDINGS.md) attaches a
+// `PreToolUse` type:http hook to the real `claude` TUI over TCP loopback. This module is the
+// REVERSIBLE, NON-DESTRUCTIVE config-mutation seam that injects that hook into `settings.local.json`
+// BEFORE the PTY spawns and restores the user's prior config on teardown — it owns NO server, no
+// deny/allow logic, and no engine wiring (those are separate Degrau-2 stories).
+//
+// HOOK SHAPE (authoritative — empirically FIRED against real claude 2.1.161; see GATE_FINDINGS.md
+// keystone + experiments/e-gate.ts `buildScratchSettings`):
+//   { hooks: { PreToolUse: [ { matcher, hooks: [ { type:"http", url, timeout } ] } ] } }
+// `timeout` is in SECONDS (claude default 600). The endpoint is a 127.0.0.1 TCP-loopback URL
+// carrying the dynamically allocated free port (story 032 Task 1 / R1) — a unix-socket URL is
+// silently ignored by claude (blocker b), so loopback TCP is mandatory.
+//
+// FORK-OWNED MARKER (so teardown can surgically remove ONLY our hook — Task 3.2 / R4.3): the hook's
+// `url` carries a fixed sentinel PATH segment ({@link FORK_HOOK_MARKER_PATH}). The URL is opaque to
+// claude (passed through verbatim), so this is a safe, parse-surviving identifier that never
+// collides with a user's own hook entry. We also stamp the matcher group with the same sentinel on a
+// dedicated `__forkAcpGate` key for human-readability; the URL path is the AUTHORITATIVE marker.
+//
+// Tasks 2.1 (buildHookEntry) + 2.2 (mergeHook) live here; the inject/restore seam (Task 3) is added
+// below them. The read side reuses `parseJsonc` from zed-register.ts (tolerant of a user's
+// hand-edited JSONC settings) rather than a parallel parser.
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { parseJsonc } from "../zed-register.js";
+/** Fixed fork-owned sentinel path segment embedded in the hook URL — the surgical-removal marker. */
+export const FORK_HOOK_MARKER_PATH = "/__fork-acp-gate__";
+/** Key stamped on the fork's matcher group for human-readability; the URL path is authoritative. */
+export const FORK_HOOK_MARKER_KEY = "__forkAcpGate";
+/** Default hook timeout in SECONDS (claude default is 600); kept a parameter so nothing is magic. */
+export const DEFAULT_HOOK_TIMEOUT_SECONDS = 600;
+/** Tool matcher for the gate hook; `"*"` matches all tools (the shape the story-007 probe fired). */
+export const FORK_HOOK_MATCHER = "*";
+/**
+ * Build the fork's `PreToolUse` `type:http` hook group, pointing at the 127.0.0.1 TCP-loopback
+ * endpoint for the dynamically allocated free port (R1 / R2.3). The URL carries the fork-owned
+ * sentinel path ({@link FORK_HOOK_MARKER_PATH}) so teardown can surgically remove ONLY this group.
+ *
+ * @param port the verified-free port from {@link import("./port.js").findFreePort} — a positive integer.
+ * @param timeout hook timeout in SECONDS (default {@link DEFAULT_HOOK_TIMEOUT_SECONDS}).
+ * @returns the `{ matcher, hooks:[{type:"http",…}], __forkAcpGate:true }` group.
+ * @throws {Error} if `port` is not a positive integer (a bad port would produce a malformed/ungated
+ *   hook — fail loud rather than silently emit a hook claude ignores).
+ */
+export function buildHookEntry(port, timeout = DEFAULT_HOOK_TIMEOUT_SECONDS) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`buildHookEntry: port must be a positive integer in 1..65535, got ${String(port)} — refusing ` +
+            `to build a malformed hook (claude would ignore it and the tool would run ungated).`);
+    }
+    return {
+        matcher: FORK_HOOK_MATCHER,
+        hooks: [
+            {
+                type: "http",
+                url: `http://127.0.0.1:${port}${FORK_HOOK_MARKER_PATH}`,
+                timeout,
+            },
+        ],
+        [FORK_HOOK_MARKER_KEY]: true,
+    };
+}
+/** True iff `group` is the FORK's own injected hook group (sentinel key OR sentinel URL path). */
+export function isForkHookGroup(group) {
+    if (typeof group !== "object" || group === null) {
+        return false;
+    }
+    const g = group;
+    if (g[FORK_HOOK_MARKER_KEY] === true) {
+        return true;
+    }
+    // Fall back to the authoritative URL-path marker (survives even if the sentinel key were stripped).
+    const hooks = g.hooks;
+    if (Array.isArray(hooks)) {
+        for (const h of hooks) {
+            if (h !== null &&
+                typeof h === "object" &&
+                typeof h.url === "string" &&
+                (h.url.includes(FORK_HOOK_MARKER_PATH))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Merge the fork hook `group` into an existing-or-absent settings object, preserving EVERY
+ * pre-existing key/value AND the user's own hooks (R2.1, R2.2, R2.4). Never mutates `prior`.
+ *
+ *   - `prior` null/absent  → return a minimal object containing ONLY the fork hook (R2.2).
+ *   - `prior` present      → deep-clone it, then APPEND the fork group to `hooks.PreToolUse`
+ *                            without dropping/overwriting any existing entry (R2.4). An existing
+ *                            fork group (idempotent re-inject) is replaced in place, not duplicated.
+ *
+ * @param prior the parsed prior settings object, or `null` if the file was absent.
+ * @param group the fork hook group from {@link buildHookEntry}.
+ * @returns a NEW settings object — a superset of `prior` differing only by the added fork hook.
+ * @throws {Error} if `prior` is a non-object (array/scalar) — a corrupt root is surfaced loudly, not
+ *   silently overwritten (R2.1: a corrupt user file is never clobbered blindly).
+ */
+export function mergeHook(prior, group) {
+    if (prior === null || prior === undefined) {
+        return { hooks: { PreToolUse: [structuredClone(group)] } };
+    }
+    if (typeof prior !== "object" || Array.isArray(prior)) {
+        throw new Error(`mergeHook: prior settings root must be a JSON object, got ${Array.isArray(prior) ? "array" : typeof prior}. ` +
+            `Refusing to overwrite a malformed settings.local.json (the user's config is never clobbered blindly).`);
+    }
+    const merged = structuredClone(prior);
+    if (typeof merged.hooks !== "object" || merged.hooks === null || Array.isArray(merged.hooks)) {
+        merged.hooks = {};
+    }
+    const hooks = merged.hooks;
+    if (!Array.isArray(hooks.PreToolUse)) {
+        hooks.PreToolUse = [];
+    }
+    // Drop any prior fork group (idempotent re-inject) but keep every user group, then append ours.
+    hooks.PreToolUse = hooks.PreToolUse.filter((g) => !isForkHookGroup(g));
+    hooks.PreToolUse.push(structuredClone(group));
+    return merged;
+}
+/**
+ * Parse settings text tolerantly (JSONC — a user may have hand-edited comments/trailing commas) into
+ * a {@link SettingsLike} object. Reuses zed-register's `parseJsonc`. A parse failure is surfaced as a
+ * clear error (NOT silently swallowed) so a corrupt user file is never clobbered blindly (R2.1).
+ *
+ * @param text the raw on-disk file contents.
+ * @returns the parsed object.
+ * @throws {Error} wrapping the underlying parse error with a clear, attributable message.
+ */
+export function parsePriorSettings(text) {
+    try {
+        const parsed = parseJsonc(text);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error(`parsed root is ${Array.isArray(parsed) ? "an array" : typeof parsed}, expected an object`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`parsePriorSettings: settings.local.json is not parseable JSON/JSONC (${reason}). Refusing to ` +
+            `clobber it blindly — the inject path must fall back to a safe handling of a corrupt file.`);
+    }
+}
+/**
+ * Durably write `text` to `filePath` via a temp-file + fsync + atomic `rename` so a reader (claude on
+ * startup) never observes a partial file (R3.2). On any failure the partial temp is removed before
+ * the error propagates, so a failed write leaves no half-written file behind.
+ */
+async function durableWrite(filePath, text) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(filePath)}.fork-tmp-${process.pid}-${Date.now()}`);
+    let handle = null;
+    try {
+        handle = await fs.open(tmp, "w");
+        await handle.writeFile(text, "utf8");
+        await handle.sync(); // flush the file's own bytes to disk before the rename
+        await handle.close();
+        handle = null;
+        await fs.rename(tmp, filePath); // atomic swap into place
+        // Best-effort fsync of the directory entry so the rename itself is durable.
+        try {
+            const dirHandle = await fs.open(dir, "r");
+            try {
+                await dirHandle.sync();
+            }
+            finally {
+                await dirHandle.close();
+            }
+        }
+        catch {
+            // Some platforms reject O_RDONLY dir fsync; the file fsync above is the load-bearing one.
+        }
+    }
+    catch (err) {
+        if (handle !== null) {
+            try {
+                await handle.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        try {
+            await fs.rm(tmp, { force: true });
+        }
+        catch {
+            // ignore — nothing durable to clean
+        }
+        throw err;
+    }
+}
+/** Read the prior file bytes, or `null` if it does not exist. Non-ENOENT errors propagate. */
+async function readPriorBytes(settingsPath) {
+    try {
+        return await fs.readFile(settingsPath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * Capture the prior on-disk state, compute the merged settings, and DURABLY write
+ * `settings.local.json` BEFORE the claude PTY is spawned (R3.1, R3.2, R4.1).
+ *
+ * CALLER CONTRACT (BLOCKER c — setup ordering): the spawn path MUST `await injectHook(...)` BEFORE it
+ * spawns the `claude` PTY, because `claude` reads hook config only at startup; a write that lands
+ * after spawn misses the first tool call. The engine-wiring that enforces this ordering is a separate
+ * Degrau-2 story (out of scope here — this module is the standalone seam).
+ * TODO(degrau-2 engine wiring): call `await injectHook(...)` in createSession BEFORE spawnPty, and
+ * `await restore(backup)` on session teardown. Tracked by the Degrau-2 engine-integration story.
+ *
+ * @param opts.settingsPath absolute path to the `settings.local.json` to mutate.
+ * @param opts.port the verified-free port from {@link import("./port.js").findFreePort} (R1).
+ * @param opts.timeout optional hook timeout in SECONDS (default {@link DEFAULT_HOOK_TIMEOUT_SECONDS}).
+ * @returns a {@link Backup} handle carrying the exact prior bytes (or absence) for {@link restore}.
+ * @throws {Error} if the prior file is unreadable for a reason other than absence, or if the merged
+ *   config cannot be written — on a write failure the prior bytes are restored (or the partial temp
+ *   deleted) before rejecting, so a failed inject never leaves a file claude could read half-written.
+ */
+export async function injectHook(opts) {
+    const { settingsPath, port, timeout } = opts;
+    // 1) Snapshot the prior state (bytes or absence) — captured BEFORE any mutation (R4.1).
+    const priorBytes = await readPriorBytes(settingsPath);
+    const backup = { settingsPath, existed: priorBytes !== null, priorBytes };
+    // 2) Compute the merged object from the prior (parsed tolerantly) + the fork hook.
+    const group = buildHookEntry(port, timeout);
+    let prior = null;
+    if (priorBytes !== null) {
+        const text = priorBytes.toString("utf8").trim();
+        // An empty existing file is treated as "no prior settings" rather than a parse error.
+        prior = text.length === 0 ? null : parsePriorSettings(text);
+    }
+    const merged = mergeHook(prior, group);
+    const out = `${JSON.stringify(merged, null, 2)}\n`;
+    // 3) Durably write BEFORE returning control to the spawn path (R3.1, R3.2). On failure, roll back
+    //    to the prior bytes (or delete a file we just created) so claude never reads a half-written file.
+    try {
+        await durableWrite(settingsPath, out);
+    }
+    catch (err) {
+        try {
+            if (backup.existed && backup.priorBytes !== null) {
+                await durableWrite(settingsPath, backup.priorBytes.toString("utf8"));
+            }
+            else {
+                await fs.rm(settingsPath, { force: true });
+            }
+        }
+        catch {
+            // best-effort rollback; surface the ORIGINAL write error below regardless
+        }
+        throw new Error(`injectHook: failed to write ${settingsPath} (${err instanceof Error ? err.message : String(err)}). ` +
+            `Rolled back to the prior on-disk state; refusing to leave a half-written settings.local.json.`);
+    }
+    return backup;
+}
+/** Rewrite the captured prior bytes, or delete the file if the backup recorded absence (R4.2). */
+async function applyBackup(backup) {
+    if (backup.existed && backup.priorBytes !== null) {
+        await durableWrite(backup.settingsPath, backup.priorBytes.toString("utf8"));
+    }
+    else {
+        await fs.rm(backup.settingsPath, { force: true });
+    }
+}
+/**
+ * Teardown: remove the fork's injected hook, leaving ZERO residue (R4.2, R4.3).
+ *
+ * Preferred path (`'surgical'`): re-read the current on-disk file; if it parses, delete ONLY the
+ * group bearing the fork-owned marker ({@link isForkHookGroup}) and re-write the rest — preserving
+ * any edits the user made AFTER inject. If removing the fork group empties `hooks.PreToolUse`/`hooks`,
+ * and the backup recorded absence (the fork created the file), the file is deleted so no empty husk
+ * is left behind.
+ *
+ * Fallback path (`'backup'`): if the current file is unparseable, or surgical isolation of the fork
+ * entry is not possible, restore the captured prior state — delete the file if it did not previously
+ * exist, else rewrite the exact prior bytes.
+ *
+ * @param backup the handle returned by {@link injectHook}.
+ * @returns which path ran, so the caller can log it (R4.3).
+ * @throws {Error} only if BOTH the surgical path AND the backup fallback fail — the message names the
+ *   underlying error so teardown never silently strands the fork hook.
+ */
+export async function restore(backup) {
+    // Re-read the CURRENT on-disk file (it may carry post-inject user edits).
+    let currentBytes;
+    try {
+        currentBytes = await readPriorBytes(backup.settingsPath);
+    }
+    catch {
+        currentBytes = null; // unreadable for a non-ENOENT reason → fall back to the backup
+    }
+    // If the file is gone, the desired end-state is already the backup's "absence" or prior bytes.
+    if (currentBytes === null) {
+        try {
+            await applyBackup(backup);
+            return { path: "backup" };
+        }
+        catch (err) {
+            throw new Error(`restore: file missing and backup re-apply failed (${err instanceof Error ? err.message : String(err)}).`);
+        }
+    }
+    // Try the SURGICAL path: parse, drop only the fork group, re-write the rest.
+    try {
+        const text = currentBytes.toString("utf8").trim();
+        const parsed = text.length === 0 ? {} : parsePriorSettings(text);
+        const next = structuredClone(parsed);
+        const hooks = next.hooks;
+        let removedSomething = false;
+        if (hooks && Array.isArray(hooks.PreToolUse)) {
+            const before = hooks.PreToolUse.length;
+            hooks.PreToolUse = hooks.PreToolUse.filter((g) => !isForkHookGroup(g));
+            removedSomething = hooks.PreToolUse.length < before;
+            if (hooks.PreToolUse.length === 0) {
+                delete hooks.PreToolUse;
+            }
+            if (Object.keys(hooks).length === 0) {
+                delete next.hooks;
+            }
+        }
+        // If, after removing the fork hook, the document is empty AND the file did not exist before
+        // inject (the fork created it), delete it so no empty `{}` husk is left as residue (R4.2).
+        if (!backup.existed && Object.keys(next).length === 0) {
+            await fs.rm(backup.settingsPath, { force: true });
+            return { path: "surgical" };
+        }
+        void removedSomething; // a no-op removal is still a valid surgical outcome (idempotent teardown)
+        await durableWrite(backup.settingsPath, `${JSON.stringify(next, null, 2)}\n`);
+        return { path: "surgical" };
+    }
+    catch {
+        // Surgical isolation impossible (unparseable / corrupt post-inject file) → backup fallback (R4.3).
+        try {
+            await applyBackup(backup);
+            return { path: "backup" };
+        }
+        catch (err) {
+            throw new Error(`restore: surgical removal failed AND backup fallback failed ` +
+                `(${err instanceof Error ? err.message : String(err)}). The fork hook may be stranded — manual ` +
+                `inspection of ${backup.settingsPath} is required.`);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
+import { runAcp } from "./acp-agent.js";
+import { resolveClaudePath } from "./claude-path.js";
+import { usageUpdateEnabled } from "./usage-env.js";
+import { liveDiffEnabled } from "./live-diff-env.js";
+import { liveSubagentWatchEnabled } from "./live-subagent-env.js";
+if (process.argv.includes("--cli")) {
+    const { spawn } = await import("node:child_process");
+    const args = process.argv.slice(2).filter((arg) => arg !== "--cli");
+    const child = spawn(process.env.CLAUDE_CODE_EXECUTABLE ?? resolveClaudePath(), args, {
+        stdio: "inherit",
+    });
+    const signals = process.platform === "win32"
+        ? ["SIGINT", "SIGTERM"]
+        : ["SIGINT", "SIGTERM", "SIGHUP"];
+    for (const sig of signals) {
+        process.on(sig, () => {
+            if (!child.killed)
+                child.kill(sig);
+        });
+    }
+    child.on("exit", (code, signal) => {
+        if (signal && process.platform !== "win32") {
+            // Remove our listener so re-raising actually terminates instead of
+            // re-entering the no-op handler, which would let us exit with code 0
+            // instead of the signal's conventional 128+N.
+            process.removeAllListeners(signal);
+            process.kill(process.pid, signal);
+        }
+        else {
+            process.exit(code ?? 1);
+        }
+    });
+    child.on("error", (err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}
+else {
+    // Apply env vars from the managed-policy tier before any SDK call so the
+    // SDK subprocess inherits them. Going through resolveSettings (vs. a raw
+    // read of managed-settings.json) also picks up MDM sources on macOS and
+    // HKLM/HKCU on Windows.
+    const policy = await resolveSettings({ settingSources: [] });
+    for (const [key, value] of Object.entries(policy.effective.env ?? {})) {
+        process.env[key] = value;
+    }
+    // stdout is used to send messages to the client
+    // we redirect everything else to stderr to make sure it doesn't interfere with ACP
+    console.log = console.error;
+    console.info = console.error;
+    console.warn = console.error;
+    console.debug = console.error;
+    process.on("unhandledRejection", (reason, promise) => {
+        console.error("Unhandled Rejection at:", promise, "reason:", reason);
+    });
+    // Story 042 (R1.1): the UNSTABLE usage_update notification now defaults ON — unset/empty (or any
+    // value other than the opt-out) → ON; opt OUT only via USAGE_UPDATE=0 / USAGE_UPDATE=false. This
+    // flips the story-038 default-OFF posture now that story 039's ZED-CLIENT-STUDY confirmed the
+    // user's Zed ACCEPTS+RENDERS usage_update by code; the per-session R8 reject latch still guards a
+    // client that rejects it. Parsed by the pure `usageUpdateEnabled` (src/usage-env.ts) so the truth
+    // table is unit-checkable; threaded through runAcp → AgentDeps → the agent.
+    const usageUpdate = usageUpdateEnabled();
+    // Story 034 (§9 / R3.3): the HYBRID permission gate is the v1 policy (PERMISSIONS.md §1), so the
+    // production bootstrap resolves it ON by default — `FORK_GATE=off` is the documented diagnostic
+    // escape hatch (and the R5 v1-no-gate fallback switch). With the gate OFF, createSession starts
+    // NO hook server, writes NO scratch settings, and the spawn argv carries no `--settings` — the
+    // ungated spawn is byte-for-byte pre-034. Any other value (absent, "1", "on", even "0") stays ON:
+    // for a safety gate the conservative direction is gated, so only the exact documented escape
+    // hatch disables it. Threaded through runAcp → AgentDeps → the agent (the usageUpdate pattern).
+    const gate = process.env.FORK_GATE !== "off";
+    // Story 043 (R2.2): the live Edit/Write diff now defaults ON — unset/empty (or any value other
+    // than the opt-out) → ON; opt OUT only via LIVE_DIFF=0 / LIVE_DIFF=false. With the PTY engine the
+    // PostToolUse hook that once produced diffs is gone, so the reduced-shape JSONL renders no diff
+    // until `toolUseResult` is hydrated by uuid (diff-enriched-reader.ts, FORK.md 4.2); defaulting ON
+    // restores the story-021 diff on BOTH the live pump and the session/load replay. OFF → byte-for-byte
+    // the pre-043 reduced reader. Parsed by the pure `liveDiffEnabled` (src/live-diff-env.ts) so the
+    // truth table is unit-checkable; threaded through runAcp → AgentDeps → the agent.
+    const liveDiff = liveDiffEnabled();
+    // Story 044 (R4.1): the live sub-agent watcher now defaults ON — unset/empty (or any value other
+    // than the opt-out) → ON; opt OUT only via FORK_LIVE_SUBAGENT_WATCH=0 / =false. It arms the
+    // Option-B 2nd watcher (a POLL of the SDK sidechain readers while a turn is in flight) so a
+    // long-running sub-agent — whose rows land in subagents/*.jsonl while the MAIN transcript stays
+    // silent — feeds the turn detector's noteActivity() seam and renders incrementally instead of
+    // false-stalling the story-024 watchdog (the story-041 R4.2 live gap). OFF → byte-for-byte today's
+    // pull-only path: NO 2nd watcher armed (R4.2). Parsed by the pure `liveSubagentWatchEnabled`
+    // (src/live-subagent-env.ts) so the truth table is unit-checkable; threaded through
+    // runAcp → AgentDeps → the agent.
+    const liveSubagentWatch = liveSubagentWatchEnabled();
+    const { connection, agent } = runAcp({ usageUpdate, gate, liveDiff, liveSubagentWatch });
+    async function shutdown() {
+        await agent.dispose().catch((err) => {
+            console.error("Error during cleanup:", err);
+        });
+        process.exit(0);
+    }
+    // Exit cleanly when the ACP connection closes (e.g. stdin EOF, transport
+    // error). Without this, `process.stdin.resume()` keeps the event loop
+    // alive indefinitely, causing orphan process accumulation in oneshot mode.
+    connection.closed.then(shutdown);
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+    // Keep process alive while connection is open
+    process.stdin.resume();
+}