@tech-leads-club/harness-toolkit 0.2.1

package/src/platform/process.ts

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+
+const TIMEOUT_EXIT_CODE = 124;
+
+export async function readStdinText(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runProcess(args: {
+  command: string[];
+  cwd?: string;
+  input?: string;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+}): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const [file, ...argv] = args.command;
+  if (file === undefined) {
+    return { exitCode: 0, stdout: "", stderr: "" };
+  }
+  return await new Promise((resolve, reject) => {
+    const child = spawn(file, argv, {
+      cwd: args.cwd,
+      stdio: ["pipe", "pipe", "pipe"] as const,
+      env: args.env ?? process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer =
+      args.timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+          }, args.timeoutMs);
+
+    child.stdout.on("data", (c: Buffer) => {
+      stdout += c.toString();
+    });
+    child.stderr.on("data", (c: Buffer) => {
+      stderr += c.toString();
+    });
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (timedOut) {
+        resolve({ exitCode: TIMEOUT_EXIT_CODE, stdout, stderr: `${stderr}\n(process timed out)` });
+        return;
+      }
+      resolve({ exitCode: code ?? 1, stdout, stderr });
+    });
+    if (args.input !== undefined) {
+      child.stdin.write(args.input);
+    }
+    child.stdin.end();
+  });
+}

package/src/platform/sanitize.ts

