feat: /team --writable worktree mode (v0.8.0)

Add an opt-in writable mode to /team: CLI/native agents make REAL file
changes in isolated git worktrees, merged into one local integration branch.
The read-only default is unchanged and now explicit — it never creates a
branch; the orchestrator applies edits to the current branch directly.

- backends.mjs: invoke() threads opts.cwd (run the CLI in the subtask's
  worktree) and opts.writable (use the backend's writable_extra/full-auto
  instead of the read-only `extra`); runChild + runPty both honor cwd.
  invocationExtra() warns loudly if writable is requested but a backend has
  no writable_extra (never silently runs read-only).
- roster.json + config.mjs: per-backend `writable_extra` (codex
  --dangerously-bypass-approvals-and-sandbox; agy keeps its flags, differing
  only by the worktree cwd), passed through config normalization.
- run.mjs: --cwd / --writable flags (also readable from the call file; the
  explicit flag wins). Inert when absent — default/read-only runs unchanged.
- workflows/team.mjs: WRITABLE mode. Deterministic slug + git-ref/path-safe
  safeLabel (no .., no .lock, no leading/trailing ./-). Setup stage creates
  the integration branch + a per-subtask worktree + a DEDICATED integration
  worktree, all off HEAD and idempotent (resume-safe via show-ref||branch).
  Dispatch passes --cwd --writable. Integrate stage merges each subtask
  branch INSIDE the integration worktree (never the user's checkout),
  --no-ff, aborts + reports conflicts (keeps conflicted worktrees), removes
  only clean/empty ones. User's branch is untouched; no gh PR. Returns
  mode + writable.{integration_branch, integration}.
- commands/team.md + CLAUDE.md: document both modes + the read-only
  no-branch rule; pass writable through the Workflow args.
- Tests: 99/99 offline (was 93) — end-to-end cwd-write isolation + writable
  vs read-only flag selection (real subprocess), --cwd/--writable (incl
  --cwd=VALUE) parsing, writable-mode workflow markers, and a safeLabel
  git-ref edge-case test. Docs/badge -> 99.

Codex-verified: codex reviewed the diff (FAIL), I fixed every real finding
(dedicated integration worktree so the user's tree is never touched; loud
writable-without-config warning; safeLabel ref-safety; idempotent setup;
keep conflicted worktrees; string-form writable), disproved one false
positive (--cwd=VALUE parsing), and a focused re-review returned PASS.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: WatchAndyTW

.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "multi-model-team",
   "displayName": "Multi-Model Team",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "Delegates token-heavy, self-contained tasks to local CLI backends chosen by task size and type, with credit-exhaustion fallback through the backend chain to native Claude and a glanceable statusline HUD. Routing and shipped backend behavior are configured in config/roster.json; adding a new backend kind requires invoker and health support in code. /team runs a decompose → dispatch → verify → fix → synthesize pipeline; an optional config-gated UserPromptSubmit hook can proactively nudge delegation.",
   "author": {
     "name": "WatchAndyTW",

CLAUDE.md

@@ -9,7 +9,7 @@ glanceable statusline HUD.
 (the agy lane runs under a real pseudo-terminal — ConPTY on Windows, forkpty on POSIX); everything
 else is Node stdlib. Cross-platform (Windows/Linux/macOS). `package.json` `"type":"module"`.
 
-**Status:** built, adversarially reviewed, and green. `npm test` passes **93/93** offline
+**Status:** built, adversarially reviewed, and green. `npm test` passes **99/99** offline
 (plus live agy + codex smoke tests under `MMT_LIVE=1`). Two live backends: **agy** (Gemini)
 and **codex** (OpenAI Codex CLI); opencode remains a config-only stub. codex also serves as the
 **`/team` verifier**. See `README.md` (user-facing), `PROBES.md` (grounded CLI findings), and
@@ -178,12 +178,25 @@ agy; `premium` pulls standard-coding up to Sonnet (keeps agy for its categorical
 
 ## /team — multi-model team pipeline (v0.3)
 
-`/team [N:gemini,M:claude] <task>` runs a task through a staged **plan → exec → verify → fix**
+`/team [--writable] [N:gemini,M:claude] <task>` runs a task through a staged **plan → exec → verify → fix**
 pipeline: **native, agy and codex are equal, configurable tools** — the decomposer assigns each
 subtask to its best-fit backend, native Claude plans/synthesizes, and any backend (default codex)
 verifies. Stages: **decompose → dispatch (dependency-aware) → verify → fix (bounded) → synthesize**.
 Flow (in `commands/team.md`):
 
+**Two modes (`--writable`).** *read-only (default):* CLI agents stay read-only (`-s read-only`), return
+text, and the **orchestrator applies edits directly to the CURRENT branch — no branch, no worktree, no
+PR** (back-compat). *writable (`--writable`):* each subtask gets its **own git worktree + branch** off
+HEAD; the agent makes **real changes** there (CLI **full-auto** via `run.mjs --cwd <wt> --writable`,
+selecting the backend's `writable_extra` instead of `extra`); then a deterministic **Setup → Integrate**
+pair of Bash sub-agents (the Workflow runtime has no fs/git) create the worktrees and **merge each into
+one integration branch `mmt/team-<slug>`** off HEAD — **conflicts reported, never auto-resolved**; the
+user's branch is untouched (no auto-merge) and **no `gh` PR** is created. Worktrees live under
+`.mmt/worktrees/<slug>/` (gitignored). Enable per-invocation (`--writable` / Workflow `args.writable`)
+or via roster `team.mode:"writable"`. The full-auto sandbox is config-tunable: each backend's
+`writable_extra` in `roster.json` (codex `--dangerously-bypass-approvals-and-sandbox`; agy keeps its
+`--dangerously-skip-permissions`, differing from read-only only by the worktree cwd).
+
 1. Parse the optional cap spec via `src/lib/team-spec.mjs` → `{gemini, claude}` (caps = max
    agents per backend; `gemini`=agy, `claude`=native; defaults 4/2; aliases + clamp).
 2. Claude decomposes the task, then **writes `.mmt/plans/plan.json`** (array of
@@ -335,7 +348,7 @@ fallback hop.
 ## Testing
 
 ```bash
-npm test                         # offline: 93/93 routing + unit tests (no backend calls)
+npm test                         # offline: 99/99 routing + unit tests (no backend calls)
 MMT_LIVE=1 npm test              # + live agy + codex smoke tests (network required)
 ```
 

README.md

@@ -8,7 +8,7 @@ Multi-model orchestration for Claude Code. Route by task, fan out in parallel, f
 
 ![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)
 ![Type](https://img.shields.io/badge/module-ESM-f7df1e)
-![Tests](https://img.shields.io/badge/tests-93%2F93%20passing-3fb950)
+![Tests](https://img.shields.io/badge/tests-99%2F99%20passing-3fb950)
 ![Platforms](https://img.shields.io/badge/platform-win%20%7C%20linux%20%7C%20macOS-555)
 ![Deps](https://img.shields.io/badge/runtime%20deps-1%20(node--pty)-blue)
 
@@ -276,7 +276,7 @@ docs/REASONING.md            design contract for the /reasoning Fusion pipeline
 ## 🧪 Testing
 
 ```bash
-npm test                # offline: 93/93 routing + unit tests (no backend calls)
+npm test                # offline: 99/99 routing + unit tests (no backend calls)
 MMT_LIVE=1 npm test     # also run live agy + codex smoke tests (network required)
 ```
 

commands/team.md

@@ -1,6 +1,6 @@
 ---
-description: Run a task through the multi-model team pipeline — decompose into backend-assigned subtasks (commodity → parallel agy/Gemini, judgment/hard-line → native Claude), dispatch dependency-aware, verify each result, fix failures in a bounded loop, then synthesize. Optional caps like "5:gemini,2:claude".
-argument-hint: "[N:gemini,M:claude] <task>"
+description: Run a task through the multi-model team pipeline — decompose into backend-assigned subtasks (commodity → parallel agy/Gemini, judgment/hard-line → native Claude), dispatch dependency-aware, verify each result, fix failures in a bounded loop, then synthesize. Optional caps like "5:gemini,2:claude". Add --writable to give each agent its own git worktree and merge into an integration branch.
+argument-hint: "[--writable] [N:gemini,M:claude] <task>"
 allowed-tools: Bash, Write, Task
 ---
 
@@ -52,6 +52,25 @@ MMT_ARGS_EOF
 `"spec"`** (the user actually typed a spec); on `"default"`, omit caps so the roster `team.caps`
 applies. If `.note` is non-empty, surface it.
 
+### Mode: read-only (default) vs `--writable`
+Before decomposing, detect the mode from the raw input. If the input contains the token **`--writable`**
+(strip it from the task text first — it is a mode flag, not part of the task), run in **writable mode**;
+otherwise **read-only mode** (the default).
+
+- **read-only (DEFAULT):** the CLI agents (agy/codex) stay **read-only** — they return text, not edits.
+  Any file changes are applied by **you (the orchestrator) directly to the CURRENT branch**. Do **NOT**
+  create a branch, a worktree, or a PR in this mode. This is the back-compat behaviour.
+- **writable (`--writable`):** each subtask gets its **own git worktree + branch** off the current HEAD;
+  the assigned agent (CLI **full-auto** via `run.mjs --cwd <worktree> --writable`, or a native solver
+  writing in the worktree) makes **real file changes** there; then the orchestrator **merges every
+  subtask branch into one integration branch `mmt/team-<slug>`** off HEAD, **reports conflicts** (never
+  blind-resolves them), and leaves that branch for you. Your current branch is **untouched** (no
+  auto-merge), and **no GitHub PR is created** — you inspect/merge/PR the integration branch yourself.
+
+In the Ultracode path, pass `writable: true` in the Workflow args for writable mode (the workflow runs
+the Setup → Dispatch → Integrate stages). In the Task-agent path, follow the writable steps marked
+**(writable mode)** below; in read-only mode skip them and apply edits to the current branch directly.
+
 ## 1.5 · Load the team roles config (and honor in-session overrides)
 The pipeline's roles are **config-driven**, not hardcoded. Read the merged team config (roster
 `team` over built-in defaults) — this never touches the task text, so it's safe to run plainly:
@@ -231,6 +250,7 @@ Workflow({
           // optional top-level in-session overrides — these WIN over teamConfig (omit if none):
           caps: <{ gemini, codex, claude } ONLY if the cap spec source=="spec">,
           verifier: "<any backend, or 'native'>",
+          writable: <true ONLY if the user passed --writable; omit/false otherwise>,
           verify: true, maxFixLoops: 1 }
 })
 ```
@@ -242,8 +262,12 @@ back if it's unavailable), runs a bounded fix loop on failures, and synthesizes.
 `args.teamConfig` (the roster `team` section): `dispatch_backends` (the equal set), `verifier`
 (`"native"` = Claude judgment), `caps`, `tier_models`, `verify`, `max_fix_loops`. Per-invocation args
 override (`verifier`, `caps`, `verify`, `maxFixLoops`). With no `teamConfig`, the built-in defaults
-apply (all three backends eligible; codex verify). Read its returned `{ plan, backends, caps,
-counts:{byBackend,…}, verifier, results, final }` and present `final`, noting `counts.failed` if
-non-zero. (`args.task` is passed as a JSON value, not shell — injection-safe.)
+apply (all three backends eligible; codex verify). Read its returned `{ plan, mode, backends, caps,
+counts:{byBackend,…}, verifier, writable, results, final }` and present `final`, noting `counts.failed`
+if non-zero. **In writable mode** (`mode:"writable"`), also surface `writable.integration_branch` and
+`writable.integration` — tell the user the changes are on that branch (their current branch is
+untouched), list any `writable.integration.conflicts` that still need manual resolution, and how to
+inspect it (`git switch <integration_branch>` / `git log <integration_branch>`). (`args.task` is passed
+as a JSON value, not shell — injection-safe.)
 
 A trivial single task needs no fan-out: one subtask reduces this to a plain verified dispatch.

config/roster.json

@@ -39,6 +39,8 @@
       "oneshot_flag": "--print",
       "model_flag": "--model",
       "extra": ["--dangerously-skip-permissions", "--print-timeout", "5m"],
+      "_writable_note": "Flags used INSTEAD of `extra` in /team --writable mode (full-auto: agy may write files + run commands in its worktree cwd). agy's --dangerously-skip-permissions already lets it act; the writable lane only differs by running in the worktree cwd. Same flags here = no sandbox swap needed for agy, just cwd.",
+      "writable_extra": ["--dangerously-skip-permissions", "--print-timeout", "5m"],
       "models": { "cheap": "Gemini 3.5 Flash (Low)", "standard": "Gemini 3.1 Pro (Low)" },
       "health": "--version",
       "list_models": "models",
@@ -68,6 +70,8 @@
       "oneshot_flag": "exec",
       "model_flag": "-m",
       "extra": ["-s", "read-only", "--skip-git-repo-check", "--color", "never"],
+      "_writable_note": "Flags used INSTEAD of `extra` in /team --writable mode. Full-auto: `--dangerously-bypass-approvals-and-sandbox` lets codex write files, run commands, and use the network — confined to the worktree cwd the orchestrator passes via --cwd. Drop --skip-git-repo-check since a worktree IS a git repo.",
+      "writable_extra": ["--dangerously-bypass-approvals-and-sandbox", "--color", "never"],
       "models": { "cheap": "gpt-5.4-mini", "standard": "gpt-5.5" },
       "health": "--version",
       "add_dir_flag": "--add-dir",

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "multi-model-team",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "type": "module",
   "private": true,
   "description": "Delegates token-heavy, self-contained tasks to local CLI backends (agy/Gemini, codex) chosen by task size and type, with credit-exhaustion fallback to native Claude and a statusline HUD. Node ESM, zero-build, cross-platform (Windows/Linux/macOS).",

package.json

@@ -29,7 +29,7 @@ const COMPACT_PROMPT = (task) => `${COMPACT_CONTRACT}\n\n${task}`;
 
 // ---- arg parsing -----------------------------------------------------------
 function parseArgs(argv) {
-  const o = { preset: '', tags: '', roster: '', decision: '', callFile: '', taskFile: '', decisionFile: '', sandbox: false, addDir: '', task: '' };
+  const o = { preset: '', tags: '', roster: '', decision: '', callFile: '', taskFile: '', decisionFile: '', sandbox: false, addDir: '', cwd: '', writable: false, task: '' };
   let i = 0;
   const positional = [];
   while (i < argv.length) {
@@ -54,6 +54,11 @@ function parseArgs(argv) {
       case '--task-file':     o.taskFile = next() ?? ''; break;
       case '--decision-file': o.decisionFile = next() ?? ''; break;
       case '--add-dir':      o.addDir = next() ?? ''; break;
+      // /team --writable mode: run the backend CLI IN this dir (the subtask's git worktree) and use
+      // the backend's writable_extra (full-auto) so it can actually write files there. Both are inert
+      // when absent — default/read-only runs are unchanged.
+      case '--cwd':          o.cwd = next() ?? ''; break;
+      case '--writable':     o.writable = true; break;
       case '--sandbox':      o.sandbox = true; break;
       case '--':             positional.push(...argv.slice(i + 1)); i = argv.length; break;
       default:
@@ -227,6 +232,11 @@ async function main() {
   if (!task) task = (await readStdin()).trim();
   if (!task) { process.stderr.write('run.mjs: no task text\n'); process.exit(2); }
 
+  // Writable-mode inputs: a --cwd (the subtask's worktree) + --writable (full-auto). The relay may
+  // carry them in the call file too; the explicit flag wins. Both inert when absent (default lane).
+  const cwd = opts.cwd || (callPayload && typeof callPayload.cwd === 'string' ? callPayload.cwd : '');
+  const writable = opts.writable || !!(callPayload && callPayload.writable);
+
   // --roster flag wins; else shared resolver: .mmt/roster.json (cwd) > ~/.claude/mmt-roster.json > plugin default.
   const rosterPath = opts.roster || resolveRosterPath(MMT_ROOT);
   const tagsPath = opts.tags || path.join(MMT_ROOT, 'config', 'tags.txt');
@@ -350,7 +360,7 @@ async function main() {
     const stopHeartbeat = startHeartbeat({ callId, statusFile, backend: be, model, tier: D_tier, rule: D_rule, startMs });
     let res;
     try {
-      res = await invoke(invokeCfg, fullPrompt, { model, tier: D_tier, addDir: opts.addDir });
+      res = await invoke(invokeCfg, fullPrompt, { model, tier: D_tier, addDir: opts.addDir, cwd, writable });
     } catch (e) {
       res = { ok: false, stdout: '', stderr: String(e && e.message || e), code: 1, quota: false };
     }