opencode-resolve 0.1.6 → 0.1.8

package/README.ko.md

@@ -10,7 +10,7 @@
 >
 > 독립 실행형 애플리케이션이 아니며, 모델 프로바이더도, 매일 실행하는 별도 CLI도, `opencode.json` 설정을 대체하는 것도 아닙니다. OpenCode 플러그인이며 그 이상도 이하도 아닙니다.
 
-**고정 역할(fixed-role) 검증 해결 루프**를 제공합니다 — **resolver**(컨텍스트 효율적 플래너/판정자)와 **coder**(집중된 구현자)가 자동 승인 권한으로 실행되어 매 단계마다 프롬프트를 띄우지 않고 작업을 완료합니다. Resolver는 관련 파일만 검사하고, 가장 작은 패치를 계획하고, 정확한 지시와 함께 coder를 디스패치하며, 검증된 체크포인트를 통해 반복합니다. 각 체크포인트는 실패 시 최대 3회 재시도되며, 그 후 resolver는 다음 단계로 진행합니다. 내부 전문가 서브에이전트(**explorer**, **reviewer**, **deep-reviewer**)는 OpenCode 네이티브 서브에이전트로 기본 주입됩니다 — resolver가 필요하다고 판단할 때 디스패치되지만, 핵심 경로의 일부가 아니며 사용자 대면 기본 역할이 아닙니다. 역할을 정의할 뿐 모델 프로바이더를 정의하지 않습니다: 에이전트는 사용자가 지정하지 않는 한 OpenCode 기본 모델을 상속합니다.
+**고정 역할(fixed-role) 검증 해결 루프**를 제공합니다 — **resolver**(컨텍스트 효율적 플래너/판정자)와 **coder**(집중된 구현자)가 편집, 검증, 안전한 셸 명령에 대해 저마찰 권한으로 실행됩니다. Resolver는 관련 파일만 검사하고, 가장 작은 패치를 계획하고, 정확한 지시와 함께 coder를 디스패치하며, 검증된 체크포인트를 통해 반복합니다. 반복 실패 시 debugger/architect 회복 가이드를 쓰고, 연속 실패가 누적되면 완료한 척하지 않고 차단 사항을 보고해야 합니다. 내부 전문가 서브에이전트(**explorer**, **reviewer**, **deep-reviewer**)는 OpenCode 네이티브 서브에이전트로 기본 주입됩니다 — resolver가 필요하다고 판단할 때 디스패치되지만, 핵심 경로의 일부가 아니며 사용자 대면 기본 역할이 아닙니다. 역할을 정의할 뿐 모델 프로바이더를 정의하지 않습니다: 에이전트는 사용자가 지정하지 않는 한 OpenCode 기본 모델을 상속합니다.
 
 ```
 # AI 코딩 어시스턴트에 붙여넣기만 하면 전체 설정이 자동으로 완료됩니다
@@ -42,6 +42,7 @@ OpenCode가 설치되어 있지 않거나 실행 중이 아니면 opencode-resol
 - [빠른 시작](#빠른-시작)
 - [드롭인 설정 (LLM에 전달)](#드롭인-설정-llm에-전달)
 - [기본 동작](#기본-동작)
+- [프로젝트 컨텍스트 소스](#프로젝트-컨텍스트-소스)
 - [설정](#설정)
 - [설정 참조](#설정-참조)
 - [자동 승인](#자동-승인)
@@ -63,9 +64,10 @@ OpenCode가 설치되어 있지 않거나 실행 중이 아니면 opencode-resol
 ## 기능
 
 - **고정 역할(fixed-role) 검증 해결 루프** — `resolver`(컨텍스트 효율적 플래너/판정자) + `coder`(집중된 구현자)
-- **기본적으로 컨텍스트 효율적** — 최소 파일 읽기, 가장 작은 패치, 대상 검증, 체크포인트 실행으로 실패한 체크포인트당 최대 3회 재시도
+- **기본적으로 컨텍스트 효율적** — 최소 파일 읽기, 가장 작은 패치, 대상 검증, 체크포인트 실행, 반복 수정 실패 시 명시적 차단 사항 보고
+- **커밋된 팀 컨텍스트 감지** — `HARNESS.md`, `AGENTS.md`, `.opencode/context`, `.claude/context`, `context/`, Agentic 스타일 `thoughts/`를 감지하고 패턴 문서 목록을 노출해 전체 repo를 프롬프트에 밀어 넣지 않고도 필요한 컨텍스트만 로드
 - **OpenCode 네이티브 내부 전문가 서브에이전트** — `reviewer`(검증 갭 감사), `explorer`(코드베이스 스카우트), `deep-reviewer`(위험/보안 리뷰) — 서브에이전트로 기본 주입되지만 핵심 경로가 아님; resolver가 필요할 때만 디스패치
-- **자동 승인 권한** — coder와 resolver는 작업별 프롬프트 없이 동작
+- **저마찰 권한** — 쓰기 에이전트의 edit/webfetch는 허용, bash는 분류기 라우팅으로 안전 명령은 허용하고 위험 명령은 거부하며 알 수 없는 명령은 계속 ask 유지
 - **Context7 MCP** — `context7: true` 시 [Context7](https://context7.com) 문서 조회를 자동 등록
 - **모델 핀닝** — 이점을 측정한 경우 역할별로 다른 모델 지정 가능; 기본적으로 모든 역할이 OpenCode 기본 모델을 상속
 - **소프트 병렬 상한** — `maxParallelSubagents`가 resolver의 coder 동시 실행 수를 제어
@@ -138,7 +140,7 @@ OpenCode는 `~/.config/opencode/opencode.json`에 유효한 API 키와 함께
 }
 ```
 
