@damiangilgonzalez/harness 1.3.11 → 1.3.13

package/targets/agents-md-shadow.js

@@ -0,0 +1,153 @@
+// agents-md-shadow.js — keep the always-on body from arriving twice in Claude Code.
+//
+// THE DEFECT. rsc delivers its always-on layer through two different surfaces, one per
+// assistant family:
+//   - Claude Code  → a SessionStart hook (targets/claude.js) that PRINTS suggest's body.
+//   - AGENTS.md family (codex, opencode, amp, jules, zed) → the body is written INTO the
+//     root AGENTS.md between markers (targets/_md-block.js).
+// Wiring both in one project is an ordinary install — this repo's own workspace does it.
+// Until Claude Code 2.1.277 the two never met, because Claude Code did not read AGENTS.md.
+//
+// From 2.1.277 it does: with NO CLAUDE.md in the working directory or above it, Claude Code
+// reads the root AGENTS.md as the project instructions. In a dual-wired project that makes
+// the same ~7 KB body land twice per session — once printed by the hook, once loaded from
+// the file. Anthropic documents the shape of this exact collision and its remedy ("A
+// SessionStart hook that prints AGENTS.md: remove it. Once Claude reads AGENTS.md directly,
+// the hook adds a second copy to the context").
+//
+// WHY THIS IS NOT SOLVED BY MAKING THE HOOK STAY SILENT. The hook cannot know whether it is
+// talking to a Claude Code that reads AGENTS.md: the SessionStart payload carries session_id,
+// cwd, source and sometimes model — there is no version field, and no env var exposes one.
+// Staying silent on a guess would, on every client older than 2.1.277, swallow the always-on
+// layer completely. hook-once.mjs states the rule this file obeys: "A duplicated block costs
+// context; a swallowed always-on layer costs the session its behaviour."
+//
+// THE FIX, version-free. Claude Code reads AGENTS.md only when no CLAUDE.md exists. So give
+// it one. A CLAUDE.md at the project root makes every Claude Code — old or new — take the
+// hook as the single source of the always-on body, and leaves AGENTS.md to the assistants it
+// was written for. No version sniffing, no guess, same bytes on every client.
+//
+// The shadow deliberately does NOT `@AGENTS.md`-import: the import would expand the rsc block
+// into context and recreate the duplication it exists to prevent.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+
+// The marker _md-block.js wraps the always-on body in. Its presence in a root AGENTS.md is
+// what makes that file a second carrier of the body rather than the user's own prose.
+const SUGGEST_MARK = '<!-- rsc-suggest:start -->';
+
+// Identifies a CLAUDE.md as ours. Block-level HTML comments are stripped from Claude Code's
+// context before injection, so everything explanatory below costs the user zero tokens.
+export const SHADOW_MARK = '<!-- rsc:claude-md-shadow -->';
+
+export const SHADOW_BODY = `${SHADOW_MARK}
+# Project instructions
+
+Claude Code reads this file. Every other assistant wired in this project reads \`AGENTS.md\`.
+
+Project instructions for Claude Code go below.
+
+<!--
+  Why rsc created this file
+  =========================
+  rsc's always-on layer reaches Claude Code through its SessionStart hook, and reaches the
+  AGENTS.md-family assistants through the root AGENTS.md. From Claude Code 2.1.277, a project
+  with no CLAUDE.md is read through AGENTS.md directly — which would deliver that same body a
+  second time, every session. The existence of this file is what prevents it.
+
+  Do NOT add "@AGENTS.md" here: the import would expand the always-on block into context and
+  bring the duplication back.
+
+  rsc removes this file on uninstall while it is still untouched. Edit it and it is yours —
+  rsc then leaves it alone, and it keeps doing its job just as well.
+-->
+`;
+
+// The three files whose presence stops Claude Code reading AGENTS.md (per its memory docs).
+// A user's own CLAUDE.md already does the shadow's job, so we never touch a project that has one.
+const CLAUDE_MD_FORMS = ['CLAUDE.md', join('.claude', 'CLAUDE.md'), 'CLAUDE.local.md'];
+
+// Claude Code looks for those files in the working directory AND every directory above it, so a
+// CLAUDE.md two levels up already suppresses the AGENTS.md read. Walking up costs a few stats and
+// keeps us from planting a file that was never needed.
+function claudeMdAboveOrAt(root) {
+  let dir = root;
+  for (;;) {
+    for (const form of CLAUDE_MD_FORMS) if (existsSync(join(dir, form))) return join(dir, form);
+    const up = dirname(dir);
+    if (up === dir || dir === parse(dir).root) return null;
+    dir = up;
+  }
+}
+
+// Is the Claude Code target wired in this project? Same predicate session-start.mjs and doctor
+// use: an rsc command in .claude/settings.json. The backslash normalization is not cosmetic —
+// a Windows install stores the path with separators that JSON escapes as pairs, and reading only
+// for `.rsc/` answered "not wired" on the exact platform where duplication hurt most.
+function claudeWired(root) {
+  try {
+    return readFileSync(join(root, '.claude', 'settings.json'), 'utf8')
+      .replace(/\\\\/g, '/')
+      .includes('.rsc/');
+  } catch { return false; }
+}
+
+// Does the root AGENTS.md carry rsc's always-on block (as opposed to being the user's own prose)?
+function agentsMdCarriesBody(root) {
+  try { return readFileSync(join(root, 'AGENTS.md'), 'utf8').includes(SUGGEST_MARK); } catch { return false; }
+}
+
+/**
+ * Write the shadow CLAUDE.md when — and only when — this project is in the configuration that
+ * duplicates: Claude Code wired, the root AGENTS.md carrying rsc's block, and no CLAUDE.md of
+ * any form at the root or above it.
+ *
+ * Called from BOTH adapters' wireHook. Installs run one target per call, so whichever of the two
+ * is wired second is the one that sees the full picture; calling from both is what makes the fix
+ * independent of the order the user picks their assistants in.
+ *
+ * @returns the path written, or null when nothing was needed. Never throws: a shadow we could not
+ * write costs context, and that must not be the thing that fails an install.
+ */
+export function ensureShadowClaudeMd(projectRoot) {
+  try {
+    const dest = shadowTarget(projectRoot);
+    if (!dest) return null;
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, SHADOW_BODY);
+    return dest;
+  } catch { return null; }
+}
+
+/**
+ * Where the shadow would go, or null when this project does not need one — the decision without
+ * the write, so the installer can declare the file BEFORE it exists. A path this returns but the
+ * install plan omits is a file no --dry-run mentions and no `rsc restore` can bring back.
+ *
+ * @param assumeClaudeWired for a claude install in flight: settings.json names the project as
+ * wired only after wireHook writes it, so at plan time the answer has to be assumed, not read.
+ */
+export function shadowTarget(projectRoot, { assumeClaudeWired = false } = {}) {
+  try {
+    if (!assumeClaudeWired && !claudeWired(projectRoot)) return null;
+    if (!agentsMdCarriesBody(projectRoot)) return null;
+    if (claudeMdAboveOrAt(projectRoot)) return null;
+    return join(projectRoot, 'CLAUDE.md');
+  } catch { return null; }
+}
+
+/**
+ * Take back exactly what we gave: remove the shadow only while it is byte-identical to what
+ * ensureShadowClaudeMd wrote. The moment the user edits it, it is their project instructions —
+ * uninstalling rsc must not delete those. Same discipline _md-block.js applies to its block.
+ *
+ * @returns the path removed, or null.
+ */
+export function removeShadowClaudeMd(projectRoot) {
+  try {
+    const dest = join(projectRoot, 'CLAUDE.md');
+    if (readFileSync(dest, 'utf8') !== SHADOW_BODY) return null;
+    rmSync(dest, { force: true });
+    return dest;
+  } catch { return null; }
+}

