@ericrisco/rsc 3.0.9 → 3.0.10

package/README.md

@@ -98,8 +98,8 @@ rsc 3.0 fixes all four, by default, with no new commands to learn:
 
 **Commit, push and pull request without a prompt each time.** A harness installed from scratch lets
 the agent run `git commit`, `git push` and `gh pr create` without asking, because those are the steps
-that close every lane. A force-push still asks. The guards still decide: a commit on a closed `main` is
-refused whatever the permission says. It is a project decision, saved as `gitPermissions` in
+that close every lane. A force-push still asks. In Claude Code, rsc's guards still decide: a commit on a
+closed `main` is refused whatever the permission says. No other assistant runs those guards. It is a project decision, saved as `gitPermissions` in
 `.rsc.json`. A clone gets the same setting. A project adopted before this is left as it was until
 someone runs `rsc git-permissions on`.
 
@@ -108,16 +108,32 @@ someone runs `rsc git-permissions on`.
 | Claude Code | `.claude/settings.json` → `permissions.allow` (force-push under `ask`). Claude Code applies it once the folder is trusted. |
 | Codex | `.codex/rules/rsc-git.rules` (`prefix_rule`; force-push → `prompt`). Loaded when the project is trusted. |
 | Gemini | `.gemini/settings.json` → `tools.allowed` |
-| OpenCode | `opencode.json` → `permission.bash` (force-push → `ask`) |
+| OpenCode | `opencode.json`. With OpenCode 2 installed: the top-level `permissions` list (`shell` rules; force-push → `ask`). rsc's rules go before yours, so any rule of yours that matches later still wins; only a leading `"*"` allow/ask default stays in front. With OpenCode 1.x, or when `opencode --version` cannot be read: `permission.bash`, which both versions read. Moving to 2 moves rsc's entries over. An `opencode.jsonc` is read but never rewritten (its comments would be lost): rsc prints the rules to paste. |
 | Cursor | Not covered: its CLI matches only the first word, so allowing a push would allow every git command. |
 | DeepSeek Harness | Not covered: dsh has no per-command allow list. Its own Permissions selector (`/permission`) sets approval for every command at once. |
 
 ```bash
-rsc git-permissions status   # decided or not, and wired per assistant
-rsc git-permissions off      # ask again for commit, push and PR (saved in .rsc.json)
+rsc git-permissions status   # per assistant: wired or not, and in which format (--json for scripts)
+rsc git-permissions off      # remove rsc's rules (saved in .rsc.json)
 rsc git-permissions on       # turn it on, also for a project adopted before
 ```
 
+**What `off` turns off.** Only rsc's allow rules. Each command says, per assistant, what rsc controls
+there, what stops when it is off, and what is left to the assistant. `off` does not hand rsc's
+protections to the assistant. Claude Code keeps rsc's guards (branch-guard, danger-guard), because
+they do not depend on this switch. OpenCode, Codex and Gemini run no rsc guard. There, your own
+settings decide. With no rule matching, OpenCode 2 asks and OpenCode 1.x runs the command. To refuse a
+force-push in OpenCode 2, add this at the end of `permissions` (use `"ask"` to get a human approval):
+
+```json
+{ "action": "shell", "resource": "git push --force*", "effect": "deny" },
+{ "action": "shell", "resource": "git push -f*", "effect": "deny" },
+{ "action": "shell", "resource": "git push * --force*", "effect": "deny" },
+{ "action": "shell", "resource": "git push * -f*", "effect": "deny" }
+```
+
+In OpenCode 1.x the same patterns go at the end of `permission.bash` (`"git push --force*": "deny"`, …).
+
 **How does it know a project is "complex or in production"?** There are two layers. A hook counts
 what anyone can check: a CI setup, a deployment file (`Dockerfile`, `vercel.json`, `fly.toml`…) or
 at least two people in the last 50 commits. If any of those is there, a commit on the default branch
@@ -403,6 +419,10 @@ rsc memory resume                    # print this branch/worktree continuation
 rsc memory learn --text "…" --evidence "…" --confidence 0.8 --approve
 rsc memory off                       # disable hooks, commands and injection project-wide
 rsc sync --target claude,codex       # refresh managed skills/hooks from the current package version
+rsc agent-model opencode openai/gpt-5   # pin the model the generated agents carry (saved in .rsc.json)
+rsc agent-model opencode inherit     # back to the session's model (OpenCode's default)
+rsc agents status                    # installed agents, and which ones you edited
+rsc agents reset developer           # take rsc's version of an agent you edited (yours is backed up first)
 rsc backups                          # list project-local snapshots
 rsc restore latest --dry-run         # preview restoring the newest snapshot
 rsc restore <snapshot-id>            # restore a project-local snapshot
@@ -410,6 +430,29 @@ rsc upgrade --dry-run                # show npm upgrade + sync commands
 rsc uninstall postgresdb --dry-run   # preview a removal
 ```
 
+### `rsc doctor`: harness health vs onboarding readiness
+
+`doctor` answers two different questions, and prints both first, on separate lines:
+
+```text
+Harness health: healthy
+Onboarding readiness: pending
+Pending: 02-DOCS/wiki/sdd/constitution.md (draft)
+Next: Complete 02-DOCS/wiki/sdd/constitution.md with the `constitution` phase …
+```
+
+- **Harness health** (`healthy` in `--json`) says whether what is installed works: skills, agents,
+  commands and hook scripts are on disk. It is the only thing the exit code follows (1 when
+  unhealthy), so CI and editor extensions can rely on it.
+- **Onboarding readiness** (`onboarding` in `--json`: `status`, `missing`, `pending`, `action`) says
+  whether onboarding is finished. It checks the accepted plan's floor, the same check that prints
+  `RSC_ONBOARDING_READY`, plus drafts. The status is `ready`; `pending` when a draft such as the
+  onboarding constitution still has to be completed; `incomplete` when part of the floor is missing,
+  for example a deleted constitution in an SDD plan, with the exact phase or command that fixes it;
+  or `not onboarded` when there is no onboarding record, as in a manual `rsc add` install. Readiness
+  never changes `healthy` or the exit code. `Missing:` and `Pending:` appear only when they have
+  entries.
+
 ---
 
 
@@ -846,6 +889,15 @@ selective specialists) and 53 command entries (20 fixed + 33 stack aliases).
 Unsupported means rsc writes nothing for that surface; it does not emulate a
 provider feature with an unverified file.
 
+**Generated agents follow your project, not rsc's defaults.** OpenCode agents carry no `model:`, so
+they use whatever model the session runs (a local one, OpenAI, Anthropic). To pin one for the whole
+team, run `rsc agent-model opencode <model>`: it is saved as `agentModels` in `.rsc.json` and works
+for any target with agents (`inherit` drops the pin). OpenCode agents never grant a tool either: a
+read-only reviewer only gets `edit`, `write`, `patch` and `bash` set to `false`, and an agent that may
+edit or run commands gets no `tools` block, so your project's permission policy decides. If you edit
+a generated agent, `rsc sync` keeps your file and says so. `rsc agents reset <name>` (or `--all`)
+takes rsc's version back after a backup in `.rsc/backups/`.
+
 ---
 
 ## Skill format

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.9",
+  "version": "3.0.10",
   "counts": {
     "skills": 270,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.0.9",
+  "version": "3.0.10",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -17,10 +17,11 @@ import { countGaps, listSkills, listAgents } from './lib/capabilities.js';
 import { resolveCommands, commandPath, targetHasCommands } from '../targets/commands.js';
 import { inspectMemoryWiring } from '../targets/memory.js';
 import { metricsSummary } from '../targets/session-memory-core.mjs';
-import { agentPath } from '../targets/agents.js';
+import { agentPath, targetHasAgents, effectiveAgentModel } from '../targets/agents.js';
 import { projectOptOuts } from '../targets/opt-outs.js';
 import { versionReport } from './lib/versions.js';
 import { CONSTITUTION_PATH, constitutionIsDraft } from './lib/constitution-draft.js';
+import { onboardingReadiness } from './lib/onboarding-apply.js';
 
 // Gates the committed manifest says the team disarmed, still armed here. Read through the same
 // partition the installer uses, so a machine-only switch somebody's older rsc wrote into the
@@ -298,6 +299,11 @@ export function doctor({ target, home, cwd }) {
     memory,
     missingAgents,
     agentCollisions: state.agentCollisions || [],
+    // #298 — generated agents the user edited and sync kept as they are. Not unhealthy: theirs on
+    // purpose. Named with the way back, so a stale edit is one command from rsc's version.
+    agentsEditedByYou: (state.agentsKept || []).map((k) => ({ ...k, action: `\`npx @ericrisco/rsc agents reset ${k.name}\` takes rsc's version (yours is backed up first).` })),
+    // Which model the agents carry: the session's (inherit) or a project pin (`rsc agent-model`).
+    agentModel: targetHasAgents(target) ? (effectiveAgentModel(target, root) || 'inherit') : null,
     missingCommands,
     commandOrphans,
     commandCollisions: state.commandCollisions || [],