-> 추가 API 키나 MCP 서버는 필요 없습니다. Context7은 플러그인이 자동으로 등록합니다.
+> 플러그인 자체에는 추가 API 키가 필요 없습니다. Context7은 플러그인이 자동으로 등록합니다. GLM/ZAI 사용자의 경우 postinstall이 로컬 ZAI MCP 서버 부트스트랩을 추가할 수 있지만, API 키를 `opencode.json`에 복사하지 않습니다. 해당 MCP 서버가 키를 요구하면 셸에서 `Z_AI_API_KEY`를 export 하세요.
 
 ---
 
@@ -154,7 +156,7 @@ npm install -g opencode-resolve
 
 1. `opencode-resolve`를 `~/.config/opencode/opencode.json`의 `plugin` 배열에 추가 (이미 없는 경우).
 2. 파일이 존재하지 않는 경우, 현재 모델 프로바이더에 맞게 적응된 `~/.config/opencode/resolve.json`을 생성:
-   - **GLM/ZAI 모델 감지** → GLM + GPT 혼합 별칭 프리셋 (`coder` → GLM, `resolver` → GPT).
+   - **GLM/ZAI 모델 감지** → GLM-only 별칭 프리셋(GPT 의존 없음) 및 비밀값 없는 로컬 ZAI MCP 부트스트랩.
    - **OpenAI/GPT 모델 감지** → 모든 역할에 현재 모델을 사용하는 단일 프로바이더 GPT 프리셋.
    - **다른 프로바이더 또는 모델 없음** → 모델 중립적 `models: {}` (모든 역할이 OpenCode 기본 모델 상속).
 
@@ -190,7 +192,7 @@ opencode plugin opencode-resolve --global --force
 opencode
 ```
 
-`resolver`, `coder` 에이전트가 사용 가능한지 확인합니다.
+사용자 대면 resolve 에이전트인 `resolver`가 사용 가능한지 확인합니다. `coder`는 resolver가 디스패치하는 서브에이전트로 활성화되므로 primary picker에는 보이지 않을 수 있습니다.
 
 ---
 
@@ -307,7 +309,7 @@ provider가 **하나도 설정되지 않은 경우** 진행을 멈추고, `openc
 
 `maxParallelSubagents`는 사용자가 hard cap을 명시적으로 원할 때만 물어보세요. 흔한 케이스: GLM coding-plan 사용자가 "burst 절대 안 됨" 보장 원할 때. 권장 멘트:
 
-> _(optional, 관련된 경우만)_ _`coder` 모델이 GLM이네요 — coding-plan은 burst 시 throttle 걸립니다. 안전하게 `maxParallelSubagents: 2`로 핀닝할까요?_
+> _(optional, 관련된 경우만)_ _`coder` 모델이 GLM이네요 — coding-plan은 burst 시 throttle 걸립니다. 엄격한 직렬 coder 디스패치를 위해 `maxParallelSubagents: 1`로 핀닝할까요?_
 
 그 외엔 필드 자체를 생략.
 
