Prevent accidental in-place agent starts on protected branches

The branch start helper now requires explicit --allow-in-place alongside --in-place, keeping the default path isolated in agent worktrees.\n\nAlso added regression tests for default worktree behavior and the in-place guard/override flow, and documented the explicit override in README.

Constraint: Preserve existing default branch/worktree flow for current users

Rejected: Remove --in-place entirely | some advanced local workflows still need an explicit escape hatch

Confidence: high

Scope-risk: narrow

Reversibility: clean

Directive: Keep main/dev workflows worktree-first; do not relax in-place guard without adding equivalent safety

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

Not-tested: End-to-end GitHub Actions run for this commit

Author: NagyVikt

README.md

@@ -94,6 +94,9 @@ By default this writes:
 
 ![musafety branch start protocol screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-branch-start.svg)
 
+`agent-branch-start` defaults to isolated worktrees. In-place starts are blocked unless you pass both
+`--in-place --allow-in-place` explicitly.
+
 ### 2) Lock claim + deletion guard protocol
 
 ![musafety lock and delete guard screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-lock-guard.svg)

templates/scripts/agent-branch-start.sh

@@ -1,11 +1,13 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-TASK_NAME="${1:-task}"
-AGENT_NAME="${2:-agent}"
-BASE_BRANCH="${3:-dev}"
+TASK_NAME="task"
+AGENT_NAME="agent"
+BASE_BRANCH="dev"
 WORKTREE_MODE=1
+ALLOW_IN_PLACE=0
 WORKTREE_ROOT_REL=".omx/agent-worktrees"
+POSITIONAL_ARGS=()
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -25,25 +27,52 @@ while [[ $# -gt 0 ]]; do
       WORKTREE_MODE=0
       shift
       ;;
+    --allow-in-place)
+      ALLOW_IN_PLACE=1
+      shift
+      ;;
     --worktree-root)
       WORKTREE_ROOT_REL="${2:-.omx/agent-worktrees}"
       shift 2
       ;;
     --)
       shift
+      while [[ $# -gt 0 ]]; do
+        POSITIONAL_ARGS+=("$1")
+        shift
+      done
       break
       ;;
     -*)
       echo "[agent-branch-start] Unknown option: $1" >&2
-      echo "Usage: $0 [task] [agent] [base] [--in-place] [--worktree-root <path>]" >&2
+      echo "Usage: $0 [task] [agent] [base] [--in-place --allow-in-place] [--worktree-root <path>]" >&2
       exit 1
       ;;
     *)
-      break
+      POSITIONAL_ARGS+=("$1")
+      shift
       ;;
   esac
 done
 
+if [[ "${#POSITIONAL_ARGS[@]}" -gt 3 ]]; then
+  echo "[agent-branch-start] Too many positional arguments." >&2
+  echo "Usage: $0 [task] [agent] [base] [--in-place --allow-in-place] [--worktree-root <path>]" >&2
+  exit 1
+fi
+
+if [[ "${#POSITIONAL_ARGS[@]}" -ge 1 ]]; then
+  TASK_NAME="${POSITIONAL_ARGS[0]}"
+fi
+
+if [[ "${#POSITIONAL_ARGS[@]}" -ge 2 ]]; then
+  AGENT_NAME="${POSITIONAL_ARGS[1]}"
+fi
+
+if [[ "${#POSITIONAL_ARGS[@]}" -ge 3 ]]; then
+  BASE_BRANCH="${POSITIONAL_ARGS[2]}"
+fi
+
 sanitize_slug() {
   local raw="$1"
   local slug
@@ -83,6 +112,12 @@ if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
 fi
 
 if [[ "$WORKTREE_MODE" -eq 0 ]]; then
+  if [[ "$ALLOW_IN_PLACE" -ne 1 ]]; then
+    echo "[agent-branch-start] --in-place is blocked by default to prevent accidental edits on protected branches." >&2
+    echo "[agent-branch-start] If you really need it, pass both: --in-place --allow-in-place" >&2
+    exit 1
+  fi
+
   if ! git diff --quiet || ! git diff --cached --quiet; then
     echo "[agent-branch-start] Working tree is not clean. Commit/stash changes before starting an in-place branch." >&2
     exit 1

test/install.test.js

@@ -310,6 +310,71 @@ test('setup --no-gitignore skips creating managed gitignore block', () => {
   assert.equal(fs.existsSync(path.join(repoDir, '.gitignore')), false);
 });
 
+test('agent-branch-start keeps main worktree branch unchanged by default', () => {
+  const repoDir = initRepo();
+  seedCommit(repoDir);
+
+  let result = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+
+  result = runCmd('git', ['rev-parse', '--abbrev-ref', 'HEAD'], repoDir);
+  assert.equal(result.status, 0, result.stderr);
+  const beforeBranch = result.stdout.trim();
+  assert.equal(beforeBranch, 'dev');
+
+  result = runCmd(
+    'bash',
+    ['scripts/agent-branch-start.sh', 'verify-default-worktree', 'doctor'],
+    repoDir,
+  );
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.match(result.stdout, /Created branch: agent\/doctor\//);
+  assert.match(result.stdout, /Worktree: /);
+
+  const branchMatch = result.stdout.match(/Created branch: ([^\n]+)/);
+  assert.notEqual(branchMatch, null);
+  const createdBranch = branchMatch[1].trim();
+
+  result = runCmd('git', ['rev-parse', '--abbrev-ref', 'HEAD'], repoDir);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout.trim(), beforeBranch, 'current branch should stay unchanged in main worktree');
+
+  result = runCmd('git', ['show-ref', '--verify', '--quiet', `refs/heads/${createdBranch}`], repoDir);
+  assert.equal(result.status, 0, 'created agent branch should exist');
+});
+
+test('agent-branch-start blocks in-place mode unless explicitly allowed', () => {
+  const repoDir = initRepo();
+  seedCommit(repoDir);
+
+  let result = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+
+  result = runCmd('git', ['add', '.'], repoDir);
+  assert.equal(result.status, 0, result.stderr);
+  result = runCmd('git', ['commit', '-m', 'post-setup'], repoDir, {
+    ALLOW_COMMIT_ON_PROTECTED_BRANCH: '1',
+  });
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+
+  result = runCmd(
+    'bash',
+    ['scripts/agent-branch-start.sh', 'verify-in-place-guard', 'doctor', '--in-place'],
+    repoDir,
+  );
+  assert.equal(result.status, 1, 'in-place should be blocked by default');
+  assert.match(result.stderr, /--in-place is blocked by default/);
+  assert.match(result.stderr, /--in-place --allow-in-place/);
+
+  result = runCmd(
+    'bash',
+    ['scripts/agent-branch-start.sh', 'verify-in-place-override', 'doctor', '--in-place', '--allow-in-place'],
+    repoDir,
+  );
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.match(result.stdout, /Created in-place branch: agent\/doctor\//);
+});
+
 test('protect command manages configured protected branches', () => {
   const repoDir = initRepo();
   seedCommit(repoDir);