@@ -0,0 +1,23 @@
+const ALLOWED = /[A-Za-z0-9._-]/;
+const EMPTY_PLACEHOLDER = "_empty_";
+
+export function sanitizeSegment(input: string): string {
+  if (input.length === 0) {
+    return EMPTY_PLACEHOLDER;
+  }
+  let out = "";
+  for (const ch of input) {
+    if (ALLOWED.test(ch)) {
+      out += ch;
+      continue;
+    }
+    for (const byte of Buffer.from(ch, "utf8")) {
+      out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  return out;
+}
+
+export function normalizeSeparators(input: string): string {
+  return input.replace(/\\/g, "/");
+}

package/src/platform/screen.ts

@@ -0,0 +1,46 @@
+import { KV_WIDTH, type StatusLevel, type Style, SYMBOLS } from "./style.ts";
+
+export type Row = { label: string; value: string; level?: StatusLevel };
+
+export type Section = { title?: string; rows?: Row[]; lines?: string[] };
+
+export type Screen = {
+  title: string;
+  summary?: string[];
+  sections: Section[];
+  footer?: string;
+};
+
+// why: screens describe their content and never their paint, so spacing, colour and alignment are decided once.
+// A new screen can only emit this shape, which is what makes "no screen outside the standard" mechanical.
+export function render(screen: Screen, style: Style): string {
+  const out: string[] = [style.heading(screen.title.toUpperCase())];
+
+  if (screen.summary && screen.summary.length > 0) {
+    out.push(`   ${screen.summary.join(style.dim(` ${SYMBOLS.bar} `))}`);
+  }
+
+  const width = Math.max(
+    KV_WIDTH,
+    ...screen.sections.flatMap((section) => (section.rows ?? []).map((row) => row.label.length + 1)),
+  );
+
+  for (const section of screen.sections) {
+    out.push("");
+    if (section.title) {
+      out.push(style.paint("accent", section.title));
+    }
+    for (const row of section.rows ?? []) {
+      const value = row.level ? style.status(row.level, row.value) : row.value;
+      out.push(style.kv(row.label, value, width));
+    }
+    for (const line of section.lines ?? []) {
+      out.push(line === "" ? "" : `  ${line}`);
+    }
+  }
+
+  if (screen.footer) {
+    out.push("", style.footer(screen.footer));
+  }
+  return out.join("\n");
+}

package/src/platform/style.ts

@@ -0,0 +1,103 @@
+export const COLORS = {
+  structure: "#3d3a4a",
+  accent: "#a78bfa",
+  success: "#6ee7b7",
+  warning: "#d4a574",
+  error: "#f87171",
+  info: "#93c5fd",
+  textMain: "#f5f5f7",
+  textMuted: "#9ca3af",
+  textDim: "#6b7280",
+} as const;
+
+export const SYMBOLS = {
+  check: "✔",
+  cross: "✖",
+  warning: "⚠",
+  arrow: "→",
+  arrowRight: "▸",
+  dot: "•",
+  bar: "│",
+  rule: "══",
+  dash: "──",
+} as const;
+
+function rgb(hex: string): string {
+  const match = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex.trim());
+  if (!match) {
+    return "255;255;255";
+  }
+  return [match[1], match[2], match[3]].map((part) => Number.parseInt(part as string, 16)).join(";");
+}
+
+const ESC = String.fromCharCode(27);
+const RESET = `${ESC}[0m`;
+
+export type ColorName = keyof typeof COLORS;
+
+// hazard: the TTY check is load-bearing, not politeness. This CLI's output is redirected into files, quoted into
+// gate follow-ups and read by the repository's own checkers, and an escape reaching any of those already sent an
+// agent to fix `39msrc/…`, a file that does not exist.
+export function colorEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+  argv: readonly string[] = process.argv,
+  isTty: boolean = process.stdout.isTTY === true,
+): boolean {
+  if ("NO_COLOR" in env) {
+    return false;
+  }
+  if (argv.includes("--no-color")) {
+    return false;
+  }
+  return isTty;
+}
+
+export type StatusLevel = "ok" | "warn" | "fail" | "info";
+
+export type Style = {
+  paint: (name: ColorName, text: string) => string;
+  bold: (text: string) => string;
+  dim: (text: string) => string;
+  heading: (text: string) => string;
+  footer: (text: string) => string;
+  // why: one shape for a label/value row and one for a status line, so a new screen inherits the standard instead
+  // of inventing spacing ([/decisions/ad-063.md](/decisions/ad-063.md)).
+  kv: (label: string, value: string, width?: number) => string;
+  status: (level: StatusLevel, text: string) => string;
+  enabled: boolean;
+};
+
+const STATUS_COLOR: Record<StatusLevel, ColorName> = {
+  ok: "success",
+  warn: "warning",
+  fail: "error",
+  info: "info",
+};
+
+const STATUS_MARK: Record<StatusLevel, string> = {
+  ok: SYMBOLS.check,
+  warn: SYMBOLS.warning,
+  fail: SYMBOLS.cross,
+  info: SYMBOLS.arrowRight,
+};
+
+export const KV_WIDTH = 16;
+
+// why: truecolor written directly because this package has no runtime dependency and ships no binary
+// ([/decisions/ad-012.md](/decisions/ad-012.md)).
+export function createStyle(enabled = colorEnabled()): Style {
+  const wrap = (code: string, text: string) => (enabled ? `${ESC}[${code}m${text}${RESET}` : text);
+  const paint = (name: ColorName, text: string) => wrap(`38;2;${rgb(COLORS[name])}`, text);
+  return {
+    enabled,
+    paint,
+    bold: (text) => wrap("1", text),
+    dim: (text) => paint("textDim", text),
+    heading: (text) => paint("accent", `${SYMBOLS.rule} ${text} ${SYMBOLS.rule}`),
+    footer: (text) => paint("textDim", `${SYMBOLS.dash} ${text} ${SYMBOLS.dash}`),
+    kv: (label, value, width = KV_WIDTH) => `  ${paint("textMuted", `${label}:`.padEnd(width))} ${value}`,
+    status: (level, text) => `${paint(STATUS_COLOR[level], STATUS_MARK[level])} ${text}`,
+  };
+}
+
+export const PLAIN: Style = createStyle(false);

package/src/providers/claude/claude.capabilities.ts

@@ -0,0 +1,25 @@
+import type { ProviderCapabilities } from "../../contracts/index.ts";
+
+export function claudeCapabilities(): ProviderCapabilities {
+  return {
+    enforcesHooks: true,
+    askSupportedOn: ["tool.before", "shell.before", "mcp.before", "read.before"],
+    sessionEnv: false,
+    nativeLoopCounter: false,
+    dedicatedShellEvent: false,
+    toolInputRewrite: true,
+    toolOutputRewrite: true,
+    contextAtToolBefore: true,
+    contextAtToolAfter: true,
+    // why: `Stop` accepts `hookSpecificOutput.additionalContext` for feedback that continues the turn, which is
+    // exactly what a non-blocking gate advisory is.
+    contextAtStop: true,
+    // why: `SessionStart` delivers `hookSpecificOutput.additionalContext`, capped at 10,000 characters. Only that
+    // field — a top-level `additional_context` is read as well and not deduplicated, so emitting both injects twice.
+    sessionStartContextReliable: true,
+    toolOutputAtAfter: true,
+    usageInPayload: false,
+    effortSignal: true,
+    thoughtEvent: false,
+  };
+}

