freeharness 0.4.1 → 0.4.3

package/dist/adapters/harness/claude-code.d.ts

@@ -1,7 +1,9 @@
-import type { Capability } from "@freeharness/core";
+import type { Capability, HarnessTarget } from "@freeharness/core";
 import type { AdapterResult, InstallContext } from "@freeharness/core";
 import type { HarnessPort } from "@freeharness/core";
 export { ROUTING_FILE } from "../../infra/routing.js";
+/** Writes the SDD skill's `reference/tiers.md` under `skillsDir`; nothing when the canonical skills lack the SDD skill. */
+export declare function emitTierReference(canonicalDir: string, skillsDir: string, target: HarnessTarget, dryRun: boolean): string[];
 /**
  * Capabilities that live in the machine-global install (~/.claude). At project scope the
  * adapter refuses them unless `allowProjectCopies` is set: Claude Code loads user and
@@ -12,10 +14,16 @@ export declare const GLOBAL_ONLY_CAPABILITIES: readonly string[];
 export declare const FH_CONTEXT_COMMAND: string;
 /** SessionStart matcher: compact/resume/fork get the re-orientation block, startup/clear the pointer. */
 export declare const SESSION_START_MATCHER = "startup|clear|compact|resume|fork";
-/** Flags baked into the hook commands (the fragment defaults; edit settings.json to tune). */
+/**
+ * Flags baked into the hook commands (the fragment defaults). `update` resets FreeHarness
+ * hook flags to these shipped values, so a flag tuned in settings.json does not survive it:
+ * keeping the tuned entry beside the shipped one would run the hook twice.
+ */
 export declare const OUTPUT_PRUNER_FLAGS = "--max-bytes 8192 --max-lines 200";
 export declare const CONTEXT_MONITOR_FLAGS = "--budget 200000 --thresholds 60,85";
-export declare const CONFIG_GUARD_FLAGS = "--ttl 30";
+/** Config-guard allow-marker window in minutes; feeds both the hook flag and the install note. */
+export declare const CONFIG_GUARD_TTL_MIN = 240;
+export declare const CONFIG_GUARD_FLAGS = "--ttl 240";
 export declare const REPEAT_TOOL_FLAGS = "--thresholds 3,5,8 --preview-chars 500";
 /**
  * Per-hook timeout (seconds) on SessionEnd entries. Claude Code gives SessionEnd hooks a
@@ -24,12 +32,27 @@ export declare const REPEAT_TOOL_FLAGS = "--thresholds 3,5,8 --preview-chars 500
  * pushes past 1.5 s.
  */
 export declare const SESSION_END_TIMEOUT_S = 10;
+/** Status line quota tap, emitted with the cost capability; the owner wires it, never a settings hook. */
+export declare const QUOTA_TAP_SCRIPT = "freeharness-quota-tap.mjs";
 /** Every hook script FreeHarness emits (rules + safety + cost capabilities), for doctor and uninstall. */
 export declare const HOOK_SCRIPTS: readonly string[];
 export declare class ClaudeCodeAdapter implements HarnessPort {
     readonly target: "claude-code";
+    private readonly autoMemoryMerged;
+    private turnOffAutoMemoryOnce;
     apply(cap: Capability, ctx: InstallContext): Promise<AdapterResult>;
 }
+/**
+ * Mirrors `freeMemEnabled` in `../../cli/install-facts.js`, duplicated rather than
+ * shared: adapters never import the cli layer (`scripts/check-arch.mjs`). Exported so a
+ * test can hold both copies to the same answers.
+ */
+export declare function freeMemEnabled(claudeDir: string): boolean;
+/**
+ * free-mem is the only memory owner; Claude Code auto memory (and agent memory with it) would
+ * keep a second store nothing recalls. Added only when absent, so an owner's explicit value wins.
+ */
+export declare function turnOffAutoMemory(settingsPath: string, dry: boolean, res: AdapterResult): void;
 /**
  * Reports and, only once confirmed, strips a trailing `[1m]` suffix from the scope's own
  * `model` value. The emitted defaults never force or replace a model family: a value with no

package/dist/adapters/harness/claude-code.js

@@ -1,15 +1,39 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { randomBytes } from "node:crypto";
 import { copyDir, copyExecutable, ensureDir, mergeClaudeHook, mergeSettingsKeys, readText, writeText, writeTextIfAbsent } from "../../infra/fsutil.js";
+import { mergePriceTable } from "../../infra/prices.js";
 import { AGENT_MEMORY_GITIGNORE_LINE, AGENT_MEMORY_LOCAL_GITIGNORE_LINE, SDD_DIR, SDD_GITIGNORE_LINE, ensureGitignoreLine, ensureSddDir, } from "../../infra/dogfood.js";
-import { rewriteAgentModel } from "@freeharness/core";
+import { mapModel, rewriteAgentModel } from "@freeharness/core";
 import { initProject } from "@freeharness/sdd/init";
-import { VendoredMemory, vendoredMemoryEngineDir } from "../memory/vendored.js";
+import { PLUGIN_KEY, VendoredMemory, vendoredMemoryEngineDir } from "../memory/vendored.js";
 import { vendoredSddBin } from "../../infra/paths.js";
 import { ROUTING_FILE, routingSourcePath } from "../../infra/routing.js";
 // Re-exported: callers keep importing the routing file name from the claude-code adapter.
 export { ROUTING_FILE } from "../../infra/routing.js";
+const SDD_SKILL = "subagent-driven-development";
+/**
+ * The tier -> model table the SDD skill resolves a brief's `Tier:` through, rendered for one target.
+ * The use column repeats the implementer dispatch rule's classes, since the agents README that
+ * also states them is never emitted and this file is what a dispatching lead reads.
+ */
+function tierReference(target) {
+    const rows = [
+        ["strong", "security and complex (Effort: high), code, any other class or none, every class below"],
+        ["standard", "docs, extraction, exploration, mechanical, summary, code (Route: C1-C7)"],
+        ["fast", "extraction, summary (reading set under 100,000 tokens)"],
+        ["frontier", "agentic-architect role (per dispatch)"],
+    ].map(([tier, use]) => `| ${tier} | ${mapModel(target, tier)} | ${use} |`);
+    const note = target === "opencode" ? "\nA `${OPENCODE_*_MODEL}` placeholder is the provider model id the environment sets.\n" : "";
+    return ["# Tier map", "", "The per-dispatch model for a brief's `Tier:`.", "", "| Tier | Model | Use |", "|------|-------|-----|", ...rows, note].join("\n");
+}
+/** Writes the SDD skill's `reference/tiers.md` under `skillsDir`; nothing when the canonical skills lack the SDD skill. */
+export function emitTierReference(canonicalDir, skillsDir, target, dryRun) {
+    if (!fs.existsSync(path.join(canonicalDir, "skills", SDD_SKILL, "SKILL.md")))
+        return [];
+    return [writeText(path.join(skillsDir, SDD_SKILL, "reference", "tiers.md"), tierReference(target), dryRun)];
+}
 /**
  * Capabilities that live in the machine-global install (~/.claude). At project scope the
  * adapter refuses them unless `allowProjectCopies` is set: Claude Code loads user and
@@ -20,10 +44,16 @@ export const GLOBAL_ONLY_CAPABILITIES = ["skills", "agents", "safety", "cost", "
 export const FH_CONTEXT_COMMAND = path.join(".claude", "commands", "fh-context.md");
 /** SessionStart matcher: compact/resume/fork get the re-orientation block, startup/clear the pointer. */
 export const SESSION_START_MATCHER = "startup|clear|compact|resume|fork";
