@orchestrator-claude/definitions 3.30.2 → 3.31.0

package/hooks/mailbox-listener.ts

@@ -0,0 +1,246 @@
+/**
+ * mailbox-listener.ts — PostToolUse + SessionStart hook (RFC-025 v3.1)
+ *
+ * PostToolUse: Checks the agent's mailbox inbox after every tool call.
+ * SessionStart: Consumes inbox at session boot so agents start with context.
+ *
+ * Environment variables (set by WorktreeIsolator in sprint worktrees):
+ *   SPRINT_ID  — tmux session name (e.g., "sprint-cd213cab")
+ *   PANE_ROLE  — agent's mailbox address (e.g., "implementer-0")
+ *
+ * When NOT in a sprint (no env vars), exits silently with zero overhead.
+ *
+ * Message format: RFC-025 MessageEnvelope (Zod-validated JSON files).
+ * Consume semantics: read → validate → delete (FIFO order).
+ * Invalid files are moved to quarantine/ (not lost, not injected).
+ *
+ * SessionStart branch:
+ *   - Reads hook payload from stdin (JSON with hook_event_name)
+ *   - If hook_event_name === "SessionStart" → consume inbox and outputContext("SessionStart", ...)
+ *   - Backward compat: if process.stdin.isTTY → skip stdin read (PostToolUse path)
+ */
+
+import { readdirSync, readFileSync, unlinkSync, renameSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { log, outputContext } from "./lib/api-client.js";
+
+const HOOK = "MAILBOX-LISTENER";
+
+// --- Types (minimal, no Zod dependency in hooks) ---
+
+interface MailboxMessage {
+  id: string;
+  from: { role: string; index: number };
+  to: { role: string; index: number };
+  timestamp: string;
+  body: {
+    type: string;
+    taskId?: string;
+    title?: string;
+    description?: string;
+    summary?: string;
+    progress?: number;
+    message?: string;
+    errorCode?: string;
+    acceptanceCriteria?: string[];
+  };
+}
+
+// --- Stdin reader (same pattern as sprint-registry.ts) ---
+
+async function readStdinPayload(): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+// --- Core inbox consumption logic (shared between SessionStart and PostToolUse) ---
+
+function consumeInbox(
+  inboxPath: string,
+  quarantinePath: string,
+  paneRole: string,
+): { consumed: MailboxMessage[]; errors: string[] } {
+  // List .json files (exclude .tmp- in-flight writes)
+  let files: string[];
+  try {
+    files = readdirSync(inboxPath)
+      .filter((f) => f.endsWith(".json") && !f.startsWith(".tmp-"))
+      .sort(); // FIFO by filename (UUID-based, but sorted for determinism)
+  } catch {
+    return { consumed: [], errors: [] }; // Directory read error — fail silently
+  }
+
+  if (files.length === 0) {
+    return { consumed: [], errors: [] };
+  }
+
+  log(HOOK, `${files.length} message(s) in ${paneRole} inbox`);
+
+  const consumed: MailboxMessage[] = [];
+  const errors: string[] = [];
+
+  for (const file of files) {
+    const filePath = join(inboxPath, file);
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const parsed = JSON.parse(raw) as MailboxMessage;
+
+      // Basic validation (no Zod in hooks — keep deps minimal)
+      if (!parsed.id || !parsed.from || !parsed.to || !parsed.body?.type) {
+        throw new Error(`Invalid envelope: missing required fields`);
+      }
+
+      // Consume: delete after successful parse
+      unlinkSync(filePath);
+      consumed.push(parsed);
+      log(HOOK, `Consumed: ${parsed.id} (${parsed.body.type} from ${parsed.from.role}-${parsed.from.index})`);
+    } catch (err) {
+      // Quarantine malformed message
+      const errMsg = err instanceof Error ? err.message : String(err);
+      errors.push(`${file}: ${errMsg}`);
+      log(HOOK, `Quarantine: ${file} — ${errMsg}`);
+      try {
+        mkdirSync(quarantinePath, { recursive: true });
+        renameSync(filePath, join(quarantinePath, file));
+      } catch {
+        // Best-effort quarantine
+      }
+    }
+  }
+
+  return { consumed, errors };
+}
+
+// --- Context builder (shared between SessionStart and PostToolUse) ---
+
+function buildContext(
+  consumed: MailboxMessage[],
+  errors: string[],
+  paneRole: string,
+): string | null {
+  if (consumed.length === 0 && errors.length === 0) {
+    return null;
+  }
+
+  const parts: string[] = [
+    `[MAILBOX] ${consumed.length} new message(s) for ${paneRole}:`,
+  ];
+
+  for (const msg of consumed) {
+    const from = `${msg.from.role}-${msg.from.index}`;
+    parts.push("");
+    parts.push(`--- Message from ${from} (${msg.body.type}) ---`);
+
+    switch (msg.body.type) {
+      case "task_assignment":
+        parts.push(`Task: ${msg.body.taskId}`);
+        parts.push(`Title: ${msg.body.title}`);
+        if (msg.body.description) parts.push(`Description: ${msg.body.description}`);
+        if (msg.body.acceptanceCriteria?.length) {
+          parts.push(`Acceptance Criteria:`);
+          for (const ac of msg.body.acceptanceCriteria) {
+            parts.push(`  - ${ac}`);
+          }
+        }
+        break;
+
+      case "task_complete":
+        parts.push(`Task: ${msg.body.taskId}`);
+        parts.push(`Summary: ${msg.body.summary}`);
+        break;
+
+      case "status_update":
+        parts.push(`Task: ${msg.body.taskId}`);
+        parts.push(`Progress: ${msg.body.progress}%`);
+        parts.push(`Status: ${msg.body.message}`);
+        break;
+
+      case "error_report":
+        parts.push(`Error: ${msg.body.errorCode}`);
+        parts.push(`Message: ${msg.body.message}`);
+        if (msg.body.taskId) parts.push(`Task: ${msg.body.taskId}`);
+        break;
+
+      case "ping":
+        parts.push(`Ping received — respond with pong if appropriate.`);
+        break;
+
+      case "pong":
+        parts.push(`Pong received — heartbeat confirmed.`);
+        break;
+
+      default:
+        parts.push(`Type: ${msg.body.type}`);
+        parts.push(`Raw: ${JSON.stringify(msg.body)}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    parts.push("");
+    parts.push(`[MAILBOX-WARN] ${errors.length} malformed message(s) quarantined:`);
+    for (const e of errors) {
+      parts.push(`  - ${e}`);
+    }
+  }
+
+  return parts.join("\n");
+}
+
+// --- Main ---
+
+async function main(): Promise<void> {
+  const sprintId = process.env.SPRINT_ID;
+  const paneRole = process.env.PANE_ROLE;
+
+  // Not in a sprint — exit silently (zero overhead path)
+  if (!sprintId || !paneRole) {
+    return;
+  }
+
+  const inboxPath = `/tmp/${sprintId}/mailbox/${paneRole}/inbox`;
+  const quarantinePath = `/tmp/${sprintId}/mailbox/${paneRole}/quarantine`;
+
+  // No inbox directory — sprint may not have mailbox enabled
+  if (!existsSync(inboxPath)) {
+    return;
+  }
+
+  // Determine hook event: read stdin unless this is an interactive TTY (PostToolUse path)
+  let hookEventName: string | undefined;
+  if (!process.stdin.isTTY) {
+    try {
+      const payload = await readStdinPayload();
+      hookEventName = payload.hook_event_name as string | undefined;
+    } catch {
+      // Stdin read failure — fall through to PostToolUse behaviour
+    }
+  }
+
+  // Consume inbox
+  const { consumed, errors } = consumeInbox(inboxPath, quarantinePath, paneRole);
+
+  if (consumed.length === 0 && errors.length === 0) {
+    return;
+  }
+
+  // Build context string
+  const context = buildContext(consumed, errors, paneRole);
+  if (!context) {
+    return;
+  }
+
+  // Emit context with the appropriate hook event name
+  const effectiveEvent = hookEventName === "SessionStart" ? "SessionStart" : "PostToolUse";
+  outputContext(effectiveEvent, context);
+}
+
+void main();

package/hooks/pre-agent-dispatch.ts

@@ -0,0 +1,57 @@
+/**
+ * pre-agent-dispatch.ts — PreToolUse hook for Agent tool (RFC-027 Sprint 4)
+ *
+ * Warns when dispatching known agents without subagent_type.
+ * Non-blocking: always exits 0.
+ */
+
+import { log, readStdin, getField, outputContext } from "./lib/api-client.js";
+
+const HOOK = "PRE-AGENT-DISPATCH";
+
+const KNOWN_AGENTS = [
+  "implementer",
+  "planner",
+  "specifier",
+  "reviewer",
+  "task-generator",
+  "researcher",
+];
+
+const KNOWN_AGENTS_REGEX = new RegExp(
+  `\\b(${KNOWN_AGENTS.join("|")})\\b`,
+  "i"
+);
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  const toolInput = getField(stdin, "tool_input") || "";
+  const subagentType =
+    getField(stdin, "tool_input.subagent_type") ||
+    getField(stdin, "tool_input.subagentType") ||
+    "";
+
+  // If subagent_type is present, no warning needed
+  if (subagentType) {
+    log(HOOK, `Agent dispatched with subagent_type="${subagentType}", OK`);
+    return;
+  }
+
+  // Check if prompt mentions a known agent
+  const prompt =
+    getField(stdin, "tool_input.prompt") ||
+    getField(stdin, "tool_input.description") ||
+    (typeof toolInput === "string" ? toolInput : JSON.stringify(toolInput));
+
+  const match = prompt.match(KNOWN_AGENTS_REGEX);
+  if (match) {
+    const detected = match[1].toLowerCase();
+    outputContext(
+      HOOK,
+      `[WARN] Agent dispatched without subagent_type. Known agent detected: "${detected}". Add subagent_type for proper frontmatter loading.`
+    );
+    log(HOOK, `WARN: known agent "${detected}" without subagent_type`);
+  }
+}
+
+main().catch(() => process.exit(0));

package/hooks/sprint-registry.ts

@@ -0,0 +1,85 @@
+/**
+ * sprint-registry.ts — SessionStart self-registration hook (RFC-025 M4)
+ *
+ * Reads SPRINT_ID and PANE_ROLE from environment, then writes a registry
+ * entry to /tmp/sprint-<SPRINT_ID>/registry/<PANE_ROLE>.json.
+ *
+ * IMPORTANT: No imports from scripts/lib/ — uses raw Node.js fs only.
+ * This hook runs in isolated worktree environments where scripts/lib may
+ * not be available on the module resolution path.
+ *
+ * Hook input (stdin): Claude Code SessionStart JSON payload (ignored).
+ * Exit 0 always — registration failure must not block the session.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function log(msg: string): void {
+  process.stderr.write(`[sprint-registry] ${msg}\n`);
+}
+
+/** Read hook JSON payload from stdin (async, same pattern as api-client.ts). */
+async function readStdin(): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  const raw = Buffer.concat(chunks).toString('utf-8').trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+async function main(): Promise<void> {
+  // Read SessionStart payload from stdin — contains session_id
+  const stdin = await readStdin();
+  const sessionId = (stdin.session_id as string) ?? undefined;
+
+
+  // Read required env vars
+  const sprintId = process.env['SPRINT_ID'];
+  const paneRole = process.env['PANE_ROLE'];
+
+  if (!sprintId || !paneRole) {
+    log(`Skipping: SPRINT_ID=${sprintId ?? 'unset'} PANE_ROLE=${paneRole ?? 'unset'}`);
+    process.exit(0);
+  }
+
+  const registryDir = `/tmp/${sprintId}/registry`;
+  const entryPath = join(registryDir, `${paneRole}.json`);
+
+  const workflowId = process.env['WORKFLOW_ID'];
+
+  const entry: Record<string, unknown> = {
+    role: paneRole,
+    sprintId,
+    pid: process.pid,
+    registeredAt: new Date().toISOString(),
+    worktreePath: process.cwd(),
+  };
+
+  if (sessionId) {
+    entry.sessionId = sessionId;
+  }
+
+  if (workflowId) {
+    entry.workflowId = workflowId;
+  }
+
+  try {
+    mkdirSync(registryDir, { recursive: true });
+    writeFileSync(entryPath, JSON.stringify(entry, null, 2), 'utf-8');
+    log(`Registered ${paneRole} for sprint ${sprintId} (pid=${process.pid}, session=${sessionId ?? 'unknown'})`);
+  } catch (err) {
+    // Log but do not fail — registration is best-effort
+    log(`Registration failed: ${err}`);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/verification-before-completion.ts

@@ -0,0 +1,97 @@
+/**
+ * verification-before-completion.ts — PreToolUse[Bash] hook
+ *
+ * Injects a verification reminder when the model is about to run
+ * `git commit` or `git push`. Does NOT block — only adds context.
+ *
+ * Principle: Evidence before claims, always.
+ * Source: verification-before-completion skill (superpowers 5.0.7)
+ *
+ * Flow:
+ *   1. readStdin() → extract bash command
+ *   2. commandMatchesGitOp() → check for commit/push
+ *   3. If match → output allow + context reminder
+ *   4. If no match → silent pass-through (no output)
+ */
+
+import { log, readStdin, getField, outputPreToolUse } from "./lib/api-client.js";
+
+const HOOK = "VERIFICATION-REMINDER";
+
+// ─────────────────────────────────────────────────────────────
+// Dependency injection interface (enables testing without IO)
+// ─────────────────────────────────────────────────────────────
+
+export interface HookDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  output: (opts: { decision: "allow" | "deny"; reason?: string; context?: string }) => void;
+  log: (prefix: string, msg: string) => void;
+}
+
+const defaultDeps: HookDeps = {
+  readStdin,
+  output: outputPreToolUse,
+  log,
+};
+
+// ─────────────────────────────────────────────────────────────
+// Pure helpers (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns true when the bash command string contains a git commit or git push
+ * operation. Handles common variations: `git commit`, `git push`, multi-command
+ * pipelines (`&&`, `;`), and quoted forms.
+ */
+export function commandMatchesGitOp(command: string): boolean {
+  return /git\s+(commit|push)/.test(command);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Core logic (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+export async function mainWithDeps(deps: HookDeps): Promise<void> {
+  const { readStdin, output, log } = deps;
+
+  const stdin = await readStdin();
+
+  // Extract the bash command from the tool input envelope
+  const command =
+    (getField(stdin, "tool_input.command") as string | undefined) ||
+    (getField(stdin, "command") as string | undefined) ||
+    "";
+
+  if (!commandMatchesGitOp(command)) {
+    // Silent pass-through — not a git commit/push, nothing to do
+    log(HOOK, `PASS (no git op): ${command.slice(0, 60)}`);
+    return;
+  }
+
+  log(HOOK, `REMIND git op detected: ${command.slice(0, 80)}`);
+
+  // Allow the command but inject a verification reminder as context.
+  // This hook NEVER blocks — it only nudges the model to verify first.
+  output({
+    decision: "allow",
+    context: [
+      "[VERIFICATION-REMINDER] You are about to run a git commit/push.",
+      "Before proceeding, confirm:",
+      "  1. Tests pass — run the test command and paste the output.",
+      "  2. Lint clean — run the lint command and confirm 0 errors.",
+      "  3. Build succeeds — run the build command and confirm exit 0.",
+      "  4. All acceptance criteria have matching test evidence.",
+      "Evidence before claims. No shortcuts for verification.",
+    ].join("\n"),
+  });
+}
+
+// ─────────────────────────────────────────────────────────────
+// Entry point (production use)
+// ─────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
+}
+
+main().catch(() => process.exit(0));