@@ -333,7 +335,7 @@ provider가 **하나도 설정되지 않은 경우** 진행을 멈추고, `openc
     "planner":       "gold"
   },
   "agents": {
-    "coder":         { "enabled": true,  "mode": "all" },
+    "coder":         { "enabled": true,  "mode": "subagent" },
     "resolver":      { "enabled": true },
     "explorer":      { "enabled": true,  "mode": "subagent" },
     "reviewer":      { "enabled": true,  "mode": "subagent" },
@@ -402,16 +404,16 @@ opencode run "list available agents"
 | 에이전트는 보이는데 호출 시 "model not found" | `models`에 핀닝된 ID가 실제로 없음 | `resolve.json`을 다시 열어, 해당 ID를 사용자가 실제 보유한 ID로 교체 후 재시작. |
 | 분할(B)을 골랐는데 한 단계만 작동 | `models` 블록에 `fast` 또는 `strong` 누락 | 3단계의 3d부터 다시 실행. |
 
-내부 전문가 서브에이전트(`explorer`, `reviewer`, `deep-reviewer`)는 서브에이전트 전용이므로 기본 picker에는 나타나지 않습니다 — `resolver`(그리고 `mode: "all"`을 가진 `coder`)만 거기 보입니다.
+내부 전문가 서브에이전트(`coder`, `explorer`, `reviewer`, `deep-reviewer`, `planner`)는 서브에이전트 전용이므로 기본 picker에는 나타나지 않습니다 — `resolver`가 기본 사용자 대면 resolve 에이전트입니다.
 
 ### 이 템플릿을 사용하는 이유
 
 | 설정 | 이유 |
 |---|---|
-| `enabled: ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"]` | 고정 핵심 경로(resolver→coder) + OpenCode 네이티브 내부 전문가 서브에이전트 기본 주입 |
-| `autoApprove: true` | Coder와 resolver가 작업별 프롬프트 없이 동작 |
-| `maxParallelSubagents: 2` | 최대 2개의 coder가 독립 작업에 병렬 실행 가능 |
-| `agents.coder.mode = "all"` | Coder가 에이전트 선택기에 표시됨 (서브에이전트 전용이 아님) |
+| `enabled: ["coder", "resolver", "explorer", "reviewer", "deep-reviewer", "planner"]` | 고정 핵심 경로(resolver→coder) + OpenCode 네이티브 내부 전문가 서브에이전트 기본 주입 |
+| `autoApprove: true` | 하위 호환/가독성 플래그. 실제 저마찰 동작은 기본 권한과 `permission.ask` bash 분류기가 담당 |
+| 기본적으로 `maxParallelSubagents` 미설정 | resolver는 soft fan-out 가이드를 유지; GLM profile은 토큰 효율 프롬프트를 쓰지만 사용자가 설정하지 않는 한 hard concurrency cap을 걸지 않음 |
+| `agents.coder.mode = "subagent"` | Coder는 사용자 대면 기본 역할이 아니라 고정 resolver→coder 경로에 머무름 |
 | `agents.{explorer,reviewer,deep-reviewer}.mode = "subagent"` | 내부 전문가는 서브에이전트 전용 — 사용자 대면 기본 역할이 아님 |
 | `context7: true` | 플러그인이 Context7 MCP를 자동 등록 — 수동 MCP 설정 불필요 |
 | `models` 별칭 | 기본적으로 비어있음 — 모든 역할이 OpenCode 기본 모델을 상속. 이점을 측정한 경우에만 역할별 모델 핀닝 |
@@ -424,7 +426,7 @@ opencode run "list available agents"
 3. **사소한 작업** — Resolver가 직접 작은 편집을 적용합니다. 서브에이전트 불필요.
 4. **구현** — 정확한 파일 경로와 집중된 지시와 함께 `coder`를 디스패치합니다.
 5. **검증** — 가장 저렴한 의미 있는 검증을 먼저 실행합니다 (대상 테스트, 타입 체크, 린트).
-6. **재시도** — 문제가 남아있으면, 검증 로그에서 집중적인 수정과 함께 `coder`를 다시 디스패치합니다. 실패한 체크포인트당 최대 3회 재시도. 검증 통과 시 다음 체크포인트로 진행.
+6. **회복** — 문제가 남아있으면, 근본 원인을 진단하도록 `debugger`를 쓰거나 집중적인 수정과 함께 `coder`를 다시 디스패치합니다. 연속 실패가 누적되면 완료를 주장하지 않고 차단 사항을 보고합니다.
 7. **보고** — 변경 사항, 검증 결과, 남은 차단 사항의 간결한 증거 요약을 반환합니다.
 8. **내부 전문가** — 필요 시: `explorer`(범위가 불명확할 때), `reviewer`(비사소한 변경에 검증 갭), `deep-reviewer`(위험/보안/고영향도만). 서브에이전트로 기본 사용 가능하지만 핵심 경로가 아님.
 