-/** Flags baked into the hook commands (the fragment defaults; edit settings.json to tune). */
+/**
+ * Flags baked into the hook commands (the fragment defaults). `update` resets FreeHarness
+ * hook flags to these shipped values, so a flag tuned in settings.json does not survive it:
+ * keeping the tuned entry beside the shipped one would run the hook twice.
+ */
 export const OUTPUT_PRUNER_FLAGS = "--max-bytes 8192 --max-lines 200";
 export const CONTEXT_MONITOR_FLAGS = "--budget 200000 --thresholds 60,85";
-export const CONFIG_GUARD_FLAGS = "--ttl 30";
+/** Config-guard allow-marker window in minutes; feeds both the hook flag and the install note. */
+export const CONFIG_GUARD_TTL_MIN = 240;
+export const CONFIG_GUARD_FLAGS = `--ttl ${CONFIG_GUARD_TTL_MIN}`;
 export const REPEAT_TOOL_FLAGS = "--thresholds 3,5,8 --preview-chars 500";
 /**
  * Per-hook timeout (seconds) on SessionEnd entries. Claude Code gives SessionEnd hooks a
@@ -32,6 +62,8 @@ export const REPEAT_TOOL_FLAGS = "--thresholds 3,5,8 --preview-chars 500";
  * pushes past 1.5 s.
  */
 export const SESSION_END_TIMEOUT_S = 10;