@@ -316,6 +322,14 @@ export function doctor({ target, home, cwd }) {
   report.pending = constitutionIsDraft(root)
     ? [{ id: 'constitution-draft', path: CONSTITUTION_PATH, action: 'Complete it with the `constitution` phase before the first SDD feature; ratifying removes `status: draft`.' }]
     : [];
+  // #298 — onboarding readiness is a SEPARATE question from health: is the accepted plan's floor
+  // on disk (the same check that prints RSC_ONBOARDING_READY), and is anything still a draft. It is
+  // reported, never folded into `healthy`: `healthy` and the exit code keep meaning "the installed
+  // harness works", which is what CI and editor extensions built on #277 read. Wrapped because a
+  // report must never fail for asking an extra question.
+  try { report.onboarding = onboardingReadiness(root); } catch (error) {
+    report.onboarding = { status: 'incomplete', missing: ['<onboarding readiness could not be read>'], pending: [], action: String(error?.message || error).slice(0, 200) };
+  }
   report.healthy = report.hookWired && !report.missing.length && !missingAgents.length && !missingCommands.length
     && !report.opencodePluginsOutdated.length;
   return report;

package/scripts/install-apply.js

@@ -7,7 +7,7 @@ import { planInstall } from './install-plan.js';
 import { targetPaths, writeSkill, wireHook, unwireHook, baseDir, TARGET_IDS } from '../targets/index.js';
 import { shadowTarget } from '../targets/agents-md-shadow.js';
 import {
-  targetHasAgents, reconcileAgents, agentPath, agentNames,
+  targetHasAgents, reconcileAgents, agentPath, agentNames, writeAgentsDetailed,
   resolveAgentNames, agentByName, allAgentNames, readDeveloperTier, writeDeveloperTier,
 } from '../targets/agents.js';
 import { projectOptOuts } from '../targets/opt-outs.js';
@@ -223,6 +223,7 @@ export function recordInManifest({ cwd, target, skillIds, agentIds = [], catalog
     optOuts: optOuts ?? projectOptOuts(prev.optOuts),
     memory: prev.memory,
     gitPermissions: gitPermissions ?? prev.gitPermissions,
+    agentModels: prev.agentModels,
     onboarding: onboarding ?? prev.onboarding,
   });
 }
@@ -306,13 +307,19 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
       ? explicit
       : resolveAgentNames(Object.keys(state.skills || {}), explicit);
   const previousAgents = state.agents || [];
+  let keptAgents = [];
   if (targetHasAgents(target)) {
     const agentResult = reconcileAgents(target, cwd, readDeveloperTier(cwd), previousAgents, desiredAgents);
     state.agents = agentResult.names;
     state.agentCollisions = agentResult.collisions;
+    // #298 — agents the user edited and rsc left alone. Recorded so `doctor` can say it on any run,
+    // and returned so the command that just ran says it now.
+    keptAgents = agentResult.kept;
+    state.agentsKept = keptAgents.map(({ name, path }) => ({ name, path }));
   } else {
     state.agents = [];
     state.agentCollisions = [];
+    state.agentsKept = [];
   }
   state.explicitAgents = explicit;
   const memoryResult = policy?.memory === false
@@ -381,7 +388,7 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
     if (existsSync(join(cwd, '.git'))) mergeHook = installMergeHook(cwd);
   } catch (err) { mergeHook = { installed: false, state: 'skipped', reason: err.message }; }
   ignoreLocalState(cwd, target);
-  return { ...state, backup, mergeHook };
+  return { ...state, backup, mergeHook, keptAgents };
 }
 
 // `.rsc/` holds local machine state — hook scripts, install markers, the sello's
