@ericrisco/rsc 3.0.8 → 3.0.10

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';
@@ -25,6 +28,7 @@ import {
   buildOnboardingPlan, decodeGoal, encodeGoal, identifyPlan, recommendDeferredComponents,
 } from './lib/onboarding.js';
 import { applyAcceptedOnboarding, verifyOnboarding, ensureHarnessSkeleton, harnessReadiness } from './lib/onboarding-apply.js';
+import { CONSTITUTION_PATH, constitutionIsDraft, ensureConstitutionDraft } from './lib/constitution-draft.js';
 
 const rawArgv = process.argv.slice(2);
 
@@ -42,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');
@@ -73,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++) {
@@ -298,6 +302,14 @@ async function runOnboarding(targets) {
   } catch (error) {
     say(`RSC_SKELETON_FAILED ${error.message}`);
   }
+  // La constitución, como BORRADOR, cuando el plan eligió SDD y no hay ninguna. Sin esto una
+  // instalación no interactiva de software complejo acababa INCOMPLETE: sólo una fase agéntica la
+  // escribía. Mismo sitio y mismo motivo que el esqueleto: fuera de la transacción, sin residuo.
+  try {
+    ensureConstitutionDraft(process.cwd(), plan);
+  } catch (error) {
+    say(`RSC_SKELETON_FAILED ${error.message}`);
+  }
   // The audit cadence starts at install. Without a baseline the very first session after onboarding
   // announced "a skill audit is due" about a set chosen minutes earlier. Never overwrites a real run.
   try { recordAuditBaseline(process.cwd()); } catch { /* a missing baseline only means an early nudge */ }
@@ -313,7 +325,14 @@ async function runOnboarding(targets) {
 // poco se cumplía entero. Spec: 02-DOCS/wiki/sdd/specs/install-completion-floor.md
 function emitHarnessReadiness(plan, planId) {
   const readiness = harnessReadiness(process.cwd(), plan);
-  if (readiness.ready) return void say(`RSC_ONBOARDING_READY ${planId}`);
+  if (readiness.ready) {
+    say(`RSC_ONBOARDING_READY ${planId}`);
+    // Listo no es «nada pendiente»: el borrador se nombra para que la cadena SDD lo complete primero.
+    if ((plan.floorPaths || []).includes(CONSTITUTION_PATH) && constitutionIsDraft(process.cwd())) {
+      say(`  Pending: ${CONSTITUTION_PATH} is a draft — complete it with the \`constitution\` phase before the first SDD feature.`);
+    }
+    return;
+  }
   say(`RSC_ONBOARDING_INCOMPLETE ${planId}`);
   for (const missing of safeLines(readiness.missing)) say(`  ${missing}`);
   say(`  Next: ${readiness.action}`);
@@ -400,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) {
@@ -557,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
@@ -569,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.
@@ -608,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}`);
     }
@@ -854,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));
     }
@@ -936,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;
     }
@@ -1007,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/skills/constitution/SKILL.md

@@ -86,6 +86,8 @@ Write `02-DOCS/wiki/sdd/constitution.md` from the template in `references/consti
 
 Create `02-DOCS/wiki/sdd/` if it does not exist. Do not overwrite an existing constitution — amend it.
 
+**A draft is "complete me", not "amend me".** `rsc onboard` writes a skeleton with `status: draft` in the frontmatter: the template's headings, the facts onboarding knew (goal, kind, scope, workflow, detected stack) and no principle. Keep those facts, run the interview, fill the sections, then on ratification drop `status: draft`, set `version: v1.0.0` and log v1.0.0 in the amendment log.
+
 ## Versioning & amendment protocol
 
 The constitution is versioned so `analyze` and `review` can cite "constitution v1.2.0, principle 4".

package/skills/ftd/SKILL.md

@@ -34,6 +34,11 @@ repository**: whoever clones it should get code, not somebody else's notes in pr
 It is written **before the first change**, not after, and it holds exactly this:
 
 ```markdown
+---
+author: <who asked for it — git user.name>
+branch: <the branch the work runs on>
+status: in-progress
+---
 # <feature>
 
 ## Intent          — what changes, and why it is worth doing
@@ -43,6 +48,10 @@ It is written **before the first change**, not after, and it holds exactly this:
 ## Next            — the single next step, so an interruption costs nothing
 ```
 
+The frontmatter says whose work it is, so «¿qué ha hecho cada uno?» has an answer. You never close
+it by hand: when the branch lands on the default branch, rsc's post-merge hook sets `status: done`
+and replaces Next with where and when it merged (on a closed default branch, via `rsc/knowledge`).
+
 No decision journal, no phase records, no approvals. If a decision was meaningful, one line of
 rationale goes next to the task it belongs to.
 

package/skills/sdd/SKILL.md

@@ -77,7 +77,7 @@ When a request lands, do not start typing code. Place it on the map first, then
 > **The new-feature gate (hard).** The moment the user is thinking about a new feature or change — "add…", "build…", "it should also…", "quiero añadir…" — it goes to `specify` first, *even if a stack skill (nextjs/fastapi/flutter/react…) also fired and could just build it*. **No feature code is written — by any skill — until a spec AND a plan exist and the user has approved them.** A stack skill about to build an unspec'd, non-trivial feature must stop and route here. The only exception is a genuinely one-line, low-risk change; name it and skip.
 
 1. **No `02-DOCS/wiki/sdd/config.yaml` and this is non-trivial?** → `sdd-init`.
-2. **No constitution yet AND this project will grow?** → `constitution` once, then come back to the chain.
+2. **No constitution yet AND this project will grow — or its frontmatter says `status: draft` (the one `rsc onboard` writes)?** → `constitution` once, then come back to the chain.
 3. **Ambiguous / architectural / risky change before spec?** → optional proposal artifact via `specify`.
 4. **A new idea, fuzzy, no spec on disk?** → `specify`.
 5. **A spec exists but feels risky / has open questions?** → `clarify`.
@@ -93,7 +93,7 @@ If you genuinely cannot tell which phase you are in, ask the user one question:
 ### Skip rules (be honest about them)
 
 - A **one-line, low-risk change** (typo, copy tweak, config bump) does not need the full chain. Say so, do it, and verify. The method serves shipping, not ceremony.
-- `constitution` runs **once per project**, not per feature. If `02-DOCS/wiki/sdd/constitution.md` exists, read it as guardrails and move on.
+- `constitution` runs **once per project**, not per feature. If `02-DOCS/wiki/sdd/constitution.md` exists, read it as guardrails and move on — unless it is still `status: draft`: then complete it first.
 - `clarify` and `analyze` are **gates, not paperwork**. If a spec is genuinely unambiguous and tiny, name that out loud and pass through — but the bias is to run them, because skipped gates are where drift hides.
 
 ## Autopilot mode — run the whole chain on one up-front yes

package/skills/specify/SKILL.md

@@ -341,7 +341,7 @@ repeated here as prohibitions: naming a behaviour makes it more available, not l
 ## Project grounding (02-DOCS + CLAUDE.md)
 
 - Read `02-DOCS/wiki/sdd/config.yaml` if present. If it is missing and the change is non-trivial, recommend `sdd-init` before proceeding; if the user asks to continue, record the missing config as a risk.
-- Read `02-DOCS/wiki/sdd/constitution.md` first — its principles are inherited constraints, not things to re-decide. If it's missing, note that the project has no constitution yet and suggest the `constitution` phase before continuing (you can still draft a spec, but flag the absence).
+- Read `02-DOCS/wiki/sdd/constitution.md` first — its principles are inherited constraints, not things to re-decide. If it's missing, note that the project has no constitution yet and suggest the `constitution` phase before continuing (you can still draft a spec, but flag the absence). If its frontmatter says `status: draft` (written by `rsc onboard`, unratified), route to `constitution` first and come back: a draft has no principles to inherit.
 - **No constitution yet?** Still write the spec, but inherit nothing — lean harder on the wiki and the user's answers, and record every constraint you would have inherited as a *point to clarify* instead of assuming it.
 - Write the spec to `02-DOCS/wiki/sdd/specs/<slug>.md`. Create the directory if absent.
 - Add a row in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) linking the new spec under the `sdd/specs` topic (additive only — never delete existing rows). Create the index if absent.

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/clone-bootstrap.mjs

@@ -43,7 +43,7 @@ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/i;
  * nothing checks is just drift with a head start.
  */
 export const PROJECT_OPT_OUTS = [
-  'audit', 'auto-update', 'claudemd-check', 'danger-guard', 'feature-gate', 'ftd-nudge', 'gitmoji', 'knowledge-sync', 'ship-guard', 'trunk-guard', 'trunk-open', 'worktree-cleanup', 'worktree-isolation',
+  'audit', 'auto-update', 'claudemd-check', 'danger-guard', 'feature-gate', 'ftd-close', 'ftd-nudge', 'gitmoji', 'knowledge-sync', 'ship-guard', 'trunk-guard', 'trunk-open', 'worktree-cleanup', 'worktree-isolation',
 ];
 
 /**

package/targets/ftd-nudge.mjs

@@ -23,7 +23,7 @@ const KEEP = 50;
 
 export const NUDGE = 'rsc · lane: this session is changing code and has no feature document yet. ' +
   'Before going on, decide the lane and say it in one line: simple → write 02-DOCS/wiki/ftd/<slug>.md now ' +
-  '(Intent, Scope, Checklist with how each item is proven, Evidence, Next) — one document per feature, ' +
+  '(frontmatter author/branch/status: in-progress; Intent, Scope, Checklist with how each item is proven, Evidence, Next) — one document per feature, ' +
   'a box ticked only with its observed proof under Evidence, Next kept current; big or ' +
   'interlocking → SDD (spec first). A one-line, zero-risk change needs no document: say so instead.';