Auto-enforce Codex agent branches during setup and doctor

Pre-commit now blocks Codex/OMX session commits on non-agent branches by default, while allowing human branch workflows to continue.\n\nSetup and doctor now auto-refresh managed safety files ( and ) when templates drift, so rerunning musafety applies the latest branch-safety logic without requiring manual force flags. Added regression coverage for the Codex guard plus auto-refresh behavior.

Constraint: Keep existing human VS Code commits on non-protected feature branches working

Rejected: Block all non-agent branch commits for everyone | would break normal human trunk/feature workflows

Confidence: high

Scope-risk: moderate

Reversibility: clean

Directive: Treat Codex branch guard and template auto-refresh as safety-critical defaults; do not weaken without replacement controls

Tested: npm test; node --check bin/multiagent-safety.js; npm pack --dry-run

Not-tested: GitHub Actions run for this new commit

Author: NagyVikt

README.md

@@ -269,10 +269,17 @@ Configuration is stored in local git config key:
 multiagent.protectedBranches
 ```
 
+Codex/OMX agent branch guard is enabled by default in pre-commit and can be configured with:
+
+```text
+multiagent.codexRequireAgentBranch
+```
+
 ## What is protected
 
 - direct commits to protected branches (defaults: `dev`, `main`, `master`; configurable via `musafety protect ...`)
 - protected-branch commits are blocked regardless of commit client (including VS Code Source Control)
+- Codex/OMX session commits are blocked on non-`agent/*` branches by default (keeps human branch untouched while agents use isolated branches)
 - overlapping file ownership between agents
 - unapproved deletions of claimed files
 - risky stale/missing lock state

bin/multiagent-safety.js

@@ -36,6 +36,11 @@ const TEMPLATE_FILES = [
   'claude/commands/musafety.md',
 ];
 
+const AUTO_SYNC_TEMPLATE_FILES = new Set([
+  'scripts/agent-branch-start.sh',
+  'githooks/pre-commit',
+]);
+
 const EXECUTABLE_RELATIVE_PATHS = new Set([
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
@@ -352,7 +357,7 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
       ensureExecutable(destinationPath, destinationRelativePath, dryRun);
       return { status: 'unchanged', file: destinationRelativePath };
     }
-    if (!force) {
+    if (!force && !AUTO_SYNC_TEMPLATE_FILES.has(relativeTemplatePath)) {
       throw new Error(
         `Refusing to overwrite existing file without --force: ${destinationRelativePath}`,
       );
@@ -381,8 +386,16 @@ function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
       return { status: 'unchanged', file: destinationRelativePath };
     }
 
-    // In fix mode, avoid silently replacing local customizations.
-    return { status: 'skipped-conflict', file: destinationRelativePath };
+    if (!AUTO_SYNC_TEMPLATE_FILES.has(relativeTemplatePath)) {
+      // In fix mode, avoid silently replacing local customizations.
+      return { status: 'skipped-conflict', file: destinationRelativePath };
+    }
+
+    if (!dryRun) {
+      fs.writeFileSync(destinationPath, sourceContent, 'utf8');
+      ensureExecutable(destinationPath, destinationRelativePath, dryRun);
+    }
+    return { status: dryRun ? 'would-update' : 'updated', file: destinationRelativePath };
   }
 
   ensureParentDir(destinationPath, dryRun);

templates/githooks/pre-commit

@@ -43,6 +43,41 @@ MSG
   exit 1
 fi
 
+codex_require_agent_branch_raw="${MUSAFETY_CODEX_REQUIRE_AGENT_BRANCH:-$(git config --get multiagent.codexRequireAgentBranch || true)}"
+if [[ -z "$codex_require_agent_branch_raw" ]]; then
+  codex_require_agent_branch_raw="true"
+fi
+codex_require_agent_branch="$(printf '%s' "$codex_require_agent_branch_raw" | tr '[:upper:]' '[:lower:]')"
+
+should_require_codex_agent_branch=0
+case "$codex_require_agent_branch" in
+  1|true|yes|on) should_require_codex_agent_branch=1 ;;
+  0|false|no|off) should_require_codex_agent_branch=0 ;;
+  *) should_require_codex_agent_branch=1 ;;
+esac
+
+if [[ "$should_require_codex_agent_branch" == "1" && "${MUSAFETY_ALLOW_CODEX_ON_NON_AGENT:-0}" != "1" ]]; then
+  is_codex_session=0
+  if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}" == "1" ]]; then
+    is_codex_session=1
+  fi
+
+  if [[ "$is_codex_session" == "1" && "$branch" != agent/* ]]; then
+    cat >&2 <<'MSG'
+[codex-branch-guard] Codex agent commit blocked on non-agent branch.
+Use isolated branch/worktree first:
+  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+Then commit from the created agent/* branch.
+
+Temporary bypass (not recommended):
+  MUSAFETY_ALLOW_CODEX_ON_NON_AGENT=1 git commit ...
+Disable this rule for a repo (not recommended):
+  git config multiagent.codexRequireAgentBranch false
+MSG
+    exit 1
+  fi
+fi
+
 if [[ "$branch" == agent/* ]]; then
   if ! python3 scripts/agent-file-locks.py validate --branch "$branch" --staged; then
     cat >&2 <<'MSG'

test/install.test.js

@@ -84,7 +84,10 @@ function initRepoOnBranch(branchName) {
 function seedCommit(repoDir) {
   let result = runCmd('git', ['add', '.'], repoDir);
   assert.equal(result.status, 0, result.stderr);
-  result = runCmd('git', ['commit', '-m', 'seed'], repoDir);
+  result = runCmd('git', ['commit', '-m', 'seed'], repoDir, {
+    ALLOW_COMMIT_ON_PROTECTED_BRANCH: '1',
+    MUSAFETY_ALLOW_CODEX_ON_NON_AGENT: '1',
+  });
   assert.equal(result.status, 0, result.stderr);
 }
 
@@ -126,7 +129,7 @@ function commitFile(repoDir, relativePath, contents, message) {
   assert.equal(result.status, 0, result.stderr);
   const commitEnv = ['dev', 'main', 'master'].includes(branchName)
     ? { ALLOW_COMMIT_ON_PROTECTED_BRANCH: '1' }
-    : {};
+    : { MUSAFETY_ALLOW_CODEX_ON_NON_AGENT: '1' };
   result = runCmd('git', ['commit', '-m', message], repoDir, commitEnv);
   assert.equal(result.status, 0, result.stderr);
 }
@@ -310,6 +313,36 @@ test('setup --no-gitignore skips creating managed gitignore block', () => {
   assert.equal(fs.existsSync(path.join(repoDir, '.gitignore')), false);
 });
 
+test('setup auto-refreshes managed pre-commit guard when template changed', () => {
+  const repoDir = initRepo();
+
+  let result = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+
+  fs.writeFileSync(path.join(repoDir, '.githooks', 'pre-commit'), '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+
+  result = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+
+  const repaired = fs.readFileSync(path.join(repoDir, '.githooks', 'pre-commit'), 'utf8');
+  assert.match(repaired, /\[codex-branch-guard\] Codex agent commit blocked on non-agent branch/);
+});
+
+test('doctor auto-refreshes managed pre-commit guard when template changed', () => {
+  const repoDir = initRepo();
+
+  let result = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+
+  fs.writeFileSync(path.join(repoDir, '.githooks', 'pre-commit'), '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+
+  result = runNode(['doctor', '--target', repoDir], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+
+  const repaired = fs.readFileSync(path.join(repoDir, '.githooks', 'pre-commit'), 'utf8');
+  assert.match(repaired, /\[codex-branch-guard\] Codex agent commit blocked on non-agent branch/);
+});
+
 test('agent-branch-start keeps main worktree branch unchanged by default', () => {
   const repoDir = initRepo();
   seedCommit(repoDir);
@@ -443,6 +476,50 @@ test('pre-commit blocks protected branch commits even from VS Code Source Contro
   assert.match(hookResult.stderr, /Direct commits on protected branches are blocked/);
 });
 
+test('pre-commit blocks Codex session commits on non-agent branches by default', () => {
+  const repoDir = initRepoOnBranch('feature/codex-guard');
+  seedCommit(repoDir);
+
+  const setupResult = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(setupResult.status, 0, setupResult.stderr || setupResult.stdout);
+
+  const hookResult = runCmd(
+    'bash',
+    ['.githooks/pre-commit'],
+    repoDir,
+    {
+      ALLOW_COMMIT_ON_PROTECTED_BRANCH: '0',
+      CODEX_THREAD_ID: 'codex-thread-test',
+    },
+  );
+
+  assert.equal(hookResult.status, 1, hookResult.stderr || hookResult.stdout);
+  assert.match(hookResult.stderr, /Codex agent commit blocked on non-agent branch/);
+});
+
+test('pre-commit allows non-agent branch commits for Codex when repo guard is disabled', () => {
+  const repoDir = initRepoOnBranch('feature/codex-guard-optout');
+  seedCommit(repoDir);
+
+  const setupResult = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(setupResult.status, 0, setupResult.stderr || setupResult.stdout);
+
+  let result = runCmd('git', ['config', 'multiagent.codexRequireAgentBranch', 'false'], repoDir);
+  assert.equal(result.status, 0, result.stderr);
+
+  const hookResult = runCmd(
+    'bash',
+    ['.githooks/pre-commit'],
+    repoDir,
+    {
+      ALLOW_COMMIT_ON_PROTECTED_BRANCH: '0',
+      CODEX_THREAD_ID: 'codex-thread-test',
+    },
+  );
+
+  assert.equal(hookResult.status, 0, hookResult.stderr || hookResult.stdout);
+});
+
 test('sync command rebases current agent branch onto latest origin/dev', () => {
   const repoDir = initRepo();
   seedCommit(repoDir);
@@ -671,7 +748,10 @@ test('validate blocks unapproved deletions until allow-delete is set', () => {
 
   result = runCmd('git', ['add', '.'], repoDir);
   assert.equal(result.status, 0, result.stderr);
-  result = runCmd('git', ['commit', '-m', 'seed'], repoDir);
+  result = runCmd('git', ['commit', '-m', 'seed'], repoDir, {
+    ALLOW_COMMIT_ON_PROTECTED_BRANCH: '1',
+    MUSAFETY_ALLOW_CODEX_ON_NON_AGENT: '1',
+  });
   assert.equal(result.status, 0, result.stderr);
 
   result = runCmd(