Add User scope toggle for variant runs

Runs default to `--setting-sources project` (project-only). The new
topbar chip lets the user opt into `user,project`, which pulls in
`~/.claude/CLAUDE.md`, slash commands from `~/.claude/skills/`,
enabled plugins, and the env/permissions from `~/.claude/settings.json`.
With user scope on, `--disable-slash-commands` is dropped so installed
slash commands actually dispatch.

Replaces the old `skillsEnabled` field; the schema migrates the old
key forward. The rename reflects that this is all-or-nothing in
`claude -p` — there is no finer knob that loads skills alone, so
the toggle has to advertise the wider scope honestly.

Folds in CLAUDE.md docs for both the user-scope flag gating and the
write-mode --append-system-prompt landed in 9f7a280, since the two
edits to the Spawn paragraph were physically interleaved.

Author: slaFFik

CLAUDE.md

@@ -65,7 +65,7 @@ Tests are plain tsx scripts, not a framework. Each file declares scenarios via a
    - Top-level entries of the user's project are mirrored by recursively walking the source tree, creating real directories on the sandbox side and **hardlinking individual files** (with a copy fallback on `EXDEV` when source and storage live on different filesystems). Hardlinks rather than symlinks because Claude Code's `Glob` and `Grep` are backed by `rg --files`, which skips symlinks without `--follow` — symlinked leaves would make the entire tree invisible to glob discovery. Filtering applies at every level: `HARD_EXCLUDED` (`.git`, `.claude`, `node_modules`, `.DS_Store`), root + nested `.gitignore`, the user's global git excludes file, source-side symlinks whose realpath escapes `cwd`, and symlink cycles.
    - Filtering subtleties — easy to regress when refactoring `sandbox.ts`: the ignore chain is walked **most-specific to least-specific** using `Ignore.test()` so a nested `!keep.log` overrides a root `*.log` (matches git's per-directory precedence — don't switch to `.ignores()`, which short-circuits and ignores negation). `Mirror.walk` records the **realpath of every directory it descends into** (not only symlink targets), so a symlink pointing back at a real-dir ancestor (`a/b/loop -> a`) is rejected on first encounter rather than after a wasted level of mirroring. Storage-root exclusion uses **realpath** (`realIsStorageRoot` against `classified.realTarget ?? <cwdReal>/<name>`), not the entry's path string — a top-level symlink like `alias -> .storage` would otherwise pass a name-based guard and let the mirror copy the sandbox's own state into a run dir.
    - In `write` mode, a `.claude/settings.json` allows `Write`/`Edit` only against `../outputs/**` (the per-run outputs dir, one level above the child's cwd). Read-only mode passes a tools allowlist of `Read,Glob,Grep,WebSearch,WebFetch`; write mode adds `Write,Edit`.
-3. **Spawn** (`src/server/runner.ts`) — invokes `claude -p <prompt> --output-format stream-json --include-partial-messages --verbose --model <m> --tools <list> --allowedTools <list> --strict-mcp-config --setting-sources project --disable-slash-commands`. The runner **strips** `NODE_OPTIONS`, `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_COMMON_DIR`, `GIT_CEILING_DIRECTORIES`, `CLAUDE_PROJECT_DIR`, `CLAUDE_PROJECT_NAME` from the spawn environment so a parent shell can't override the planted sandbox. `HOME` / `CLAUDE_CONFIG_DIR` are kept so the child reads the user's auth.
+3. **Spawn** (`src/server/runner.ts`) — invokes `claude -p <prompt> --output-format stream-json --include-partial-messages --verbose --model <m> --tools <list> --allowedTools <list> --strict-mcp-config --setting-sources <scope>` and (when user scope is off) `--disable-slash-commands`. The two trailing flags are gated by `session.userScopeEnabled` (topbar "User scope" chip): off by default ⇒ `--setting-sources project --disable-slash-commands`; on ⇒ `--setting-sources user,project` and the disable flag is dropped. `user,project` is all-or-nothing in `claude -p` — there's no finer knob that loads `~/.claude/skills/` alone, so flipping it on also injects the user CLAUDE.md, enabled plugins (skills/hooks/agents), and the env/permissions blocks from `~/.claude/settings.json`. Naive removal of `--disable-slash-commands` looks like it should re-enable installed skills but doesn't: the user setting source has to be widened too. When `mode === 'write'`, the runner additionally passes `--append-system-prompt <WRITE_MODE_SYSTEM_PROMPT>` (text lives in `src/shared/constants.ts`) telling the child to mirror source paths under `../outputs/<rel>` and write full files — without this nudge, models often recognize the `Write(**)`/`Edit(**)` deny rule from the planted `.claude/settings.json` and bail out ("I cannot apply these fixes") instead of producing modified copies in the outputs dir. Confounder to watch for when designing a write-mode variant: if the variant's own content prescribes a different output convention (e.g. "place results in `results/`"), it conflicts with this directive — that's the first place to look if write-mode A/B results seem off. The runner **strips** `NODE_OPTIONS`, `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_COMMON_DIR`, `GIT_CEILING_DIRECTORIES`, `CLAUDE_PROJECT_DIR`, `CLAUDE_PROJECT_NAME` from the spawn environment so a parent shell can't override the planted sandbox. `HOME` / `CLAUDE_CONFIG_DIR` are kept so the child reads the user's auth.
 4. **Stream parsing** (`src/server/claudeStream.ts`) — line-buffers stdout into Anthropic stream events. Normalizes them into `NormalizedEvent`s (see `src/shared/schemas/events.ts`). Two non-obvious rules:
    - **Turn counting:** increment on every `message_stop` where `currentMessageRole === 'assistant'`. Tool-use stops count too, so the live counter advances on each intermediate assistant message — useful as a "model is doing work" heartbeat. Partial deltas never count.
    - **Tool result pairing:** `tool_result` events arrive in a later (user) message and may be reordered relative to their `tool_use` blocks. Pair by `tool_use_id`, not by recency (issue #5).

src/server/routes.ts

@@ -141,6 +141,8 @@ export function createRouter(deps: RouteDeps) {
             }
             s.judgeModel = next;
           }
+          if (body.userScopeEnabled !== undefined)
+            s.userScopeEnabled = Boolean(body.userScopeEnabled);
           if (body.defaultModel !== undefined) s.defaultModel = String(body.defaultModel);
         });
         return json(res, 200, updated);