+/** Status line quota tap, emitted with the cost capability; the owner wires it, never a settings hook. */
+export const QUOTA_TAP_SCRIPT = "freeharness-quota-tap.mjs";
 /** Every hook script FreeHarness emits (rules + safety + cost capabilities), for doctor and uninstall. */
 export const HOOK_SCRIPTS = [
     "freeharness-session-start",
@@ -43,11 +75,23 @@ export const HOOK_SCRIPTS = [
     "freeharness-output-pruner.mjs",
     "freeharness-context-monitor.mjs",
     "freeharness-precompact.mjs",
-    "freeharness-auto-memory.mjs",
+    "freeharness-reload-context.mjs",
     "freeharness-converge.mjs",
+    "freeharness-sdd-context.mjs",
+    // Doctor warns about a missing tap only when settings.json names it; wrapper wiring is not seen.
+    QUOTA_TAP_SCRIPT,
 ];
 export class ClaudeCodeAdapter {
     target = "claude-code";
+    // The runner keeps one adapter per pass, so a later capability case sees the key this pass
+    // already merged and would report it as the owner's value.
+    autoMemoryMerged = new Set();
+    turnOffAutoMemoryOnce(settingsPath, dry, res) {
+        if (this.autoMemoryMerged.has(settingsPath))
+            return;
+        this.autoMemoryMerged.add(settingsPath);
+        turnOffAutoMemory(settingsPath, dry, res);
+    }
     async apply(cap, ctx) {
         const res = { capabilityId: cap.id, target: this.target, written: [], actions: [], notes: [] };
         const C = ctx.canonicalDir;
@@ -69,9 +113,6 @@ export class ClaudeCodeAdapter {
         const hooksDir = user
             ? path.join(home, ".claude", "freeharness", "hooks")
             : path.join(ctx.projectRoot, ".freeharness", "hooks");
-        const safetyFile = user
-            ? path.join(home, ".claude", "freeharness", "safety.md")
-            : path.join(ctx.projectRoot, ".freeharness", "safety.md");
         const ssScript = path.join(hooksDir, "freeharness-session-start");
         const mgScript = path.join(hooksDir, "freeharness-memory-guard.mjs");
         // user scope bakes an absolute path; project scope uses ${CLAUDE_PROJECT_DIR}.
@@ -89,15 +130,38 @@ export class ClaudeCodeAdapter {
             ? `node "${ctScript}"`
             : 'node "${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-cost-tracker.mjs"';
         const hookCmd = (script, flags) => `${user ? `node "${path.join(hooksDir, script)}"` : `node "\${CLAUDE_PROJECT_DIR}/.freeharness/hooks/${script}"`}${flags ? ` ${flags}` : ""}`;
-        const emitHook = (script, flags, events, note) => {
+        const mergeOwned = (event, entry, ownerKey) => ({ event, r: mergeClaudeHook(settingsPath, event, entry, dry, ownerKey) });
+        const mainNote = (script, cmd, merged, addedNote, presentNote, guard) => {
+            const replaced = merged.flatMap((m) => (m.r.outcome === "replaced" ? [m.r] : []));
+            const hasAdded = merged.some((m) => m.r.outcome === "added");
+            if (replaced.length > 0) {
+                const stale = replaced.find((r) => r.replacedCommand !== undefined)?.replacedCommand;
+                const updatedNote = stale !== undefined
+                    ? `Updated ${script} hook (flags changed: ${stale} -> ${cmd}). Update resets FreeHarness hook flags to the shipped values.`
+                    : replaced.some((r) => r.onFailureChanged)
+                        ? `Updated ${script} hook (onFailure reset to the shipped value).`
+                        : `Updated ${script} hook (collapsed duplicate ${guard ? "guard" : "hook"} entries).`;
+                if (hasAdded)
+                    return [updatedNote, addedNote];
+                return [updatedNote];
+            }
+            if (hasAdded)
+                return [addedNote];
+            return [presentNote];
+        };
+        // A shared entry is never rewritten, so the owner removes that copy by hand.
+        const hookNotes = (script, cmd, merged, addedNote, presentNote, guard = false) => {
+            const shared = merged.filter((m) => m.r.hasSharedCopy).map((m) => `${script} also runs inside a hook entry shared with other commands in ${m.event}; remove it there by hand.`);
+            return [...mainNote(script, cmd, merged, addedNote, presentNote, guard), ...shared];
+        };
+        const emitHook = (script, flags, events, note, guard = false) => {
             res.written.push(writeText(path.join(hooksDir, script), readText(path.join(C, "hooks", script)), dry));
             const cmd = hookCmd(script, flags);
-            let added = false;
-            for (const e of events) {
-                const entry = { ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [{ type: "command", command: cmd, ...(e.event === "SessionEnd" ? { timeout: SESSION_END_TIMEOUT_S } : {}) }] };
-                added = mergeClaudeHook(settingsPath, e.event, entry, dry).added || added;
-            }
-            res.notes.push(added ? `Added ${note}.` : `${script} hook already present.`);
+            const merged = events.map((e) => {
+                const hook = { type: "command", command: cmd, ...(e.event === "SessionEnd" || e.event === "SubagentStop" ? { timeout: SESSION_END_TIMEOUT_S } : {}) };
+                return mergeOwned(e.event, { ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [hook] }, hookCmd(script, ""));
+            });
+            res.notes.push(...hookNotes(script, cmd, merged, `Added ${note}.`, `${script} hook already present.`, guard));
         };
         switch (cap.id) {
             case "rules": {
@@ -127,18 +191,23 @@ export class ClaudeCodeAdapter {
                 }
                 res.written.push(copyExecutable(path.join(C, "hooks", "freeharness-session-start"), ssScript, dry));
                 const ssEntry = { matcher: SESSION_START_MATCHER, hooks: [{ type: "command", command: ssCmd, async: false }] };
-                const ss = mergeClaudeHook(settingsPath, "SessionStart", ssEntry, dry);
-                res.notes.push(ss.added ? "Added SessionStart pointer hook (additive; claude-mem untouched; compact/resume re-inject the checkpoint)." : "SessionStart hook already present.");
+                // The session-start script runs without `node`, so its quoted path alone is the owner key.
+                const ss = mergeOwned("SessionStart", ssEntry, ssCmd);
+                res.notes.push(...hookNotes("freeharness-session-start", ssCmd, [ss], "Added SessionStart pointer hook (additive; memory plugin hooks untouched; compact/resume re-inject the checkpoint).", "SessionStart hook already present."));
                 // Routing table beside the script the hook reads it from.
                 res.written.push(writeText(path.join(hooksDir, ROUTING_FILE), readText(routingSourcePath(C)), dry));
                 res.written.push(writeText(mgScript, readText(path.join(C, "hooks", "freeharness-memory-guard.mjs")), dry));
+                // The guards sit under the permission layer, so a guard that cannot run allows the call.
                 const mgEntry = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: mgCmd }] };
-                const mg = mergeClaudeHook(settingsPath, "PreToolUse", mgEntry, dry);
-                res.notes.push(mg.added ? "Added memory-guard hook (PreToolUse denies memory .md writes; saves tokens)." : "Memory-guard hook already present.");
-                emitHook("freeharness-config-guard.mjs", CONFIG_GUARD_FLAGS, [{ event: "PreToolUse", matcher: "Edit|Write|MultiEdit|Bash" }], "config-guard hook (PreToolUse denies settings/.mcp.json/hook/CLAUDE.md writes without .freeharness/allow-config-edit)");
+                const mg = mergeOwned("PreToolUse", mgEntry, mgCmd);
+                res.notes.push(...hookNotes("freeharness-memory-guard.mjs", mgCmd, [mg], "Added memory-guard hook (PreToolUse denies memory .md writes; saves tokens).", "Memory-guard hook already present.", true));
+                emitHook("freeharness-config-guard.mjs", CONFIG_GUARD_FLAGS, [{ event: "PreToolUse", matcher: "Edit|Write|MultiEdit|Bash" }], `config-guard hook (PreToolUse denies edits to live configuration by location: settings in a .claude directory, .mcp.json, the user .claude.json and CLAUDE.md, hook directories and the plugin tree, unless an allow marker from the last ${CONFIG_GUARD_TTL_MIN} minutes is present)`, true);
                 emitHook("freeharness-repeat-tool.mjs", REPEAT_TOOL_FLAGS, [{ event: "PreToolUse" }, { event: "UserPromptSubmit" }], "repeat-tool hook (PreToolUse reminds at 3/5/8 identical calls; UserPromptSubmit resets; advisory)");
                 // Memory-independent: the skeleton is built locally; the worker summary is best effort.
-                emitHook("freeharness-precompact.mjs", "", [{ event: "PreCompact" }], "precompact hook (PreCompact writes the checkpoint skeleton + file-op list for SessionStart and asks a running claude-mem worker for a summary; worker down = skipped)");
+                emitHook("freeharness-precompact.mjs", "", [{ event: "PreCompact" }], "precompact hook (PreCompact writes the checkpoint skeleton + file-op list for SessionStart and asks a running memory worker for a summary; worker down = skipped)");
+                emitHook("freeharness-reload-context.mjs", "", [{ event: "UserPromptSubmit" }], "reload-context hook (UserPromptSubmit answers the exact prompt `reload context` with the newest saved handoff or PreCompact skeleton; other prompts untouched)");
+                if (user && freeMemEnabled(claudeDir))
+                    this.turnOffAutoMemoryOnce(settingsPath, dry, res);
                 break;
             }
             case "skills": {
@@ -146,6 +215,7 @@ export class ClaudeCodeAdapter {
                     transform: (c) => rewriteAgentModel(c, this.target),
                     transformOnly: (n) => n === "SKILL.md",
                 }));
+                res.written.push(...emitTierReference(C, skillsDir, this.target, dry));
                 const rfScripts = path.join(skillsDir, "report-formatting", "scripts");
                 res.actions.push({
                     description: "Install report-formatting .docx deps (docx, image-size)",
@@ -168,13 +238,12 @@ export class ClaudeCodeAdapter {
                 }));
                 break;
             case "safety": {
-                res.written.push(writeText(safetyFile, readText(path.join(C, "rules", "safety.md")), dry));
                 // Advisory PreToolUse hook: warns on vulnerability sinks in Edit/Write content,
                 // never blocks. Same additive merge as the memory guard.
                 res.written.push(writeText(sgScript, readText(path.join(C, "hooks", "freeharness-security-guidance.mjs")), dry));
                 const sgEntry = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: sgCmd }] };
-                const sg = mergeClaudeHook(settingsPath, "PreToolUse", sgEntry, dry);
-                res.notes.push(sg.added ? "Added security-guidance hook (PreToolUse warns on vulnerability sinks; advisory only)." : "Security-guidance hook already present.");
+                const sg = mergeOwned("PreToolUse", sgEntry, sgCmd);
+                res.notes.push(...hookNotes("freeharness-security-guidance.mjs", sgCmd, [sg], "Added security-guidance hook (PreToolUse warns on vulnerability sinks; advisory only).", "Security-guidance hook already present."));
                 break;
             }
             case "sdd": {
@@ -226,14 +295,9 @@ export class ClaudeCodeAdapter {
                 break;
             }
             case "memory": {
-                // Optional tier-0 spike, off by default (FREEHARNESS_AUTO_MEMORY=on); registered even
-                // when the vendored engine is absent because it only reads the dogfood log.
-                emitHook("freeharness-auto-memory.mjs", "", [{ event: "SessionEnd" }], "auto-memory hook (SessionEnd curates one line per project into ~/.claude/freeharness/MEMORY.md; OFF until FREEHARNESS_AUTO_MEMORY=on)");
                 const engineDir = vendoredMemoryEngineDir(C);
                 if (!engineDir) {
-                    // --bridge fallback: vendored engine absent; upstream installer does the rest.
-                    res.actions.push({ description: "Install claude-mem plugin + wire hooks/MCP (bridge: vendored engine absent)", command: "npx claude-mem install", optional: true });
-                    res.notes.push("Vendored engine not found; bridging to upstream `npx claude-mem install`.");
+                    res.notes.push("Vendored engine not found; the memory capability is skipped.");
                     break;
                 }
                 // Real plugin install from OUR build (MemoryPort). Dry-run previews every step
@@ -253,6 +317,9 @@ export class ClaudeCodeAdapter {
                 merge(await mem.migrateExisting(ctx));
                 merge(await mem.install(ctx.scope, ctx));
                 merge(await mem.registerHooks(ctx.scope, ctx));
+                // Registering enables free-mem, so the key follows in the same run; pass 1 previews it.
+                if (user)
+                    this.turnOffAutoMemoryOnce(settingsPath, dry, res);
                 res.notes.push("Worker start + recall are verified on the machine (needs the Claude Agent SDK key / network); not exercised by the installer.");
                 break;
             }
@@ -264,29 +331,30 @@ export class ClaudeCodeAdapter {
                         continue;
                     res.actions.push({
                         description: `Register MCP server ${s.name}${s.optional ? " (optional)" : ""}`,
-                        command: `claude mcp add ${s.name} -s ${sc} -- ${s.command} ${s.args.join(" ")}`,
+                        // `claude mcp add` exits 1 for a registered name; the get guard keeps a re-run quiet.
+                        command: `claude mcp get ${s.name} >/dev/null 2>&1 || claude mcp add ${s.name} -s ${sc} -- ${s.command} ${s.args.join(" ")}`,
                         optional: true, // a failing/missing `claude` must not abort the whole install
                     });
                 }
                 break;
             }
             case "cost": {
-                // Stop + SessionEnd append usage snapshots to cost/usage.jsonl; the price table is
-                // seeded once and never overwritten (the user edits it to the account's contract).
                 res.written.push(writeText(ctScript, readText(path.join(C, "hooks", "freeharness-cost-tracker.mjs")), dry));
-                const prices = writeTextIfAbsent(ctPrices, readText(path.join(C, "hooks", "cost-prices.json")), dry);
-                res.written.push(prices.path);
-                if (prices.skipped)
-                    (res.skipped ??= []).push(prices.path);
-                const stop = mergeClaudeHook(settingsPath, "Stop", { hooks: [{ type: "command", command: ctCmd }] }, dry);
-                const end = mergeClaudeHook(settingsPath, "SessionEnd", { hooks: [{ type: "command", command: ctCmd, timeout: SESSION_END_TIMEOUT_S }] }, dry);
+                applyPriceTable(ctPrices, readText(path.join(C, "hooks", "cost-prices.json")), dry, res);
+                const stop = mergeOwned("Stop", { hooks: [{ type: "command", command: ctCmd }] }, ctCmd);
+                const end = mergeOwned("SessionEnd", { hooks: [{ type: "command", command: ctCmd, timeout: SESSION_END_TIMEOUT_S }] }, ctCmd);
                 // SubagentStop mirrors SessionEnd: a long dispatch also pushes the subagent's own
                 // transcript past the default budget.
-                const subagentStop = mergeClaudeHook(settingsPath, "SubagentStop", { hooks: [{ type: "command", command: ctCmd, timeout: SESSION_END_TIMEOUT_S }] }, dry);
-                res.notes.push(stop.added || end.added || subagentStop.added ? "Added cost-tracker hooks (Stop + SessionEnd + SubagentStop append usage/ledger entries; never block)." : "Cost-tracker hooks already present.");
-                res.notes.push(prices.skipped ? `Price table kept as is: ${ctPrices} (edit to your contract).` : `Price table seeded at ${ctPrices} — placeholders; edit to your contract. Report: freeharness cost report.`);
+                const subagentStop = mergeOwned("SubagentStop", { hooks: [{ type: "command", command: ctCmd, timeout: SESSION_END_TIMEOUT_S }] }, ctCmd);
+                res.notes.push(...hookNotes("freeharness-cost-tracker.mjs", ctCmd, [stop, end, subagentStop], "Added cost-tracker hooks (Stop + SessionEnd + SubagentStop append usage/ledger entries; never block).", "Cost-tracker hooks already present."));
                 emitHook("freeharness-output-pruner.mjs", OUTPUT_PRUNER_FLAGS, [{ event: "PostToolUse", matcher: "Bash" }], "output-pruner hook (PostToolUse trims Bash output over 8 KB / 200 lines; full copy under ~/.claude/freeharness/tool-output/)");
-                emitHook("freeharness-context-monitor.mjs", CONTEXT_MONITOR_FLAGS, [{ event: "Stop" }], "context-monitor hook (Stop warns the user once at 60% and 85% of the context budget)");
+                emitHook("freeharness-context-monitor.mjs", CONTEXT_MONITOR_FLAGS, [{ event: "Stop" }], "context-monitor hook (Stop warns the user once at 60% and 85% of the context budget, writes a handoff at the highest threshold and suggests /clear)");
+                // Emitted beside the tracker, whose brief-path rule it imports from its own directory.
+                emitHook("freeharness-sdd-context.mjs", "", [{ event: "SubagentStart" }, { event: "SubagentStop" }], "sdd-context hook (SubagentStart gives every subagent a free-mem project brief; SubagentStop saves an implementer's checkpoint to the task state and leaves the report, tagged with its change and task, with the worker; FREEHARNESS_SDD_CONTEXT_WORKER=off turns the worker calls off)");
+                // The status line feeds the tap, not a hook event: no settings entry, and statusLine
+                // stays the owner's to wire.
+                res.written.push(writeText(path.join(hooksDir, QUOTA_TAP_SCRIPT), readText(path.join(C, "hooks", QUOTA_TAP_SCRIPT)), dry));
+                res.notes.push(`${QUOTA_TAP_SCRIPT} emitted; pipe your status line input to it by hand to record quota readings (Documents/ADVANCED.md, Quota tap). FreeHarness never writes statusLine.`);
                 // Cache-hygiene settings: additive, existing keys win.
                 const tpl = JSON.parse(readText(path.join(C, "settings", "settings.cache-hygiene.claude-code.json")));
                 const merged = mergeSettingsKeys(settingsPath, tpl, dry);
@@ -302,6 +370,109 @@ export class ClaudeCodeAdapter {
         return res;
     }
 }
+/**
+ * Mirrors `freeMemEnabled` in `../../cli/install-facts.js`, duplicated rather than
+ * shared: adapters never import the cli layer (`scripts/check-arch.mjs`). Exported so a
+ * test can hold both copies to the same answers.
+ */
+export function freeMemEnabled(claudeDir) {
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(path.join(claudeDir, "settings.json"), "utf8"));
+    }
+    catch {
+        return false;
+    }
+    return settings?.enabledPlugins?.[PLUGIN_KEY] === true;
+}
+/**
+ * free-mem is the only memory owner; Claude Code auto memory (and agent memory with it) would
+ * keep a second store nothing recalls. Added only when absent, so an owner's explicit value wins.
+ */
+export function turnOffAutoMemory(settingsPath, dry, res) {
+    let merged;
+    try {
+        merged = mergeSettingsKeys(settingsPath, { autoMemoryEnabled: false }, dry);
+    }
+    catch (e) {
+        const reason = e instanceof SyntaxError ? "not parsed" : "not updated";
+        res.notes.push(`autoMemoryEnabled not set: ${settingsPath} ${reason} (${e instanceof Error ? e.message : String(e)}).`);
+        return;
+    }
+    if (merged.added.length > 0) {
+        res.notes.push(`${dry ? "Would add" : "Added"} autoMemoryEnabled = false to ${settingsPath} (free-mem is the only memory; Claude Code auto memory and agent memory off).`);
+    }
+    else {
+        res.notes.push(`autoMemoryEnabled already set in ${settingsPath}; left as the owner set it.`);
+    }
+}
+/** Seeds the price table once, then merges missing rows and previously shipped values into it on later runs. */
+function applyPriceTable(file, shippedText, dry, res) {
+    if (!fs.existsSync(file)) {
+        const seeded = writeTextIfAbsent(file, shippedText, dry);
+        res.written.push(seeded.path);
+        res.notes.push(`Price table seeded at ${file} — placeholders; edit to your contract. Report: freeharness cost report.`);
+        return;
+    }
+    res.written.push(file);
+    // An unreadable table is left as is.
+    let installedText;
+    try {
+        installedText = readText(file);
+    }
+    catch (e) {
+        (res.skipped ??= []).push(file);
+        res.notes.push(`Price table left as is (${e instanceof Error ? e.message : String(e)}): ${file}.`);
+        return;
+    }
+    const merge = mergePriceTable(installedText, shippedText);
+    if ("warning" in merge) {
+        (res.skipped ??= []).push(file);
+        res.notes.push(`Price table left as is (${merge.warning}): ${file}.`);
+        return;
+    }
+    if (merge.added.length === 0 && merge.corrected.length === 0) {
+        (res.skipped ??= []).push(file);
+        res.notes.push(`Price table kept as is: ${file} (edit to your contract).`);
+        return;
+    }
+    // Pass-2 notes never print; one wording covers both.
+    const changes = [
+        ...(merge.added.length > 0 ? [`adds rows ${merge.added.join(", ")}`] : []),
+        ...(merge.corrected.length > 0 ? [`corrects ${merge.corrected.length} previously shipped value(s)`] : []),
+    ];
+    res.notes.push(`Price table ${file}: ${changes.join("; ")}.`);
+    for (const key of merge.added)
+        res.notes.push(`add ${key}`);
+    for (const c of merge.corrected) {
+        res.notes.push(`correct ${c.row}.${c.field} ${JSON.stringify(c.from)} -> ${JSON.stringify(c.to)}`);
+    }
+    if (dry) {
+        (res.skipped ??= []).push(file);
+        return;
+    }
+    // Merge into the symlink's real path so its link survives.
+    let target = file;
+    try {
+        if (fs.lstatSync(file).isSymbolicLink())
+            target = fs.realpathSync(file);
+    }
+    catch (e) {
+        (res.skipped ??= []).push(file);
+        res.notes.push(`Price table left as is (symlink target unreadable: ${e instanceof Error ? e.message : String(e)}): ${file}.`);
+        return;
+    }
+    // Random suffix + "wx" refuse a symlinked temp path.
+    const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        fs.writeFileSync(tmp, merge.text, { encoding: "utf8", flag: "wx" });
+        fs.renameSync(tmp, target);
+    }
+    catch (e) {
+        fs.rmSync(tmp, { force: true });
+        throw e;
+    }
+}
 /**
  * Splits a model id on a trailing `[suffix]` tag (e.g. `claude-fable-5-1[1m]`). Mirrors
  * `splitModelSuffix` in `../../cli/doctor.js`, duplicated here rather than shared: adapters

package/dist/adapters/harness/opencode.js

@@ -6,7 +6,7 @@ import { routingSourcePath } from "../../infra/routing.js";
 import { frontmatterHasKey, rewriteAgentModel, stripAgentKeys } from "@freeharness/core";
 import { initProject } from "@freeharness/sdd/init";
 import { vendoredSddBin } from "../../infra/paths.js";
-import { seedProjectEvidence } from "./claude-code.js";
+import { emitTierReference, seedProjectEvidence } from "./claude-code.js";
 /**
  * Whether any canonical agent (excluding README.md) carries a `memory:` front matter key.
  * Reads the source tree directly, independent of `dryRun`, so a preview names the same
@@ -36,6 +36,19 @@ function anyAgentCarriesMemoryKey(agentsSrc) {
     };
     return walk(agentsSrc);
 }
+/**
+ * Drops the free-mem MCP tool ids from an agent's `tools:` front matter line. OpenCode runs no
+ * free-mem MCP server, so an agent naming those tools would list tools it can never call; the
+ * line's other entries keep their order.
+ * @param content The agent file text.
+ * @returns The text with every `mcp__plugin_free-mem_` entry removed from the first `tools:` line.
+ */
+function dropFreeMemTools(content) {
+    return content.replace(/^tools:[ \t]*(.*)$/m, (_line, list) => {
+        const kept = list.split(",").map((t) => t.trim()).filter((t) => t && !t.startsWith("mcp__plugin_free-mem_"));
+        return `tools: ${kept.join(", ")}`;
+    });
+}
 // OpenCode adapter: emits AGENTS.md + best-effort skill/agent layouts; no session-start hook (OpenCode has no hook contract we emit to).
 export class OpenCodeAdapter {
     target = "opencode";
@@ -65,6 +78,7 @@ export class OpenCodeAdapter {
                     transform: (c) => stripAgentKeys(c, ["disable-model-invocation", "context", "agent", "model"]),
                     transformOnly: (n) => n === "SKILL.md",
                 }));
