@fusengine/harness 0.1.90 → 0.1.92

package/src/codex-rules/rules/rm-variants.ts

@@ -0,0 +1,58 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * `rm` prefix rules — hand-mapped from `security.ts`'s two `rm -rf`-family
+ * CRITICAL_PATTERNS labels. Both source regexes accept `-rf`/`-fr` combined
+ * or `-r -f`/`-f -r` split flags, so each label needs 3 prefix_rule variants
+ * (combined flag + 2 split-flag orders) to avoid a flag-order gap.
+ */
+export const RM_VARIANT_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of / or ~",
+    pattern: ["rm", ["-rf", "-fr"], ["/", "~"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of the filesystem root or home directory.",
+    match: ["rm -rf /", "rm -fr ~"],
+    notMatch: ["rm -rf /tmp/build"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of / or ~",
+    pattern: ["rm", "-r", "-f", ["/", "~"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of the filesystem root or home directory (split flags).",
+    match: ["rm -r -f /", "rm -r -f ~"],
+    notMatch: ["rm -r -f /tmp/build"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of / or ~",
+    pattern: ["rm", "-f", "-r", ["/", "~"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of the filesystem root or home directory (split flags, reversed).",
+    match: ["rm -f -r /", "rm -f -r ~"],
+    notMatch: ["rm -f -r /tmp/build"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of a system directory",
+    pattern: ["rm", ["-rf", "-fr"], ["/etc", "/usr", "/var", "/bin", "/sbin", "/boot", "/lib"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of a core system directory.",
+    match: ["rm -rf /etc", "rm -fr /usr"],
+    notMatch: ["rm -rf /home/user/project"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of a system directory",
+    pattern: ["rm", "-r", "-f", ["/etc", "/usr", "/var", "/bin", "/sbin", "/boot", "/lib"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of a core system directory (split flags).",
+    match: ["rm -r -f /var", "rm -r -f /bin"],
+    notMatch: ["rm -r -f /home/user"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: recursive delete of a system directory",
+    pattern: ["rm", "-f", "-r", ["/etc", "/usr", "/var", "/bin", "/sbin", "/boot", "/lib"]],
+    decision: "forbidden",
+    justification: "Recursive force-delete of a core system directory (split flags, reversed).",
+    match: ["rm -f -r /sbin", "rm -f -r /lib"],
+    notMatch: ["rm -f -r /tmp"],
+  },
+];

package/src/codex-rules/rules/single-commands.ts

@@ -0,0 +1,57 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * Single-purpose destructive binaries — hand-mapped 1:1 from `security.ts`'s
+ * `chmod 777 on /`, `shred`, `fdisk` CRITICAL_PATTERNS labels. `mkfs`,
+ * `dd`, and `diskutil erase` live in their own files (`mkfs.ts`, `dd.ts`,
+ * `diskutil.ts`) — each needed a wider case/variant enumeration than fits
+ * this file's SRP scope. The root-chmod rule needs the same flag-order
+ * alternation as `chmod-ask.ts` — source security.ts accepts flags before
+ * `777` for the root case too (`chmod -R 777 /` is still CRITICAL there).
+ */
+export const SINGLE_COMMAND_RULES: CodexPrefixRule[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777 on /",
+    pattern: ["chmod", "777", "/"],
+    decision: "forbidden",
+    justification: "World-writable permissions on the filesystem root.",
+    match: ["chmod 777 /"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777 on /",
+    pattern: ["chmod", "-R", "777", "/"],
+    decision: "forbidden",
+    justification: "World-writable permissions on the filesystem root, recursive.",
+    match: ["chmod -R 777 /"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777 on /",
+    pattern: ["chmod", "-r", "777", "/"],
+    decision: "forbidden",
+    justification: "World-writable permissions on the filesystem root, recursive (lowercase flag).",
+    match: ["chmod -r 777 /"],
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: chmod 777 on /",
+    pattern: ["chmod", "-v", "777", "/"],
+    decision: "forbidden",
+    justification: "World-writable permissions on the filesystem root, verbose flag.",
+    match: ["chmod -v 777 /"],
+  },
+  {
+    sourceLabel: "CRITICAL: Detected dangerous command 'shred'",
+    pattern: ["shred"],
+    decision: "forbidden",
+    justification: "Irreversibly overwrites file contents.",
+    match: ["shred -u secrets.txt"],
+    notMatch: ["cat secrets.txt"],
+  },
+  {
+    sourceLabel: "CRITICAL: Detected dangerous command 'fdisk'",
+    pattern: ["fdisk"],
+    decision: "forbidden",
+    justification: "Edits disk partition tables.",
+    match: ["fdisk /dev/sda"],
+    notMatch: ["cat /proc/partitions"],
+  },
+];

package/src/codex-rules/skip-list.ts

@@ -0,0 +1,25 @@
+import type { CodexSkipEntry } from "./types";
+
+/**
+ * `security.ts` labels with NO argv-prefix equivalent. Every entry here is
+ * shell syntax (pipes, redirection, function-definition syntax) that never
+ * appears as a plain argv token when a command is exec'd without a shell —
+ * Codex execpolicy's `prefix_rule` cannot express them. Covered instead by
+ * `sandbox_mode`/`approval_policy`. Never drop a label silently: it is
+ * either a prefix_rule (see `rules/`) or an entry here.
+ */
+export const SKIP_LIST: CodexSkipEntry[] = [
+  {
+    sourceLabel: "DANGEROUS PATTERN: fork bomb",
+    reason:
+      "Shell function-definition syntax `:(){ :|:& };:` is not a single argv invocation — no prefix_rule can express it.",
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: redirect to a raw disk device",
+    reason: "`>`/`>>` redirection to /dev/sda is shell syntax, invisible to argv-prefix matching.",
+  },
+  {
+    sourceLabel: "DANGEROUS PATTERN: write to /etc",
+    reason: "`>`/`>>` redirection into /etc/* is shell syntax, invisible to argv-prefix matching.",
+  },
+];

package/src/codex-rules/starlark.ts

@@ -0,0 +1,46 @@
+import type { CodexPrefixRule } from "./types";
+
+/**
+ * Neutralize characters that would break out of a Starlark `#` line comment
+ * (a bare `\n`/`\r` in an interpolated label/reason would start a new line
+ * no longer prefixed by `#`, corrupting the generated file).
+ */
+export function sanitizeComment(text: string): string {
+  return text.replace(/[\r\n]+/g, " ");
+}
+
+/** Render a string array as a Starlark list literal (double-quoted strings). */
+function starlarkList(values: string[]): string {
+  return `[${values.map((v) => JSON.stringify(v)).join(", ")}]`;
+}
+
+/** Render one pattern element: a bare token, or a `[...]` alternation. */
+function starlarkPatternElement(el: string | string[]): string {
+  return Array.isArray(el) ? starlarkList(el) : JSON.stringify(el);
+}
+
+/**
+ * Render a single `CodexPrefixRule` as a Starlark `prefix_rule(...)` call,
+ * prefixed by a traceability comment pointing back at its `security.ts` label.
+ */
+export function renderPrefixRule(rule: CodexPrefixRule): string {
+  const pattern = `[${rule.pattern.map(starlarkPatternElement).join(", ")}]`;
+  const lines = [
+    `# source: security.ts label "${sanitizeComment(rule.sourceLabel)}"`,
+    "prefix_rule(",
+    `    pattern = ${pattern},`,
+    `    decision = "${rule.decision}",`,
+    `    justification = ${JSON.stringify(rule.justification)},`,
+    `    match = ${starlarkList(rule.match)},`,
+  ];
+  if (rule.notMatch && rule.notMatch.length > 0) {
+    lines.push(`    not_match = ${starlarkList(rule.notMatch)},`);
+  }
+  lines.push(")");
+  return lines.join("\n");
+}
+
+/** Render a list of rules, each block separated by a blank line. */
+export function renderPrefixRules(rules: CodexPrefixRule[]): string {
+  return rules.map(renderPrefixRule).join("\n\n");
+}

package/src/codex-rules/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Types for the Codex execpolicy `.rules` (Starlark) generator.
+ * Verified contract (openai/codex `codex-rs/execpolicy/README.md` +
+ * learn.chatgpt.com/docs/agent-configuration/rules): `prefix_rule(pattern,
+ * decision, justification?, match?, not_match?)`; decisions are
+ * allow < prompt < forbidden (strictest wins across matching rules);
+ * `match`/`not_match` are validated as inline unit tests at file-load time.
+ */
+
+/** Codex execpolicy decision severity. */
+export type CodexDecision = "allow" | "prompt" | "forbidden";
+
+/**
+ * One argv-prefix rule, hand-mapped from a single `security.ts`
+ * `LabeledPattern`. `pattern` entries are exact argv tokens; a nested
+ * array element means "any of these tokens at this position" (Codex
+ * execpolicy alternation) — never a mechanical regex-to-prefix derivation.
+ */
+export interface CodexPrefixRule {
+  /** Exact `label` string from `CRITICAL_PATTERNS`/`ASK_PATTERNS` this rule maps to. */
+  sourceLabel: string;
+  /** Argv-prefix tokens; an element may be `string[]` for alternation. */
+  pattern: (string | string[])[];
+  decision: CodexDecision;
+  justification: string;
+  /** Example invocations that must satisfy this rule (validated at load time). */
+  match: string[];
+  /** Example invocations that must NOT satisfy this rule (validated at load time). */
+  notMatch?: string[];
+}
+
+/** A `security.ts` label with no argv-prefix equivalent — named, never dropped silently. */
+export interface CodexSkipEntry {
+  sourceLabel: string;
+  reason: string;
+}

package/src/config/dotenv.ts

@@ -0,0 +1,55 @@
+/**
+ * Native .env loader. Ports the claude-plugins `services/env-file.ts`
+ * (`loadEnvFile`) into the engine so a hook run hydrates `process.env` from the
+ * harness home `.env` (`~/.claude/.env`, `~/.codex/.env`, …) plus the project
+ * `<cwd>/.env`, instead of relying on Bun auto-dotenv or `BASH_ENV`. A value
+ * already present in the environment always wins (the file never overwrites it).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { harnessHome } from "./home-dir";
+import type { HarnessId } from "../detect/harness";
+
+/** Home config dir holding the `.env` for each harness (defaults to `.claude`). */
+export const HOME_DIR: Partial<Record<HarnessId, string>> = {
+  "claude-code": ".claude", codex: ".codex", cursor: ".cursor",
+  cline: ".clinerules", "gemini-cli": ".gemini", opencode: ".opencode",
+  hermes: ".hermes", kimi: ".kimi-code",
+};
+
+/** Parse a `.env` file into a key→value map (`export KEY="v"` or `KEY=v`). */
+export function parseEnvFile(path: string): Record<string, string> {
+  if (!existsSync(path)) return {};
+  let content = "";
+  try { content = readFileSync(path, "utf-8"); } catch { return {}; }
+  const out: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/)) {
+    if (line.trimStart().startsWith("#")) continue;
+    const m = line.match(/^\s*(?:export\s+)?(\w+)\s*=\s*["']?([^"'\n]*)["']?\s*$/);
+    if (m?.[1]) out[m[1]] = m[2] ?? "";
+  }
+  return out;
+}
+
+/** The `.env` paths probed for a harness: home `.env` then `<cwd>/.env`. */
+export function envCandidates(id: HarnessId, home: string = homedir(), cwd: string = process.cwd()): string[] {
+  return [join(harnessHome(id, process.env, home), ".env"), join(cwd, ".env")];
+}
+
+/**
+ * Load `.env` files into `env` without overwriting existing keys. Reads the
+ * harness home `.env` then `<cwd>/.env`. Best-effort (missing/unreadable files
+ * are skipped) so a hook never fails on env loading.
+ * @param id - Detected harness id (selects the home dir).
+ * @param env - Target environment (defaults to `process.env`).
+ * @param home - Home dir.
+ * @param cwd - Project root.
+ */
+export function loadDotenv(id: HarnessId, env: NodeJS.ProcessEnv = process.env, home: string = homedir(), cwd: string = process.cwd()): void {
+  for (const path of envCandidates(id, home, cwd)) {
+    for (const [k, v] of Object.entries(parseEnvFile(path))) {
+      if (env[k] === undefined) env[k] = v;
+    }
+  }
+}

package/src/config/env.ts

@@ -0,0 +1,10 @@
+/**
+ * Robust integer-from-env parser.
+ * undefined / empty / whitespace / NaN / float / <= 0 all fall back to `fallback`.
+ * `Number("")` is 0, so the empty guard is required before `Number()`.
+ */
+export function parseEnvInt(raw: string | undefined, fallback: number): number {
+  if (!raw?.trim()) return fallback;
+  const n = Number(raw.trim());
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}

package/src/config/home-dir.ts

@@ -0,0 +1,36 @@
+/**
+ * Harness home-dir resolution with env overrides. `dotenv.ts`'s static
+ * `HOME_DIR` table knows every harness's default config dir but cannot move
+ * with the user's data root — Kimi Code CLI documents `KIMI_CODE_HOME` for
+ * exactly that (isolated data roots get isolated skills/agents/hooks), so the
+ * override is honored here instead of hardcoding `~/.kimi-code`.
+ *
+ * Deliberately consumed only where a USER-HOME path is built (`envCandidates`
+ * today): `harnessHomeSegment` (`policy/apex-target.ts`) also serves
+ * project-relative joins (`<project>/.kimi-code/apex`), which an absolute
+ * override would corrupt — those sites stay segment-based.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { HarnessId } from "../detect/harness";
+import { HOME_DIR } from "./dotenv";
+
+/** Documented env var relocating a harness home dir, when one exists. */
+const HOME_ENV: Partial<Record<HarnessId, string>> = { kimi: "KIMI_CODE_HOME" };
+
+/**
+ * Resolve a harness's home config dir as an absolute path.
+ * @param id - Harness id.
+ * @param env - Environment (defaults to `process.env`).
+ * @param home - OS home dir (injectable for tests).
+ * @returns The override path when set, else `join(home, HOME_DIR[id])`.
+ */
+export function harnessHome(
+  id: string,
+  env: Record<string, string | undefined> = process.env,
+  home: string = homedir(),
+): string {
+  const key = HOME_ENV[id as HarnessId];
+  const override = key ? env[key] : undefined;
+  return override ?? join(home, HOME_DIR[id as HarnessId] ?? ".claude");
+}

package/src/config/index.ts

@@ -0,0 +1,5 @@
+export * from "./env";
+export * from "./ttl";
+export * from "./limits";
+export * from "./layout";
+export * from "./dotenv";

package/src/config/layout.ts

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+
+/** Top-level project state dir — neutral + harness-agnostic (not `.claude/…`). */
+export const STATE_ROOT = ".harness";
+
+/**
+ * The selective `.gitignore` for `.harness/`: ignore the machine-local session
+ * state (track, cache, throttle) but keep the curated `memory/LESSON.md`.
+ */
+export const STATE_GITIGNORE = "track/\ncache/\nmemory/state.json\n";
+
+/** Every project-state path the package uses, derived from one project root. */
+export interface ProjectLayout {
+  root: string;
+  /** `<root>/.harness` — the single state dir. */
+  stateDir: string;
+  /** `<root>/.harness/track` — session track files. */
+  trackDir: string;
+  /** `<root>/.harness/cache` — MCP/WebFetch cache. */
+  cacheDir: string;
+  /** `<root>/.harness/memory` — lessons + throttle. */
+  memoryDir: string;
+  /** `<root>/.harness/memory/LESSON.md` — curated, committable. */
+  lessonsFile: string;
+  /** `<root>/.harness/memory/state.json` — machine-local throttle. */
+  memoryStateFile: string;
+  /** `<root>/.harness/track/solid-notice.json` — SubagentStop dedup sidecar. */
+  solidNoticeFile: string;
+  /** `<root>/.harness/.gitignore`. */
+  gitignoreFile: string;
+}
+
+/**
+ * The single source of truth for where every package file lives under a project
+ * root. All modules (runtime storage, memory, init) derive their paths here —
+ * nothing hardcodes a directory name elsewhere.
+ */
+export function projectLayout(root: string): ProjectLayout {
+  const stateDir = join(root, STATE_ROOT);
+  const memoryDir = join(stateDir, "memory");
+  return {
+    root,
+    stateDir,
+    trackDir: join(stateDir, "track"),
+    solidNoticeFile: join(stateDir, "track", "solid-notice.json"),
+    cacheDir: join(stateDir, "cache"),
+    memoryDir,
+    lessonsFile: join(memoryDir, "LESSON.md"),
+    memoryStateFile: join(memoryDir, "state.json"),
+    gitignoreFile: join(stateDir, ".gitignore"),
+  };
+}

package/src/config/limits.ts

@@ -0,0 +1,56 @@
+import { parseEnvInt } from "./env";
+
+/** Default SOLID max lines per file. */
+export const DEFAULT_MAX_LINES = 100;
+
+/** Default env var name carrying the max-lines override. */
+export const MAX_LINES_ENV_KEY = "FUSE_SOLID_MAX_LINES";
+
+/**
+ * Resolve the SOLID max-lines limit from an env map.
+ * @param env - environment map (defaults to `process.env`)
+ * @param key - env var name (defaults to `FUSE_SOLID_MAX_LINES`)
+ */
+export function resolveMaxLines(
+  env: Record<string, string | undefined> = process.env,
+  key: string = MAX_LINES_ENV_KEY,
+): number {
+  return parseEnvInt(env[key], DEFAULT_MAX_LINES);
+}
+
+/** Advisory module-split headroom = `maxLines - 10` (never below 1). */
+export function splitTarget(maxLines: number): number {
+  return Math.max(maxLines - 10, 1);
+}
+
+/**
+ * Custom-hook line budget, derived from the global limit (ratio 0.3 — with
+ * the default 100 this yields the owner template's 30; one variable,
+ * `FUSE_SOLID_MAX_LINES`, drives every budget proportionally).
+ * @param maxLines - The global limit (from {@link resolveMaxLines}).
+ */
+export function hookBudget(maxLines: number): number {
+  return Math.max(Math.round(maxLines * 0.3), 1);
+}
+
+/**
+ * Store line budget, derived from the global limit (ratio 0.4 — 40 at the
+ * default 100, per owner rules/07-state-management).
+ * @param maxLines - The global limit (from {@link resolveMaxLines}).
+ */
+export function storeBudget(maxLines: number): number {
+  return Math.max(Math.round(maxLines * 0.4), 1);
+}
+
+/** Default stdin cap for hook payloads: 16 MiB. */
+export const DEFAULT_STDIN_MAX_BYTES: number = 16 * 1024 * 1024;
+
+/**
+ * Resolve the hook stdin cap (`FUSE_HOOK_STDIN_MAX_BYTES`, default 16 MiB;
+ * absent/invalid falls back to the default). The only new env var of the
+ * mission — owner-approved exception.
+ * @param env - environment map (defaults to `process.env`)
+ */
+export function resolveStdinMaxBytes(env: Record<string, string | undefined> = process.env): number {
+  return parseEnvInt(env.FUSE_HOOK_STDIN_MAX_BYTES, DEFAULT_STDIN_MAX_BYTES);
+}

package/src/config/ttl.ts

@@ -0,0 +1,30 @@
+import { parseEnvInt } from "./env";
+
+/**
+ * Default enforcement-freshness window, in seconds (2 minutes). Matches the
+ * plugin's original `FUSE_ENFORCE_TTL_SEC` default. This is the constant that
+ * actually reaches production (via `resolveTtlSec` -> `bin.ts`); `gate.ts`'s
+ * `DEFAULT_WINDOW_MS` is only a fallback for direct programmatic callers that
+ * omit `windowMs` (e.g. tests) and never applies on the real CLI path.
+ */
+export const DEFAULT_TTL_SEC = 120;
+
+/** Default env var name carrying the TTL override. */
+export const TTL_ENV_KEY = "FUSE_ENFORCE_TTL_SEC";
+
+/**
+ * Resolve the enforcement TTL (seconds) from an env map.
+ * @param env - environment map (defaults to `process.env`)
+ * @param key - env var name (defaults to `FUSE_ENFORCE_TTL_SEC`)
+ */
+export function resolveTtlSec(
+  env: Record<string, string | undefined> = process.env,
+  key: string = TTL_ENV_KEY,
+): number {
+  return parseEnvInt(env[key], DEFAULT_TTL_SEC);
+}
+
+/** Human label for a TTL: 120 -> "2min", 240 -> "4min", 90 -> "90s". */
+export function ttlLabel(sec: number): string {
+  return sec % 60 === 0 ? `${sec / 60}min` : `${sec}s`;
+}

package/src/detect/harness.ts

@@ -0,0 +1,73 @@
+/**
+ * Runtime detection of the AI coding harness, and its integration mode.
+ * Env-signal names verified 2026 (agentx, agents.md#136, @vercel/detect-agent,
+ * official Claude Code / Cursor / Gemini / Codex docs). Presence-based: the
+ * value is ignored except for the `AGENT` / `AI_AGENT` standards.
+ */
+import type { HarnessId, HarnessMode, HarnessInfo } from "./interfaces/types";
+
+export type { HarnessId, HarnessMode, HarnessVia, HarnessInfo } from "./interfaces/types";
+
+/** Tool-specific env var (presence) -> harness id. Order = detection priority. */
+const ENV_SIGNALS: ReadonlyArray<readonly [string, HarnessId]> = [
+  ["CLAUDECODE", "claude-code"], ["CODEX_SANDBOX", "codex"],
+  ["CURSOR_AGENT", "cursor"], ["CLINE", "cline"], ["CLINE_AGENT", "cline"],
+  ["GEMINI_CLI", "gemini-cli"], ["OPENCODE", "opencode"],
+  ["WINDSURF_AGENT", "windsurf"], ["CODEIUM_AGENT", "windsurf"],
+  ["COPILOT_AGENT", "copilot"], ["AIDER", "aider"], ["KIRO", "kiro"],
+  ["GOOSE", "goose"], ["AMP", "amp"], ["HERMES_SESSION_ID", "hermes"],
+  // No documented session-marker env var for Kimi Code CLI (unlike CLAUDECODE,
+  // CURSOR_AGENT, ...). `KIMI_CODE_HOME`/`KIMI_PLUGIN_ROOT` are injected only
+  // into PLUGIN-declared hooks (customization/plugins.html: "The hook process
+  // receives two extra environment variables"), never into config.toml hooks —
+  // verified live against kimi-code v0.27.0: a config.toml hook process sees
+  // neither var, and no session marker at all. Detection therefore falls
+  // through to the `AGENT=kimi` / `AI_AGENT=kimi` standard above.
+];
+
+/** `AGENT=<name>` / `AI_AGENT=<name>` standard value -> harness id. */
+const STD_NAMES: Record<string, HarnessId> = {
+  goose: "goose", amp: "amp", claude: "claude-code", "claude-code": "claude-code",
+  cursor: "cursor", codex: "codex", cline: "cline", aider: "aider",
+  opencode: "opencode", gemini: "gemini-cli", copilot: "copilot", kiro: "kiro",
+  hermes: "hermes", kimi: "kimi",
+};
+
+/** Harnesses exposing a native hook system (vs CLI-only integration). */
+const HOOK_CAPABLE: ReadonlySet<HarnessId> = new Set([
+  "claude-code", "codex", "cursor", "cline", "gemini-cli", "opencode", "hermes", "kimi",
+]);
+
+/** Integration mode for a harness id. */
+export function modeFor(id: HarnessId): HarnessMode {
+  return HOOK_CAPABLE.has(id) ? "hook" : "cli";
+}
+
+/**
+ * Detect the current AI coding harness from environment signals.
+ * Priority: `AGENT` standard -> `AI_AGENT` standard -> tool-specific vars -> unknown.
+ * @param env - environment map (defaults to `process.env`)
+ */
+export function detectHarness(
+  env: Record<string, string | undefined> = process.env,
+): HarnessInfo {
+  const agent = env.AGENT?.trim().toLowerCase();
+  const agentId = agent ? STD_NAMES[agent] : undefined;
+  if (agentId) return { id: agentId, mode: modeFor(agentId), via: "agent-std" };
+
+  const ai = env.AI_AGENT?.trim().toLowerCase();
+  const aiId = ai ? STD_NAMES[ai] : undefined;
+  if (aiId) return { id: aiId, mode: modeFor(aiId), via: "ai-agent-std" };
+
+  for (const [key, id] of ENV_SIGNALS) {
+    if (env[key]?.trim()) return { id, mode: modeFor(id), via: "env" };
+  }
+  return { id: "unknown", mode: "cli", via: "fallback" };
+}
+
+/** Convenience: the integration mode of the current harness. */
+export function detectMode(
+  env: Record<string, string | undefined> = process.env,
+): HarnessMode {
+  return detectHarness(env).mode;
+}

package/src/detect/index.ts

@@ -0,0 +1 @@
+export * from "./harness";

package/src/detect/interfaces/types.ts

@@ -0,0 +1,18 @@
+/** Known AI coding harnesses detectable at runtime. */
+export type HarnessId =
+  | "claude-code" | "codex" | "cursor" | "cline" | "gemini-cli"
+  | "opencode" | "windsurf" | "copilot" | "aider" | "kiro"
+  | "goose" | "amp" | "hermes" | "kimi" | "unknown";
+
+/** Integration mode: `hook` = native lifecycle hooks; `cli` = run as an external step. */
+export type HarnessMode = "hook" | "cli";
+
+/** How the harness was identified. */
+export type HarnessVia = "agent-std" | "ai-agent-std" | "env" | "fallback";
+
+/** Result of {@link detectHarness}. */
+export interface HarnessInfo {
+  id: HarnessId;
+  mode: HarnessMode;
+  via: HarnessVia;
+}