package/src/providers/claude/claude.detect.ts

@@ -0,0 +1,14 @@
+// why: Claude payloads use PascalCase hook_event_name + cwd/transcript_path; Cursor payloads don't.
+const PASCAL_CASE_EVENT_NAME = /^[A-Z][a-zA-Z0-9]*$/;
+
+export function detectClaude(raw: unknown): boolean {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return false;
+  }
+  const value = raw as Record<string, unknown>;
+  const eventName = value.hook_event_name;
+  if (typeof eventName !== "string" || !PASCAL_CASE_EVENT_NAME.test(eventName)) {
+    return false;
+  }
+  return typeof value.cwd === "string" || typeof value.transcript_path === "string";
+}

package/src/providers/claude/claude.inbound.ts

@@ -0,0 +1,252 @@
+import { isEffortLevel } from "../../contracts/effort.ts";
+import type { EffortLevel, HarnessEvent, HarnessEventKind } from "../../contracts/index.ts";
+import { sanitizeSegment } from "../../platform/sanitize.ts";
+
+const EVENT_KIND_BY_HOOK: Record<string, HarnessEventKind> = {
+  SessionStart: "session.start",
+  SessionEnd: "session.end",
+  UserPromptSubmit: "prompt.submit",
+  PostToolUseFailure: "tool.failure",
+  SubagentStart: "subagent.start",
+  SubagentStop: "subagent.stop",
+  Stop: "stop",
+  PreCompact: "compact.before",
+  MessageDisplay: "response.after",
+};
+
+const MCP_TOOL_NAME = /^mcp__/;
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function asStatus(value: unknown): "completed" | "aborted" | "error" | undefined {
+  return value === "completed" || value === "aborted" || value === "error" ? value : undefined;
+}
+
+function sessionKeyFor(raw: Record<string, unknown>): string {
+  const seed = asString(raw.session_id) ?? "default";
+  return `claude-${sanitizeSegment(seed)}`;
+}
+
+function projectDirFor(raw: Record<string, unknown>): string {
+  const envDir = process.env.CLAUDE_PROJECT_DIR;
+  if (envDir) {
+    return envDir;
+  }
+  const cwd = asString(raw.cwd);
+  if (cwd) {
+    return cwd;
+  }
+  return process.cwd();
+}
+
+function effortFor(raw: Record<string, unknown>): EffortLevel | undefined {
+  const effort = asRecord(raw.effort);
+  const level = effort?.level;
+  return isEffortLevel(level) ? level : undefined;
+}
+
+// why: PreToolUse fans out by tool_name — Claude has no dedicated shell/MCP/read event.
+function preToolUseKind(toolName: string | undefined): HarnessEventKind {
+  if (toolName === "Bash") {
+    return "shell.before";
+  }
+  if (toolName && MCP_TOOL_NAME.test(toolName)) {
+    return "mcp.before";
+  }
+  if (toolName === "Read") {
+    return "read.before";
+  }
+  return "tool.before";
+}
+
+function postToolUseKind(toolName: string | undefined): HarnessEventKind {
+  if (toolName === "Bash") {
+    return "shell.after";
+  }
+  if (toolName && MCP_TOOL_NAME.test(toolName)) {
+    return "mcp.after";
+  }
+  if (toolName === "Edit" || toolName === "Write") {
+    return "edit.after";
+  }
+  return "tool.after";
+}
+
+/** Never throws on a malformed payload — returns null instead. */
+export function claudeToEvent(raw: Record<string, unknown>): HarnessEvent | null {
+  const hookEventName = asString(raw.hook_event_name);
+  if (!hookEventName) {
+    return null;
+  }
+
+  const toolName = asString(raw.tool_name);
+  const toolInput = asRecord(raw.tool_input);
+
+  let eventKind: HarnessEventKind | undefined;
+  if (hookEventName === "PreToolUse") {
+    eventKind = preToolUseKind(toolName);
+  } else if (hookEventName === "PostToolUse") {
+    eventKind = postToolUseKind(toolName);
+  } else {
+    eventKind = EVENT_KIND_BY_HOOK[hookEventName];
+  }
+  if (!eventKind) {
+    return null;
+  }
+
+  const event: HarnessEvent = {
+    provider: "claude",
+    event: eventKind,
+    sessionKey: sessionKeyFor(raw),
+    projectDir: projectDirFor(raw),
+    raw,
+  };
+
+  const permissionMode = asString(raw.permission_mode);
+  if (permissionMode) {
+    event.permissionMode = permissionMode;
+  }
+
+  const isSpawnEvent = eventKind === "subagent.start" || eventKind === "subagent.stop";
+  const model = isSpawnEvent ? undefined : asString(raw.model);
+  if (model) {
+    event.model = model;
+  }
+  const effort = effortFor(raw);
+  if (effort) {
+    event.effort = effort;
+  }
+  const contextUsagePercent = asNumber(raw.context_usage_percent);
+  if (contextUsagePercent !== undefined) {
+    event.contextUsagePercent = contextUsagePercent;
+  }
+  const transcriptPath = asString(raw.transcript_path);
+  if (transcriptPath) {
+    event.transcriptPath = transcriptPath;
+  }
+  if (!isSpawnEvent) {
+    const callerAgentType = asString(raw.agent_type);
+    if (callerAgentType) {
+      event.subagentType = callerAgentType;
+    }
+  }
+
+  switch (eventKind) {
+    case "prompt.submit": {
+      const text = asString(raw.prompt);
+      if (text !== undefined) {
+        event.text = text;
+      }
+      break;
+    }
+    case "response.after": {
+      const text = asString(raw.text);
+      if (text !== undefined) {
+        event.text = text;
+      }
+      break;
+    }
+    case "shell.before":
+    case "shell.after": {
+      const command = toolInput ? asString(toolInput.command) : undefined;
+      if (command !== undefined) {
+        event.command = command;
+      }
+      break;
+    }
+    case "mcp.before":
+    case "mcp.after": {
+      if (toolName) {
+        event.toolName = toolName;
+      }
+      if (toolInput) {
+        event.toolInput = toolInput;
+      }
+      break;
+    }
+    case "read.before": {
+      const filePath = toolInput ? asString(toolInput.file_path) : undefined;
+      if (filePath !== undefined) {
+        event.filePath = filePath;
+      }
+      break;
+    }
+    case "edit.after": {
+      if (toolName) {
+        event.toolName = toolName;
+      }
+      const filePath = toolInput ? asString(toolInput.file_path) : undefined;
+      if (filePath !== undefined) {
+        event.filePath = filePath;
+      }
+      break;
+    }
+    case "tool.before":
+    case "tool.after":
+    case "tool.failure": {
+      if (toolName) {
+        event.toolName = toolName;
+      }
+      // why: an object here, unlike the two string fields Cursor uses. Serialising is the translation this layer
+      // exists to do, and core reads one shape ([/decisions/ad-004.md](/decisions/ad-004.md)).
+      const toolOutput = raw.tool_response;
+      if (toolOutput !== undefined && toolOutput !== null) {
+        event.toolOutput = typeof toolOutput === "string" ? toolOutput : JSON.stringify(toolOutput);
+      }
+      if (toolInput) {
+        event.toolInput = toolInput;
+      }
+      const filePath = toolInput ? asString(toolInput.file_path) : undefined;
+      if (filePath !== undefined) {
+        event.filePath = filePath;
+      }
+      const spawnSubagentType = toolInput ? asString(toolInput.subagent_type) : undefined;
+      if (spawnSubagentType) {
+        event.spawnSubagentType = spawnSubagentType;
+      }
+      const spawnModel = toolInput ? asString(toolInput.model) : undefined;
+      if (spawnModel) {
+        event.spawnModel = spawnModel;
+      }
+      break;
+    }
+    case "subagent.start":
+    case "subagent.stop": {
+      const spawnSubagentType =
+        asString(raw.agent_type) ??
+        asString(raw.subagent_type) ??
+        (toolInput ? asString(toolInput.subagent_type) : undefined);
+      if (spawnSubagentType) {
+        event.spawnSubagentType = spawnSubagentType;
+      }
+      const spawnModel = (toolInput ? asString(toolInput.model) : undefined) ?? asString(raw.model);
+      if (spawnModel) {
+        event.spawnModel = spawnModel;
+      }
+      break;
+    }
+    case "stop": {
+      const status = asStatus(raw.status);
+      if (status) {
+        event.status = status;
+      }
+      break;
+    }
+    default:
+      break;
+  }
+
+  return event;
+}