package/targets/agents.js

@@ -32,7 +32,7 @@ const AGENT_TARGETS = {
   claude: { dir: '.claude/agents', ext: '.md', format: 'md', model: (t) => (t === 'heavy' ? 'opus' : 'sonnet') },
   junie: { dir: '.junie/agents', ext: '.md', format: 'md', model: (t) => (t === 'heavy' ? 'opus' : 'sonnet') },
   cursor: { dir: '.cursor/agents', ext: '.md', format: 'md', model: (t) => TIER_MODEL.anthropic[t] },
-  opencode: { dir: '.opencode/agents', ext: '.md', format: 'md', mode: 'subagent', model: (t) => `anthropic/${TIER_MODEL.anthropic[t]}` },
+  opencode: { dir: '.opencode/agents', ext: '.md', format: 'md', mode: 'subagent', toolsFormat: 'map', model: (t) => `anthropic/${TIER_MODEL.anthropic[t]}` },
   gemini: { dir: '.gemini/agents', ext: '.md', format: 'md', model: (t) => TIER_MODEL.google[t] },
   copilot: { dir: '.github/agents', ext: '.agent.md', format: 'md', model: (t) => TIER_MODEL.anthropic[t] },
   kiro: { dir: '.kiro/agents', ext: '.json', format: 'json', model: (t) => (t === 'heavy' ? 'claude-opus-4' : 'claude-sonnet-4') },
@@ -160,7 +160,14 @@ export function writeDeveloperTier(cwd, tier) {
 function renderMd(spec, model, agent) {
   const fm = ['---', `name: ${agent.name}`, `description: "${agent.desc}"`, `model: ${model}`];
   if (spec.mode) fm.push(`mode: ${spec.mode}`);
-  if (agent.tools) fm.push(`tools: [${agent.tools.join(', ')}]`);
+  if (agent.tools) {
+    if (spec.toolsFormat === 'map') {
+      fm.push('tools:');
+      for (const tool of agent.tools) fm.push(`  ${tool}: true`);
+    } else {
+      fm.push(`tools: [${agent.tools.join(', ')}]`);
+    }
+  }
   fm.push('---', '');
   return `${fm.join('\n')}${agent.body}\n`;
 }

package/targets/claude.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSyn
 import { dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { linkOrCopy } from './index.js';
+import { ensureShadowClaudeMd, removeShadowClaudeMd } from './agents-md-shadow.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 // Shell tools the PreToolUse guards listen on. On Windows the primary shell is the PowerShell tool,
@@ -48,11 +49,23 @@ export function hookWiringOf(entry) {
 // other settings are preserved. Empty event arrays (and an empty hooks object) are
 // pruned so we don't leave noise behind.
 export function unwireHook(paths) {
+  // The bootstrap lives in the COMMITTED tree, so leaving it behind does not just orphan a file the
+  // way a stray `.rsc/` entry would — it leaves an executable in something the user pushes. Nothing
+  // else removes it: uninstall and purge only ever knew about `.rsc/`.
+  try {
+    rmSync(join(paths.projectRoot, '.claude', 'rsc-bootstrap.mjs'), { force: true });
+  } catch { /* never let cleanup be the thing that fails */ }
+
+  // The shadow CLAUDE.md exists only to keep the hook from being doubled by a natively-read
+  // AGENTS.md. Unwiring the hook removes the reason for it. Only ever takes back an untouched one.
+  const shadow = removeShadowClaudeMd(paths.projectRoot);
+  const removed = shadow ? [shadow] : [];
+
   const file = paths.hookTarget;
-  if (!existsSync(file)) return [];
+  if (!existsSync(file)) return removed;
   let settings;
-  try { settings = JSON.parse(readFileSync(file, 'utf8')); } catch { return []; }
-  if (!settings.hooks) return [];
+  try { settings = JSON.parse(readFileSync(file, 'utf8')); } catch { return removed; }
+  if (!settings.hooks) return removed;
   for (const event of Object.keys(settings.hooks)) {
     settings.hooks[event] = (settings.hooks[event] || []).filter((e) => {
       const s = hookWiringOf(e);
@@ -62,7 +75,7 @@ export function unwireHook(paths) {
   }
   if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return [file];
+  return [...removed, file];
 }
 
 // SessionStart runs a project-local session-start.mjs via `node`: it prints
@@ -82,6 +95,23 @@ export function unwireHook(paths) {
 const P = '${CLAUDE_PROJECT_DIR}';
 const at = (...seg) => `${P}/${seg.join('/')}`;
 
+// Everything below points at `.rsc/`, which git does not carry — so in a clone every one of these
+// commands runs against a file that is not there and the client shows the module loader's stack
+// trace instead of a hook. The fix is not to make each script survive its own absence (it cannot:
+// the guards import only node builtins, so a missing entry file fails before a line of theirs runs).
+// The fix is to point the wiring at a file that IS committed, and let it decide: delegate when the
+// harness is mounted, speak once when it is not.
+//
+// The script's own path stays in the command as an argument, so every dedup/unwire needle
+// (`.rsc/session-start.`, `.rsc/ship-guard.`, …) still matches and idempotency is untouched.
+// Three modes, because a hook's event decides what it is allowed to say. `announce` is the one hook
+// that may open with the offer (one per session, no marker needed). `guard` is a shell guard, and in
+// an unbuilt harness it is the only place that can notice someone is about to do the thing the
+// missing guard protected. `quiet` delegates and never speaks.
+const BOOTSTRAP = '.claude/rsc-bootstrap.mjs';
+const viaBootstrap = (mode, target, ...args) =>
+  [`node "${at(...BOOTSTRAP.split('/'))}"`, `"${mode}"`, `"${P}"`, `"${target}"`, ...args].join(' ');
+
 export function wireHook(paths, sourceMd, policy = {}) {
   const scriptDest = join(paths.projectRoot, '.rsc', 'session-start.mjs');
   mkdirSync(dirname(scriptDest), { recursive: true });
@@ -92,6 +122,11 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // sibling too. Missing it does not break startup — the sweep is wrapped — it just goes silent.
   copyFileSync(join(HERE, 'worktree-reaper.mjs'), join(paths.projectRoot, '.rsc', 'worktree-reaper.mjs'));
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
+  // The one harness file that belongs in the committed tree rather than in `.rsc/`: it is the only
+  // thing standing between a clone and seven stack traces, so it has to survive `git clone`.
+  const bootstrapDest = join(paths.projectRoot, '.claude', 'rsc-bootstrap.mjs');
+  mkdirSync(dirname(bootstrapDest), { recursive: true });
+  copyFileSync(join(HERE, 'clone-bootstrap.mjs'), bootstrapDest);
 
   let suggestRel = at(relative(paths.projectRoot, paths.skillDir('suggest')).split(sep).join('/'), 'SKILL.md');
   const operationsSuggest = join(paths.projectRoot, '.rsc', 'suggest-always-on.md');
@@ -99,7 +134,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
     writeFileSync(operationsSuggest, '# rsc-suggest — always-on operations layer\n\nRead `docs/wiki/harness/user-profile.md` before acting. Use `orient` to keep the user situated and `suggest` to offer a missing skill only when the current task needs it. Close with the configured orientation block.\n');
     suggestRel = at('.rsc', 'suggest-always-on.md');
   } else if (existsSync(operationsSuggest)) rmSync(operationsSuggest, { force: true });
-  const cmd = `node "${at('.rsc', 'session-start.mjs')}" "${suggestRel}" "${P}"`;
+  const cmd = viaBootstrap('announce', at('.rsc', 'session-start.mjs'), `"${suggestRel}"`, `"${P}"`);
 
   const file = paths.hookTarget;
   const settings = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
@@ -118,9 +153,9 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // the workspace has no harness wiki. Registered idempotently on both events, with
   // any prior rsc worklog-checkpoint entry (.sh or .mjs) dropped first.
   const wlDest = join(paths.projectRoot, '.rsc', 'worklog-checkpoint.mjs');
-  const written = [paths.hookTarget, scriptDest, wlDest];
+  const written = [paths.hookTarget, scriptDest, wlDest, bootstrapDest];
   copyFileSync(join(HERE, 'worklog-checkpoint.mjs'), wlDest);
-  const wlCmd = `node "${at('.rsc', 'worklog-checkpoint.mjs')}" "${P}"`;
+  const wlCmd = viaBootstrap('quiet', at('.rsc', 'worklog-checkpoint.mjs'), `"${P}"`);
   for (const event of ['PreCompact', 'SessionEnd']) {
     settings.hooks[event] ||= [];
     settings.hooks[event] = settings.hooks[event].filter(
@@ -140,7 +175,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // sello.mjs is ship-guard's sibling import (hooks are materialized file-by-file,
   // so the deterministic sello core must land next to the guard that loads it).
   copyFileSync(join(HERE, 'sello.mjs'), join(paths.projectRoot, '.rsc', 'sello.mjs'));
-  const sgCmd = `node "${at('.rsc', 'ship-guard.mjs')}" "${P}"`;
+  const sgCmd = viaBootstrap('guard', at('.rsc', 'ship-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse ||= [];
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/ship-guard.'),
@@ -154,7 +189,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // node-run (Windows-safe), idempotent, fail-open, opt-out via .rsc/.no-danger-guard.
   const dgDest = join(paths.projectRoot, '.rsc', 'danger-guard.mjs');
   copyFileSync(join(HERE, 'danger-guard.mjs'), dgDest);
-  const dgCmd = `node "${at('.rsc', 'danger-guard.mjs')}" "${P}"`;
+  const dgCmd = viaBootstrap('guard', at('.rsc', 'danger-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/danger-guard.'),
   );
@@ -169,7 +204,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // .rsc/.no-gitmoji.
   const gmDest = join(paths.projectRoot, '.rsc', 'gitmoji-guard.mjs');
   copyFileSync(join(HERE, 'gitmoji-guard.mjs'), gmDest);
-  const gmCmd = `node "${at('.rsc', 'gitmoji-guard.mjs')}" "${P}"`;
+  const gmCmd = viaBootstrap('guard', at('.rsc', 'gitmoji-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/gitmoji-guard.'),
   );
@@ -185,7 +220,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // (non-rsc) UserPromptSubmit hooks are preserved.
   const fgDest = join(paths.projectRoot, '.rsc', 'userprompt-gate.mjs');
   copyFileSync(join(HERE, 'userprompt-gate.mjs'), fgDest);
-  const fgCmd = `node "${at('.rsc', 'userprompt-gate.mjs')}" "${P}"`;
+  const fgCmd = viaBootstrap('quiet', at('.rsc', 'userprompt-gate.mjs'), `"${P}"`);
   settings.hooks.UserPromptSubmit ||= [];
   settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
     (e) => !hookWiringOf(e).includes('.rsc/userprompt-gate.'),
@@ -215,5 +250,11 @@ export function wireHook(paths, sourceMd, policy = {}) {
 
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+
+  // settings.json now names this project as rsc-wired, which is the predicate the shadow reads —
+  // so this call belongs AFTER the write, not before it. No-op unless the root AGENTS.md also
+  // carries the always-on body and no CLAUDE.md exists: see targets/agents-md-shadow.js.
+  const shadow = ensureShadowClaudeMd(paths.projectRoot);
+  if (shadow) written.push(shadow);
   return written;
 }