@lannguyensi/harness 0.5.0

package/README.md

@@ -0,0 +1,154 @@
+# harness
+
+**Declarative control plane for agent harnesses.**
+
+One zod-validated YAML manifest for grounding, tools, memory, hooks, and policies — plus a CLI that describes, validates, diffs, applies, audits, and *enforces*.
+
+> Most config tools tell you what an agent is configured to use. `harness` tells you what an agent is *allowed to do*, under this exact context, and why.
+
+`harness` collapses the six-to-eight surfaces a working agent harness leaks across (`settings.json`, `CLAUDE.md`, memory frontmatter, MCP registrations, per-project overrides, hook scripts) into a single source of truth. Today (`v0.4.0`) policies fire end-to-end: a `mcp__agent-tasks__pull_requests_merge` call against a session without a `review:${PR_NUMBER}` ledger entry refuses; `harness explain review-before-merge --trace` shows exactly why. Phase 6 adds an *Understanding Gate* (agents confirm task interpretation before editing); Phase 7 adds a *Risk Gate* that blocks `DROP TABLE` against a prod target — even when the model would happily run it.
+
+## Try it in 60 seconds
+
+```bash
+git clone https://github.com/LanNguyenSi/harness && cd harness
+npm install && npm run build
+
+# Statically predict which policies fire for a tool call (no ledger, no LLM)
+node dist/cli/main.js dry-run "merge PR 42" \
+  --tool mcp__agent-tasks__pull_requests_merge \
+  --tool-args '{"prNumber":42}' \
+  --config docs/examples/full-manifest.yaml
+```
+
+`dry-run` reads the reference manifest (`docs/examples/full-manifest.yaml`), runs the trigger matcher, substitutes `${PR_NUMBER}=42` through the JSONPath-restricted extract DSL, and tells you exactly which hooks would fire and which policies would match — before any ledger I/O.
+
+## What a run looks like
+
+```yaml
+prompt: merge PR 42
+tool: mcp__agent-tasks__pull_requests_merge
+toolArgs:
+  prNumber: 42
+Hooks that would fire:
+  - event: SessionStart
+    name: git-preflight
+  - event: PreToolUse
+    name: require-review-evidence
+  - event: PreToolUse
+    name: require-dogfood-evidence
+  - event: PreToolUse
+    name: require-preflight-evidence
+Policies that match:
+  - name: review-before-merge
+    ledgerQuery: review:42
+    requires:
+      ledger_tag: review:${PR_NUMBER}
+    enforcement: block
+    triggerEvent: PreToolUse
+  - name: two-reviewers-required
+    ledgerQuery: review:42
+    requires:
+      ledger_tag: review:${PR_NUMBER}
+      count:
+        min: 2
+    enforcement: warn
+    triggerEvent: PreToolUse
+Policies that COULD match (need --tool):
+  - name: dogfood-before-release
+    triggerEvent: PreToolUse
+    reason: --tool "mcp__agent-tasks__pull_requests_merge" does not contain trigger.match "Bash"
+  - name: preflight-before-investigation
+    triggerEvent: PreToolUse
+    reason: --tool "mcp__agent-tasks__pull_requests_merge" does not contain trigger.match "Bash"
+Memories that would route:
+  - path: ~/.claude/projects/{project}/memory
+    scope: project
+```
+
+When the matching policy actually fires (via `harness policy intercept`, wired by `harness apply` into `settings.json` as a `PreToolUse` hook), and the evidence ledger has no `review:42` entry, the runtime emits Claude Code's deny shape on stdout:
+
+```json
+{"decision":"deny","reason":"review-before-merge: no matching ledger entry for tag `review:42`"}
+```
+
+After the entry is recorded, the same call is silently allowed. Every fire writes a `policy_decision` row that `harness audit` and `harness explain --trace` replay:
+
+```
+$ node dist/cli/main.js audit --since 1h --policy review-before-merge --session sess-1 --config docs/examples/full-manifest.yaml
+
+timestamp                 policy               outcome  reason
+------------------------  -------------------  -------  ---------------------------------------------
+2026-04-30T18:30:00.000Z  review-before-merge  deny     no matching ledger entry for tag `review:42`
+2026-04-30T18:31:00.000Z  review-before-merge  allow    1 matching ledger entries for tag `review:42`
+```
+
+## Next steps
+
+| If you want to... | Read |
+|------|------|
+| Understand the YAML shape, CLI surface, drift handling, `requires` schema | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
+| See phase-by-phase scope, deliverables, acceptance criteria, exit gates | [`docs/ROADMAP.md`](docs/ROADMAP.md) |
+| Read the long-form positioning (three pillars, ecosystem map, gaps) | [`docs/VISION.md`](docs/VISION.md) |
+| Browse a manifest covering every field | [`docs/examples/full-manifest.yaml`](docs/examples/full-manifest.yaml) |
+| Track what's shipping and what's deferred | [`CHANGELOG.md`](CHANGELOG.md) |
+
+## Common commands
+
+```bash
+node dist/cli/main.js init --template full --config /tmp/harness-demo/harness.yaml
+node dist/cli/main.js describe   --config /tmp/harness-demo/harness.yaml --pillar tools
+node dist/cli/main.js doctor     --config /tmp/harness-demo/harness.yaml --shallow
+node dist/cli/main.js validate   --config /tmp/harness-demo/harness.yaml
+node dist/cli/main.js apply      --config /tmp/harness-demo/harness.yaml   # regenerate settings.json + MEMORY.md, write harness.lock
+node dist/cli/main.js diff --since-apply --config /tmp/harness-demo/harness.yaml
+node dist/cli/main.js explain review-before-merge --trace --config docs/examples/full-manifest.yaml
+node dist/cli/main.js audit --since 24h --config docs/examples/full-manifest.yaml
+```
+
+## What's next
+
+Two structurally larger themes are queued after Phase 5's polish:
+
+**Phase 6 — Understanding Gate.** Before an agent edits files, runs shell, commits, or opens a PR, it must produce an *Understanding Report* (its interpretation of the task: derived todos, acceptance criteria, assumptions, out-of-scope, risks). The user confirms, corrects, or "grills me until precise enough". Only after explicit approval is recorded in the evidence ledger may write-capable tools fire. Ships as the first `harness` *Policy Pack* — a reusable bundle of instruction template + hooks + policies + permission profiles. Long-form design lives in the internal `lava-ice-logs` logbook (2026-04-30).
+
+**Phase 7 — Risk Gate.** Today's policy model evaluates a rule per matching trigger and returns a binary block/allow. Phase 7 makes harness reason about *the action itself*: an Action Envelope (tool + raw input + session + runtime context) is enriched by a Context Resolver (production / staging / dev / unknown), classified by a Risk Classifier (severity + categories + reversibility), then matched against policies whose `when:` clauses can reference `risk.severity_at_least`, `environment.name`, and similar. The decision space extends to `allow / warn / require_approval / deny`. Motivating use case: prevent `DROP TABLE users`, `kubectl delete namespace prod`, `terraform destroy` against an unverified production target before they reach the runtime — even if the model would have happily run them. Long-form design lives in the internal `lava-ice-logs` logbook (2026-04-30).
+
+Both build on Phase 4's `policy intercept` runtime backbone; neither replaces it.
+
+> Bring your favorite agent harness. Add governance.
+
+## Status
+
+- [x] Repo bootstrap (LICENSE, .gitignore)
+- [x] README + VISION — repo legible
+- [x] ARCHITECTURE — YAML shape + CLI surface agreed
+- [x] ROADMAP — phases 1–4 with acceptance criteria
+- [x] Phase 1 — read-only inventory (`describe`, `validate`, `doctor`, `list`, `explain`, `diff`) — released as [`v0.1.0`](CHANGELOG.md#010---2026-04-29)
+- [x] Phase 2 — managed edits (`init`, `add`, `remove`, `adopt`, `export`) — released as [`v0.2.0`](CHANGELOG.md#020---2026-04-29)
+- [x] Phase 3 — declarative truth (`apply`, `diff --since-apply`, `harness.lock`) — released as [`v0.3.0`](CHANGELOG.md#030---2026-04-30)
+- [x] Phase 4 — policy layer (`policy intercept`, `explain --trace`, `audit`, `dry-run`, requires-evaluator + extract DSL + grounding-mcp adapter) — released as [`v0.4.0`](CHANGELOG.md#040---2026-04-30)
+- [ ] Phase 5 — polish + dogfood lessons (`apply --strict-lock`, `validate --check-lock`, sessionId default, `--verbose` deny diagnostics, sysexits normalisation, real-Claude-Code dogfood)
+- [ ] Phase 6 — Understanding Gate Policy Pack (agents must expose and confirm task understanding before write-capable tools fire)
+- [ ] Phase 7 — Risk Gate (Action Envelope + Risk Classifier + `allow / warn / require_approval / deny` for destructive-action prevention)
+
+## Why this exists
+
+A working agent harness today has six to eight configuration surfaces, each with its own schema and lifecycle: `~/.claude/settings.json`, `CLAUDE.md` (per repo + root), `~/.claude/projects/*/memory/*.md` with frontmatter, `~/.claude/keybindings.json`, MCP server registrations in `~/.claude.json`, skill directories, per-project overrides, and external CLIs that behave differently per project.
+
+There is no single place that answers *"what can this agent do right now, and why is that configured that way?"*. Drift between sessions is invisible until it breaks something. Humans editing one surface don't know which other surfaces they need to touch. A fresh agent instance has no way to audit its own setup.
+
+Our entry point into this problem: on 2026-04-23, an `agent-grounding` checkout that was 16 commits behind origin led two tasks to be incorrectly called "stale". The check that would have caught it already exists — [`agent-preflight`](https://github.com/LanNguyenSi/agent-preflight) runs `git fetch` + `git status` (alongside lint, typecheck, test, audit) and emits a structured `ready` + confidence-score result. The missing piece wasn't the check itself, it was the deterministic *trigger*: a `SessionStart` hook that invokes `preflight run` and a policy that gates further work on the result. Building that wiring needs an agreed-upon place for harness config to live first. That conversation is the origin of this repo.
+
+## Related
+
+- [`agent-grounding`](https://github.com/LanNguyenSi/agent-grounding) — grounding primitives (evidence-ledger, claim-gate, review-claim-gate); `grounding-mcp` is the canonical client surface harness queries through `queryLedgerByTag` (Phase 4 #3).
+- [`agent-memory`](https://github.com/LanNguyenSi/agent-memory) — memory surfaces the control plane inventories.
+- [`agent-tasks`](https://github.com/LanNguyenSi/agent-tasks) — the MCP-registered task platform whose registration + health appear in `harness describe`.
+- [`agent-preflight`](https://github.com/LanNguyenSi/agent-preflight) — local preflight validator; the canonical implementation of preflight-hook content harness wires (see `docs/ARCHITECTURE.md` §5 for the canonical hook-script shape and §6 for the Phase 4 policy that gates further work on a `preflight:${REPO}` ledger entry).
+- [`codebase-oracle`](https://github.com/LanNguyenSi/codebase-oracle) — one of the MCP surfaces being registered.
+- [`dev-tools`](https://github.com/LanNguyenSi/dev-tools) — `git-batch-cli`, a day-to-day tool whose inventory appears in `harness describe`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/cli/add/index.d.ts

@@ -0,0 +1,14 @@
+import { type AddEntry } from "./mutate.js";
+export interface AddOptions {
+    configPath?: string;
+    homeDir?: string;
+    dryRun?: boolean;
+}
+export interface AddResult {
+    path: string;
+    type: AddEntry["type"];
+    name: string;
+    diff: string;
+    applied: boolean;
+}
+export declare function add(action: AddEntry, opts?: AddOptions): Promise<AddResult>;

package/dist/cli/add/index.js

@@ -0,0 +1,71 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { withFileLock } from "../../io/lock.js";
+import { unifiedDiff } from "../../io/patch.js";
+import { formatValidationErrors, validateBeforeWrite, } from "../../io/validate-before-write.js";
+import { parseManifest } from "../../schema/index.js";
+import { runAssetChecks } from "../validate/checks.js";
+import { fmtDiagnostic } from "../validate/types.js";
+import { EX_FAIL, EX_NOINPUT, HarnessExitError } from "../exit-codes.js";
+import { applyAdd } from "./mutate.js";
+const DEFAULT_BASENAME = "harness.yaml";
+const LOCK_BASENAME = ".harness.lock";
+function resolveTargetPath(opts) {
+    if (opts.configPath)
+        return path.resolve(opts.configPath);
+    return path.join(opts.homeDir ?? path.join(os.homedir(), ".claude"), DEFAULT_BASENAME);
+}
+function entryName(action) {
+    return action.type === "skill" ? action.entry : action.entry.name;
+}
+export async function add(action, opts = {}) {
+    const target = resolveTargetPath(opts);
+    if (!fs.existsSync(target)) {
+        throw new HarnessExitError(`harness manifest not found at ${target}; run \`harness init\` first`, EX_NOINPUT);
+    }
+    const original = fs.readFileSync(target, "utf8");
+    const proposed = applyAdd(original, action);
+    const diff = unifiedDiff({
+        fileName: path.basename(target),
+        oldText: original,
+        newText: proposed,
+        oldHeader: "current",
+        newHeader: "proposed",
+    });
+    // Schema gate.
+    const schemaResult = validateBeforeWrite(parseYaml(proposed));
+    if (!schemaResult.ok) {
+        throw new HarnessExitError(`proposed manifest fails schema validation:\n${formatValidationErrors(schemaResult.errors)}`, EX_FAIL);
+    }
+    // Asset gate — surfaces hook +x failures, missing required CLIs, etc.
+    // We use parseManifest (not the result of validateBeforeWrite) so we have a
+    // typed Manifest for runAssetChecks. defaults flow through.
+    const manifest = parseManifest(parseYaml(proposed));
+    const assetDiagnostics = runAssetChecks(manifest, { homeDir: opts.homeDir }).filter((d) => d.severity === "error");
+    if (assetDiagnostics.length > 0) {
+        const lines = assetDiagnostics.map(fmtDiagnostic).join("\n");
+        throw new HarnessExitError(`proposed manifest fails asset validation:\n${lines}`, EX_FAIL);
+    }
+    if (opts.dryRun) {
+        return { path: target, type: action.type, name: entryName(action), diff, applied: false };
+    }
+    const lockPath = path.join(path.dirname(target), LOCK_BASENAME);
+    await withFileLock(lockPath, () => {
+        // Re-read under the lock and re-apply so we never clobber a concurrent
+        // commit. The schema/asset checks above ran on the pre-lock snapshot;
+        // the post-lock apply re-validates implicitly via parseDocument round-trip
+        // and the inserted entry is still added because applyAdd is purely additive.
+        const current = fs.readFileSync(target, "utf8");
+        const next = applyAdd(current, action);
+        const recheck = validateBeforeWrite(parseYaml(next));
+        if (!recheck.ok) {
+            throw new HarnessExitError(`proposed manifest fails schema validation after lock acquisition:\n${formatValidationErrors(recheck.errors)}`, EX_FAIL);
+        }
+        atomicWriteFile(target, next);
+    });
+    return { path: target, type: action.type, name: entryName(action), diff, applied: true };
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/add/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/add/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/add/mutate.d.ts

@@ -0,0 +1,39 @@
+export type AddType = "mcp" | "cli" | "skill" | "hook";
+export interface McpEntry {
+    name: string;
+    command: string | string[];
+    env?: Record<string, string>;
+    health?: {
+        verb: string;
+        timeout_ms?: number;
+    };
+    enabled?: boolean;
+}
+export interface CliEntry {
+    name: string;
+    binary: string;
+    required?: boolean;
+    min_version?: string;
+}
+export interface HookEntry {
+    name: string;
+    event: string;
+    command: string;
+    match?: string;
+    blocking: boolean | "soft" | "hard";
+    budget_ms?: number;
+}
+export type AddEntry = {
+    type: "mcp";
+    entry: McpEntry;
+} | {
+    type: "cli";
+    entry: CliEntry;
+} | {
+    type: "skill";
+    entry: string;
+} | {
+    type: "hook";
+    entry: HookEntry;
+};
+export declare function applyAdd(yamlText: string, action: AddEntry): string;

package/dist/cli/add/mutate.js

@@ -0,0 +1,36 @@
+import { isSeq, parseDocument } from "yaml";
+export function applyAdd(yamlText, action) {
+    const doc = parseDocument(yamlText);
+    switch (action.type) {
+        case "mcp":
+            addToSequence(doc, ["tools", "mcp"], action.entry);
+            break;
+        case "cli":
+            addToSequence(doc, ["tools", "cli"], action.entry);
+            break;
+        case "skill":
+            addToSequence(doc, ["tools", "skills", "enabled"], action.entry);
+            break;
+        case "hook":
+            addToSequence(doc, ["hooks"], action.entry);
+            break;
+    }
+    // Match the conventions used elsewhere in the codebase so a no-op round-trip
+    // on a manifest authored in our style stays byte-equivalent (lineWidth:0
+    // disables 80-col folding on long flow sequences; flowCollectionPadding:false
+    // matches the [a, b] style without inner spaces).
+    return doc.toString({ flowCollectionPadding: false, lineWidth: 0 });
+}
+function addToSequence(doc, pathSegments, entry) {
+    const node = doc.getIn(pathSegments);
+    if (node === undefined || node === null) {
+        doc.setIn(pathSegments, [entry]);
+        return;
+    }
+    if (isSeq(node)) {
+        node.add(entry);
+        return;
+    }
+    throw new Error(`expected a YAML sequence at ${pathSegments.join(".")}, got ${typeof node}`);
+}
+//# sourceMappingURL=mutate.js.map

package/dist/cli/add/mutate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutate.js","sourceRoot":"","sources":["../../../src/cli/add/mutate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,aAAa,EAAiB,MAAM,MAAM,CAAC;AAkC3D,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,MAAgB;IACzD,MAAM,GAAG,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACpC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK;YACR,aAAa,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACnD,MAAM;QACR,KAAK,KAAK;YACR,aAAa,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACnD,MAAM;QACR,KAAK,OAAO;YACV,aAAa,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACjE,MAAM;QACR,KAAK,MAAM;YACT,aAAa,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5C,MAAM;IACV,CAAC;IACD,6EAA6E;IAC7E,yEAAyE;IACzE,8EAA8E;IAC9E,kDAAkD;IAClD,OAAO,GAAG,CAAC,QAAQ,CAAC,EAAE,qBAAqB,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,aAAa,CACpB,GAAoB,EACpB,YAAsB,EACtB,KAAc;IAEd,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACxC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;QACjC,OAAO;IACT,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAChB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,KAAK,CACb,+BAA+B,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,OAAO,IAAI,EAAE,CAC5E,CAAC;AACJ,CAAC"}

package/dist/cli/adopt/derive.d.ts

@@ -0,0 +1,38 @@
+import type { Manifest } from "../../schema/index.js";
+export interface DerivedHook {
+    event: string;
+    command: string;
+    match?: string;
+}
+export interface SettingsHookGroup {
+    matcher?: string;
+    hooks: {
+        type?: string;
+        command: string;
+    }[];
+}
+export interface SettingsRoot {
+    hooks?: Record<string, SettingsHookGroup[]>;
+}
+/**
+ * Flatten the nested ~/.claude/settings.json hooks tree into a list of
+ * manifest-style hook records so we can diff it against the manifest.
+ */
+export declare function parseSettingsHooks(raw: unknown): DerivedHook[];
+/**
+ * Project the manifest's hooks[] into the same flat shape so drift comparison
+ * is symmetric.
+ */
+export declare function manifestProjection(manifest: Manifest): DerivedHook[];
+/**
+ * settings.json minus manifest, keyed on (event, command, match).
+ * Returns hooks present in settings but not declared in the manifest.
+ */
+export declare function computeDrift(settingsHooks: DerivedHook[], manifestHooks: DerivedHook[]): DerivedHook[];
+/**
+ * Synthesize a manifest hook name from the derived entry.
+ * Strategy: take the command's first token's basename without extension; if
+ * that collides with an existing name, append -2, -3, etc. Falls back to
+ * `adopted-hook` if the command has no recognisable basename.
+ */
+export declare function synthesizeName(d: DerivedHook, taken: Set<string>): string;

package/dist/cli/adopt/derive.js

@@ -0,0 +1,94 @@
+const KNOWN_EVENTS = new Set([
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+    "SubagentStop",
+    "PreCompact",
+]);
+/**
+ * Flatten the nested ~/.claude/settings.json hooks tree into a list of
+ * manifest-style hook records so we can diff it against the manifest.
+ */
+export function parseSettingsHooks(raw) {
+    if (!isRecord(raw))
+        return [];
+    const root = raw;
+    if (!root.hooks || !isRecord(root.hooks))
+        return [];
+    const out = [];
+    for (const [event, groups] of Object.entries(root.hooks)) {
+        if (!KNOWN_EVENTS.has(event))
+            continue;
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!isRecord(group))
+                continue;
+            const matcher = typeof group.matcher === "string" && group.matcher.length > 0
+                ? group.matcher
+                : undefined;
+            const inner = group.hooks;
+            if (!Array.isArray(inner))
+                continue;
+            for (const h of inner) {
+                if (!isRecord(h))
+                    continue;
+                if (typeof h.command !== "string" || h.command.length === 0)
+                    continue;
+                out.push({
+                    event,
+                    command: h.command,
+                    ...(matcher !== undefined ? { match: matcher } : {}),
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Project the manifest's hooks[] into the same flat shape so drift comparison
+ * is symmetric.
+ */
+export function manifestProjection(manifest) {
+    return manifest.hooks.map((h) => {
+        const out = { event: h.event, command: h.command };
+        if (h.match !== undefined)
+            out.match = h.match;
+        return out;
+    });
+}
+/**
+ * settings.json minus manifest, keyed on (event, command, match).
+ * Returns hooks present in settings but not declared in the manifest.
+ */
+export function computeDrift(settingsHooks, manifestHooks) {
+    const declared = new Set(manifestHooks.map(keyOf));
+    return settingsHooks.filter((h) => !declared.has(keyOf(h)));
+}
+function keyOf(h) {
+    return `${h.event}\x00${h.command}\x00${h.match ?? ""}`;
+}
+/**
+ * Synthesize a manifest hook name from the derived entry.
+ * Strategy: take the command's first token's basename without extension; if
+ * that collides with an existing name, append -2, -3, etc. Falls back to
+ * `adopted-hook` if the command has no recognisable basename.
+ */
+export function synthesizeName(d, taken) {
+    const firstToken = d.command.trim().split(/\s+/)[0] ?? "";
+    const last = firstToken.split("/").pop() ?? "";
+    const stem = last.replace(/\.[^.]+$/, "");
+    const base = stem.length > 0 ? stem : "adopted-hook";
+    if (!taken.has(base))
+        return base;
+    let i = 2;
+    while (taken.has(`${base}-${i}`))
+        i++;
+    return `${base}-${i}`;
+}
+function isRecord(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+//# sourceMappingURL=derive.js.map

package/dist/cli/adopt/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../../src/cli/adopt/derive.ts"],"names":[],"mappings":"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"}

package/dist/cli/adopt/index.d.ts

@@ -0,0 +1,20 @@
+export interface AdoptOptions {
+    configPath?: string;
+    homeDir?: string;
+    yes?: boolean;
+    /** Optional injection point for tests; defaults to readline against stdin. */
+    prompt?: (message: string) => Promise<string>;
+}
+export interface AdoptResult {
+    manifestPath: string;
+    settingsPath: string;
+    driftCount: number;
+    /** The unified diff of the proposed change. Empty when nothing to adopt. */
+    diff: string;
+    applied: boolean;
+    /** Names synthesised for the new manifest entries. */
+    adoptedNames: string[];
+    /** Human-readable status: "no-drift" | "declined" | "applied". */
+    outcome: "no-drift" | "declined" | "applied";
+}
+export declare function adopt(settingsPath: string, opts?: AdoptOptions): Promise<AdoptResult>;

package/dist/cli/adopt/index.js

@@ -0,0 +1,156 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as readline from "node:readline/promises";
+import { parse as parseYaml } from "yaml";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { withFileLock } from "../../io/lock.js";
+import { unifiedDiff } from "../../io/patch.js";
+import { formatValidationErrors, validateBeforeWrite, } from "../../io/validate-before-write.js";
+import { parseManifest } from "../../schema/index.js";
+import { applyAdd } from "../add/mutate.js";
+import { EX_FAIL, EX_NOINPUT, HarnessExitError } from "../exit-codes.js";
+import { computeDrift, manifestProjection, parseSettingsHooks, synthesizeName, } from "./derive.js";
+const DEFAULT_BASENAME = "harness.yaml";
+const LOCK_BASENAME = ".harness.lock";
+function resolveManifestPath(opts) {
+    if (opts.configPath)
+        return path.resolve(opts.configPath);
+    return path.join(opts.homeDir ?? path.join(os.homedir(), ".claude"), DEFAULT_BASENAME);
+}
+async function defaultPrompt(message) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(message);
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function adopt(settingsPath, opts = {}) {
+    const manifestPath = resolveManifestPath(opts);
+    if (!fs.existsSync(manifestPath)) {
+        throw new HarnessExitError(`harness manifest not found at ${manifestPath}; run \`harness init\` first`, EX_NOINPUT);
+    }
+    if (!fs.existsSync(settingsPath)) {
+        throw new HarnessExitError(`cannot adopt: file does not exist: ${settingsPath}`, EX_NOINPUT);
+    }
+    const originalYaml = fs.readFileSync(manifestPath, "utf8");
+    const manifest = parseManifest(parseYaml(originalYaml));
+    const projection = manifestProjection(manifest);
+    let settingsRaw;
+    try {
+        settingsRaw = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    }
+    catch (e) {
+        throw new HarnessExitError(`cannot adopt: ${settingsPath} is not valid JSON: ${e.message}`, EX_FAIL);
+    }
+    const settingsHooks = parseSettingsHooks(settingsRaw);
+    const drift = computeDrift(settingsHooks, projection);
+    if (drift.length === 0) {
+        return {
+            manifestPath,
+            settingsPath,
+            driftCount: 0,
+            diff: "",
+            applied: false,
+            adoptedNames: [],
+            outcome: "no-drift",
+        };
+    }
+    const taken = new Set(manifest.hooks.map((h) => h.name));
+    const adoptedNames = [];
+    let proposedYaml = originalYaml;
+    for (const d of drift) {
+        const name = synthesizeName(d, taken);
+        taken.add(name);
+        adoptedNames.push(name);
+        proposedYaml = applyAdd(proposedYaml, {
+            type: "hook",
+            entry: buildHookEntry(name, d),
+        });
+    }
+    const diff = unifiedDiff({
+        fileName: path.basename(manifestPath),
+        oldText: originalYaml,
+        newText: proposedYaml,
+        oldHeader: "current",
+        newHeader: "proposed",
+    });
+    // Defence-in-depth gate. From a happy-path adopt (well-formed input manifest +
+    // well-formed settings.json) every synthesised hook field is already
+    // schema-valid by construction (event from KNOWN_EVENTS, non-empty command,
+    // disambiguated name, blocking:false). The gate is here to catch structural
+    // bugs in synthesizeName / applyAdd that future maintainers might introduce.
+    const validation = validateBeforeWrite(parseYaml(proposedYaml));
+    if (!validation.ok) {
+        throw new HarnessExitError(`proposed manifest fails schema validation:\n${formatValidationErrors(validation.errors)}`, EX_FAIL);
+    }
+    if (!opts.yes) {
+        const promptFn = opts.prompt ?? defaultPrompt;
+        const answer = (await promptFn(`${diff}\nApply (y/N)? `)).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            return {
+                manifestPath,
+                settingsPath,
+                driftCount: drift.length,
+                diff,
+                applied: false,
+                adoptedNames,
+                outcome: "declined",
+            };
+        }
+    }
+    const lockPath = path.join(path.dirname(manifestPath), LOCK_BASENAME);
+    await withFileLock(lockPath, () => {
+        const current = fs.readFileSync(manifestPath, "utf8");
+        let next = current;
+        const currentManifest = parseManifest(parseYaml(current));
+        const lockTaken = new Set(currentManifest.hooks.map((h) => h.name));
+        for (let i = 0; i < drift.length; i++) {
+            const d = drift[i];
+            const name = adoptedNames[i];
+            // If a concurrent adopt landed the same drift, skip silently rather than
+            // duplicating. This makes adopt idempotent across repeated runs.
+            // KNOWN GAP: a concurrent adopt that resolved the same drift to a
+            // *different* name (e.g. our `foo` vs their `foo-2`) would NOT be caught
+            // here — both would land as separate hooks with different names. Schema
+            // accepts it (no name collision), but the manifest contains two entries
+            // pointing at the same command. Acceptable rarity for Phase 2; revisit
+            // when a SHA-based drift identity ships in Phase 3 alongside harness.lock.
+            if (lockTaken.has(name))
+                continue;
+            next = applyAdd(next, { type: "hook", entry: buildHookEntry(name, d) });
+            lockTaken.add(name);
+        }
+        const recheck = validateBeforeWrite(parseYaml(next));
+        if (!recheck.ok) {
+            throw new HarnessExitError(`proposed manifest fails schema validation after lock acquisition:\n${formatValidationErrors(recheck.errors)}`, EX_FAIL);
+        }
+        atomicWriteFile(manifestPath, next);
+    });
+    return {
+        manifestPath,
+        settingsPath,
+        driftCount: drift.length,
+        diff,
+        applied: true,
+        adoptedNames,
+        outcome: "applied",
+    };
+}
+function buildHookEntry(name, d) {
+    // Adopted hooks default to non-blocking so the captured entry doesn't
+    // unexpectedly start gating tool calls. The user can promote to soft/hard
+    // explicitly if they want enforcement.
+    const entry = {
+        name,
+        event: d.event,
+        command: d.command,
+        blocking: false,
+    };
+    if (d.match !== undefined)
+        entry.match = d.match;
+    return entry;
+}
+//# sourceMappingURL=index.js.map