package/src/providers/claude/claude.lessons-view.ts

@@ -0,0 +1,33 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { projectConfigPath } from "../../platform/paths.ts";
+
+const IMPORT_LINE = "@.tlc/harness/lessons.md";
+
+// why: mirrors core/lesson/lesson.garden.ts's lessonsMarkdownPath — providers cannot import core, so the join is duplicated.
+export function claudeLessonsSourcePath(root: string): string {
+  return join(dirname(projectConfigPath(root)), "lessons.md");
+}
+
+export function claudeMdPath(root: string): string {
+  return join(root, "CLAUDE.md");
+}
+
+export function renderClaudeLessonsView(root: string): string | null {
+  if (!existsSync(claudeLessonsSourcePath(root))) {
+    return null;
+  }
+
+  const path = claudeMdPath(root);
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const alreadyImported = existing.split("\n").some((line) => line.trim() === IMPORT_LINE);
+  if (alreadyImported) {
+    return path;
+  }
+
+  const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  const content = existing.length > 0 ? `${existing}${separator}\n${IMPORT_LINE}\n` : `${IMPORT_LINE}\n`;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+  return path;
+}

package/src/providers/claude/claude.outbound.ts

@@ -0,0 +1,65 @@
+import type { Decision, HarnessEvent, HarnessEventKind, Rendered } from "../../contracts/index.ts";
+
+// why: Claude has no dedicated thought event (thoughtEvent: false) — this entry is never reached.
+const HOOK_EVENT_NAME_BY_KIND: Record<HarnessEventKind, string> = {
+  "session.start": "SessionStart",
+  "session.end": "SessionEnd",
+  "prompt.submit": "UserPromptSubmit",
+  "tool.before": "PreToolUse",
+  "tool.after": "PostToolUse",
+  "tool.failure": "PostToolUseFailure",
+  "shell.before": "PreToolUse",
+  "shell.after": "PostToolUse",
+  "mcp.before": "PreToolUse",
+  "mcp.after": "PostToolUse",
+  "read.before": "PreToolUse",
+  "edit.after": "PostToolUse",
+  "subagent.start": "SubagentStart",
+  "subagent.stop": "SubagentStop",
+  stop: "Stop",
+  "compact.before": "PreCompact",
+  "response.after": "MessageDisplay",
+  "thought.after": "MessageDisplay",
+};
+
+function renderPermission(
+  permissionDecision: "allow" | "deny" | "ask",
+  hookEventName: string,
+  reason: string | undefined,
+): string {
+  const hookSpecificOutput: Record<string, unknown> = { hookEventName, permissionDecision };
+  if (reason !== undefined) {
+    hookSpecificOutput.permissionDecisionReason = reason;
+  }
+  return JSON.stringify({ hookSpecificOutput });
+}
+
+export function claudeRender(decision: Decision, event: HarnessEvent): Rendered {
+  const hookEventName = HOOK_EVENT_NAME_BY_KIND[event.event];
+  switch (decision.kind) {
+    case "abstain":
+      return { stdout: null, exitCode: 0 };
+    case "allow":
+      return { stdout: renderPermission("allow", hookEventName, undefined), exitCode: 0 };
+    case "deny":
+      return { stdout: renderPermission("deny", hookEventName, decision.reason), exitCode: 0 };
+    case "ask":
+      return { stdout: renderPermission("ask", hookEventName, decision.reason), exitCode: 0 };
+    case "context":
+      return {
+        stdout: JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext: decision.text } }),
+        exitCode: 0,
+      };
+    case "continue":
+      return { stdout: JSON.stringify({ decision: "block", reason: decision.text }), exitCode: 0 };
+    case "rewriteInput":
+      return {
+        stdout: JSON.stringify({ hookSpecificOutput: { hookEventName, updatedInput: decision.input } }),
+        exitCode: 0,
+      };
+    default: {
+      const exhaustive: never = decision;
+      throw new Error(`unreachable decision kind: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}

package/src/providers/claude/claude.policy-defaults.ts

@@ -0,0 +1,9 @@
+import type { ProviderPolicyDefaults } from "../../contracts/index.ts";
+
+export function claudePolicyDefaults(): ProviderPolicyDefaults {
+  return {
+    blockedPatterns: [],
+    minEffort: null,
+    untrustedTools: ["WebFetch", "WebSearch"],
+  };
+}