@@ -434,16 +436,52 @@ opencode run "list available agents"
 
 | 항목 | 기본값 |
 |---|---|
-| 활성화된 에이전트 | `coder`, `resolver`, `explorer`, `reviewer`, `deep-reviewer` |
+| 활성화된 에이전트 | `coder`, `resolver`, `explorer`, `reviewer`, `deep-reviewer`, `planner` |
 | 핵심 경로 | `resolver` → `coder` (고정 역할 검증 루프) |
 | 내부 서브에이전트 | `explorer`, `reviewer`, `deep-reviewer` (서브에이전트 전용, 필요 시 디스패치) |
 | 새 작업의 기본 에이전트 | `resolver` (`mode: "all"`) |
 | 에이전트 모델 | 최상위 OpenCode `model` 상속 |
 | 네이티브 `plan` / `build` | 그대로 보존 |
+| 프로젝트 컨텍스트 소스 | `HARNESS.md`, `AGENTS.md`, `CLAUDE.md`, `CONVENTIONS.md`, `.opencode/context`, `.claude/context`, `context/`, `thoughts/` |
 | Context7 MCP 프리셋 | `context7: true` 시 자동 추가 |
 | 선택적 명령어 | 비활성화 |
-| `autoApprove` | `true` (coder/resolver에 작업별 프롬프트 없음) |
-| 체크포인트당 최대 재시도 | 3회 (resolver 프롬프트를 통해) |
+| `autoApprove` | `true` (하위 호환/가독성 플래그; bash 라우팅은 permission hook이 처리) |
+| 반복 실패 동작 | 진단, 다른 수정으로 재시도, 실패가 많으면 architect로 전략 전환, 그래도 막히면 완료 주장 대신 차단 사항 보고 |
+
+---
+
+## 프로젝트 컨텍스트 소스
+
+opencode-resolve는 전체 저장소를 프롬프트에 밀어 넣지 않고도 커밋된 프로젝트 지식을 발견할 수 있습니다. Resolver는 사용 가능한 소스 목록을 보고, 현재 작업과 관련된 문서만 읽어야 합니다.
+
+감지하는 최상위 지식 파일:
+
+| 소스 | 용도 |
+|---|---|
+| `HARNESS.md` | 빌드, 검증, 인프라, 배포, 프로젝트 함정 |
+| `AGENTS.md` | 에이전트 동작, 디스패치 규칙, 리뷰 기대치, 로컬 워크플로우 |
+| `CLAUDE.md` | 다른 AI 코딩 도구에서 쓰던 기존 가이드 |
+| `CONVENTIONS.md` | 코드 스타일, 네이밍, 아키텍처, 저장소 규칙 |
+
+감지하는 컨텍스트 디렉터리:
+
+| 소스 | 동작 |
+|---|---|
+| `.opencode/context/` | OpenCode/OAC 스타일 팀 패턴 문서 |
+| `.claude/context/` | Claude 스타일 공유 컨텍스트 문서 |
+| `context/` | 일반 프로젝트 컨텍스트 문서 |
+| `thoughts/` | Agentic 스타일 영속 지식: architecture, tickets, research, plans, reviews |
+
+컨텍스트 디렉터리에서는 `.md`, `.mdx`, `.txt`, `.json`, `.jsonc`, `.yaml`, `.yml` 파일을 제한된 깊이와 개수 안에서 목록화합니다. `thoughts/archive/`는 의도적으로 제외합니다. 보관 문서는 오래됐거나 오해를 만들 수 있기 때문입니다.
+
+로컬 런타임 상태는 git에서 제외합니다:
+
+```text
+.opencode/resolve-state.json
+.opencode/*.local.json
+```
+
+반대로 `.opencode/context/`와 `thoughts/` 같은 커밋된 컨텍스트는 ignore하지 않습니다.
 
 ---
 
@@ -470,7 +508,7 @@ opencode run "list available agents"
 
 ```json
 {
-  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer", "planner"],
   "autoApprove": true,
   "context7": true,
   "commands": false
@@ -485,7 +523,7 @@ opencode run "list available agents"
     [
       "opencode-resolve",
       {
-        "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
+        "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer", "planner"],
         "autoApprove": true,
         "context7": true,
         "commands": false
@@ -505,12 +543,15 @@ opencode run "list available agents"
 
 | 키 | 타입 | 기본값 | 용도 |
 |---|---|---|---|
-| `enabled` | `string[]` | `["coder", "resolver", "explorer", "reviewer", "deep-reviewer"]` | 주입할 resolve 에이전트. 핵심 경로: resolver→coder. 내부 전문가(explorer, reviewer, deep-reviewer)는 서브에이전트 전용. 에이전트별 `agents.<name>.enabled`가 이것을 재정의. |
+| `profile` | `"mix" \| "gpt" \| "glm"` | `"mix"` | 최상위 동작 프로필. `mix`가 명시적 기본값이며, `gpt`와 `glm`은 프로바이더별 프롬프트, 활성 에이전트 기본값, chat 파라미터를 적용. |
+| `tier` | `"bronze" \| "silver" \| "gold"` | _없음_ | 선택적 활성 에이전트 프리셋. `bronze`는 최소 구성, `silver`는 표준, `gold`는 전체 전문가 세트를 활성화. |
+| `enabled` | `string[]` | `["coder", "resolver", "explorer", "reviewer", "deep-reviewer", "planner"]` | 주입할 resolve 에이전트. 핵심 경로: resolver→coder. 내부 전문가(coder, explorer, reviewer, deep-reviewer, planner)는 서브에이전트 전용. 에이전트별 `agents.<name>.enabled`가 이것을 재정의. |
 | `preserveNative` | `boolean` | `true` | 네이티브 `plan`/`build`는 항상 보존됨. 가독성을 위해 허용됨. |
 | `context7` | `boolean` | `true` | true인 경우, 이미 구성되지 않았으면 Context7 MCP 서버를 등록. |
 | `commands` | `boolean` | `false` | true인 경우, `resolve`, `resolve-code`, `resolve-review` 명령어 추가. |
-| `autoApprove` | `boolean` | `true` | 활성화된 에이전트의 기본 `"ask"` 권한을 `"allow"`로 전환. `"deny"`나 사용자가 설정한 키는 건드리지 않음. |
-| `maxParallelSubagents` | `positive integer` | `2` | resolver가 역할당 동시에 디스패치하는 서브에이전트의 상한. |
+| `autoApprove` | `boolean` | `true` | 하위 호환/가독성 플래그. 현재 동작은 내장 기본 권한과 `permission.ask` bash 분류기가 제어하며, 이 플래그가 권한을 재작성하지 않음. |
+| `autoUpdate` | `boolean` | `true` | npm 버전 확인과 OpenCode 플러그인 캐시 갱신 알림을 best-effort로 수행. 비활성화하려면 false. |
+| `maxParallelSubagents` | `positive integer` | _미설정_ | 동시 coder 수에 대한 선택적 프롬프트 수준 상한. 미설정 시 resolver는 soft fan-out 가이드를 사용하고 rate-limit 에러에 backoff. GLM profile도 사용자가 설정하지 않는 한 hard cap을 걸지 않음. |
 | `models` | `object` | `{}` | 별칭 맵. 키는 에이전트 이름 또는 `fast`/`strong`/`mini`/`codex`/`quick`/`deep`/`glm`/`gpt`. 값은 모델 id 또는 다른 별칭. 기본적으로 비어있음 — 모든 역할이 OpenCode 기본 모델을 상속. |
 | `agents` | `object` | `{}` | 에이전트별 재정의 (아래 참조). |
 | `config` | `string` | _없음_ | 설정 파일의 사용자 정의 경로 (프로젝트 상대경로 또는 절대경로). |
@@ -549,19 +590,20 @@ opencode run "list available agents"
 
 ## 자동 승인
 
-`autoApprove` (기본값 `true`)는 **활성화된** 에이전트의 모든 `"ask"` 권한을 `"allow"`로 전환하여, coder와 resolver가 작업별 프롬프트 없이 계속 작동합니다. `"deny"`는 건드리지 않으며, 사용자가 명시적으로 설정한 권한 키도 재정의하지 않습니다.
+`autoApprove` (기본값 `true`)는 이제 하위 호환/가독성 플래그입니다. 기존 `resolve.json`이 계속 로드되도록 설정에서 허용하지만, 현재 하네스는 이 값으로 권한을 `"ask"`에서 `"allow"`로 재작성하지 않습니다.
 
-| 권한 상태 | autoApprove: true | autoApprove: false |
-|---|---|---|
-| 기본 `"ask"` | `"allow"`가 됨 | `"ask"` 유지 |
-| 기본 `"deny"` | `"deny"` 유지 | `"deny"` 유지 |
-| 사용자 명시 `"ask"` | `"ask"` 유지 | `"ask"` 유지 |
-| 사용자 명시 `"allow"` | `"allow"` 유지 | `"allow"` 유지 |
-| 사용자 명시 `"deny"` | `"deny"` 유지 | `"deny"` 유지 |
+저마찰 자율 동작은 두 가지 명시적 기본값에서 옵니다:
 
-`"deny"` 기본값을 가진 에이전트(예: reviewer의 `edit` 및 `bash`)는 `autoApprove: true`에서도 거부가 유지됩니다. Reviewer는 내부 서브에이전트로 기본 활성화됩니다 — deny 권한은 읽기 전용을 보장합니다.
+| 권한 | 현재 기본 동작 |
+|---|---|
+| 쓰기 에이전트 `edit` / `webfetch` | `allow` |
+| 쓰기 에이전트 `bash` | `ask`, 플러그인의 `permission.ask` 분류기로 라우팅 |
+| 안전한 bash 명령 | 분류기가 자동 허용 |
+| 위험한 bash 명령 | 분류기가 자동 거부 |
+| 알 수 없는 bash 명령 | OpenCode/사용자 처리를 위해 `ask` 유지 |
+| 읽기 전용 에이전트 `edit` / `bash` | `deny`; write-capable 플러그인 도구도 read-only 에이전트를 차단 |
 
-보수적인 매번-묻기 동작을 원할 때 끄세요:
+의도를 나타내기 위해 config에 그대로 둘 수 있습니다:
 
 ```json
 {
@@ -569,18 +611,18 @@ opencode run "list available agents"
 }
 ```
 
-> **신뢰 참고:** `autoApprove: true`는 작업공간과 구성된 모델을 신뢰한다고 가정합니다. 신뢰할 수 없는 코드의 경우 샌드박스나 VM을 사용하고, 모든 작업을 검사하려면 `autoApprove: false`로 유지하세요.
+> **신뢰 참고:** 저마찰 쓰기 에이전트 권한은 작업공간과 구성된 모델을 신뢰한다고 가정합니다. 신뢰할 수 없는 코드의 경우 샌드박스나 VM을 사용하세요. Bash는 무조건 허용이 아니라 분류기 라우팅을 유지합니다.
 
 ---
 
 ## 병렬 서브에이전트 제한
 
-`maxParallelSubagents` (기본값 `2`)는 **resolver**가 **역할당** 동시에 디스패치할 수 있는 서브에이전트 수를 제한합니다. 기본값 `2`는 최대 2개의 coder가 독립 작업에 병렬로 실행됨을 의미합니다.
+`maxParallelSubagents`는 선택 사항입니다. 생략하면 **resolver**는 soft fan-out 가이드를 사용합니다: 진짜 독립적인 작업에는 coder를 분산하고, rate-limit 에러가 보이면 backoff합니다. resolver 프롬프트에 명시적인 역할별 동시 실행 상한을 넣고 싶을 때만 설정하세요. GLM profile도 기본적으로 hard cap은 없습니다.
 
 | 값 | 동작 |
 |---|---|
 | `1` | 한 번에 하나의 coder만. |
-| `2` (기본값) | 최대 2개의 coder 동시 실행. 독립 작업 분산에 유용. |
+| `2` | 최대 2개의 coder 동시 실행. 독립 작업 분산에 유용. |
 | `N > 2` | 최대 N개의 coder 동시 실행. 컨텍스트 낭비를 피하기 위해 신중하게 사용. |
 
 프로젝트별 또는 사용자별 재정의:
@@ -601,7 +643,7 @@ opencode run "list available agents"
 
 `opencode-resolve`의 새 버전으로 업그레이드하면, `postinstall` 스크립트가 기존 `~/.config/opencode/resolve.json`에 **추가적 마이그레이션**을 실행합니다:
 
-- 새 최상위 키(예: `autoApprove`, `maxParallelSubagents`)를 기본값과 함께 추가 (없는 경우).
+- 새 최상위 키(현재 `autoApprove`)를 기본값과 함께 추가 (없는 경우).
 - 이미 설정한 키는 **절대** 수정하지 않음.
 - `enabled` 목록, `models` 맵, 또는 `agents` 재정의를 **절대** 다시 쓰지 않음.
 - `enabled`가 설정되어 있고 `"resolver"`를 포함하지 않으면, 추가를 제안하는 한 줄 팁을 출력. 파일은 그대로 유지.
@@ -612,9 +654,10 @@ opencode run "list available agents"
 
 | 감지된 프로바이더 | 프리셋 |
 |---|---|
-| GLM / ZAI | GLM + GPT 혼합: coder/explorer → GLM, resolver/reviewer/deep-reviewer → GPT |
+| GLM/ZAI + OpenAI/GPT | Mixed: `profile: "mix"`, scout/coder 별칭은 GLM, resolver/reviewer/planner 별칭은 GPT |
+| GLM / ZAI | GLM-only: 모든 resolve 에이전트가 GLM 별칭 사용, GPT 의존 없음 |
 | OpenAI / GPT | 단일 프로바이더: 모든 역할이 현재 OpenAI 모델 사용 |
-| 다른 프로바이더 또는 없음 | 모델 중립적: `models: {}` (모든 역할이 OpenCode 기본 모델 상속) |
+| 다른 프로바이더 또는 없음 | `profile: "mix"`와 모델 중립적 `models: {}` (모든 역할이 OpenCode 기본 모델 상속) |
 
 언제든지 프리셋을 변경하려면 `resolve.json`의 `models`를 직접 편집하거나, 파일을 삭제하고 재설치하세요.
 
@@ -718,17 +761,18 @@ OPENCODE_RESOLVE_SKIP_POSTINSTALL=1 npm install -g opencode-resolve
 
 | 에이전트 | 기본 | 모드 | Edit | Bash | WebFetch | 용도 |
 |---|:---:|---|---|---|---|---|
-| `resolver` | 예 (핵심) | `all` | ask → allow | ask → allow | ask → allow | 컨텍스트 효율적 오케스트레이터. 작업을 검증된 체크포인트로 분해, coder 디스패치, 각각 검증, 진행 상황 전달. 실패한 체크포인트당 최대 3회 재시도. |
-| `coder` | 예 (핵심) | `subagent` | ask → allow | ask → allow | ask → allow | 집중된 구현자. 가장 작은 올바른 패치. 필요한 파일만 읽음. |
-| `explorer` | 예 (서브에이전트) | `subagent` | **deny** | ask → allow | ask → allow | 내부 빠른 코드베이스 스카우트. Resolver가 범위가 불명확할 때만 디스패치; 좁은 범위는 로컬 read/grep/glob 선호. |
-| `reviewer` | 예 (서브에이전트) | `subagent` | **deny** | **deny** | ask → allow | 내부 검증 갭 감사자. 비사소한 변경에 검증 갭이 있을 때 디스패치. |
-| `deep-reviewer` | 예 (서브에이전트) | `subagent` | **deny** | **deny** | ask → allow | 내부 위험/보안/아키텍처 변경에 대한 철저한 리뷰. 고영향도 작업에만 디스패치. |
-| `architect` | 아니오 | `subagent` | deny | ask → allow | ask → allow | 설계 및 작업 분해. |
-| `gpt-coder` | 아니오 | `subagent` | ask → allow | ask → allow | ask → allow | 더 강력한 추론 구현 폴백. |
-| `debugger` | 아니오 | `subagent` | ask → allow | ask → allow | ask → allow | 재현 및 근본 원인 분석. |
-| `researcher` | 아니오 | `subagent` | deny | ask → allow | ask → allow | 코드베이스 및 문서 연구. |
-
-`ask → allow`는 기본이 `"ask"`이며 `autoApprove` (기본 켜짐)가 `"allow"`로 전환함을 의미합니다. `"ask"`로 유지하려면 `autoApprove: false`로 설정하세요.
+| `resolver` | 예 (핵심) | `all` | allow | ask (분류기 라우팅) | allow | 컨텍스트 효율적 오케스트레이터. 작업을 검증된 체크포인트로 분해, coder 디스패치, 각각 검증, 반복 회복 실패 시 차단 사항 보고. |
+| `coder` | 예 (핵심) | `subagent` | allow | ask (분류기 라우팅) | allow | 집중된 구현자. 가장 작은 올바른 패치. 필요한 파일만 읽음. |
+| `explorer` | 예 (서브에이전트) | `subagent` | **deny** | **deny** | allow | 내부 빠른 코드베이스 스카우트. Resolver가 범위가 불명확할 때만 디스패치; 좁은 범위는 로컬 read/grep/glob 선호. |
+| `reviewer` | 예 (서브에이전트) | `subagent` | **deny** | **deny** | allow | 내부 검증 갭 감사자. 비사소한 변경에 검증 갭이 있을 때 디스패치. |
+| `deep-reviewer` | 예 (서브에이전트) | `subagent` | **deny** | **deny** | allow | 내부 위험/보안/아키텍처 변경에 대한 철저한 리뷰. 고영향도 작업에만 디스패치. |
+| `planner` | 예 (서브에이전트) | `subagent` | **deny** | **deny** | allow | 명시적 계획 전문가. 사용자가 계획/분해/전략을 요청할 때만 디스패치. |
+| `architect` | 아니오 | `subagent` | **deny** | **deny** | allow | 설계 및 작업 분해. |
+| `gpt-coder` | 아니오 | `subagent` | allow | ask (분류기 라우팅) | allow | 더 강력한 추론 구현 폴백. |
+| `debugger` | 아니오 | `subagent` | allow | ask (분류기 라우팅) | allow | 재현 및 근본 원인 분석. |
+| `researcher` | 아니오 | `subagent` | **deny** | **deny** | allow | 코드베이스 및 문서 연구. |
+
+쓰기 에이전트의 `bash: ask`는 의도된 값입니다. 플러그인의 `permission.ask` 훅이 알려진 안전 명령은 자동 허용, 위험 명령은 자동 거부, 알 수 없는 명령은 OpenCode/사용자 처리를 위해 남깁니다.
 
 지원되는 모드:
 
@@ -746,14 +790,15 @@ OPENCODE_RESOLVE_SKIP_POSTINSTALL=1 npm install -g opencode-resolve
 
 ### Resolver 오케스트레이션 규칙
 
-Resolver는 컨텍스트 효율적 접근과 체크포인트 실행(실패한 체크포인트당 최대 3회 재시도)을 사용합니다:
+Resolver는 컨텍스트 효율적 접근, 체크포인트 실행, 반복 실패 회복을 사용합니다:
 
 - 계획 전에 작업을 **quick**, **normal**, **deep**, **risky**로 **분류**.
 - **관련 파일만 검사** — 로컬 도구 사용, 광범위한 탐색 지양.
 - 사소한 작업은 직접 편집 적용 — 서브에이전트 불필요.
 - 집중된 파일/동작 지시와 함께 **coder** 디스패치.
 - **가장 저렴한 의미 있는 검증**을 먼저 실행.
-- 문제가 남아있으면 검증 로그에서 재시도. 실패한 체크포인트당 최대 3회 재시도; 그 후 진행하거나 차단 사항 보고.
+- 문제가 남아있으면 검증 로그에서 재시도; 검증 실패 시 근본 원인을 진단한 뒤 다른 수정 지시로 coder를 다시 디스패치.
+- 연속 실패가 누적되면 완료를 주장하지 않고 차단 사항을 보고; 전체 실패가 많아지면 `architect`로 전략을 전환.
 - 범위가 불명확하고 로컬 read/grep/glob이 불충분할 때만 **explorer** 사용 (내부 서브에이전트, 핵심 경로 아님).
 - 비사소한 변경에 검증 갭이 있을 때만 **reviewer** 사용 (내부 서브에이전트, 핵심 경로 아님).
 - 위험, 보안, 아키텍처, 고영향도 변경에만 **deep-reviewer** 사용 (내부 서브에이전트, 핵심 경로 아님).
@@ -785,7 +830,7 @@ Resolver는 컨텍스트 효율적 접근과 체크포인트 실행(실패한
 }
 ```
 
-이를 통해 모든 resolve 에이전트가 `resolve-library-id` 및 `query-docs` 도구를 통해 최신 라이브러리 및 프레임워크 문서에 접근할 수 있습니다 — 수동 MCP 설정이 필요 없습니다.
+이를 통해 resolve 에이전트가 OpenCode의 MCP 통합을 통해 Context7 문서 도구에 접근할 수 있습니다 — 수동 MCP 설정이 필요 없습니다.
 
 Context7 등록을 비활성화하려면 (예: 이미 구성되어 있거나 원하지 않는 경우):
 
@@ -905,7 +950,7 @@ GitHub Actions에서 `Publish to npm` 워크플로우를 수동으로 실행하
 - Resolver는 비사소한 변경에 검증 갭이 있을 때만 `reviewer` 디스패치.
 - Resolver는 위험, 보안, 아키텍처, 고영향도 변경에만 `deep-reviewer` 디스패치.
 - Reviewer와 deep-reviewer는 읽기 전용 — 수정은 항상 `coder` 또는 `resolver`를 거침.
-- 실패한 체크포인트당 최대 3회 재시도로 컨텍스트 낭비 방지. 대규모 작업은 검증된 체크포인트로 분해됨.
+- 반복 검증 실패는 진단, 다른 수정 전략, 차단 사항 보고로 이어져야 함. 대규모 작업은 검증된 체크포인트로 분해됨.
 - Resolver는 컨텍스트 효율을 위해 `maxParallelSubagents`를 준수.
 - 편집 전에 검색하고 검사. 가장 작은 올바른 변경. 실용적인 경우 검증.
 - 필요한 파일만 읽음. 광범위한 탐색 지양. 대상 검증, 전체 스위트 아님.