From d0f26e296173576d3a1103e266c9fd6aff2551c0 Mon Sep 17 00:00:00 2001
From: choiyounggi <74581798+choiyounggi@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:05:45 +0900
Subject: [PATCH] docs(orchestrate): document coordinator permission
 requirements for the tmux substrate

---
 README.ko.md                | 11 +++++++++++
 README.md                   | 12 ++++++++++++
 skills/orchestrate/SKILL.md | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 56 insertions(+)

diff --git a/README.ko.md b/README.ko.md
index b7bfee2..8c0983f 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -143,6 +143,17 @@ Orca가 없어도 같은 런이 **raw tmux** 위에서 같은 보호를 파일 
 플래닝 중에 죽은 워커도 기다리지 않고 잡습니다. guardrails 에스컬레이션 규약은
 두 기판에서 동일합니다.
 
+**auto 모드 코디네이터를 위한 셋업 노트 (tmux):** 런처는 각 워커를
+`claude --permission-mode bypassPermissions`로 띄우는데, auto 모드 권한
+분류기는 이를 권한 상승으로 플래그합니다 — 이를 안전하게 만드는 guardrails
+deny-net을 분류기는 볼 수 없기 때문입니다. 코디네이터 세션이 auto 모드로
+돌아간다면 워커 관리 스크립트 3개(`launch-session.sh`, `send-prompt.sh`,
+`watch-status.sh`)를 프로젝트의 `.claude/settings.local.json`에 사전
+승인하세요 — 정확한 `permissions.allow` + `autoMode.allow` 스니펫은
+orchestrate SKILL.md의 Preflight 섹션에 있습니다. `safe-cleanup.sh`는 파괴적
+verb가 일반 검토를 계속 받도록 의도적으로 제외했고, 차단당한 코디네이터는
+분류기를 우회하는 대신 스니펫을 보여주고 멈춥니다.
+
 ---
 
 ## 지식 수집 루프
diff --git a/README.md b/README.md
index 4675859..12fb657 100644
--- a/README.md
+++ b/README.md
@@ -144,6 +144,18 @@ on-screen chooser is answered with allowlisted key events
 worker that dies during planning is caught instead of waited out. The
 guardrails escalation contract is identical on both substrates.
 
+**One setup note for auto-mode coordinators (tmux):** the launcher starts each
+worker as `claude --permission-mode bypassPermissions`, which an auto-mode
+permission classifier flags as privilege escalation — it cannot see the
+guardrails deny-net that makes it safe. If your coordinator session runs in
+auto mode, pre-approve the three worker-management scripts
+(`launch-session.sh`, `send-prompt.sh`, `watch-status.sh`) in the project's
+`.claude/settings.local.json` — the exact `permissions.allow` +
+`autoMode.allow` snippet is in the orchestrate SKILL.md's Preflight section.
+`safe-cleanup.sh` is deliberately excluded so destructive verbs keep their
+normal review, and a blocked coordinator will show you the snippet and stop
+rather than work around the classifier.
+
 ---
 
 ## The knowledge-capture loop
diff --git a/skills/orchestrate/SKILL.md b/skills/orchestrate/SKILL.md
index d6f9c07..acdb211 100644
--- a/skills/orchestrate/SKILL.md
+++ b/skills/orchestrate/SKILL.md
@@ -39,6 +39,39 @@ advisory only; this skill must hard-require them). For a missing tmux: with the
 user's consent, install it (macOS: `brew install tmux`; otherwise advise) before
 launching sessions. Never auto-install without consent.
 
+**Coordinator permissions (tmux substrate).** `launch-session.sh` starts each
+worker as `claude --permission-mode bypassPermissions` — the exact surface an
+auto-mode permission classifier hard-flags as privilege escalation. It cannot
+see the context that makes this safe (each worker worktree carries a guardrails
+deny-net that still blocks dangerous commands in bypass mode and escalates
+`ask` rules to you), so under an auto-mode coordinator the launch may be
+DENIED. If that happens: do **not** work around the block — an agent widening
+its own permissions is itself classifier-blocked, by design, so only the user
+can clear it. Show them this snippet for the project's
+`.claude/settings.local.json`, then stop until it is added (substitute the real
+plugin cache path; `safe-cleanup.sh` is deliberately absent so destructive
+verbs keep their normal review):
+
+```json
+{
+  "permissions": { "allow": [
+    "Bash(sh /Users/<you>/.claude/plugins/cache/*/dev-loop/*/skills/orchestrate/scripts/launch-session.sh *)",
+    "Bash(sh /Users/<you>/.claude/plugins/cache/*/dev-loop/*/skills/orchestrate/scripts/send-prompt.sh *)",
+    "Bash(sh /Users/<you>/.claude/plugins/cache/*/dev-loop/*/skills/orchestrate/scripts/watch-status.sh *)"
+  ]},
+  "autoMode": { "allow": [
+    "$defaults",
+    "Running the dev-loop orchestrate plugin's worker-management scripts (launch-session.sh, send-prompt.sh, watch-status.sh) is allowed, including launch-session.sh starting a tmux worker with `claude --permission-mode bypassPermissions`: the user sanctioned this orchestration workflow, and each worker worktree is sandboxed by groundwork guardrails, which still blocks dangerous commands in bypass mode and escalates `ask` rules to the coordinator. This does NOT extend to safe-cleanup.sh or other destructive commands, which keep their normal review."
+  ]}
+}
+```
+
+The path rules cover full-path invocations; the `autoMode.allow` rule teaches
+the classifier the context so variable-form invocations (`sh $SKILL/scripts/…`)
+pass too. The Orca substrate does not spawn through `launch-session.sh`, but
+its worker terminals embed the same flag — if a classifier flags those, the
+same `autoMode.allow` rule is the fix.
+
 ## Phase 0 — Intake + Clarify
 Two ways the work-list arrives:
 - **`intake` role configured** (e.g. an issue tracker) → if the user names a parent