@@ -551,9 +558,16 @@ export async function uninstall({ skillIds = [], agentIds = [], target, home, cw
     delete state.skills[id];
   }
   const agentResult = reconcileAgents(target, cwd, readDeveloperTier(cwd), state.agents || [], desiredAgents);
-  state.agents = agentResult.names;
+  // An edited agent no longer wanted stays on disk (#298) and stays recorded as rsc-managed, so a
+  // later reset or uninstall can still find it.
+  state.agents = [...new Set([...agentResult.names, ...agentResult.kept.map((k) => k.name)])];
   state.agentCollisions = agentResult.collisions;
+  state.agentsKept = agentResult.kept.map(({ name, path }) => ({ name, path }));
   state.explicitAgents = nextExplicit;
+  for (const k of agentResult.kept) {
+    const i = removed.indexOf(k.path);
+    if (i >= 0) removed.splice(i, 1);
+  }
   const desiredCommands = resolveCommands({
     target,
     skills: remainingSkillIds,
@@ -712,7 +726,30 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
   // question sat untracked, one `git add -A` from the team repo (team simulation D13). Sync is what a
   // clone runs, so it writes the same exclude. Lazy import: onboarding-apply imports this module.
   try { (await import('./lib/onboarding-apply.js')).excludePersonalProfile(cwd); } catch { /* not a repo → nothing */ }
-  return { synced: declared, syncedAgents: declaredAgents, backup: nextState.backup };
+  return { synced: declared, syncedAgents: declaredAgents, backup: nextState.backup, keptAgents: nextState.keptAgents || [] };
+}
+
+/**
+ * #298 — `rsc agents reset <name|--all>`: take rsc's version of agents the user edited. The user's
+ * file is snapshotted first (a backup under .rsc/backups/), and the answer says where, so taking rsc's
+ * version is never the loss the protection exists to prevent.
+ */
+export function resetAgents({ target, home, cwd = process.cwd(), names = [], all = false }) {
+  if (!targetHasAgents(target)) return { reset: [], backup: null, kept: [] };
+  const paths = targetPaths(target, home, cwd);
+  const state = readState(paths.stateFile);
+  const installed = state.agents || [];
+  const chosen = all ? installed : names;
+  const unknown = chosen.filter((name) => !installed.includes(name));
+  if (unknown.length) throw new Error(`${unknown.join(', ')}: not an agent rsc installed for ${target} (installed: ${installed.join(', ') || 'none'})`);
+  if (!chosen.length) return { reset: [], backup: null, kept: [] };
+  const files = chosen.map((name) => agentPath(target, cwd, name));
+  const backup = createBackup({ cwd, operation: 'agents-reset', target, paths: files.filter((f) => existsSync(f)), cliVersion: CLI_VERSION });
+  const { written } = writeAgentsDetailed(target, cwd, readDeveloperTier(cwd), chosen, { force: true });
+  state.agentsKept = (state.agentsKept || []).filter((k) => !chosen.includes(k.name));
+  writeState(paths.stateFile, state);
+  const rel = (p) => relative(cwd, p).split(sep).join('/');
+  return { reset: chosen, written, backup: backup ? rel(join(cwd, '.rsc', 'backups', backup.id)) : null };
 }
 
 // Remove EVERYTHING rsc put in this project: installed skills across all targets,

package/scripts/lib/manifest-file.js

@@ -15,7 +15,7 @@ import { join } from 'node:path';
 export const MANIFEST = '.rsc.json';
 export const manifestPath = (cwd = process.cwd()) => join(cwd, MANIFEST);
 
-const KEYS = ['version', 'targets', 'skills', 'agents', 'ownSkills', 'catalogVersion', 'tier', 'optOuts', 'memory', 'gitPermissions', 'onboarding'];
+const KEYS = ['version', 'targets', 'skills', 'agents', 'ownSkills', 'catalogVersion', 'tier', 'optOuts', 'memory', 'gitPermissions', 'agentModels', 'onboarding'];
 
 export function readManifest(cwd = process.cwd()) {
   const file = manifestPath(cwd);
@@ -40,10 +40,19 @@ export function readManifest(cwd = process.cwd()) {
     memory: raw.memory ?? undefined,
     // true on a project installed from scratch since 3.0.3; absent on older ones; false once turned off.
     gitPermissions: typeof raw.gitPermissions === 'boolean' ? raw.gitPermissions : undefined,
+    // #298 — per-target agent model: { opencode: 'openai/gpt-5' | 'inherit' }. Only plain objects of
+    // strings survive the read; what each value may contain is checked where it is rendered.
+    agentModels: agentModelsFrom(raw.agentModels),
     onboarding: raw.onboarding ?? undefined,
   };
 }
 
+function agentModelsFrom(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const entries = Object.entries(value).filter(([, v]) => typeof v === 'string').sort(([a], [b]) => a.localeCompare(b));
+  return entries.length ? Object.fromEntries(entries) : undefined;
+}
+
 // Stable output: fixed key order, arrays one entry per line, order as given. Rewriting an
 // unchanged manifest must produce identical bytes, or every install shows up as a diff.
 export function writeManifest(cwd, manifest) {

package/scripts/lib/onboarding-apply.js

@@ -10,7 +10,7 @@ import { readManifest, writeManifest } from './manifest-file.js';
 import { encodeGoal, identifyPlan } from './onboarding.js';
 import { createBackup, restoreBackup } from './backups.js';
 import { RETIRED_SKILLS, replaceRetired } from './retired-skills.js';
-import { CONSTITUTION_PATH } from './constitution-draft.js';
+import { CONSTITUTION_PATH, constitutionIsDraft } from './constitution-draft.js';
 import { LAYER_IGNORE, TEMPLATE_SOURCE, targetName, templateAssets } from './tools-skeleton.js';
 
 const sameSet = (a = [], b = []) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
@@ -445,7 +445,10 @@ function floorSatisfied(cwd, path) {
 // conflictos de merge, y que un repo clonado puede traer preparado. Así que se valida la forma antes
 // de mirar el disco: un `..` daba el suelo por satisfecho MIRANDO FUERA de la raíz, y un `null` o una
 // cadena en lugar de un array tumbaban `rsc install` después de haber instalado.
-export function missingHarnessFloor(cwd = process.cwd(), plan = {}) {
+//
+// Devuelve los CAMINOS que faltan (como se muestran). `missingHarnessFloor` los redacta para el
+// instalador y `onboardingReadiness` los entrega tal cual a `doctor`: una comprobación, dos lectores.
+export function harnessFloorGaps(cwd = process.cwd(), plan = {}) {
   const declared = Array.isArray(plan?.floorPaths) ? plan.floorPaths : [];
   const missing = [];
   for (const path of declared) {
@@ -453,15 +456,19 @@ export function missingHarnessFloor(cwd = process.cwd(), plan = {}) {
     const usable = segments.length > 0 && !segments.includes('..') && !String(path).startsWith('/');
     // Un camino que no se puede usar se reporta como NO satisfecho, nunca como satisfecho, y sin
     // repetir su contenido: es dato ajeno y va a un canal que lee un agente.
-    if (!usable) { missing.push('missing harness floor <invalid declaration>'); continue; }
+    if (!usable) { missing.push('<invalid declaration>'); continue; }
     // La barra sólo si el camino declarado la traía: el suelo condicional es un FICHERO, y decir
     // `constitution.md/` invita a buscar un directorio que no existe.
     const shown = String(path).endsWith('/') ? `${floorKey(path)}/` : floorKey(path);
-    if (!floorSatisfied(cwd, path)) missing.push(`missing harness floor ${shown}`);
+    if (!floorSatisfied(cwd, path)) missing.push(shown);
   }
   return missing;
 }
 
+export function missingHarnessFloor(cwd = process.cwd(), plan = {}) {
+  return harnessFloorGaps(cwd, plan).map((shown) => `missing harness floor ${shown}`);
+}
+
 /**
  * Lo que el instalador puede afirmar honestamente, y qué hacer si no.
  *
@@ -479,3 +486,50 @@ export function harnessReadiness(cwd = process.cwd(), plan = {}) {
       : '',
   };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Preparación del onboarding, como pregunta PROPIA (#298 punto 5).
+//
+// `doctor` respondía sólo «¿el arnés instalado funciona?» (`healthy`, y el exit code con él) y un
+// usuario leía ese `true` como «el onboarding está terminado» con la constitución sin escribir. Son
+// dos preguntas: ésta se calcula con el MISMO suelo que decide RSC_ONBOARDING_READY/INCOMPLETE
+// (`harnessFloorGaps`) más los borradores, y nunca toca `healthy`.
+//
+//   ready          suelo completo, nada en borrador
+//   pending        suelo completo, pero algo es un borrador que el usuario debe completar
+//   incomplete     falta parte del suelo del plan aceptado (o el recibo no cuadra con su id)
+//   not-onboarded  no hay recibo: instalación manual (`rsc add`) o anterior al onboarding
+//
+// Un recibo de una versión que no declaraba suelo queda exento por construcción (P3), igual que en
+// el instalador: aquí no se inventa un suelo que el plan aceptado no traía.
+const ONBOARD_ACTION = 'Run `npx @ericrisco/rsc@latest onboard` to record a plan for this harness (optional: what is installed keeps working).';
+const draftAction = (path) => `Complete ${path} with the \`constitution\` phase (tell your agent "constitution") before the first SDD feature; ratifying removes \`status: draft\`.`;
+
+export function onboardingReadiness(cwd = process.cwd(), manifest = readManifest(cwd)) {
+  const pending = constitutionIsDraft(cwd) ? [CONSTITUTION_PATH] : [];
+  const receipt = manifest?.onboarding;
+  if (!receipt?.plan) {
+    return { status: 'not-onboarded', missing: [], pending, action: ONBOARD_ACTION };
+  }
+  let identical = false;
+  try { identical = identifyPlan(receipt.plan) === receipt.acceptedPlanId; } catch { /* ilegible: no cuadra */ }
+  if (!identical) {
+    return {
+      status: 'incomplete', missing: ['<onboarding receipt does not match its accepted plan id>'], pending,
+      action: 'Do not trust the receipt. Re-run `npx @ericrisco/rsc@latest onboard` and accept a fresh plan.',
+    };
+  }
+  const missing = harnessFloorGaps(cwd, receipt.plan);
+  if (missing.length) {
+    const actions = [];
+    if (missing.includes(CONSTITUTION_PATH)) {
+      actions.push(`Write ${CONSTITUTION_PATH} with the \`constitution\` phase (tell your agent "constitution"); the SDD plan you accepted requires it.`);
+    }
+    if (missing.some((path) => path !== CONSTITUTION_PATH)) {
+      actions.push('Invoke the `harness` skill to scaffold 01-TOOLS/ + 02-DOCS/.');
+    }
+    return { status: 'incomplete', missing, pending, action: actions.join(' ') };
+  }
+  if (pending.length) return { status: 'pending', missing, pending, action: draftAction(CONSTITUTION_PATH) };
+  return { status: 'ready', missing, pending, action: '' };
+}

package/scripts/rsc.js

@@ -4,9 +4,12 @@ import { detectTarget, installedTargets, resolveTargets, TARGETS } from '../targ
 import { detectRepo } from './detect-repo.js';
 import { rank } from './consult.js';
 import { expandRecommends, toOutcomes, hasOutcome } from './lib/recommend.js';
-import { applyInstall, listInstalled, listInstalledAgents, listInstalledCommands, uninstall, syncInstalled, purgeReport, collisions, ownSkillPaths } from './install-apply.js';
+import { applyInstall, listInstalled, listInstalledAgents, listInstalledCommands, uninstall, syncInstalled, purgeReport, collisions, ownSkillPaths, resetAgents } from './install-apply.js';
 import { isAbsolute, relative, sep } from 'node:path';
-import { stackAgentNames } from '../targets/agents.js';
+import {
+  stackAgentNames, targetHasAgents, isValidAgentModel, agentModelSetting, targetInheritsByDefault,
+  effectiveAgentModel, writeAgentsDetailed, readDeveloperTier, AGENT_MODEL_INHERIT, AGENT_TARGET_IDS,
+} from '../targets/agents.js';
 import { doctor } from './doctor.js';
 import { ask, say, select, pickFrom, banner, confirm, isInteractive } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
@@ -43,7 +46,7 @@ if (['--version', '-v', 'version'].includes(rawArgv[0])) {
   process.exit(0);
 }
 const GENERAL_HELP = [
-  'Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id...> | purge | help',
+  'Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | agent-model <target> <model|inherit|status> | agents [status|reset <name|--all>] | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id...> | purge | help',
   'Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)',
   '   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.',
 ].join('\n');
@@ -74,7 +77,7 @@ const PURGE_HELP = [
 const GLOBAL_VALUE_FLAGS = new Set([
   '--target', '--technical-level', '--accompaniment', '--project-kind', '--goal', '--goal-base64', '--software-scope', '--workflow', '--accept-plan',
 ]);
-const COMMANDS = new Set(['onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'knowledge-sync', 'git-permissions', 'main', 'isolation', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'sello', 'repair', 'uninstall', 'purge']);
+const COMMANDS = new Set(['onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'knowledge-sync', 'git-permissions', 'agent-model', 'agents', 'main', 'isolation', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'sello', 'repair', 'uninstall', 'purge']);
 function positionalTokens(input) {
   const out = [];
   for (let i = 0; i < input.length; i++) {
@@ -416,7 +419,7 @@ function reportUnknown(ids) {
 // flag says which: `purge` sweeps every target by design, and the catalog/consult
 // side barely touches one, so blocking them would be a regression, not a safeguard.
 const NEEDS_TARGET = new Set([
-  'onboard', 'add', 'install', 'list', 'doctor', 'sync', 'uninstall', 'capabilities', 'catalog', 'registry',
+  'onboard', 'add', 'install', 'list', 'doctor', 'sync', 'uninstall', 'capabilities', 'catalog', 'registry', 'agents',
 ]);
 
 function flag(name) {
@@ -573,6 +576,11 @@ function printAgentHandoff() {
   }
   if (readiness.ready) {
     say('  3. Tell the user rsc is ready; they can start in their own words.');
+    // #298 — ready is not «nothing pending»: the onboarding draft is named here too, not only in
+    // RSC_ONBOARDING_READY, so an agent arriving through install/sync tells the user before an SDD feature.
+    let draft = false;
+    try { draft = constitutionIsDraft(process.cwd()); } catch { /* unreadable is not a draft */ }
+    if (draft) say(`     Tell them too: ${CONSTITUTION_PATH} is a draft — complete it with the \`constitution\` phase before the first SDD feature.`);
     say('     Do NOT auto-start a task — wait for the user.');
   } else {
     // El otro emisor. Decía «ready» desde el wizard y desde `install` sin mirar el suelo, así que
@@ -585,6 +593,19 @@ function printAgentHandoff() {
   say('════════════════════════════════════════════════');
 }
 
+// #298 — the two answers a person looks for first, before any figure or JSON: does the installed
+// harness work (`healthy`, the one the exit code follows) and is onboarding finished (the accepted
+// plan's floor plus drafts). Kept apart on purpose — readiness never changes health nor the exit code.
+const READINESS_LABEL = { ready: 'ready', pending: 'pending', incomplete: 'incomplete', 'not-onboarded': 'not onboarded' };
+function printDoctorHeadline(report) {
+  const o = report.onboarding || {};
+  say(`Harness health: ${report.healthy ? 'healthy' : 'unhealthy'}`);
+  say(`Onboarding readiness: ${READINESS_LABEL[o.status] || 'unknown'}`);
+  if (o.missing?.length) say(`Missing: ${safeLines(o.missing).join(', ')}`);
+  if (o.pending?.length) say(`Pending: ${safeLines(o.pending).map((p) => (p === CONSTITUTION_PATH ? `${p} (draft)` : p)).join(', ')}`);
+  if (o.action) say(`Next: ${o.action}`);
+}
+
 // What the harness costs in context before the user types anything. Printed ahead of the raw
 // health JSON because it is the part a human acts on: the figures say whether the harness is
 // paying its way, and the findings say what to do about it.
@@ -624,6 +645,7 @@ async function syncDeclared(targets, dry = false) {
     const result = await syncInstalled({ target: t, dryRun: dry });
     const verb = dry ? 'Would sync' : 'Synced';
     say(`${verb} ${t}: ${result.synced.length ? result.synced.join(', ') : '(nothing to sync)'}`);
+    for (const k of result.keptAgents || []) say(`  ${k.message}`);
     if (dry && result.paths?.length) {
       for (const p of result.paths) say(`  ${p}`);
     }
@@ -870,6 +892,7 @@ async function main() {
       // #277 — an automation on top of rsc reads the exit code, not the prose.
       if (!report.healthy) process.exitCode = 1;
       if (argv.includes('--json')) return void say(JSON.stringify(report, null, 2));
+      printDoctorHeadline(report);
       printContextBudget(report.contextBudget);
       return void say(JSON.stringify({ ...report, contextBudget: undefined }, null, 2));
     }
@@ -952,26 +975,28 @@ async function main() {
       const sub = argv[1] || 'status';
       const root = process.cwd();
       const { readManifest, writeManifest } = await import('./lib/manifest-file.js');
-      const { gitPermissionsWired, GIT_PERMISSION_TARGETS } = await import('../targets/git-permissions.js');
+      const { gitPermissionsState, explainGitPermissions, GIT_PERMISSION_TARGETS } = await import('../targets/git-permissions.js');
       if (sub === 'on' || sub === 'off') {
         const current = readManifest(root);
         if (!current) { say('No .rsc.json here: install the harness first (`npx @ericrisco/rsc onboard`).'); process.exitCode = 2; return; }
         writeManifest(root, { ...current, gitPermissions: sub === 'on' });
         for (const t of targets) await syncInstalled({ target: t, cwd: root });
-        say(sub === 'on'
-          ? 'rsc git-permissions on: the agent may git commit, git push and gh pr create without asking (a force-push still asks; Cursor is not covered). Commit .rsc.json so the team gets the same decision.'
-          : 'rsc git-permissions off: commit, push and PR ask again, as the assistant does by default. Commit .rsc.json so the team gets the same decision.');
-        return;
+        // What rsc controls, what stops when off, and what is the assistant's own job (#298).
+        return void say(explainGitPermissions({ targets, cwd: root, mode: sub }));
       }
       if (sub === 'status') {
         const declared = readManifest(root)?.gitPermissions;
+        if (!flag('json')) return void say(explainGitPermissions({ targets, cwd: root, mode: 'status', declared }));
+        const covered = targets.filter((t) => GIT_PERMISSION_TARGETS.includes(t));
+        const states = Object.fromEntries(covered.map((t) => [t, gitPermissionsState(t, root)]));
         return void say(JSON.stringify({
           declared: declared === undefined ? 'undecided' : declared,
-          wired: Object.fromEntries(targets.filter((t) => GIT_PERMISSION_TARGETS.includes(t)).map((t) => [t, gitPermissionsWired(t, root)])),
+          wired: Object.fromEntries(covered.map((t) => [t, states[t].wired])),
+          format: Object.fromEntries(covered.map((t) => [t, states[t].format])),
           notCovered: targets.filter((t) => !GIT_PERMISSION_TARGETS.includes(t)),
         }, null, 2));
       }
-      say('Use: npx @ericrisco/rsc git-permissions on|off|status');
+      say('Use: npx @ericrisco/rsc git-permissions on|off|status [--json]');
       process.exitCode = 2;
       return;
     }
@@ -1023,6 +1048,98 @@ async function main() {
       process.exitCode = 1;
       return;
     }
+    case 'agent-model': {
+      // #298 — which model the generated agents carry: the session's (`inherit`, OpenCode's default)
+      // or one the project pins. A PROJECT decision, saved as `agentModels` in .rsc.json, so a clone
+      // renders the same agents; the files of that target are re-rendered at once.
+      const root = process.cwd();
+      const t = argv[1];
+      const value = argv[2] || 'status';
+      const describe = (id) => {
+        const setting = agentModelSetting(root, id);
+        const effective = effectiveAgentModel(id, root);
+        return {
+          target: id,
+          declared: setting || (targetInheritsByDefault(id) ? 'default (inherit)' : 'default (tier model)'),
+          effective: effective || 'inherit — the agent uses the session model',
+        };
+      };
+      if (!t || t === 'status') {
+        return void say(JSON.stringify(targets.filter(targetHasAgents).map(describe), null, 2));
+      }
+      if (!targetHasAgents(t)) {
+        console.error(`rsc: ${t} has no file-based agents. Targets with agents: ${AGENT_TARGET_IDS.join(', ')}`);
+        process.exitCode = 2;
+        return;
+      }
+      if (value === 'status') return void say(JSON.stringify(describe(t), null, 2));
+      if (!isValidAgentModel(value)) {
+        console.error(`rsc: '${value}' is not a model id (letters, digits and . _ : / @ + - only), nor 'inherit'.\nUse: npx @ericrisco/rsc agent-model <target> <model|inherit|status>`);
+        process.exitCode = 2;
+        return;
+      }
+      const current = readManifest(root);
+      if (!current) { say('No .rsc.json here: install the harness first (`npx @ericrisco/rsc onboard`).'); process.exitCode = 2; return; }
+      const next = { ...(current.agentModels || {}) };
+      // `inherit` on a target whose default is inherit stores nothing: the manifest stays as small as the decision.
+      if (value === AGENT_MODEL_INHERIT && targetInheritsByDefault(t)) delete next[t];
+      else next[t] = value;
+      writeManifest(root, { ...current, agentModels: Object.keys(next).length ? next : undefined });
+      const { targetPaths: pathsOf } = await import('../targets/index.js');
+      const { readState } = await import('./lib/state.js');
+      const installedAgents = readState(pathsOf(t, undefined, root).stateFile).agents || [];
+      const { written, kept } = writeAgentsDetailed(t, root, readDeveloperTier(root), installedAgents);
+      say(value === AGENT_MODEL_INHERIT
+        ? `rsc agent-model ${t} inherit: the agents carry no model and use the session's.`
+        : `rsc agent-model ${t} ${value}: the agents are pinned to ${value}.`);
+      say(`  Re-rendered ${written.length} agent file(s). Commit .rsc.json so the team gets the same decision.`);
+      for (const k of kept) say(`  ${k.message}`);
+      return;
+    }
+    case 'agents': {
+      const sub = argv[1] || 'status';
+      const root = process.cwd();
+      if (sub === 'reset') {
+        const all = argv.includes('--all');
+        const names = requestedIds(2);
+        if (!all && !names.length) {
+          console.error('Use: npx @ericrisco/rsc agents reset <name...|--all> [--target <assistant>]');
+          process.exitCode = 2;
+          return;
+        }
+        const { targetPaths: pathsOf } = await import('../targets/index.js');
+        const { readState } = await import('./lib/state.js');
+        const withAgents = targets.filter(targetHasAgents);
+        let done = 0;
+        for (const t of withAgents) {
+          const installed = readState(pathsOf(t, undefined, root).stateFile).agents || [];
+          const mine = all ? [] : names.filter((n) => installed.includes(n));
+          if (!all && !mine.length) continue;
+          const out = resetAgents({ target: t, cwd: root, names: mine, all });
+          done += out.reset.length;
+          if (out.reset.length) {
+            say(`Reset ${t}: ${out.reset.join(', ')} — rsc's version is back.`);
+            if (out.backup) say(`  Your previous files are kept in ${out.backup}/files/ (\`rsc restore\` lists the snapshot).`);
+          }
+        }
+        if (!all && !done) {
+          console.error(`rsc: ${names.join(', ')}: not an agent rsc installed here (${withAgents.join(', ') || 'no target with agents'}).`);
+          process.exitCode = 1;
+        }
+        return;
+      }
+      if (sub === 'status') {
+        const { targetPaths: pathsOf } = await import('../targets/index.js');
+        const { readState } = await import('./lib/state.js');
+        return void say(JSON.stringify(targets.filter(targetHasAgents).map((t) => {
+          const state = readState(pathsOf(t, undefined, root).stateFile);
+          return { target: t, agents: state.agents || [], editedByYou: (state.agentsKept || []).map((k) => k.name) };
+        }), null, 2));
+      }
+      say('Use: npx @ericrisco/rsc agents status | agents reset <name...|--all>');
+      process.exitCode = 2;
+      return;
+    }
     case 'sync':
       return syncDeclared(targets, argv.includes('--dry-run'));
     case 'backups': {

package/targets/agents.js

@@ -9,7 +9,9 @@
 // elsewhere. The chosen tier (balanced default, or heavy) lives in `.rsc/developer.json`,
 // written by `init` at onboarding and read here so re-syncs honor it.
 import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, relative, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { readManifest } from '../scripts/lib/manifest-file.js';
 import {
   stackAgents, stackAgentNames, stackAgentByName,
   resolveStackAgentNames, validateAgentCatalog,
@@ -32,7 +34,12 @@ 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', toolsFormat: 'map', model: (t) => `anthropic/${TIER_MODEL.anthropic[t]}` },
+  // #298 — OpenCode is the one tool people point at a local model or another provider per session, so
+  // its agents INHERIT the session model by default (`model: null` → no `model:` line) and only carry
+  // one when the project pins it (`agentModels.opencode` in .rsc.json). And its `tools` map is
+  // restrict-only: rsc never grants a tool there, it can only take away what a role never declared,
+  // so a stricter project permission policy is never loosened by an rsc agent.
+  opencode: { dir: '.opencode/agents', ext: '.md', format: 'md', mode: 'subagent', toolsFormat: 'restrict', model: () => null, legacyModel: (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') },
@@ -157,11 +164,26 @@ export function writeDeveloperTier(cwd, tier) {
   return t;
 }
 
-function renderMd(spec, model, agent) {
-  const fm = ['---', `name: ${agent.name}`, `description: "${agent.desc}"`, `model: ${model}`];
+// OpenCode V1 tool names a declared capability maps to. `read`/`search` need nothing: what the agent
+// may read is the project's policy to decide, and saying `read: true` would be a grant.
+const RESTRICT_TOOLS = { edit: ['edit', 'write', 'patch'], shell: ['bash'] };
+function restrictedTools(tools) {
+  if (!tools) return [];
+  return Object.entries(RESTRICT_TOOLS).filter(([cap]) => !tools.includes(cap)).flatMap(([, names]) => names);
+}
+
+function renderMd(spec, model, agent, toolsFormat = spec.toolsFormat) {
+  const fm = ['---', `name: ${agent.name}`, `description: "${agent.desc}"`];
+  if (model) fm.push(`model: ${model}`);
   if (spec.mode) fm.push(`mode: ${spec.mode}`);
   if (agent.tools) {
-    if (spec.toolsFormat === 'map') {
+    if (toolsFormat === 'restrict') {
+      const denied = restrictedTools(agent.tools);
+      if (denied.length) {
+        fm.push('tools:');
+        for (const tool of denied) fm.push(`  ${tool}: false`);
+      }
+    } else if (toolsFormat === 'map') {
       fm.push('tools:');
       for (const tool of agent.tools) fm.push(`  ${tool}: true`);
     } else {
@@ -171,44 +193,146 @@ function renderMd(spec, model, agent) {
   fm.push('---', '');
   return `${fm.join('\n')}${agent.body}\n`;
 }
-const renderJson = (model, agent) => `${JSON.stringify({ name: agent.name, description: agent.desc, model, ...(agent.tools ? { tools: agent.tools } : {}), prompt: agent.body }, null, 2)}\n`;
+const renderJson = (model, agent) => `${JSON.stringify({ name: agent.name, description: agent.desc, ...(model ? { model } : {}), ...(agent.tools ? { tools: agent.tools } : {}), prompt: agent.body }, null, 2)}\n`;
 function renderToml(model, agent) {
   const esc = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
   // body as a TOML multiline LITERAL string ('''…''') — no escape processing.
   const tools = agent.tools ? `tools = [${agent.tools.map((tool) => `"${tool}"`).join(', ')}]\n` : '';
-  return `name = "${agent.name}"\ndescription = "${esc(agent.desc)}"\nmodel = "${model}"\n${tools}developer_instructions = '''\n${agent.body}\n'''\n`;
+  return `name = "${agent.name}"\ndescription = "${esc(agent.desc)}"\n${model ? `model = "${model}"\n` : ''}${tools}developer_instructions = '''\n${agent.body}\n'''\n`;
+}
+
+// ── #298: the model, decided by the project. `agentModels` in .rsc.json maps a target to a model id
+// or to `inherit`. Absent → the target's default (inherit on OpenCode, the tier model elsewhere). The
+// value lands verbatim in YAML/TOML/JSON from a COMMITTED file, so anything outside a plain model-id
+// alphabet is ignored rather than written: a pulled .rsc.json must not be able to inject frontmatter.
+export const AGENT_MODEL_INHERIT = 'inherit';
+export const isValidAgentModel = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,127}$/.test(value);
+export function agentModelSetting(cwd, target) {
+  let value;
+  try { value = readManifest(cwd)?.agentModels?.[target]; } catch { value = undefined; }
+  return isValidAgentModel(value) ? value : null;
+}
+export const targetInheritsByDefault = (target) => AGENT_TARGETS[target]?.model('balanced') === null;
+function resolveModel(target, cwd, tier) {
+  const setting = agentModelSetting(cwd, target);
+  if (setting === AGENT_MODEL_INHERIT) return null;
+  if (setting) return setting;
+  return AGENT_TARGETS[target].model(tier);
+}
+
+export const effectiveAgentModel = (target, cwd, tier = readDeveloperTier(cwd)) => (AGENT_TARGETS[target] ? resolveModel(target, cwd, tier) : null);
+
+function renderAgent(target, spec, model, agent, toolsFormat) {
+  return spec.format === 'json' ? renderJson(model, agent)
+    : spec.format === 'toml' ? renderToml(model, agent)
+      : renderMd(spec, model, agent, toolsFormat);
+}
+
+// ── #298: what rsc wrote, per file, so a user edit is told apart from rsc's own file. Machine-local
+// (.rsc/ is gitignored): a digest says "this machine's rsc wrote these bytes", which is not a team fact.
+const sha = (text) => createHash('sha256').update(text).digest('hex');
+const digestFile = (cwd) => join(cwd, '.rsc', 'agent-digests.json');
+const relKey = (cwd, path) => relative(cwd, path).split(sep).join('/');
+function readDigests(cwd) {
+  try { const d = JSON.parse(readFileSync(digestFile(cwd), 'utf8')); return d && typeof d === 'object' ? d : {}; } catch { return {}; }
+}
+function writeDigests(cwd, digests) {
+  mkdirSync(dirname(digestFile(cwd)), { recursive: true });
+  const ordered = Object.fromEntries(Object.keys(digests).sort().map((k) => [k, digests[k]]));
+  writeFileSync(digestFile(cwd), `${JSON.stringify(ordered, null, 2)}\n`);
 }
 
+// Every rendering rsc could have produced for this agent on this target: either tier, the current
+// model setting, and — for OpenCode — the pre-#298 shape (pinned Anthropic model, `tool: true` map).
+// A file with no digest that matches one of these is rsc's and may be replaced; anything else is the
+// user's. Bodies from older releases are not reconstructed: such a file is kept and reported, the safe
+// direction, and `rsc agents reset` is one command away.
+function knownRenderings(target, cwd, agent) {
+  const spec = AGENT_TARGETS[target];
+  const out = new Set();
+  for (const tier of ['balanced', 'heavy']) {
+    out.add(renderAgent(target, spec, resolveModel(target, cwd, tier), agent));
+    out.add(renderAgent(target, spec, spec.model(tier), agent));
+    if (spec.legacyModel) out.add(renderAgent(target, spec, spec.legacyModel(tier), agent, 'map'));
+  }
+  return out;
+}
+
+// 'rsc' when the file on disk is rsc's to overwrite or remove, 'user' when it carries the user's edit.
+function ownership(target, cwd, agent, path, digests) {
+  if (!existsSync(path)) return 'absent';
+  const current = readFileSync(path, 'utf8');
+  const key = relKey(cwd, path);
+  if (digests[key]) return digests[key] === sha(current) ? 'rsc' : 'user';
+  return knownRenderings(target, cwd, agent).has(current) ? 'rsc' : 'user';
+}
+
+const keptNotice = (name, path, cwd) => ({
+  name,
+  path,
+  message: `kept your edited agent ${name} (${relKey(cwd, path)}; rsc's version differs; \`rsc agents reset ${name}\` to take it)`,
+});
+
 export function agentPath(target, cwd, name = 'developer') {
   const spec = AGENT_TARGETS[target];
   return spec ? join(cwd, ...spec.dir.split('/'), `${name}${spec.ext}`) : null;
 }
 
-export function writeAgents(target, cwd, tier = readDeveloperTier(cwd), names = agentNames()) {
+/**
+ * Write the agents, keeping any the user edited. Returns { written, kept }: `kept` names each agent
+ * left as the user has it, with the message to show. `force` takes rsc's version regardless — only
+ * `rsc agents reset` passes it, after backing the user's file up.
+ */
+export function writeAgentsDetailed(target, cwd, tier = readDeveloperTier(cwd), names = agentNames(), { force = false } = {}) {
   const spec = AGENT_TARGETS[target];
-  if (!spec) return [];
+  if (!spec) return { written: [], kept: [] };
+  const digests = readDigests(cwd);
   const written = [];
+  const kept = [];
   for (const name of names) {
     const agent = byName(name);
     if (!agent) continue;
     const effectiveTier = agent.tier === 'heavy' ? 'heavy' : tier;
-    const model = spec.model(effectiveTier);
-    const content = spec.format === 'json' ? renderJson(model, agent)
-      : spec.format === 'toml' ? renderToml(model, agent)
-        : renderMd(spec, model, agent);
+    const content = renderAgent(target, spec, resolveModel(target, cwd, effectiveTier), agent);
     const path = agentPath(target, cwd, agent.name);
+    if (!force && ownership(target, cwd, agent, path, digests) === 'user') {
+      // Unless it already IS what rsc would write — then there is nothing to protect, only to record.
+      if (readFileSync(path, 'utf8') !== content) { kept.push(keptNotice(agent.name, path, cwd)); continue; }
+    }
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, content);
+    digests[relKey(cwd, path)] = sha(content);
     written.push(path);
   }
-  return written;
+  writeDigests(cwd, digests);
+  return { written, kept };
+}
+
+export function writeAgents(target, cwd, tier = readDeveloperTier(cwd), names = agentNames(), options) {
+  return writeAgentsDetailed(target, cwd, tier, names, options).written;
 }
 
 export function reconcileAgents(target, cwd, tier, previousNames = [], desiredNames = []) {
-  if (!targetHasAgents(target)) return { written: [], removed: [], collisions: [], names: [] };
+  if (!targetHasAgents(target)) return { written: [], removed: [], collisions: [], names: [], kept: [] };
   const previous = new Set(previousNames);
   const desired = new Set(desiredNames);
-  const removed = removeAgents(target, cwd, [...previous].filter((name) => !desired.has(name)));
+  const kept = [];
+  // An agent no longer wanted is removed only while it is still rsc's file. One the user edited is
+  // theirs now: deleting it on an uninstall or a stack change is the same loss sync must not cause.
+  const digests = readDigests(cwd);
+  const stale = [];
+  for (const name of [...previous].filter((n) => !desired.has(n))) {
+    const agent = byName(name);
+    const path = agentPath(target, cwd, name);
+    if (agent && ownership(target, cwd, agent, path, digests) === 'user') {
+      kept.push({ name, path, message: `kept your edited agent ${name} (${relKey(cwd, path)}); rsc no longer installs it, delete it yourself if you do not want it` });
+    } else stale.push(name);
+  }
+  const removed = removeAgents(target, cwd, stale);
+  if (removed.length) {
+    for (const path of removed) delete digests[relKey(cwd, path)];
+    writeDigests(cwd, digests);
+  }
   const written = [];
   const collisions = [];
   const names = [];
@@ -218,10 +342,12 @@ export function reconcileAgents(target, cwd, tier, previousNames = [], desiredNa
       collisions.push(path);
       continue;
     }
-    written.push(...writeAgents(target, cwd, tier, [name]));
+    const result = writeAgentsDetailed(target, cwd, tier, [name]);
+    written.push(...result.written);
+    kept.push(...result.kept);
     if (existsSync(path)) names.push(name);
   }
-  return { written, removed, collisions, names };
+  return { written, removed, collisions, names, kept };
 }
 
 /**

package/targets/git-permissions.js

@@ -1,7 +1,8 @@
 // Git permissions: on a harness installed from scratch, the agent may `git commit`, `git push` and
 // `gh pr create` without asking — the three steps that close every lane (branch → commit → push →
-// PR). A force-push still asks wherever the assistant can say so. The guards are untouched: a commit
-// on a closed default branch is still denied by branch-guard, whatever the permission says.
+// PR). A force-push still asks wherever the assistant can say so. In Claude Code the guards are
+// untouched: a commit on a closed default branch is still denied by branch-guard, whatever the
+// permission says. No other assistant runs rsc's guards, and `on|off|status` says so (#298).
 //
 // A PROJECT decision, recorded as `gitPermissions` in `.rsc.json`: true on a brand-new project, absent
 // on one adopted before this existed (nothing changes there until `rsc git-permissions on`), false
@@ -25,6 +26,9 @@ const OPENCODE_BASH = [
   ['git commit', 'allow'], ['git commit *', 'allow'], ['git push', 'allow'], ['git push *', 'allow'], ['gh pr create *', 'allow'],
   ['git push --force*', 'ask'], ['git push -f*', 'ask'], ['git push * --force*', 'ask'], ['git push * -f*', 'ask'],
 ];
+// OpenCode 2 reads an ordered top-level `permissions` array (bash → `shell`); same rules, same order.
+const OPENCODE_V2 = OPENCODE_BASH.map(([resource, effect]) => ({ action: 'shell', resource, effect }));
+const FORCE_PATTERNS = OPENCODE_BASH.filter(([, a]) => a === 'ask').map(([p]) => p);
 const CODEX_RULES = `# rsc-git-permissions:managed — written by rsc; \`rsc git-permissions off\` removes it.
 # Commit, push and open a PR without asking; a force-push still asks (the strictest match wins).
 prefix_rule(pattern = ["git", "commit"], decision = "allow", justification = "rsc: close the lane — commit")
@@ -66,6 +70,28 @@ function readJson(path) {
   } catch { return null; }
 }
 
+/** JSONC → JSON, for READING only: drops comments and trailing commas outside strings. */
+export function parseJsonc(text) {
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === '\\' ? 2 : 1;
+      out += text.slice(i, j + 1); i = j;
+    } else if (ch === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      out += '\n';
+    } else if (ch === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end < 0 ? text.length : end + 1;
+    } else out += ch;
+  }
+  // Trailing commas: only outside strings matter, and strings were copied verbatim — so strip them
+  // with a pass that also skips strings.
+  return JSON.parse(out.replace(/("(?:[^"\\]|\\.)*")|,(\s*[}\]])/g, (m, str, close) => str ?? close));
+}
+
 const writeJson = (path, value) => { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`); };
 const addAll = (list, items) => [...(Array.isArray(list) ? list : []), ...items.filter((i) => !(list || []).includes(i))];
 const dropAll = (list, items) => (Array.isArray(list) ? list.filter((i) => !items.includes(i)) : list);
@@ -74,10 +100,125 @@ export function gitPermissionsPath(target, cwd = process.cwd()) {
   return FILES[target] ? join(cwd, ...FILES[target].split('/')) : null;
 }
 
-/** Add rsc's entries. `{ mode: 'wired' | 'unsupported' | 'config-invalid', path }`. */
+// ── OpenCode: V1 (`permission.bash` map) or V2 (`permissions` array) ────────────────────────────
+// OpenCode 2 still reads the V1 map; OpenCode 1.x does not know `permissions`. So V2 is written only
+// when OpenCode 2 is seen on this machine (or the file is already V2); otherwise the V1 map, which
+// both read. `RSC_OPENCODE_MAJOR` pins the version (tests, or a machine where the probe cannot run).
+
+/** Installed OpenCode major version, or null when it cannot be told. */
+export function opencodeMajor() {
+  const pinned = process.env.RSC_OPENCODE_MAJOR;
+  if (pinned !== undefined) return /^\d+$/.test(pinned.trim()) ? Number(pinned.trim()) : null;
+  try {
+    // `opencode` is an npm .cmd shim on Windows, which only a shell resolves.
+    const win = process.platform === 'win32';
+    const out = execFileSync(win ? 'opencode --version' : 'opencode', win ? [] : ['--version'], {
+      windowsHide: true, timeout: 3000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], shell: win,
+    });
+    const m = /(\d+)\.\d+/.exec(out);
+    return m ? Number(m[1]) : null;
+  } catch { return null; }
+}
+
+const sameRule = (a, b) => a && typeof a === 'object' && a.action === b.action && a.resource === b.resource && a.effect === b.effect;
+const isRscV2 = (rule) => OPENCODE_V2.some((r) => sameRule(rule, r));
+const hasV1 = (config) => OPENCODE_BASH.every(([p, a]) => config?.permission?.bash?.[p] === a);
+const hasV2 = (config) => Array.isArray(config?.permissions) && OPENCODE_V2.every((r) => config.permissions.some((x) => sameRule(x, r)));
+const jsoncOnly = (cwd) => !existsSync(join(cwd, 'opencode.json')) && existsSync(join(cwd, 'opencode.jsonc'));
+
+function opencodeFormat(config) {
+  const major = opencodeMajor();
+  if (major !== null) return major >= 2 ? 'v2' : 'v1';
+  return Array.isArray(config?.permissions) ? 'v2' : 'v1';
+}
+
+function dropV1(config) {
+  const bash = config.permission?.bash;
+  if (!bash || typeof bash !== 'object') return;
+  for (const [pattern, action] of OPENCODE_BASH) if (bash[pattern] === action) delete bash[pattern];
+  if (!Object.keys(bash).length) delete config.permission.bash;
+  if (!Object.keys(config.permission).length) delete config.permission;
+}
+
+function dropV2(config) {
+  if (!Array.isArray(config.permissions)) return;
+  config.permissions = config.permissions.filter((r) => !isRscV2(r));
+  if (!config.permissions.length) delete config.permissions;
+}
+
+// Where rsc's V2 block goes. The last matching rule wins, so a rule placed AFTER rsc's beats it. rsc
+// must never loosen what the person decided, so its block goes BEFORE their rules: any rule of theirs
+// that matches the same command later (a `deny` on `git push *`, an `ask` on `git *`) still wins.
+// The one exception is a leading catch-all baseline (`resource: "*"` with `allow` or `ask`, the usual
+// "ask for everything" default): rsc goes after it, or that default would make rsc's allows dead —
+// what the V1 map has always done too. A catch-all `deny` is never stepped over.
+function v2InsertAt(list) {
+  let i = 0;
+  while (i < list.length && list[i]?.resource === '*' && ['*', 'shell'].includes(list[i]?.action) && list[i]?.effect !== 'deny') i++;
+  return i;
+}
+
+function wireOpencode(config, format) {
+  if (format === 'v2') {
+    if (config.permissions !== undefined && !Array.isArray(config.permissions)) return false;
+    dropV1(config); // migrating: rsc's old V1 entries go, the person's stay
+    const list = (config.permissions || []).filter((r) => !isRscV2(r));
+    const at = v2InsertAt(list);
+    config.permissions = [...list.slice(0, at), ...OPENCODE_V2.map((r) => ({ ...r })), ...list.slice(at)];
+  } else {
+    if (config.permission !== undefined && (typeof config.permission !== 'object' || config.permission === null)) return false;
+    config.permission ||= {};
+    if (typeof config.permission.bash === 'string') return false; // a blanket rule is the person's call
+    dropV2(config); // back on 1.x (or unknown on a V1 file): one block, the one this OpenCode reads
+    const bash = config.permission.bash && typeof config.permission.bash === 'object' ? config.permission.bash : {};
+    // Re-inserted so the asks stay after the allows (OpenCode: the last matching rule wins).
+    for (const [pattern] of OPENCODE_BASH) delete bash[pattern];
+    for (const [pattern, action] of OPENCODE_BASH) bash[pattern] = action;
+    config.permission.bash = bash;
+  }
+  config.$schema ||= 'https://opencode.ai/config.json';
+  return true;
+}
+
+// One rule per line: short enough to read in a terminal, valid JSON to paste.
+function snippet(format, pairs) {
+  if (format === 'v2') {
+    const rows = pairs.map(([resource, effect]) => `  ${JSON.stringify({ action: 'shell', resource, effect })}`);
+    return `"permissions": [\n${rows.join(',\n')}\n]`;
+  }
+  const rows = pairs.map(([p, a]) => `    ${JSON.stringify(p)}: ${JSON.stringify(a)}`);
+  return `"permission": {\n  "bash": {\n${rows.join(',\n')}\n  }\n}`;
+}
+
+/** The exact rules rsc would write, to paste into an OpenCode config. */
+export const opencodeRulesSnippet = (format) => snippet(format, OPENCODE_BASH);
+
+/** A stricter policy only OpenCode itself can enforce: refuse every force-push (`ask` also works). */
+export const opencodeForcePushSnippet = (format) => snippet(format, FORCE_PATTERNS.map((p) => [p, 'deny']));
+
+function readJsonc(path) {
+  try {
+    const value = parseJsonc(readFileSync(path, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch { return null; }
+}
+
+/**
+ * Add rsc's entries. `{ mode: 'wired' | 'manual' | 'unsupported' | 'config-invalid', path }`; OpenCode
+ * adds `format` ('v1' | 'v2'), and on 'manual' (an opencode.jsonc rsc will not rewrite) the `snippet`.
+ */
 export function wireGitPermissions(target, cwd = process.cwd()) {
   const path = gitPermissionsPath(target, cwd);
   if (!path) return { mode: 'unsupported', path: null };
+  if (target === 'opencode' && jsoncOnly(cwd)) {
+    // Rewriting a JSONC file would drop the person's comments: read it, never write it.
+    const jsonc = join(cwd, 'opencode.jsonc');
+    const config = readJsonc(jsonc);
+    if (config && hasV2(config)) return { mode: 'wired', path: jsonc, format: 'v2' };
+    if (config && hasV1(config)) return { mode: 'wired', path: jsonc, format: 'v1' };
+    const format = opencodeFormat(config);
+    return { mode: 'manual', path: jsonc, format, snippet: opencodeRulesSnippet(format) };
+  }
   if (target === 'codex') {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, CODEX_RULES);
@@ -95,14 +236,11 @@ export function wireGitPermissions(target, cwd = process.cwd()) {
     config.tools ||= {};
     config.tools.allowed = addAll(config.tools.allowed, GEMINI_ALLOW);
   } else if (target === 'opencode') {
-    config.permission ||= {};
-    if (typeof config.permission.bash === 'string') return { mode: 'config-invalid', path }; // a blanket rule is the person's call
-    const bash = config.permission.bash && typeof config.permission.bash === 'object' ? config.permission.bash : {};
-    // Re-inserted so the asks stay after the allows (OpenCode: the last matching rule wins).
-    for (const [pattern] of OPENCODE_BASH) delete bash[pattern];
-    for (const [pattern, action] of OPENCODE_BASH) bash[pattern] = action;
-    config.permission.bash = bash;
-    config.$schema ||= 'https://opencode.ai/config.json';
+    const format = opencodeFormat(config);
+    if (!wireOpencode(config, format)) return { mode: 'config-invalid', path, format };
+    writeJson(path, config);
+    if (!existed) excludeIfNew(cwd, path);
+    return { mode: 'wired', path, format };
   }
   writeJson(path, config);
   if (!existed && target !== 'claude') excludeIfNew(cwd, path);
@@ -129,10 +267,11 @@ export function unwireGitPermissions(target, cwd = process.cwd()) {
     config.tools.allowed = dropAll(config.tools.allowed, GEMINI_ALLOW);
     if (Array.isArray(config.tools.allowed) && !config.tools.allowed.length) delete config.tools.allowed;
     if (!Object.keys(config.tools).length) delete config.tools;
-  } else if (target === 'opencode' && config.permission?.bash && typeof config.permission.bash === 'object') {
-    for (const [pattern, action] of OPENCODE_BASH) if (config.permission.bash[pattern] === action) delete config.permission.bash[pattern];
-    if (!Object.keys(config.permission.bash).length) delete config.permission.bash;
-    if (!Object.keys(config.permission).length) delete config.permission;
+  } else if (target === 'opencode') {
+    const before = JSON.stringify(config);
+    dropV1(config); // both formats: machines on OpenCode 1.x and 2 may share this file
+    dropV2(config);
+    if (JSON.stringify(config) === before) return [];
   } else return [];
   writeJson(path, config);
   return [path];
@@ -146,6 +285,105 @@ export function gitPermissionsWired(target, cwd = process.cwd()) {
   const config = readJson(path) || {};
   if (target === 'claude') return CLAUDE_ALLOW.every((r) => config.permissions?.allow?.includes(r));
   if (target === 'gemini') return GEMINI_ALLOW.every((r) => config.tools?.allowed?.includes(r));
-  if (target === 'opencode') return OPENCODE_BASH.every(([p, a]) => config.permission?.bash?.[p] === a);
+  if (target === 'opencode') return gitPermissionsState(target, cwd).wired;
   return false;
 }
+
+/**
+ * `{ wired, format, path }` for `status`. format: Claude/Codex/Gemini → 'native'; OpenCode → 'v1' or
+ * 'v2' (where rsc's rules are, or where they would go) or 'manual' (opencode.jsonc, rules not pasted).
+ */
+export function gitPermissionsState(target, cwd = process.cwd()) {
+  const path = gitPermissionsPath(target, cwd);
+  if (!path) return { wired: false, format: null, path: null };
+  if (target !== 'opencode') return { wired: gitPermissionsWired(target, cwd), format: 'native', path };
+  if (jsoncOnly(cwd)) {
+    const jsonc = join(cwd, 'opencode.jsonc');
+    const config = readJsonc(jsonc);
+    if (config && hasV2(config)) return { wired: true, format: 'v2', path: jsonc };
+    if (config && hasV1(config)) return { wired: true, format: 'v1', path: jsonc };
+    return { wired: false, format: 'manual', path: jsonc };
+  }
+  const config = (existsSync(path) && readJson(path)) || {};
+  if (hasV2(config)) return { wired: true, format: 'v2', path };
+  if (hasV1(config)) return { wired: true, format: 'v1', path };
+  return { wired: false, format: opencodeFormat(config), path };
+}
+
+// ── What `rsc git-permissions on|off|status` says, per assistant (#298) ─────────────────────────
+// Three things, always: what rsc controls there, what stops when it is off, and what is left to the
+// assistant itself. The guards are named only where they exist: rsc's PreToolUse guards
+// (branch-guard, danger-guard) run in Claude Code alone; no other assistant runs them.
+
+const LABEL = { claude: 'Claude Code', codex: 'Codex', gemini: 'Gemini CLI', opencode: 'OpenCode', cursor: 'Cursor', deepseek: 'DeepSeek Harness' };
+const RULES = 'allow git commit, git push and gh pr create without asking, and ask before a force-push';
+
+const WHEN_OFF = {
+  claude: 'rsc removes its rules; Claude Code asks again for commit, push and PR, unless your own permissions allow them.',
+  codex: 'rsc deletes its rules file; Codex applies its own approval policy and any rules of yours in .codex/rules.',
+  gemini: 'rsc removes its entries; Gemini CLI asks before those commands unless your own tools.allowed lists them.',
+  opencode: 'rsc removes its rules; only your own OpenCode rules apply. With no rule matching, OpenCode 2 asks and OpenCode 1.x runs the command.',
+};
+
+const indent = (text, pad = '    ') => text.split('\n').map((l) => pad + l).join('\n');
+
+function claudeGuards(cwd) {
+  const rsc = join(cwd, '.rsc');
+  const out = [];
+  if (existsSync(join(rsc, 'branch-guard.mjs'))) out.push('branch-guard (refuses a commit on a closed main)');
+  if (existsSync(join(rsc, 'danger-guard.mjs')) && !existsSync(join(rsc, '.no-danger-guard'))) out.push('danger-guard (stops a force-push, reset --hard and similar)');
+  return out;
+}
+
+// The OpenCode format the snippets should use: where rsc's rules are, or where they would go.
+function opencodeSnippetFormat(state) {
+  return state.format === 'manual' ? opencodeFormat(readJsonc(state.path)) : state.format;
+}
+
+function stateLine(target, cwd, s) {
+  const where = s.path ? rel(cwd, s.path) : '';
+  if (s.format === 'manual') return `  Now: not written. ${where} has comments rsc will not rewrite; paste these rules into it:\n${indent(opencodeRulesSnippet(opencodeSnippetFormat(s)))}`;
+  const fmt = target === 'opencode' ? ` (${s.format === 'v2' ? 'OpenCode 2 `permissions`' : 'OpenCode 1.x `permission.bash`, read by 2 too'})` : '';
+  return `  Now: ${s.wired ? 'on' : 'off'} in ${where}${fmt}.`;
+}
+
+function block(target, cwd) {
+  const label = LABEL[target] || target;
+  const path = gitPermissionsPath(target, cwd);
+  if (!path) {
+    return `${label}\n  rsc controls: nothing here. ${target === 'cursor'
+      ? 'Its CLI matches only the first word, so allowing a push would allow every git command.'
+      : 'It has no per-command allow list.'}\n  ${label}'s job: every git permission.`;
+  }
+  const state = gitPermissionsState(target, cwd);
+  const lines = [label, stateLine(target, cwd, state), `  rsc controls: rules in ${rel(cwd, state.path)} that ${RULES}.`];
+  if (target === 'claude') {
+    const guards = claudeGuards(cwd);
+    lines.push(guards.length
+      ? `  Also rsc, whatever this switch says: ${guards.join('; ')}.`
+      : '  rsc\'s guards (branch-guard, danger-guard) are not installed in this project.');
+  }
+  lines.push(`  When off: ${state.path.endsWith('.jsonc')
+    ? 'rsc never edits opencode.jsonc, so remove the pasted rules yourself; then only your own OpenCode rules apply.'
+    : WHEN_OFF[target]}`);
+  if (target === 'claude') lines.push(`  ${label}'s job: anything its own permissions decide beyond rsc's rules and guards.`);
+  else {
+    lines.push(`  ${label}'s job: there is no rsc guard in ${label}, so nothing from rsc stops a commit on main or a force-push there. A stricter policy (refuse a force-push, a human approval) goes in ${label}'s own configuration.`);
+    if (target === 'opencode') {
+      const fmt = opencodeSnippetFormat(state);
+      lines.push(`  To refuse every force-push in OpenCode ${fmt === 'v2' ? '2' : '1.x'} (use "ask" for a human approval), add at the END of ${fmt === 'v2' ? '`permissions`' : '`permission.bash`'} (the last matching rule wins):`);
+      lines.push(indent(opencodeForcePushSnippet(fmt)));
+    }
+  }
+  return lines.join('\n');
+}
+
+/** The human explanation for `on`, `off` and `status`, one block per assistant in `targets`. */
+export function explainGitPermissions({ targets, cwd = process.cwd(), mode = 'status', declared } = {}) {
+  const head = {
+    on: 'rsc git-permissions on. Saved in .rsc.json: commit it so the team gets the same decision.',
+    off: 'rsc git-permissions off. Saved in .rsc.json: commit it so the team gets the same decision.',
+    status: `rsc git-permissions: ${declared === undefined ? 'undecided (this project was adopted before; nothing is changed until `rsc git-permissions on`)' : declared ? 'on' : 'off'}.`,
+  }[mode];
+  return [head, ...targets.map((t) => block(t, cwd))].join('\n\n');
+}