@@ -262,6 +264,7 @@ interface PatchSessionBody {
   mode?: string;
   judgeEnabled?: boolean;
   judgeModel?: string;
+  userScopeEnabled?: boolean;
   defaultModel?: string;
 }
 

src/server/runManager.ts

@@ -352,6 +352,7 @@ export class RunManager extends EventEmitter {
       model: col.model,
       effort: col.effort ?? defaultEffortForModel(col.model),
       mode: sessionSnap.mode as Mode,
+      userScopeEnabled: sessionSnap.userScopeEnabled,
       initialConfig,
     });
 

src/server/runner.ts

@@ -32,6 +32,9 @@ export interface RunnerInput {
   model: string;
   effort?: Effort | null; // null/undefined → omit --effort
   mode: Mode;
+  // When true, widens --setting-sources to `user,project` and drops
+  // --disable-slash-commands. See buildArgs() for the full trade-off.
+  userScopeEnabled?: boolean;
   allowedTools?: string[]; // defaults based on mode
   caps?: { turns?: number; wallClockMs?: number };
   env?: NodeJS.ProcessEnv;
@@ -425,9 +428,15 @@ export class Runner extends EventEmitter {
       toolsStr,
       '--strict-mcp-config',
       '--setting-sources',
-      'project',
-      '--disable-slash-commands',
+      // `user,project` is all-or-nothing in `claude -p` — widening also pulls
+      // in the user CLAUDE.md, plugins, env, and permissions from settings.json.
+      this.input.userScopeEnabled ? 'user,project' : 'project',
     ];
+    // With project-only sources the only slash commands are CLI built-ins;
+    // disable so they don't dispatch and make runs non-deterministic.
+    if (!this.input.userScopeEnabled) {
+      args.push('--disable-slash-commands');
+    }
     // Write mode: nudge the child to mirror source paths under ../outputs/
     // instead of bailing on the sandbox's Write(**)/Edit(**) deny rule.
     if (this.input.mode === 'write') {

src/shared/schemas/session.ts

@@ -17,16 +17,30 @@ export const ColumnConfigSchema = z.object({
 });
 export type ColumnConfig = z.infer<typeof ColumnConfigSchema>;
 
-export const SessionFileSchema = z.object({
-  mode: ModeSchema,
-  judgeEnabled: z.boolean(),
-  // Concrete model ID (not an alias) used by the Haiku-by-default judge subprocess.
-  // Optional+default keeps pre-existing session.json files (without this field) parsing cleanly.
-  judgeModel: ModelIdSchema.optional().default('claude-haiku-4-5'),
-  defaultModel: ModelIdSchema,
-  cwd: z.string(),
-  columns: z.array(ColumnConfigSchema).min(1).max(3),
-});
+// `skillsEnabled` was renamed to `userScopeEnabled`; copy the old key forward
+// so existing session.json files keep the user's prior choice.
+export const SessionFileSchema = z.preprocess(
+  (data) => {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+      const obj = data as Record<string, unknown>;
+      if ('skillsEnabled' in obj && !('userScopeEnabled' in obj)) {
+        const { skillsEnabled, ...rest } = obj;
+        return { ...rest, userScopeEnabled: skillsEnabled };
+      }
+    }
+    return data;
+  },
+  z.object({
+    mode: ModeSchema,
+    judgeEnabled: z.boolean(),
+    // Optional+default keeps pre-existing session.json files (without this field) parsing cleanly.
+    judgeModel: ModelIdSchema.optional().default('claude-haiku-4-5'),
+    userScopeEnabled: z.boolean().optional().default(false),
+    defaultModel: ModelIdSchema,
+    cwd: z.string(),
+    columns: z.array(ColumnConfigSchema).min(1).max(3),
+  }),
+);
 export type SessionFile = z.infer<typeof SessionFileSchema>;
 
 export const MAX_COLUMNS = 3;
@@ -37,6 +51,7 @@ export function makeDefaultSession(cwd: string): SessionFile {
     mode: 'read-only',
     judgeEnabled: true,
     judgeModel: 'claude-haiku-4-5',
+    userScopeEnabled: false,
     defaultModel,
     cwd,
     columns: [makeBlankColumn('col-1', defaultModel), makeBlankColumn('col-2', defaultModel)],

src/web/App.tsx

@@ -22,6 +22,7 @@ import {
 import { VariantColumn } from './components/VariantColumn.js';
 import { Footer, REPO_URL } from './components/Footer.js';
 import { Hint } from './components/Hint.js';
+import { UserScopeHint } from './components/UserScopeHint.js';
 
 type LiveEvent =
   | { kind: 'partial'; streamKind: 'text' | 'thinking'; chunk: string }
@@ -598,6 +599,16 @@ export function App(): JSX.Element {
     }
   }, []);
 
+  const onToggleUserScope = useCallback(async () => {
+    if (!state.session) return;
+    try {
+      const s = await patchSession({ userScopeEnabled: !state.session.userScopeEnabled });
+      dispatch({ type: 'session-patched', payload: s });
+    } catch (err) {
+      dispatch({ type: 'error', message: (err as Error).message });
+    }
+  }, [state.session]);
+
   const onStartNewConfirm = useCallback(async () => {
     dispatch({ type: 'set-confirm-start-new', open: false });
     try {
@@ -650,6 +661,15 @@ export function App(): JSX.Element {
             </div>
           </div>
         </div>
+        <Hint content={<UserScopeHint />}>
+          <button
+            className="chip"
+            aria-pressed={session.userScopeEnabled}
+            onClick={onToggleUserScope}
+          >
+            User scope: {session.userScopeEnabled ? 'On' : 'Off'}
+          </button>
+        </Hint>
         <span className="spacer" />
         <span style={{ color: 'var(--fg-dim)', fontFamily: 'var(--mono)', fontSize: 11 }}>
           {session.cwd}

src/web/components/UserScopeHint.tsx

@@ -0,0 +1,22 @@
+import type { JSX } from 'react';
+
+export function UserScopeHint(): JSX.Element {
+  return (
+    <div className="user-scope-hint">
+      <p>
+        <strong>Off (default)</strong> — Project-scope only. Variants run without your user-level
+        settings, skills, plugins, or CLAUDE.md.
+      </p>
+      <p>
+        <strong>On</strong> — Adds the user setting source:
+      </p>
+      <ul>
+        <li>~/.claude/CLAUDE.md</li>
+        <li>~/.claude/skills/* (slash commands)</li>
+        <li>Enabled plugins (skills, hooks, agents)</li>
+        <li>Permissions + env from settings.json</li>
+      </ul>
+      <p className="dim">Per-user reproducible only.</p>
+    </div>
+  );
+}

src/web/lib/api.ts

@@ -72,6 +72,7 @@ export async function patchSession(body: {
   mode?: string;
   judgeEnabled?: boolean;
   judgeModel?: string;
+  userScopeEnabled?: boolean;
   defaultModel?: string;
 }): Promise<SessionFile> {
   return request<SessionFile>('/api/session', {

src/web/styles.css

@@ -620,6 +620,19 @@ body {
   padding: 0 4px;
   border-radius: 2px;
 }
+.user-scope-hint p {
+  margin: 0 0 6px;
+}
+.user-scope-hint p:last-child {
+  margin-bottom: 0;
+}
+.user-scope-hint ul {
+  margin: 0 0 6px;
+  padding-left: 16px;
+}
+.user-scope-hint .dim {
+  color: var(--fg-dim);
+}
 
 .add-column {
   flex: 0 0 auto;

test/runner.smoke.ts

@@ -1308,6 +1308,79 @@ await scenario(
   },
 );
 
+await scenario(
+  'user-scope toggle: session.userScopeEnabled flows through RunManager to the spawn argv',
+  async () => {
+    for (const enabled of [false, true] as const) {
+      const cwd = await mkdtemp(join(tmpdir(), `mdredd-user-scope-${enabled}-`));
+      const storageRoot = join(cwd, 'agents', 'mdredd');
+      const dumpPath = join(cwd, 'argv.txt');
+      const savedScenario = process.env.FAKE_CLAUDE_SCENARIO;
+      const savedDump = process.env.FAKE_CLAUDE_DUMP_ARGS;
+      process.env.FAKE_CLAUDE_SCENARIO = 'happy';
+      process.env.FAKE_CLAUDE_DUMP_ARGS = dumpPath;
+      try {
+        const session = await SessionStore.load(storageRoot, cwd);
+        await session.mutate((s) => {
+          s.userScopeEnabled = enabled;
+          s.judgeEnabled = false; // unrelated to this test; skip the extra spawn
+          const col = s.columns[0]!;
+          col.variantName = `user-scope-${enabled}`; // explicit name skips slug spawn
+          col.variantContent = '# variant\n';
+          col.prompt = 'do a thing';
+        });
+        const runManager = new RunManager({ claudeBin: fakeBin, cwd, storageRoot, session });
+        await runManager.init();
+        const cfg = await runManager.startColumn('col-1');
+        const deadline = Date.now() + 10_000;
+        while (runManager.isColumnActive('col-1')) {
+          if (Date.now() > deadline) throw new Error('run did not finalize within 10s');
+          await new Promise((r) => setTimeout(r, 25));
+        }
+        const finalCfg = JSON.parse(
+          await readFile(join(storageRoot, cfg.runFolder, 'config.json'), 'utf8'),
+        ) as { status: string };
+        if (finalCfg.status !== 'completed') {
+          throw new Error(
+            `userScopeEnabled=${enabled}: expected completed, got ${finalCfg.status}`,
+          );
+        }
+        const argv = (await readFile(dumpPath, 'utf8')).split('\n');
+        const idx = argv.indexOf('--setting-sources');
+        const expectedScope = enabled ? 'user,project' : 'project';
+        if (idx < 0 || argv[idx + 1] !== expectedScope) {
+          throw new Error(
+            `userScopeEnabled=${enabled}: expected --setting-sources ${expectedScope}, got ${argv[idx + 1]}`,
+          );
+        }
+        const hasDisable = argv.includes('--disable-slash-commands');
+        if (enabled && hasDisable) {
+          throw new Error(
+            `userScopeEnabled=true: --disable-slash-commands should be absent, got argv: ${argv.join(' ')}`,
+          );
+        }
+        if (!enabled && !hasDisable) {
+          throw new Error(
+            `userScopeEnabled=false: --disable-slash-commands should be present, got argv: ${argv.join(' ')}`,
+          );
+        }
+        // Isolation flags survive the toggle change.
+        if (!argv.includes('--strict-mcp-config')) {
+          throw new Error(
+            `userScopeEnabled=${enabled}: --strict-mcp-config missing, got argv: ${argv.join(' ')}`,
+          );
+        }
+      } finally {
+        if (savedScenario === undefined) delete process.env.FAKE_CLAUDE_SCENARIO;
+        else process.env.FAKE_CLAUDE_SCENARIO = savedScenario;
+        if (savedDump === undefined) delete process.env.FAKE_CLAUDE_DUMP_ARGS;
+        else process.env.FAKE_CLAUDE_DUMP_ARGS = savedDump;
+        await rm(cwd, { recursive: true, force: true });
+      }
+    }
+  },
+);
+
 await scenario(
   'write mode: appends system prompt directing outputs to ../outputs/<rel>',
   async () => {