@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/hooks/claude-code/core/block-raw-worktree-add.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+// From shared/, never from the sibling hook: importing a hook module fires its
+// standalone tail (stdin read + exit) inside THIS process.
+import { tokenize } from '../../shared/command-tokens.js';
+
+/**
+ * block-raw-worktree-add — PreToolUse (Bash) guard against `git worktree add`.
+ *
+ * A worktree created by raw git is a worktree morph cannot see: no infra
+ * junctions (`.claude`, `node_modules`, `.morph/framework` — so NO hooks run
+ * in there), no port block (its dev server collides with the root's), no
+ * feature/task identity (invisible to `fleet`, `doctor --worktrees`,
+ * `worktree list`), and a location git chose, not `<root>/worktrees/`. The
+ * sibling guard (block-destructive-worktree-removal) protects the way OUT;
+ * this one protects the way IN, by naming the two commands that build a
+ * governed tree:
+ *
+ *   morph-spec worktree setup <feature>                — a feature's tree
+ *   morph-spec worktree provision <name> [--base <ref>] — a task-isolation tree
+ *
+ * DELIBERATELY NARROW: only the `add` subcommand. `list`, `prune`, `remove`
+ * (the sibling's business), `lock`, `unlock`, `move`, `repair` all pass. The
+ * `git` token may be followed by global options (`-C <dir>`, `--git-dir=<d>`,
+ * `-c k=v`) before `worktree`, and may sit anywhere in a chained command
+ * (`cd a && git worktree add b`) — every `git` occurrence is checked.
+ */
+
+/** Global `git` options that take a separate value: `git -C <dir> worktree add`. */
+const GIT_GLOBAL_WITH_VALUE = new Set(['-c', '-C', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env']);
+
+/**
+ * Does this command line invoke `git worktree add` anywhere?
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isRawWorktreeAdd(command) {
+  const tokens = tokenize(command);
+  const lower = tokens.map((t) => t.toLowerCase());
+  for (let i = 0; i < lower.length; i++) {
+    if (lower[i] !== 'git' && !/(^|[\\/])git(\.exe)?$/.test(lower[i])) continue;
+    let j = i + 1;
+    // Skip global options between `git` and the subcommand.
+    while (j < lower.length && lower[j].startsWith('-')) {
+      if (GIT_GLOBAL_WITH_VALUE.has(tokens[j])) j += 2; // `-C dir` consumes its value
+      else j += 1;                                       // `--git-dir=x`, `--no-pager`, …
+    }
+    if (lower[j] === 'worktree' && lower[j + 1] === 'add') return true;
+  }
+  return false;
+}
+
+/**
+ * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
+ * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
+ */
+export async function run(payload) {
+  try {
+    if (!stateExists()) return null;
+
+    const command = payload?.tool_input?.command || '';
+    if (!command || !isRawWorktreeAdd(command)) return null;
+
+    return blockResult(
+      'Bloqueado: `git worktree add` cru cria um worktree que o morph-spec NÃO enxerga — sem as junctions de infra ' +
+      '(`.claude`, `node_modules`, `.morph/framework` → nenhum hook roda lá dentro), sem bloco de portas (o dev server ' +
+      'colide com o da raiz), sem identidade (invisível para `fleet`, `doctor --worktrees` e `worktree list`) e fora de `<raiz>/worktrees/`.\n\n' +
+      'Use o comando que constrói a árvore governada:\n' +
+      '  - feature:  `morph-spec worktree setup <feature>`\n' +
+      '  - tarefa isolada (sem feature):  `morph-spec worktree provision <nome> --base <ref>`\n\n' +
+      'Os dois deixam a árvore em `<raiz>/worktrees/<nome>` com a infra completa; `list`/`prune`/`remove` do git não são afetados por este guard.'
+    );
+  } catch {
+    return null;
+  }
+}
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/chain.js

@@ -37,6 +37,13 @@
  *    mesmo grupo observam o MESMO evento real do Claude Code, então isto só
  *    importa como desempate determinístico); na ausência de qualquer elo
  *    declarando, cai para `payload.hook_event_name`; por último, `'PostToolUse'`.
+ *  - updatedInput (PreToolUse): um elo pode devolver
+ *    `hookSpecificOutput.updatedInput` (ver `updatedInputResult` em
+ *    hook-response.js) para reescrever o tool_input. O ÚLTIMO elo a devolver um
+ *    vence (só um elo do grupo reescreve, por construção). `permissionDecision:
+ *    'allow'` + `updatedInput` só entram no resultado final quando algum elo
+ *    reescreveu — um `allow` incondicional pularia o prompt de permissão de
+ *    TODO Bash, que é exatamente o contrário de um guardrail.
  *  - Fail-open POR ELO: uma exceção não tratada por um hook individual (import
  *    falhou, run() não existe, etc.) não derruba a cadeia — os elos seguintes
  *    ainda rodam. Cada hook já fail-opens sozinho dentro do seu próprio
@@ -78,6 +85,7 @@ async function main() {
 
   const contexts = [];
   let eventName = null;
+  let updatedInput = null;
 
   for (const name of names) {
     let result = null;
@@ -97,6 +105,12 @@ async function main() {
       process.exit(0);
     }
 
+    const rewrite = result?.hookSpecificOutput?.updatedInput;
+    if (rewrite && typeof rewrite === 'object') {
+      updatedInput = rewrite; // last writer wins
+      eventName = eventName || result?.hookSpecificOutput?.hookEventName;
+    }
+
     const ctx = contextOf(result);
     if (ctx) {
       contexts.push(ctx);
@@ -107,16 +121,22 @@ async function main() {
     }
   }
 
-  if (contexts.length === 0) {
+  if (contexts.length === 0 && !updatedInput) {
     process.exit(0);
   }
 
-  console.log(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: eventName || payload?.hook_event_name || 'PostToolUse',
-      additionalContext: contexts.join('\n\n'),
-    },
-  }));
+  const hookSpecificOutput = {
+    hookEventName: eventName || payload?.hook_event_name || 'PostToolUse',
+  };
+  // `permissionDecision:'allow'` ONLY travels with a rewrite — an unconditional
+  // allow would skip the permission prompt for every command the chain sees.
+  if (updatedInput) {
+    hookSpecificOutput.permissionDecision = 'allow';
+    hookSpecificOutput.updatedInput = updatedInput;
+  }
+  if (contexts.length) hookSpecificOutput.additionalContext = contexts.join('\n\n');
+
+  console.log(JSON.stringify({ hookSpecificOutput }));
   process.exit(0);
 }
 

