Skip to content

docs(orchestrate): document coordinator permission requirements for the tmux substrate #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
choiyounggi merged 1 commit into from
Aug 9, 2026
Merged

docs(orchestrate): document coordinator permission requirements for the tmux substrate #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions README.ko.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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가 일반 검토를 계속 받도록 의도적으로 제외했고, 차단당한 코디네이터는
분류기를 우회하는 대신 스니펫을 보여주고 멈춥니다.

---

## 지식 수집 루프
Expand Down
12 changes: 12 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
33 changes: 33 additions & 0 deletions skills/orchestrate/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading