@amsterdamdatalabs/enact-operator 0.1.2

package/runtime/hooks/subagents/subagent-tracker.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { rootDirFrom } from "../shared/root-dir.mjs";
+import { layoutPath } from "../shared/layout-dir.mjs";
+import { readHooksVerbose, verboseLog } from "../shared/_lib.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = join(__dirname, "..", "..", "..");
+const { isHookActive } = await import("@amsterdamdatalabs/enact-operator/hookGating");
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function appendLedger(root, entry) {
+  const dir = layoutPath(root, "logs");
+  mkdirSync(dir, { recursive: true });
+  const line = JSON.stringify({
+    schemaVersion: 1,
+    id: `ledger_${randomUUID().replace(/-/g, "").slice(0, 13)}`,
+    ...entry,
+    createdAt: new Date().toISOString(),
+  });
+  appendFileSync(layoutPath(root, "logs", "ledger.json"), line + "\n");
+}
+
+// CLI arg: "start" or "stop"
+const mode = process.argv[2];
+if (mode !== "start" && mode !== "stop") {
+  process.stdout.write(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+
+const payload = readStdin();
+const root = rootDirFrom(payload?.cwd ?? process.cwd());
+
+// ── Skill gate (team only) ────────────────────────────────────────────────────
+// Subagent tracking is only meaningful when a team lane is active.
+// In vanilla TUI mode or any non-team skill, exit immediately with noop.
+if (!isHookActive("subagent-tracker", root, payload)) {
+  process.stdout.write(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+const timestamp = new Date().toISOString();
+
+const agentId = payload?.agent_id ?? null;
+const task = payload?.task ?? null;
+const result = payload?.result ?? null;
+
+const isStart = mode === "start";
+const action = isStart ? "subagent_start" : "subagent_stop";
+const detail = isStart ? "Subagent spawned" : "Subagent completed";
+const hookEventName = isStart ? "SubagentStart" : "SubagentStop";
+
+// Log to hooks.log
+try {
+  mkdirSync(layoutPath(root, "logs"), { recursive: true });
+  appendFileSync(
+    layoutPath(root, "logs", "hooks.log"),
+    `${timestamp} ${hookEventName} agentId=${agentId ?? "unknown"} ${JSON.stringify(payload)}\n`,
+    "utf8",
+  );
+} catch {
+  // best-effort
+}
+
+// Append to ledger
+try {
+  appendLedger(root, {
+    kind: "session",
+    action,
+    detail,
+    actor: "enact-operator-hook",
+    metadata: {
+      agentId,
+      ...(isStart ? { task } : { result: typeof result === "string" ? result.slice(0, 200) : result }),
+    },
+  });
+} catch {
+  // best-effort
+}
+
+// Phase 2 — durable lifecycle + continuation / follow-up integration (compiled TS)
+try {
+  const { recordSubagentHookStart, recordSubagentHookStop } = await import(
+    "@amsterdamdatalabs/enact-operator/subagentRuntime",
+  );
+  if (isStart) {
+    recordSubagentHookStart(root, payload);
+  } else {
+    recordSubagentHookStop(root, payload);
+  }
+} catch {
+  // dist may be absent in partial checkouts; ledger + hooks.log still capture evidence
+}
+
+if (readHooksVerbose(root)) verboseLog("subagent-tracker", `${hookEventName} — agentId: ${agentId ?? "unknown"}`);
+process.stdout.write(JSON.stringify({ continue: true }));

package/runtime/hooks/tools/post-tool-use-failure.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { rootDirFrom } from "../shared/root-dir.mjs";
+import { layoutPath } from "../shared/layout-dir.mjs";
+import { emitHookFired, registerHookFailureTrap } from "../shared/observability.mjs";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = join(__dirname, "..", "..", "..");
+const {
+  recordContinuationFailure,
+  FAILURE_ESCALATION_THRESHOLD,
+  reserveContinuationEvent,
+  buildContinuationGuidance,
+} = await import("@amsterdamdatalabs/enact-operator/continuation");
+const {
+  enqueueContinuationFollowUp,
+  buildPostToolFailureDedupeKey,
+} = await import("@amsterdamdatalabs/enact-operator/continuationFollowUp");
+const { readOperatorAuthority } = await import("@amsterdamdatalabs/enact-operator/authority");
+const { isHookActive } = await import("@amsterdamdatalabs/enact-operator/hookGating");
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function appendLedger(root, entry) {
+  const dir = layoutPath(root, "logs");
+  mkdirSync(dir, { recursive: true });
+  const line = JSON.stringify({
+    schemaVersion: 1,
+    id: `ledger_${randomUUID().replace(/-/g, "").slice(0, 13)}`,
+    ...entry,
+    createdAt: new Date().toISOString(),
+  });
+  appendFileSync(layoutPath(root, "logs", "ledger.json"), line + "\n");
+}
+
+// Tools that are non-critical startup/memory reads — suppress output silently
+const OPTIONAL_STARTUP_TOOLS = new Set([
+  "Read",
+  "Glob",
+  "mcp__mempalace__mempalace_status",
+  "mcp__mempalace__mempalace_list_rooms",
+  "mcp__mempalace__mempalace_wakeup",
+  "mcp__enact_ctx__ctx_read",
+  "mcp__enact_ctx__ctx_session",
+  "mcp__enact_ctx__ctx_knowledge",
+  "mcp__plugin_oh-my-claudecode_t__project_memory_read",
+  "mcp__plugin_oh-my-claudecode_t__shared_memory_read",
+  "mcp__plugin_oh-my-claudecode_t__state_read",
+  "mcp__plugin_oh-my-claudecode_t__notepad_read",
+]);
+
+/**
+ * Exported check() for use by post-tool-use.mjs entry point.
+ * Records consecutive failures and returns a deny result when the
+ * FAILURE_ESCALATION_THRESHOLD is reached. Returns null to allow.
+ *
+ * @param {object} payload - Hook payload (tool_name, error etc.)
+ * @param {string} [rootOverride] - Optional workspace root (defaults to rootDir())
+ * @returns {object|null} deny result or null (allow)
+ */
+export async function check(payload, rootOverride) {
+  const root = rootOverride ?? rootDir();
+  const toolName = payload?.tool_name ?? "unknown";
+
+  // Only check escalation — diagnostics/logging are handled by the standalone path
+  let continuationState = null;
+  try {
+    const authority = readOperatorAuthority(root);
+    continuationState = recordContinuationFailure(root, authority, `post-tool-use-failure:${toolName}`);
+  } catch {
+    // best-effort
+  }
+  const failureEscalated = (continuationState?.consecutiveFailureCount ?? 0) >= FAILURE_ESCALATION_THRESHOLD;
+
+  if (failureEscalated) {
+    return {
+      decision: "block",
+      reason: `Runtime exec failed ${continuationState?.consecutiveFailureCount ?? FAILURE_ESCALATION_THRESHOLD} times this turn. Per loop-prevention guard, you must now write your best-effort answer using the information you already have. Manually re-implementing the flow's logic via shell commands is forbidden.`,
+    };
+  }
+
+  return null;
+}
+
+// ── Standalone script entry point (PostToolUseFailure event) ──────────────────
+// Only runs when executed directly (not imported as a module).
+export async function runHookScript(payload = readStdin()) {
+  const startedAt = Date.now();
+  const completeHook = registerHookFailureTrap({
+    payload,
+    hookEvent: "PostToolUseFailure",
+    startedAt,
+    toolName: payload?.tool_name ?? "unknown",
+  });
+  const root = rootDirFrom(payload?.cwd ?? process.cwd());
+
+  const toolName = payload?.tool_name ?? "unknown";
+
+  // ── Skill-gated: escalation check (ralph | team | ultrawork | autopilot) ────
+  // recordContinuationFailure and the deny path only run when an autonomous
+  // skill is active. Always-on: last-tool-error.json, ledger, hooks.log, obs.
+  const skillGateActive = isHookActive("post-tool-use-failure", root, payload);
+  let continuationState = null;
+  if (skillGateActive) {
+    try {
+      const authority = readOperatorAuthority(root);
+      continuationState = recordContinuationFailure(root, authority, `post-tool-use-failure:${toolName}`);
+    } catch {
+      // best-effort
+    }
+    const failureEscalated = (continuationState?.consecutiveFailureCount ?? 0) >= FAILURE_ESCALATION_THRESHOLD;
+    if (failureEscalated) {
+      try {
+        const authority = readOperatorAuthority(root);
+        const guidance = buildContinuationGuidance(authority);
+        const sid = typeof payload.session_id === "string" ? payload.session_id : null;
+        enqueueContinuationFollowUp(root, {
+          sessionId: sid,
+          dedupeKey: buildPostToolFailureDedupeKey({ sessionId: sid, toolName }),
+          trigger: "post-tool-failure",
+          lane: guidance.lane,
+          laneId: guidance.laneId,
+          prompt: `Escalated repeated failures on ${toolName}. ${guidance.resumeHint ?? ""}`.trim(),
+        });
+      } catch {
+        // best-effort
+      }
+    }
+  }
+  const failureEscalated = skillGateActive && (continuationState?.consecutiveFailureCount ?? 0) >= FAILURE_ESCALATION_THRESHOLD;
+
+  const rawError = payload?.error ?? payload?.tool_output?.error ?? String(payload?.tool_output ?? "");
+  const errorStr = typeof rawError === "string" ? rawError : JSON.stringify(rawError);
+  const inputPreview = JSON.stringify(payload?.tool_input ?? {}).slice(0, 200);
+  const timestamp = new Date().toISOString();
+
+  // Read existing error state to get retry count
+  const errorStatePath = layoutPath(root, "state", "last-tool-error.json");
+  const lastError = readJson(errorStatePath, { toolName: null, retryCount: 0 });
+  const retryCount = lastError.toolName === toolName ? (lastError.retryCount ?? 0) + 1 : 0;
+
+  // Write last-tool-error.json (always-on)
+  try {
+    writeJson(errorStatePath, {
+      toolName,
+      inputPreview,
+      error: errorStr.slice(0, 500),
+      retryCount,
+      timestamp,
+    });
+  } catch {
+    // best-effort
+  }
+
+  // Append to ledger (always-on)
+  try {
+    appendLedger(root, {
+      kind: "session",
+      action: "tool_failure",
+      detail: `Tool ${toolName} failed: ${errorStr.slice(0, 200)}`,
+      actor: "enact-operator-hook",
+      metadata: { toolName, retryCount },
+    });
+  } catch {
+    // best-effort
+  }
+
+  // Log to hooks.log (always-on)
+  try {
+    appendFileSync(
+      layoutPath(root, "logs", "hooks.log"),
+      `${timestamp} PostToolUseFailure tool=${toolName} retryCount=${retryCount} ${JSON.stringify(payload)}\n`,
+      "utf8",
+    );
+  } catch {
+    // best-effort
+  }
+
+  // Suppress output for optional startup tools
+  await emitHookFired({
+    payload,
+    hookEvent: "PostToolUseFailure",
+    outcome: "noop",
+    latencyMs: Date.now() - startedAt,
+    toolName,
+  });
+  completeHook();
+  if (OPTIONAL_STARTUP_TOOLS.has(toolName)) {
+    process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }));
+  } else if (failureEscalated) {
+    // Hard HALT: N consecutive failures reached — force synthesis, no further tool calls
+    process.stdout.write(
+      JSON.stringify({
+        decision: "block",
+        reason: `Runtime exec failed ${continuationState?.consecutiveFailureCount ?? FAILURE_ESCALATION_THRESHOLD} times this turn. Per loop-prevention guard, you must now write your best-effort answer using the information you already have. Manually re-implementing the flow's logic via shell commands is forbidden.`,
+      }),
+    );
+  } else {
+    const reservation = reserveContinuationEvent(root, {
+      key: [
+        "post-tool-use-failure",
+        toolName,
+        "normal",
+        errorStr.slice(0, 120),
+      ].join(":"),
+      source: "post-tool-use-failure",
+      ttlMs: 45_000,
+      metadata: { retryCount },
+    });
+    if (reservation.reserved) {
+      process.stdout.write(
+        JSON.stringify({
+          continue: true,
+          hookSpecificOutput: {
+            hookEventName: "PostToolUseFailure",
+            additionalContext: `Tool ${toolName} failed: ${errorStr.slice(0, 200)}`,
+          },
+        }),
+      );
+    } else {
+      process.stdout.write(JSON.stringify({ continue: true }));
+    }
+  }
+}
+
+const isMain = process.argv[1] === new URL(import.meta.url).pathname;
+if (isMain) {
+  await runHookScript();
+}

package/runtime/hooks/tools/post-tool-use.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { rootDirFrom } from "../shared/root-dir.mjs";
+import { layoutPath } from "../shared/layout-dir.mjs";
+import { emitHookFired, registerHookFailureTrap } from "../shared/observability.mjs";
+import { readHooksVerbose, verboseLog } from "../shared/_lib.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = join(__dirname, "..", "..", "..");
+const { readOperatorAuthority } = await import("@amsterdamdatalabs/enact-operator/authority");
+const { buildContinuationGuidance, continuationReminderThresholdForGuidance, formatMandatoryLocalContinuationContext, maybeRecordContinuationReminder, touchContinuationActivity } = await import("@amsterdamdatalabs/enact-operator/continuation");
+const { appendLedger } = await import("@amsterdamdatalabs/enact-operator/runtime");
+const { buildToolGuardHandlers, runToolGuards } = await import("../_toolGuards.mjs");
+
+const CONTINUATION_REMINDER_THRESHOLD = 25;
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function explicitExitCode(input) {
+  const candidate = input?.tool_output?.exit_code ?? input?.exit_code;
+  return Number.isInteger(candidate) ? candidate : null;
+}
+
+function extractToolOutput(input) {
+  const candidates = [
+    input?.tool_output?.output,
+    input?.tool_output?.stdout,
+    input?.tool_output?.stderr,
+    input?.output,
+    input?.err,
+  ];
+  const match = candidates.find((value) => typeof value === "string" && value.length > 0);
+  return typeof match === "string" ? match : "";
+}
+
+function recordFailureDiagnostics(root, payload, status) {
+  const stateDir = layoutPath(root, "state");
+  const logsDir = layoutPath(root, "logs");
+  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(logsDir, { recursive: true });
+
+  const command = payload?.tool_input?.command ?? "unknown command";
+  const toolUseId = payload?.tool_use_id;
+  const detail = `Bash command failed with exit code ${status}`;
+  const timestamp = new Date().toISOString();
+
+  const inboxPath = layoutPath(root, "state", "inbox.json");
+  const inbox = readJson(inboxPath, []);
+  inbox.push({
+    id: `inbox_${randomUUID().slice(0, 12)}`,
+    kind: "failed",
+    subject: detail,
+    body: command,
+    status: "open",
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  });
+  writeJson(inboxPath, inbox);
+
+  appendLedger(root, {
+    kind: "session",
+    action: "bash_command_failed",
+    detail,
+    actor: "enact-operator-hook",
+    metadata: {
+      command,
+      exitCode: status,
+      toolName: payload?.tool_name ?? null,
+      toolUseId: toolUseId ?? null,
+    },
+  });
+}
+
+const payload = readStdin();
+const startedAt = Date.now();
+const completeHook = registerHookFailureTrap({
+  payload,
+  hookEvent: "PostToolUse",
+  startedAt,
+  toolName: payload?.tool_name ?? "Bash",
+});
+const root = rootDirFrom(payload?.cwd ?? process.cwd());
+mkdirSync(layoutPath(root, "logs"), { recursive: true });
+
+const status = explicitExitCode(payload);
+
+// ── Doom-loop prevention: failure escalation guard ────────────────────────────
+// Only runs when the tool actually failed (non-zero exit code), matching the
+// original PostToolUseFailure event semantics.
+if (status !== null && status !== 0) {
+  const { check: failureCheck } = await import("./post-tool-use-failure.mjs");
+  const failResult = await failureCheck(payload, root);
+  if (failResult?.decision === "deny") {
+    await emitHookFired({
+      payload,
+      hookEvent: "PostToolUse",
+      outcome: "denied",
+      latencyMs: Date.now() - startedAt,
+      toolName: payload?.tool_name ?? "Bash",
+    });
+    completeHook({ blocked: true });
+    process.stdout.write(JSON.stringify(failResult));
+    process.exit(0);
+  }
+}
+touchContinuationActivity(root, `post-tool-use:${payload?.tool_name ?? "unknown"}`);
+appendFileSync(
+  layoutPath(root, "logs", "hooks.log"),
+  `${new Date().toISOString()} PostToolUse status=${status ?? "unknown"} ${JSON.stringify(payload)}\n`,
+  "utf8",
+);
+
+const output = { continue: true };
+let continuationReminder = null;
+try {
+  const authority = readOperatorAuthority(root);
+  const guidance = buildContinuationGuidance(authority);
+  const reminderThreshold = continuationReminderThresholdForGuidance(guidance, CONTINUATION_REMINDER_THRESHOLD);
+  const mandatoryContinuation = formatMandatoryLocalContinuationContext(guidance, "using more Bash turns");
+  const reminder = maybeRecordContinuationReminder(root, authority, "post-tool-use", reminderThreshold);
+  if (reminder.remind && reminder.state.resumeHint) {
+    continuationReminder =
+      [
+        `Operator reminder: no lifecycle, task, or proof progress was recorded in the last ${reminderThreshold} Bash turns.`,
+        mandatoryContinuation ?? reminder.state.resumeHint,
+      ].filter(Boolean).join(" ");
+  }
+} catch {
+  continuationReminder = null;
+}
+if (status !== null && status !== 0) {
+  recordFailureDiagnostics(root, payload, status);
+  output.hookSpecificOutput = {
+    hookEventName: "PostToolUse",
+    additionalContext: [
+      "Operator noticed a failing Bash command. Check .enact/operator inbox/ledger diagnostics.",
+      continuationReminder,
+    ].filter(Boolean).join(" "),
+  };
+} else if (continuationReminder) {
+  output.hookSpecificOutput = {
+    hookEventName: "PostToolUse",
+    additionalContext: continuationReminder,
+  };
+}
+await emitHookFired({
+  payload,
+  hookEvent: "PostToolUse",
+  outcome: "noop",
+  latencyMs: Date.now() - startedAt,
+  toolName: payload?.tool_name ?? "Bash",
+  extraPayload: {
+    status: status ?? "unknown",
+  },
+});
+// ── Tool-guard suite (PostToolUse context protection) ─────────────────────────
+try {
+  const guardResult = await runToolGuards({
+    toolName: payload?.tool_name ?? "Bash",
+    output: extractToolOutput(payload),
+    exitCode: status ?? 0,
+    workingDirectory: payload?.cwd ?? process.cwd(),
+  });
+  const guardContext = guardResult?.hookSpecificOutput?.additionalContext;
+  if (guardContext) {
+    const existing = output.hookSpecificOutput?.additionalContext ?? "";
+    output.hookSpecificOutput = {
+      ...(output.hookSpecificOutput ?? {}),
+      hookEventName: "PostToolUse",
+      additionalContext: [existing, guardContext].filter(Boolean).join(" "),
+    };
+  }
+} catch {
+  // guard suite failures are non-fatal; continue with existing output
+}
+
+if (readHooksVerbose(root)) {
+  const toolLabel = payload?.tool_name ?? "Bash";
+  const statusLabel = status === null ? "no exit code" : status === 0 ? "exit 0" : `exit ${status}`;
+  verboseLog("post-tool-use", `${toolLabel} completed — ${statusLabel}`);
+}
+completeHook();
+process.stdout.write(JSON.stringify(output));