package/framework/hooks/claude-code/core/protect-spec-files.js

@@ -20,10 +20,14 @@
  * This is the sanctioned progress path — the agent never has to rewrite the
  * whole file nor reach for a Node script to record task status.
  *
+ * A gate freezes the APPROVED ARTIFACT, so a protected file that does not yet
+ * exist on disk is a CREATION and passes — the criterion is the file's
+ * existence, never who signed the gate (see the carve-out in run()).
+ *
  * Fail-open: exits 0 on any error.
  */
 
-import { readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { stateExists, isGateApproved } from '../../shared/state-reader.js';
 import {
   isFeaturePath,
@@ -238,6 +242,35 @@ export async function run(payload) {
     }
 
     // ── Gate approved — file is locked ──────────────────────────────────────
+    const absPath = resolveTargetPath(filePath, root);
+
+    // Um gate aprovado congela o ARTEFATO APROVADO. Se o arquivo ainda não
+    // existe no disco, não há artefato aprovado a proteger: isto é a CRIAÇÃO
+    // inicial, não a edição de uma spec fechada. O caso é real e não é raro —
+    // `chore`/`hotfix` nascem com `proposal`+`plan` carimbados `policy:{tipo}`
+    // (create.js → work-types.js skippedGates), então o primeiro `Write` de
+    // `2-plan/spec.md` já chega aqui com o gate "aprovado" sem que humano
+    // nenhum tenha aprovado coisa alguma — e era barrado com uma mensagem
+    // mandando revogar o gate de um arquivo inexistente.
+    //
+    // O critério é a EXISTÊNCIA, nunca o `approvedBy`. Liberar por assinatura
+    // (`policy:` passa, `lucas` não) transformaria este carve-out em licença
+    // para reescrever qualquer spec aprovada: bastaria apagá-la antes. Por ser
+    // sobre o disco, a janela fecha sozinha no instante em que o arquivo
+    // existe — os contra-canários de test/hooks/protect-spec-files.test.js
+    // pinam exatamente isso.
+    //
+    // A decisão é explícita e vale para as DUAS metades do hook. Antes, o ramo
+    // de campos mutáveis (tasks.json) já deixava a primeira criação passar, mas
+    // por acidente — o ENOENT caía no catch fail-open da leitura — enquanto o
+    // ramo travado bloqueava. Duas metades respondendo à mesma pergunta em
+    // direções opostas; agora respondem aqui, uma vez só. O `result` distinto
+    // no log é o que torna essa unificação observável.
+    if (!existsSync(absPath)) {
+      logHookActivity('protect-spec-files', 'PreToolUse', 'ok:absent');
+      return null;
+    }
+
     const mutableFields = MUTABLE_SPEC_FIELDS[filename];
 
     // Files with mutable progress fields (e.g. tasks.json): allow a full Write
@@ -247,8 +280,9 @@ export async function run(payload) {
 
       // Build the proposed document from either a full Write or a targeted Edit,
       // then semantic-diff it against the current file on disk. Any failure to
-      // read / parse / apply → fail-open (pass), never a false block.
-      const absPath = resolveTargetPath(filePath, root);
+      // read / parse / apply → fail-open (pass), never a false block. O arquivo
+      // EXISTE aqui (a inexistência já foi decidida acima), então este catch
+      // volta a significar só o que dizia originalmente: não deu para diffar.
       let oldDoc, newDoc;
       try {
         const original = readFileSync(absPath, 'utf-8');
@@ -312,8 +346,11 @@ export async function run(payload) {
     // de leitura/reconstrução cai no bloqueio (o conservador aqui é BLOQUEAR —
     // ao contrário do ramo do tasks.json, onde não conseguir diffar significa
     // não ter como provar violação; aqui a regra base é "não se edita").
+    //
+    // O arquivo EXISTE neste ponto — a inexistência foi decidida lá em cima, e
+    // é a única coisa que este catch NÃO significa mais. ENOENT tratado como
+    // "ilegível" era o defeito F14; "ilegível de verdade" continua bloqueando.
     const toolName = getToolName(payload);
-    const absPath = resolveTargetPath(filePath, root);
     let errataCheck = null;
     try {
       const original = readFileSync(absPath, 'utf-8');

package/framework/hooks/claude-code/core/worktree-context.js

@@ -89,6 +89,59 @@ function featureFromBranch(dir) {
   }
 }
 
+/**
+ * Task-isolation worktree (`morph-task/{name}`): the tree a `WorktreeCreate`
+ * hook provisions for a parallel sub-agent batch (morph-apply §3b-w) or for a
+ * `claude -w` session with no feature behind it. Not a feature — no
+ * feature.json, no gates — but it owns a port block and the same junctions.
+ */
+function taskFromBranch(dir) {
+  try {
+    const branch = gitRevParse('--abbrev-ref HEAD', dir);
+    const match = branch.match(/^morph-task\/(.+)$/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is this secondary worktree inside the primary root's `worktrees/` (or the
+ * legacy `.worktrees/`) container? A tree kept anywhere else — `.claude/
+ * worktrees/` from a native Claude Code run before the hook existed, a
+ * sibling `../repo-x`, superpowers' `~/.config/...` — was created without
+ * morph: no junctions, no ports, invisible to `fleet`. Fail-open: any error
+ * reads as "in container" so a healthy tree is never nagged by mistake.
+ */
+function isOutsideContainer(dir) {
+  try {
+    const common = resolve(dir, gitRevParse('--git-common-dir', dir)).replace(/\\/g, '/');
+    const root = common.replace(/\/\.git$/, '');
+    const norm = resolve(dir).replace(/\\/g, '/');
+    return !['worktrees', '.worktrees'].some((d) => norm.startsWith(`${root}/${d}/`));
+  } catch {
+    return false;
+  }
+}
+
+function buildOutOfContainerWarning(dir) {
+  return '⚠ Este worktree está FORA do container do morph (worktrees/): foi criado sem o morph-spec — ' +
+    'sem junctions de infra, sem bloco de portas, invisível ao `fleet`. ' +
+    'Integre a branch e remova com `morph-spec worktree remove --target "<path>"`; ' +
+    'crie worktrees por `morph-spec worktree setup <f>` ou `worktree provision <n>` (o hook WorktreeCreate faz isso sozinho). ' +
+    'Diagnóstico: `morph-spec doctor --worktrees`.';
+}
+
+function buildTaskContext(dir, task) {
+  let text = `🧩 Worktree de isolamento de task: ${task} (branch morph-task/${task}). ` +
+    'Não é uma feature: trabalhe só na task despachada, commite na branch como último ato e NUNCA faça merge — ' +
+    'o orquestrador integra e remove este worktree.';
+  const envLine = buildEnvLine(dir);
+  if (envLine) text += `\n${envLine}`;
+  text += buildMissingInfraWarning(dir);
+  return text;
+}
+
 /** Fallback: if exactly one feature directory exists, assume that's the one. */
 function featureFromSingleDir(dir) {
   try {
@@ -114,8 +167,11 @@ function buildEnvLine(dir) {
     const port = content.match(/^PORT=(\d+)$/m)?.[1];
     if (!port) return null;
     const range = content.match(/^MORPH_PORT_RANGE=([\d-]+)$/m)?.[1];
-    return `🔌 Ambiente desta worktree: PORT=${port}${range ? ` (bloco ${range})` : ''}. ` +
-      `Suba dev servers SEMPRE nessas portas (fonte: .morph/worktree.env) — as portas padrão pertencem à raiz.`;
+    const pg = content.match(/^POSTGRES_PORT=(\d+)$/m)?.[1];
+    const project = content.match(/^COMPOSE_PROJECT_NAME=(\S+)$/m)?.[1];
+    const extras = [pg ? `POSTGRES_PORT=${pg}` : null, project ? `COMPOSE_PROJECT_NAME=${project}` : null].filter(Boolean);
+    return `🔌 Ambiente desta worktree: PORT=${port}${range ? ` (bloco ${range})` : ''}${extras.length ? `, ${extras.join(', ')}` : ''}. ` +
+      'Suba dev servers SEMPRE nessas portas (fonte: .morph/worktree.env; o hook PreToolUse injeta em npm run dev/dotnet run/docker compose) — as portas padrão pertencem à raiz.';
   } catch {
     return null;
   }
@@ -148,20 +204,25 @@ function buildWorktreeContext(dir, feature) {
   const handoffLine = buildHandoffLine(dir, feature);
   if (handoffLine) text += `\n${handoffLine}`;
 
-  // `.morph/framework` is checked alongside the other two because the hook
-  // commands resolve to `$CLAUDE_PROJECT_DIR/.morph/framework/hooks/...`: if
-  // that junction is missing, `node` finds no file and EVERY guardrail in this
-  // worktree is silently dark — the worst failure mode of the lot, and the one
-  // the old two-item check could not see.
+  text += buildMissingInfraWarning(dir);
+  return text;
+}
+
+/**
+ * `.morph/framework` is checked alongside the other two because the hook
+ * commands resolve to `$CLAUDE_PROJECT_DIR/.morph/framework/hooks/...`: if
+ * that junction is missing, `node` finds no file and EVERY guardrail in this
+ * worktree is silently dark — the worst failure mode of the lot, and the one
+ * the old two-item check could not see.
+ */
+function buildMissingInfraWarning(dir) {
   const missing = ['node_modules', '.claude', join('.morph', 'framework')]
     .filter((rel) => !existsSync(join(dir, rel)));
-  if (missing.length) {
-    text += `\n⚠ Infra compartilhada ausente (${missing.join(', ').replace(/\\/g, '/')}). Rode: morph-spec worktree link --all`;
-    if (missing.includes(join('.morph', 'framework'))) {
-      text += `\n   Sem .morph/framework os hooks do morph-spec NÃO executam neste worktree (nenhum guardrail ativo).`;
-    }
+  if (!missing.length) return '';
+  let text = `\n⚠ Infra compartilhada ausente (${missing.join(', ').replace(/\\/g, '/')}). Rode: morph-spec worktree link --all`;
+  if (missing.includes(join('.morph', 'framework'))) {
+    text += `\n   Sem .morph/framework os hooks do morph-spec NÃO executam neste worktree (nenhum guardrail ativo).`;
   }
-
   return text;
 }
 
@@ -234,9 +295,17 @@ export async function run(payload) {
     try { rotateEventsLogIfLarge(dir); } catch { /* non-blocking */ }
 
     if (isSecondaryWorktree(dir)) {
+      const task = taskFromBranch(dir);
+      if (task) {
+        return contextResult(buildTaskContext(dir, task), 'SessionStart');
+      }
       const feature = featureFromBranch(dir) || featureFromSingleDir(dir);
       if (!feature) {
-        return null;
+        // A tree with no morph identity at all: worth a warning ONLY when it
+        // also lives outside the container — that is the signature of a
+        // worktree created behind morph's back (native tool, raw git, another
+        // skill). Inside the container with no identity → stay silent.
+        return isOutsideContainer(dir) ? contextResult(buildOutOfContainerWarning(dir), 'SessionStart') : null;
       }
       return contextResult(buildWorktreeContext(dir, feature) + claimBlock(dir, feature, sessionId), 'SessionStart');
     }

package/framework/hooks/claude-code/core/worktree-create.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * worktree-create.js — WorktreeCreate hook
+ *
+ * Event: WorktreeCreate (fires for `claude -w`, the EnterWorktree tool, and
+ * `Agent isolation:"worktree"` — measured, not assumed).
+ *
+ * Claude Code's native worktree is a bare `git worktree add` somewhere under
+ * `.claude/worktrees/`: no infra junctions (so no hooks run in there), no port
+ * block, no identity, invisible to the fleet. When this hook is registered it
+ * REPLACES that logic entirely: it must print the path of the tree it created
+ * as the last non-empty stdout line and exit 0; any non-zero exit fails the
+ * creation. It cannot return JSON — the standalone tail below is therefore
+ * NOT `runStandalone` (which prints a JSON verdict). Diagnostics go to stderr.
+ *
+ * What it does:
+ *   1. root = the PRIMARY root of the repo `payload.cwd` is in (never a
+ *      secondary worktree — a tree under a tree is the fleet-invisible shape).
+ *   2. name → kebab slug (`Bold_Oak` → `bold-oak`, `agent-a1b2` stays).
+ *   3. feature or task? `<root>/.morph/features/<n>/feature.json` exists, or
+ *      branch `morph/<n>` exists → `morph-spec worktree setup <n>`; otherwise
+ *      `morph-spec worktree provision <n> [--base <ref>]`.
+ *   4. `worktree.baseRef` from the merged settings (`~/.claude/settings.json`
+ *      < `<root>/.claude/settings.json` < `<root>/.claude/settings.local.json`):
+ *      `"head"` → the current branch (or sha) of `payload.cwd`; anything else
+ *      → the repo's default branch (the CLI's own default).
+ *   5. CLI exit 0 or 2 (already exists) → its `path`. Exit 1/3 → error.
+ *      CLI unavailable → in-hook git fallback that still lands the tree under
+ *      `<root>/worktrees/<n>` on `morph-task/<n>` (degraded: no junctions, no
+ *      ports — but never outside the governed directory).
+ *
+ * `stateExists(root)` gate: outside a morph project (no `.morph/state.json`
+ * and no feature.json) there is nothing to govern — the same in-hook git
+ * fallback runs, so a non-morph repo with this hook installed still gets a
+ * worktree instead of a failed creation.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
+import { stateExists } from '../../shared/state-reader.js';
+import { resolveGitCommonDir } from '../../shared/git-paths.js';
+import { runMorphSpec } from '../../shared/morph-cli.js';
+
+const WORKTREES_DIR = 'worktrees';
+
+const fwd = (p) => String(p).replace(/\\/g, '/');
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+}
+
+/**
+ * The primary root of the repo containing `startDir`. `git worktree list`'s
+ * first entry is the primary checkout, from any worktree; the pure-filesystem
+ * common-dir resolver is the no-subprocess fallback. Null outside a repo.
+ */
+export function resolvePrimaryRoot(startDir) {
+  try {
+    const first = git(['worktree', 'list', '--porcelain'], startDir).split('\n').find((l) => l.startsWith('worktree '));
+    if (first) return fwd(first.slice('worktree '.length).trim());
+  } catch { /* fall through */ }
+  const common = resolveGitCommonDir(startDir);
+  return common ? fwd(dirname(common)) : null;
+}
+
+/** `Bold_Oak` → `bold-oak`; empty → a timestamped slug. */
+export function slugify(name) {
+  const slug = String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || `wt-${Date.now().toString(36)}`;
+}
+
+function readJsonSafe(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8').replace(/^/, '')); } catch { return null; }
+}
+
+/**
+ * `worktree.baseRef` across the three settings layers, last one wins.
+ * Fail-open per file. Returns `'fresh'` (the documented default) when unset.
+ */
+export function readBaseRefSetting(root, home = homedir()) {
+  let value = 'fresh';
+  for (const p of [
+    join(home, '.claude', 'settings.json'),
+    join(root, '.claude', 'settings.json'),
+    join(root, '.claude', 'settings.local.json'),
+  ]) {
+    const s = readJsonSafe(p);
+    const v = s?.worktree?.baseRef;
+    if (typeof v === 'string' && v) value = v;
+  }
+  return value;
+}
+
+/** The ref `baseRef:"head"` means: the branch checked out in `cwd`, or its sha. */
+function headRef(cwd) {
+  try {
+    const name = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    if (name && name !== 'HEAD') return name;
+    return git(['rev-parse', 'HEAD'], cwd) || null;
+  } catch {
+    return null;
+  }
+}
+
+function isKnownFeature(root, name) {
+  if (existsSync(join(root, '.morph', 'features', name, 'feature.json'))) return true;
+  try {
+    git(['show-ref', '--verify', '--quiet', `refs/heads/morph/${name}`], root);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultBranch(root) {
+  try {
+    const m = git(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], root).match(/^refs\/remotes\/origin\/(.+)$/);
+    if (m) return m[1];
+  } catch { /* no origin/HEAD */ }
+  for (const c of ['main', 'master']) {
+    try { git(['show-ref', '--verify', '--quiet', `refs/heads/${c}`], root); return c; } catch { /* next */ }
+  }
+  return null;
+}
+
+/**
+ * Degraded path — the CLI is not reachable, but the tree still has to land
+ * in the governed directory on the governed branch namespace.
+ */
+function gitFallback(root, name, base) {
+  const branch = `morph-task/${name}`;
+  const path = `${root}/${WORKTREES_DIR}/${name}`;
+  if (existsSync(path)) return { path };
+  try { git(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], root); }
+  catch {
+    const from = base || defaultBranch(root);
+    git(from ? ['branch', branch, from] : ['branch', branch], root);
+  }
+  mkdirSync(join(root, WORKTREES_DIR), { recursive: true });
+  git(['worktree', 'add', path, branch], root);
+  return { path };
+}
+
+/**
+ * @param {object} payload - parsed WorktreeCreate stdin payload
+ *   ({ session_id, cwd, hook_event_name, name })
+ * @returns {Promise<{ path: string }|{ error: string }>}
+ */
+export async function run(payload) {
+  const start = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const root = resolvePrimaryRoot(start) || (process.env.CLAUDE_PROJECT_DIR ? fwd(resolve(process.env.CLAUDE_PROJECT_DIR)) : null);
+  if (!root) return { error: `worktree-create: "${start}" is not inside a git repository` };
+
+  const name = slugify(payload?.name);
+  const baseSetting = readBaseRefSetting(root);
+  const base = baseSetting === 'head' ? headRef(start) : null;
+
+  // Outside a morph project there is nothing to govern beyond WHERE the tree
+  // lands — plain git, under <root>/worktrees/.
+  if (!stateExists(root)) {
+    try { return gitFallback(root, name, base); }
+    catch (err) { return { error: `worktree-create: ${err?.message || err}` }; }
+  }
+
+  const args = isKnownFeature(root, name)
+    ? ['worktree', 'setup', name, '--json']
+    : ['worktree', 'provision', name, '--json', ...(base ? ['--base', base] : [])];
+
+  const r = runMorphSpec(args, { cwd: root });
+  if (r.unavailable) {
+    process.stderr.write('worktree-create: morph-spec CLI not found — creating the tree with plain git under worktrees/ (no infra links, no port block). Run `morph-spec worktree link --all` inside it.\n');
+    try { return gitFallback(root, name, base); }
+    catch (err) { return { error: `worktree-create: ${err?.message || err}` }; }
+  }
+  if (r.stderr?.trim()) process.stderr.write(r.stderr);
+
+  const ok = r.code === 0 || r.code === 2;
+  const path = r.json?.path;
+  if (ok && path && !r.json?.error) return { path: fwd(path) };
+  const why = r.json?.error || r.json?.hint || r.stderr?.trim() || `exit ${r.code}`;
+  return { error: `worktree-create: morph-spec ${args.slice(0, 2).join(' ')} ${name} failed — ${why}` };
+}
+
+// Standalone tail — NOT runStandalone(): this event's contract is "path on
+// stdout, exit 0" / "non-zero exit", never a JSON verdict.
+if (!process.env.MORPH_HOOK_CHAINED) {
+  const { readStdin } = await import('../../shared/stdin-reader.js');
+  let result;
+  try {
+    result = await run(await readStdin());
+  } catch (err) {
+    result = { error: `worktree-create: ${err?.message || err}` };
+  }
+  if (result?.path) {
+    process.stdout.write(`${result.path}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(`${result?.error || 'worktree-create: no path produced'}\n`);
+  process.exit(1);
+}

package/framework/hooks/claude-code/core/worktree-env-inject.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * worktree-env-inject.js — PreToolUse hook (Bash matcher), last link of the
+ * Bash chain.
+ *
+ * `.morph/worktree.env` used to be a manifest nobody executed: SessionStart
+ * printed the port block and the model was expected to pass `PORT` by hand
+ * every time it started a dev server. Two worktrees whose sessions forgot
+ * collided on 3000 — a runtime clash dressed as a broken app. This hook makes
+ * the block reach the process deterministically: when the command is a
+ * dev-server / compose / spec launcher and the cwd is a worktree that owns a
+ * manifest, the command is rewritten to `export K='V' …; <command>` via
+ * `updatedInput`, and the rewrite is named in `additionalContext`.
+ *
+ * Scope is deliberately narrow: only launcher-shaped commands, only when the
+ * command does not already set a layout key itself (`PORT=…`, `--port`,
+ * `compose -p`), only for the Bash tool. Everything else passes untouched.
+ *
+ * Fail-open: no state, no manifest, unreadable manifest → null (pass).
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { stateExists } from '../../shared/state-reader.js';
+import { updatedInputResult, runStandalone } from '../../shared/hook-response.js';
+import { loadEnvFile } from '../../shared/e2e-check.js';
+
+/** Commands that start a server or a stack and therefore need the block. */
+const LAUNCHER_RE = /\b(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start)\b|next\s+(?:dev|start)\b|vite\b|dotnet\s+(?:run|watch)\b|docker(?:\s+|-)compose\b|playwright\s+test\b)/;
+
+/** The command already chose its own port/project — respect it. */
+const SELF_CONFIGURED_RE = /(?:^|[\s;&|])(?:PORT|API_PORT|POSTGRES_PORT|COMPOSE_PROJECT_NAME|ASPNETCORE_URLS)=|--port\b|(?:^|\s)-p\s+\d|compose\b[^|;&]*\s-p\s/;
+
+/** Keys the layout owns; anything else in the manifest is left alone. */
+const LAYOUT_KEYS = ['COMPOSE_PROJECT_NAME', 'MORPH_PORT_BASE', 'MORPH_PORT_RANGE', 'PORT', 'API_PORT', 'POSTGRES_PORT', 'REDIS_PORT', 'ASPNETCORE_URLS', 'PLAYWRIGHT_BASE_URL'];
+
+/** POSIX single-quote, safe for Git Bash on Windows too. */
+function shq(v) {
+  return `'${String(v).replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Pure decision: the rewritten command, or null when nothing should change.
+ * @param {string} command
+ * @param {Record<string,string>} env - parsed manifest
+ * @returns {{ command: string, injected: string[] }|null}
+ */
+export function rewriteCommand(command, env) {
+  if (!command || !LAUNCHER_RE.test(command)) return null;
+  if (SELF_CONFIGURED_RE.test(command)) return null;
+  const pairs = LAYOUT_KEYS.filter((k) => env[k]).map((k) => [k, env[k]]);
+  if (!pairs.some(([k]) => k === 'PORT')) return null;
+  // The web tier's URL is what the spec suite needs; derive it once here.
+  if (!env.PLAYWRIGHT_BASE_URL) pairs.push(['PLAYWRIGHT_BASE_URL', `http://localhost:${env.PORT}`]);
+  const prefix = `export ${pairs.map(([k, v]) => `${k}=${shq(v)}`).join(' ')}; `;
+  return { command: prefix + command, injected: pairs.map(([k, v]) => `${k}=${v}`) };
+}
+
+/**
+ * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
+ * @returns {Promise<object|null>} an updatedInput result, or null (pass).
+ */
+export async function run(payload) {
+  try {
+    if (payload?.tool_name && payload.tool_name !== 'Bash') return null;
+    if (!stateExists()) return null;
+    const command = payload?.tool_input?.command || '';
+    if (!command) return null;
+
+    const dir = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const manifest = join(dir, '.morph', 'worktree.env');
+    if (!existsSync(manifest)) return null;
+
+    const rewritten = rewriteCommand(command, loadEnvFile(manifest));
+    if (!rewritten) return null;
+
+    return updatedInputResult(
+      { ...payload.tool_input, command: rewritten.command },
+      'PreToolUse',
+      `🔌 worktree env injetado (.morph/worktree.env): ${rewritten.injected.join(' ')}`,
+    );
+  } catch {
+    return null;
+  }
+}
+
+await runStandalone(run);