+                res.written.push(...emitTierReference(C, path.join(P, ".opencode", "skills"), this.target, dry));
                 res.notes.push("Skills emitted to .opencode/skills (verify against your OpenCode version).");
                 const rfScripts = path.join(P, ".opencode", "skills", "report-formatting", "scripts");
                 res.actions.push({
@@ -86,7 +100,7 @@ export class OpenCodeAdapter {
                 const droppedMemoryKey = anyAgentCarriesMemoryKey(agentsSrc);
                 res.written.push(...copyDir(agentsSrc, path.join(P, ".opencode", "agent"), dry, {
                     skip: (name) => name === "README.md",
-                    transform: (content) => stripAgentKeys(rewriteAgentModel(content, this.target), ["memory"]),
+                    transform: (content) => dropFreeMemTools(stripAgentKeys(rewriteAgentModel(content, this.target), ["memory", "effort", "omitClaudeMd", "cache_ttl"])),
                 }));
                 res.notes.push("Agent model tiers mapped to ${OPENCODE_*_MODEL} placeholders; fill them in.");
                 if (droppedMemoryKey)
@@ -94,7 +108,7 @@ export class OpenCodeAdapter {
                 break;
             }
             case "safety":
-                res.written.push(writeText(path.join(P, ".freeharness", "safety.md"), readText(path.join(C, "rules", "safety.md")), dry));
+                res.notes.push("safety: OpenCode has no hook contract FreeHarness emits to; nothing emitted.");
                 break;
             case "sdd": {
                 const src = path.join(C, "openspec");

package/dist/adapters/harness/plugin.js

@@ -9,36 +9,44 @@ import { rewriteAgentModel } from "@freeharness/core";
 import { copyDir, copyExecutable, readText, writeText } from "../../infra/fsutil.js";
 import { cliVersion } from "../../infra/paths.js";
 import { ROUTING_FILE, routingSourcePath } from "../../infra/routing.js";
-import { CONFIG_GUARD_FLAGS, CONTEXT_MONITOR_FLAGS, OUTPUT_PRUNER_FLAGS, REPEAT_TOOL_FLAGS, SESSION_END_TIMEOUT_S, SESSION_START_MATCHER } from "./claude-code.js";
+import { CONFIG_GUARD_FLAGS, CONTEXT_MONITOR_FLAGS, OUTPUT_PRUNER_FLAGS, REPEAT_TOOL_FLAGS, SESSION_END_TIMEOUT_S, SESSION_START_MATCHER, emitTierReference } from "./claude-code.js";
 /** Plugin directory name inside the project root. */
 export const PLUGIN_DIR_NAME = "freeharness-plugin";
 /** Marketplace name (the `@marketplace` suffix in `claude plugin install freeharness@...`). */
 export const MARKETPLACE_NAME = "freeharness-local";
 /**
  * Additively merges a hook entry into the plugin's hooks.json (dedupe by command; the file is
- * created with the official `description` + `hooks` shape).
+ * created with the official `description` + `hooks` shape). Entries running only this command
+ * fold into the first one, rewritten to the current entry, so a re-emit drops a stale `onFailure`
+ * field and a stale copy never keeps running beside a current one; an entry mixing it with other
+ * commands is left as is.
  * @param file Absolute path of hooks/hooks.json.
  * @param event Hook event name (SessionStart, PreToolUse, ...).
  * @param entry Entry to add.
  * @param dryRun When true nothing is written.
- * @returns Whether the entry was added (false when already present).
+ * @returns Whether the file changed (false when the entry was already current).
  */
 function mergePluginHook(file, event, entry, dryRun) {
     let doc = {
-        description: "FreeHarness hooks: SessionStart pointer (+ post-compaction re-orientation), PreCompact checkpoint, memory guard, config guard, repeat-tool reminder, security guidance (advisory), cost tracker, output pruner, context monitor, auto-memory (flag-gated). Additive; only the memory guard and the config guard deny.",
+        description: "FreeHarness hooks: SessionStart pointer (+ post-compaction re-orientation), PreCompact checkpoint, reload-context recap, memory guard, config guard, repeat-tool reminder, security guidance (advisory), cost tracker, output pruner, context monitor, SDD context (SubagentStart task state and open findings, SubagentStop checkpoint written to the task state). Additive; only the memory guard and the config guard deny.",
         hooks: {},
     };
     if (fs.existsSync(file))
         doc = JSON.parse(fs.readFileSync(file, "utf8"));
     doc.hooks ??= {};
     doc.hooks[event] ??= [];
-    const cmd = entry.hooks[0].command;
-    const exists = doc.hooks[event].some((e) => e.hooks.some((h) => h.command === cmd));
-    if (!exists)
-        doc.hooks[event].push(entry);
-    if (!dryRun && !exists)
+    const { command: cmd, onFailure } = entry.hooks[0];
+    const arr = doc.hooks[event];
+    const own = arr.flatMap((e, i) => (e.hooks.length === 1 && e.hooks[0].command === cmd ? [i] : []));
+    const exists = arr.some((e) => e.hooks.some((h) => h.command === cmd));
+    const changed = own.length > 1 || (own.length === 1 && arr[own[0]].hooks[0].onFailure !== onFailure) || !exists;
+    if (own.length > 0 && changed)
+        doc.hooks[event] = arr.flatMap((e, i) => (i === own[0] ? [entry] : own.includes(i) ? [] : [e]));
+    else if (!exists)
+        arr.push(entry);
+    if (!dryRun && changed)
         writeText(file, JSON.stringify(doc, null, 2) + "\n", false);
-    return !exists;
+    return changed;
 }
 /**
  * Emits the FreeHarness content as a Claude Code plugin directory under
@@ -63,7 +71,8 @@ export class PluginAdapter {
         const emitHook = (script, flags, events) => {
             res.written.push(writeText(path.join(hooksDir, script), readText(path.join(C, "hooks", script)), dry));
             for (const e of events) {
-                const entry = { ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [{ type: "command", command: hookCmd(script, "node", flags), ...(e.event === "SessionEnd" ? { timeout: SESSION_END_TIMEOUT_S } : {}) }] };
+                const hook = { type: "command", command: hookCmd(script, "node", flags), ...(e.event === "SessionEnd" || e.event === "SubagentStop" ? { timeout: SESSION_END_TIMEOUT_S } : {}) };
+                const entry = { ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [hook] };
                 mergePluginHook(hooksFile, e.event, entry, dry);
             }
         };
@@ -82,11 +91,13 @@ export class PluginAdapter {
                 // it from its own directory regardless of which target installed it.
                 res.written.push(writeText(path.join(hooksDir, ROUTING_FILE), readText(routingSourcePath(C)), dry));
                 res.written.push(writeText(path.join(hooksDir, "freeharness-memory-guard.mjs"), readText(path.join(C, "hooks", "freeharness-memory-guard.mjs")), dry));
+                // The guards sit under the permission layer, so a guard that cannot run allows the call.
                 const mg = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: hookCmd("freeharness-memory-guard.mjs") }] };
                 mergePluginHook(hooksFile, "PreToolUse", mg, dry);
                 emitHook("freeharness-config-guard.mjs", CONFIG_GUARD_FLAGS, [{ event: "PreToolUse", matcher: "Edit|Write|MultiEdit|Bash" }]);
                 emitHook("freeharness-repeat-tool.mjs", REPEAT_TOOL_FLAGS, [{ event: "PreToolUse" }, { event: "UserPromptSubmit" }]);
                 emitHook("freeharness-precompact.mjs", "", [{ event: "PreCompact" }]);
+                emitHook("freeharness-reload-context.mjs", "", [{ event: "UserPromptSubmit" }]);
                 res.written.push(hooksFile);
                 break;
             }
@@ -95,6 +106,7 @@ export class PluginAdapter {
                     transform: (c) => rewriteAgentModel(c, this.target),
                     transformOnly: (n) => n === "SKILL.md",
                 }));
+                res.written.push(...emitTierReference(C, path.join(root, "skills"), this.target, dry));
                 res.notes.push("skills: report-formatting runtime deps (docx/python-pptx) are installed by the user after the plugin loads (see the plugin README).");
                 break;
             case "agents":
@@ -104,7 +116,7 @@ export class PluginAdapter {
                 }));
                 break;
             case "safety": {
-                res.notes.push("safety: rules/safety.md is a rules file (not a plugin component); only the advisory security-guidance hook ships in the plugin.");
+                res.notes.push("safety: the advisory security-guidance hook ships in the plugin.");
                 res.written.push(writeText(path.join(hooksDir, "freeharness-security-guidance.mjs"), readText(path.join(C, "hooks", "freeharness-security-guidance.mjs")), dry));
                 const sg = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: hookCmd("freeharness-security-guidance.mjs") }] };
                 mergePluginHook(hooksFile, "PreToolUse", sg, dry);
@@ -136,6 +148,8 @@ export class PluginAdapter {
                 res.notes.push("cost: SessionEnd hooks run under Claude Code's shared 1.5 s budget, which a plugin timeout does not raise; set CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=10000 for long transcripts.");
                 emitHook("freeharness-output-pruner.mjs", OUTPUT_PRUNER_FLAGS, [{ event: "PostToolUse", matcher: "Bash" }]);
                 emitHook("freeharness-context-monitor.mjs", CONTEXT_MONITOR_FLAGS, [{ event: "Stop" }]);
+                // Beside the tracker: the hook imports its brief-path rule from its own directory.
+                emitHook("freeharness-sdd-context.mjs", "", [{ event: "SubagentStart" }, { event: "SubagentStop" }]);
                 res.written.push(hooksFile);
                 res.notes.push("cost: the hook prices with hooks/cost-prices.json next to it (placeholders; edit, or point FREEHARNESS_COST_PRICES at your table).");
                 res.notes.push("cost: a plugin cannot set settings keys; add promptCacheTtl / subagentPromptCacheTtl = 1h to ~/.claude/settings.json by hand or with `freeharness init --scope user --only cost`.");
@@ -149,9 +163,6 @@ export class PluginAdapter {
                 break;
             case "memory":
                 res.notes.push("memory: not a plugin component (free-mem is its own plugin, built and registered by `freeharness init --scope user --only memory`).");
-                emitHook("freeharness-auto-memory.mjs", "", [{ event: "SessionEnd" }]);
-                res.notes.push("memory: the auto-memory tier-0 hook ships (SessionEnd; a no-op until FREEHARNESS_AUTO_MEMORY=on).");
-                res.written.push(hooksFile);
                 break;
             default:
                 res.notes.push(`No plugin action for capability '${cap.id}'.`);
@@ -245,8 +256,8 @@ its agents, skills, and hooks.
 
 ## What is not in the plugin
 
-- Behavior rules (\`CLAUDE.md\`) and \`safety.md\`: not plugin components. Install them per user with
-  \`freeharness init --scope user --only rules,safety\`.
+- Behavior rules (\`CLAUDE.md\`): not a plugin component. Install them per user with
+  \`freeharness init --scope user --only rules\`. The security-guidance hook ships in the plugin.
 - SDD (OpenSpec \`/opsx\`): per-project init, \`freeharness bootstrap\` inside the project.
 - Memory (free-mem): its own plugin, \`freeharness init --scope user --only memory\`.
 - Report-formatting runtime deps: after install run \`npm install\` in