pi-codex-auto-review 0.1.3 → 0.2.0

package/docs/usage.md

@@ -1,30 +1,32 @@
-# 사용법
+# Usage
 
-pi-codex-auto-review를 Pi 확장으로 등록하는 방법과 CLI·SDK·정책 파일 설정을 다룹니다.
+**English** | [한국어](usage.ko.md)
 
-## npm에서 설치
+This guide covers registering pi-codex-auto-review as a Pi extension and configuring the CLI, SDK, and policy files.
 
-npm에 게시된 버전은 Node.js 22.19 이상과 Pi 0.99.1 또는 1.0.0에서 설치합니다. 배포 대상은 macOS ARM64와 Linux x64이며, 패키지에 두 플랫폼의 규칙 엔진을 포함하므로 설치할 때 Rust가 필요하지 않습니다.
+## Installing from npm
 
-현재 소스의 샌드박스 제거와 `/approve`·`/approve-model` 메뉴 변경은 아직 새 npm 버전으로 게시되지 않았습니다. 아래 `0.1.2` 설치는 이전 실행 구조를 설치합니다. 변경된 동작은 소스 빌드 후 로컬 등록으로 확인합니다.
+Install the npm package with Node.js 22.19 or later and Pi 0.99.1 or 1.0.0. Version `0.2.0` distributes the rule engine as JavaScript, replacing the native executables included through `0.1.4`. The extension requires no Rust compiler or platform-specific rule binary; Pi's own native modules are separate.
+
+`0.1.4` includes English approval descriptions, `/scoped-models` integration, `/approve retry`, reapproval through ordinary user messages, and fixes for passing and restoring review context. The earlier `0.1.3` removed the sandbox and added the `/approve` and `/approve-model` settings commands.
 
 ```sh
-pi install npm:pi-codex-auto-review@0.1.2
+pi install npm:pi-codex-auto-review@0.2.0
 pi list
 pi remove npm:pi-codex-auto-review
 ```
 
-`--local`을 추가하면 현재 프로젝트의 `.pi/settings.json`에 등록합니다. 프로젝트 패키지는 해당 프로젝트의 신뢰 결정 후 로드됩니다. 버전을 명시한 설치는 그 버전으로 고정됩니다.
+Add `--local` to register the package in the current project's `.pi/settings.json`. Project packages load after a trust decision for that project. Specifying a version pins the installation to that version.
 
-Pi는 관리하는 확장에 호스트 SDK의 물리적 복사본을 설치하지 않습니다. 확장은 Pi의 공개 경로 API로 호스트 SDK를 찾으므로 별도의 SDK 복사본이나 심볼릭 링크를 추가할 필요가 없습니다.
+Pi does not install a physical copy of the host SDK for managed extensions. The extension locates the host SDK through Pi's public path API, so no additional SDK copy or symbolic link is needed.
 
-기존 버전의 `Directory metadata scope is too large to qualify safely`와 시작 지연은 샌드박스의 디렉터리 검사 경로에서 발생했습니다. 현재 소스에서는 이 실행 경로와 `@anthropic-ai/sandbox-runtime` 의존성을 제거했습니다.
+The earlier `Directory metadata scope is too large to qualify safely` error and startup delays came from sandbox directory inspection. The current source removes that execution path and the `@anthropic-ai/sandbox-runtime` dependency.
 
-기본 설치 위치인 `.pi/agent/npm` 안에서도 실행에 필요한 확장 코드와 의존성을 읽을 수 있습니다. 에이전트 설정과 자격 증명 경로의 보호는 유지합니다.
+The extension can read the code and dependencies needed to run even inside the default installation directory, `.pi/agent/npm`. Agent settings and credential paths remain protected.
 
-## 소스에서 빌드
+## Building from source
 
-소스 빌드에는 Rust 1.95 이상도 필요합니다. 저장소 루트에서 개발 의존성을 설치하고 빌드합니다. 이 명령은 현재 운영체제·아키텍처용 실행 파일을 `dist/native/<플랫폼>-<아키텍처>/`에 만듭니다. npm 게시용 패키지 준비는 [배포 안내](publishing.md)를 따릅니다.
+Source builds use TypeScript and require no Rust compiler or platform binary. Install development dependencies and build from the repository root. The official Pi SDK is installed from the committed npm lockfile; no `vendor` archive is needed. Follow the [publishing guide](publishing.md) to prepare an npm release package.
 
 ```sh
 npm ci --ignore-scripts
@@ -32,9 +34,9 @@ npm run build
 node dist/cli.js --help
 ```
 
-## Pi 플러그인으로 등록
+## Registering as a Pi plugin
 
-빌드한 저장소를 로컬 패키지로 등록합니다. 로컬 경로는 복사 없이 해당 위치에서 직접 로드됩니다.
+Register the built repository as a local package. Local paths load directly from their location without copying.
 
 ```sh
 pi install ./pi-codex-auto-review
@@ -42,9 +44,9 @@ pi list
 pi remove ./pi-codex-auto-review
 ```
 
-- 등록하면 로컬 도구와 공식 MCP가 승인 경로에 연결되고, Pi의 기본 MCP 확장은 중복 연결되지 않도록 교체됩니다.
-- 확장 등록만으로는 보호 시작을 보장하지 않습니다. Pi 자체가 확장 로딩 실패를 무시할 수 있으므로, 보호 시작이 필요하면 아래 CLI 진입점이나 SDK의 `createGuardedRuntime()`을 사용합니다.
-- 프로젝트 지침·설정·MCP 서버는 Pi에 저장된 프로젝트 신뢰 결정과 전역 `defaultProjectTrust`를 따릅니다. 결정이 없으면 프로젝트 자원을 시작하지 않습니다. 이번 실행에서 명시적으로 신뢰하려면 CLI의 `--trust-project` 또는 SDK의 `isProjectTrusted: true`를 사용합니다.
+- Registration connects local tools and official MCP tools to the approval path. Pi's default MCP extension is replaced to avoid duplicate connections.
+- Extension registration alone does not guarantee protected startup. Pi can ignore extension loading failures. When approval protection must be ready at startup, use the CLI entry point below or the SDK's `createGuardedRuntime()`.
+- Project instructions, settings, and MCP servers follow Pi's saved project trust decision and global `defaultProjectTrust`. Without a decision, project resources do not start. To explicitly trust the project for this run, use CLI `--trust-project` or SDK `isProjectTrusted: true`.
 
 ## CLI
 
@@ -55,7 +57,7 @@ node dist/cli.js --mode rpc
 node dist/cli.js --mode tui
 ```
 
-등록된 외부 공급자는 `--extension`으로 명시하고 `--provider`와 `--model`을 함께 선택합니다. `OLLAMA_API_KEY`를 export한 셸에서 실행합니다.
+Specify a registered external provider with `--extension`, and select both `--provider` and `--model`. Run from a shell with `OLLAMA_API_KEY` exported.
 
 ```sh
 node dist/cli.js \
@@ -64,19 +66,19 @@ node dist/cli.js \
   --mode print "현재 프로젝트를 분석해줘"
 ```
 
-| 옵션 | 설명 |
+| Option | Description |
 | --- | --- |
-| `--mode tui\|print\|json\|rpc` | 실행 모드. 기본은 TUI. 자동 검토는 print·JSON에서도 동작합니다 |
-| `--cwd 경로` | 시작 작업 디렉터리 |
-| `--agent-dir 경로` | Pi 자원 디렉터리. 생략하면 `PI_CODING_AGENT_DIR`, 그다음 기본 Pi 자원 디렉터리를 사용합니다 |
-| `--policy 파일` | 사용자가 관리하는 정책 JSON의 절대 경로. 잘못된 설정은 실행을 막습니다 |
-| `--trust-project` | 이번 실행에서 선택한 프로젝트를 명시적으로 신뢰합니다 |
-| `--extension 경로`, `-e` | 반복할 수 있습니다. 경로는 명령을 실행한 디렉터리 기준이며, 해당 코드 디렉터리를 신뢰하고 모델 쓰기에서 보호합니다 |
-| `--provider 공급자 --model 모델` | 함께 지정해야 합니다. 등록된 모델이 없으면 시작을 거부합니다. 키는 명령 인자에 넣지 않습니다 |
+| `--mode tui\|print\|json\|rpc` | Execution mode; defaults to TUI. Automatic review also works in print and JSON modes |
+| `--cwd path` | Initial working directory |
+| `--agent-dir path` | Pi resource directory. If omitted, uses `PI_CODING_AGENT_DIR`, then Pi's default resource directory |
+| `--policy file` | Absolute path to a user-managed policy JSON file. Invalid settings block startup |
+| `--trust-project` | Explicitly trusts the selected project for this run |
+| `--extension path`, `-e` | Repeatable. Paths are relative to the directory where the command runs. The code directory is trusted and protected from model writes |
+| `--provider provider --model model` | Must be specified together. Startup is rejected if no registered model matches. Do not put keys in command arguments |
 
 ## SDK
 
-승인 제어가 준비되지 않으면 시작을 거부해야 하는 실행은 `pi-codex-auto-review/startup`의 `createGuardedRuntime()`을 사용합니다. 확장과 승인 제어기 상태를 검사하고, 모드 재연결과 직접 사용자 셸 호출에도 같은 검사를 적용합니다.
+Use `createGuardedRuntime()` from `pi-codex-auto-review/startup` when execution must refuse to start without approval controls. It checks extension and approval controller readiness and applies the same checks to mode reconnection and direct user shell calls.
 
 ```ts
 import { createGuardedRuntime } from 'pi-codex-auto-review/startup';
@@ -92,23 +94,27 @@ try {
 }
 ```
 
-| 옵션 | 설명 |
+| Option | Description |
 | --- | --- |
-| `cwd`, `agentDir` | 시작 디렉터리와 Pi 자원 디렉터리 |
-| `settings` 또는 `settingsPath` | 정책 파일과 같은 형식의 실행 정책 |
-| `isProjectTrusted` | 명시적 프로젝트 신뢰. 지시가 없으면 Pi의 신뢰 결정과 전역 `defaultProjectTrust`를 따릅니다. 이후 디렉터리 변경은 각 디렉터리의 신뢰 기록을 따릅니다 |
-| `model` 또는 `modelSelection` | 모델 객체 또는 `{provider, id}` 선택. 둘을 함께 쓸 수는 없습니다 |
-| `trustedExtensionPaths` | 신뢰하는 확장 진입 파일. Pi의 공개 로더로 읽고, 상대 import까지 보호하도록 파일이 있는 디렉터리 전체를 모델 쓰기에서 보호합니다 |
-| `profile` | `readOnlyPaths` 등 SDK 프로필을 직접 전달합니다. 필수 제어·인증 경로 보호는 함께 적용됩니다 |
-| `mcp: false`, `mcpToolPolicies` | MCP 연결 끄기와 `서버/도구` 키별 `approvalMode` |
+| `cwd`, `agentDir` | Initial directory and Pi resource directory |
+| `settings` or `settingsPath` | Execution policy in the same format as the policy file |
+| `isProjectTrusted` | Explicit project trust. If unspecified, follows Pi's trust decision and global `defaultProjectTrust`. Later directory changes follow each directory's saved trust decision |
+| `model` or `modelSelection` | A model object or `{provider, id}` selection. These cannot be used together |
+| `trustedExtensionPaths` | Trusted extension entry files, loaded through Pi's public loader. The entire containing directory is protected from model writes, including relative imports |
+| `profile` | Directly supplies an SDK profile, including `readOnlyPaths`. Required control and authentication path protection also applies |
+| `mcp: false`, `mcpToolPolicies` | Disables MCP connections, or configures `approvalMode` by `server/tool` key |
+
+The protected entry point disables automatic extension discovery. Tools outside the known set are blocked unless they have a trusted adapter.
+
+## Policy file
 
-보호 진입점은 자동 확장 탐색을 끕니다. 알려진 도구 외에는 신뢰한 어댑터가 없는 도구를 차단합니다.
+Specify a policy with `--policy` or SDK `settings` or `settingsPath`.
 
-## 정책 파일
+A normal Pi installation uses `<agentDir>/guard/settings.json`. Choose **Approve for me** or **Ask for approval** in `/approve`. The screen uses the English descriptions from [Codex's official approval picker](https://learn.chatgpt.com/docs/security-administration) and wraps the selected description on narrow terminals. Command descriptions, selection screens, status text, and fixed approval dialog text are in English.
 
-`--policy` 또는 SDK의 `settings`·`settingsPath`로 지정합니다.
+`/approve-model` shows only available models in Pi's current `/scoped-models` scope. Without a configured scope, it shows all available models, as Pi does. If every scoped model is unavailable, it does not expand to the full list. A model removed from the scope while the picker is open is not saved; existing settings are preserved.
 
-일반 Pi 설치에서는 `<agentDir>/guard/settings.json`을 사용합니다. `/approve`에서 **Approve for me** 또는 **Ask for approval**을 선택하고, `/approve-model`에서 등록된 모델을 검색해 보조 모델을 선택합니다. **현재 Pi 모델 사용**은 `reviewModel: null`에 해당합니다. 주 모델은 바뀌지 않으며 Esc로 취소하면 저장하지 않습니다. 명시한 `settingsPath`가 있으면 메뉴도 그 파일에 저장합니다.
+**Use current Pi model** corresponds to `reviewModel: null` and uses the current main model for review instead of a secondary model. Selecting a secondary model does not change the main model. Esc cancels without saving. When `settingsPath` is specified, the menus also save to that file.
 
 ```json
 {
@@ -128,90 +134,100 @@ try {
 }
 ```
 
-| 필드 | 기본값 | 설명 |
+| Field | Default | Description |
 | --- | --- | --- |
-| `mode` | `workspace-write` | `read-only` 또는 `workspace-write` |
-| `approvalPolicy` | `on-request` | `"on-request"`, `"never"`, 또는 `{"sandbox": true, "rules": false, "mcp_elicitations": true}`. `sandbox` 키는 기존 파일 호환성을 위한 일반 승인 범주의 이름이며 OS 격리를 뜻하지 않습니다. 생략한 `mcp_elicitations`는 허용하지 않습니다. `never`와 꺼진 범주의 요청은 검토 없이 차단합니다 |
-| `approvalsReviewer` | `auto_review` | `"user"`면 사용자 검토 |
-| `reviewModel` | `null` | 현재 모델 대신 사용할 등록 모델 (`{"provider": "ollama-cloud", "id": "glm-5.3"}`). 해당 공급자를 먼저 등록해야 합니다 |
-| `ruleFiles` | `[]` | 아래 규칙 파일 경로 |
-| `commandRules` | `[]` | 리터럴 인자 접두사 규칙 (`allow`·`ask`·`deny`) |
-| `allowedDomains` | `[]` | 허용 도메인 패턴 |
-| `trustedTools` | `[]` | 알려진 도구 외에 통과할 추가 도구 이름 |
-| `reviewTimeoutMs`, `approvalTimeoutMs`, `executionTimeoutSeconds` | 20000, 60000, 120 | 검토자·승인 창은 밀리초, 쉘은 초 단위입니다 |
-| `reviewPolicy`, `reviewMaxRounds`, `reviewMaxOutputTokens`, `reviewContextChars` | `null`, 4, 2048, 60000 | 검토자의 조직 정책 부분을 교체합니다. 위험 평가·출처 구분·결과 기준은 유지합니다 |
-| `writableRoots` | `[]` | 추가 쓰기 루트 |
-| `excludeSlashTmp`, `excludeTmpdir` | `false` | 기본 임시 경로(`/tmp`, `os.tmpdir()`) 허용을 제외합니다 |
-| `projectDocMaxBytes`, `projectDocFallbackFilenames`, `projectRootMarkers` | 32768, `[]`, `null` | 프로젝트 지침 합산 한도, 보조 파일명, 루트 표시 (`null`은 `.git`, `[]`은 상위 탐색 해제) |
-
-## 규칙 파일
-
-`ruleFiles`의 `.rules`는 고정 리비전의 Codex `codex-execpolicy`가 직접 평가합니다.
-
-- Starlark 함수·조건식·컴프리헨션·문자열 보간, `prefix_rule`, `host_executable`, `network_rule`, `match`·`not_match` 검증을 지원합니다.
-- 복합 명령에는 가장 강한 규칙을 적용합니다.
-- Codex의 네트워크 규칙 변환처럼 프로토콜 표시는 호스트 허용·거부 목록으로 합쳐지며, 별도 프로토콜별 권한으로 분리하지 않습니다.
-- 해석하지 못하는 셸 구문은 신뢰한 전체 명령 규칙이 허용하지 않으면 검토합니다.
-- 신뢰한 `allow` 규칙은 일치하는 명령의 권한을 넓힐 수 있으므로 필요한 명령에만 지정합니다.
-
-## 동작 상세
-
-### 명령 검토와 승인
-
-- 승인된 도구는 Pi의 원래 SDK 실행기로 실행합니다. 셸의 최종 명령·작업 디렉터리·환경·시간 제한·취소 신호를 유지합니다.
-- 일반 범위를 넘는 파일 접근, 명시적 승인 요청, 검토 규칙, 해석하지 못하는 명령은 실행 전에 검토합니다.
-- `additional_permissions`는 검토할 범위의 설명입니다. 승인된 명령은 호스트 권한으로 실행하며 이 범위를 OS 접근 제한으로 강제하지 않습니다. 실행 중 네트워크 목적지를 가로채거나 별도 프록시를 만들지 않습니다.
-- TUI·RPC 승인 창에서 한 번, 세션, 규칙 저장을 선택할 수 있습니다. 전체 명령 권한은 한 번만 승인할 수 있습니다. 저장 승인은 정확한 도구·입력·작업 디렉터리·호출 경로·정책·권한에 묶이며, 정책 변경 시 기존 승인을 무효화합니다.
-- 모델 작업이 반복 거부로 중단돼도 이후 사용자가 직접 입력한 쉘 명령은 독립적으로 평가합니다.
-
-### 자동 검토자
-
-- 현재 모델을 기본으로 사용하고 `reviewModel`로 등록된 다른 모델을 선택할 수 있습니다.
-- 누적된 사용자 지시와 Pi가 제공한 지시의 출처를 유지하며, 도구 결과는 실행 증거로 취급합니다.
-- 조사는 읽기 전용 파일·디렉터리 도구로 제한합니다.
-- 연속 3회 또는 최근 50회 중 10회 거부되면 실제 Pi 작업을 중단합니다.
-- 오류와 시간 초과는 승인으로 바뀌지 않으며, 잘못된 위험 등급·승인 수준 응답도 검토 실패로 처리합니다.
-- `/approve`는 승인 방식 설정이고 `/approve-model`은 보조 모델 선택입니다. 설정 변경은 저장 후 즉시 적용하며 이전 정책의 대기 검토와 저장 승인을 무효화합니다.
-
-### 컨텍스트 파일
-
-- `agentDir`의 전역 지침과 프로젝트 루트부터 현재 디렉터리까지의 지침을 자동 탐색합니다.
-- 같은 디렉터리에서는 `AGENTS.override.md` → `AGENTS.md` → `projectDocFallbackFilenames` 순서로 선택합니다.
-- 보호 파일로 연결되는 별칭은 거부하고, 도구 출력에 등장한 파일명을 지침의 출처로 취급하지 않습니다. 비신뢰 프로젝트는 제외하며 새로고침 때 다시 읽습니다.
+| `mode` | `workspace-write` | `read-only` or `workspace-write` |
+| `approvalPolicy` | `on-request` | `"on-request"`, `"never"`, or `{"sandbox": true, "rules": false, "mcp_elicitations": true}`. The `sandbox` key names the general approval category for compatibility with existing files; it does not mean OS isolation. Omitted `mcp_elicitations` is not allowed. `never` and disabled categories block requests without review |
+| `approvalsReviewer` | `auto_review` | `"user"` selects user review |
+| `reviewModel` | `null` | A registered model to use instead of the current model (`{"provider": "ollama-cloud", "id": "glm-5.3"}`). Register the provider first |
+| `ruleFiles` | `[]` | Paths to the rule files described below |
+| `commandRules` | `[]` | Literal argument prefix rules (`allow`, `ask`, `deny`) |
+| `allowedDomains` | `[]` | Allowed domain patterns |
+| `trustedTools` | `[]` | Additional tool names allowed outside the known set |
+| `reviewTimeoutMs`, `approvalTimeoutMs`, `executionTimeoutSeconds` | 20000, 60000, 120 | Reviewer and approval dialog timeouts are in milliseconds; shell timeout is in seconds |
+| `reviewPolicy`, `reviewMaxRounds`, `reviewMaxOutputTokens`, `reviewContextChars` | `null`, 4, 2048, 60000 | Replaces the reviewer's organization policy section. Risk assessment, source distinction, and outcome criteria remain intact |
+| `writableRoots` | `[]` | Additional writable roots |
+| `excludeSlashTmp`, `excludeTmpdir` | `false` | Excludes the default temporary paths (`/tmp`, `os.tmpdir()`) from allowed writes |
+| `projectDocMaxBytes`, `projectDocFallbackFilenames`, `projectRootMarkers` | 32768, `[]`, `null` | Combined project instruction limit, fallback filenames, and root markers (`null` means `.git`; `[]` disables parent traversal) |
+
+## Rule files
+
+The TypeScript engine evaluates `.rules` files in `ruleFiles` using contracts ported from Codex revision `a956835d020762cb2b570053af06f643a11c0ecc`. Captured outputs from the former native engine are replayed in the [parity tests](../test/unit/execpolicy-parity.test.mjs).
+
+Evaluation exposes only Starlark values and policy functions, with no host file or network functions or JavaScript `eval`. Input/output size, execution steps, collection size, nesting, and evaluation time are bounded. The asynchronous API uses a cancellable Node.js worker; the synchronous API uses a bounded Node.js process. Invalid or unsupported input and exhausted budgets reject the rules. Without rule files, startup needs neither an evaluation worker nor an external executable.
+
+- Supports Starlark functions, conditionals, comprehensions, string interpolation, `prefix_rule`, `host_executable`, `network_rule`, and `match` and `not_match` validation.
+- Applies the strongest matching rule to compound commands.
+- As in Codex's network rule conversion, protocol labels are merged into host allow and deny lists rather than separate protocol permissions.
+- Shell syntax that cannot be interpreted requires review unless a trusted full-command rule allows it.
+- `curl` and `wget` require review when the destination is not an explicit HTTP URL or comes from a separate configuration file. Omitting the scheme or supplying the URL through a configuration file does not bypass general approval review.
+- Trusted `allow` rules can broaden permissions for matching commands; limit them to the commands that need them.
+
+## Behavior details
+
+### Command review and approval
+
+- Approved tools run through Pi's original SDK executor. The final shell command, working directory, environment, timeout, and cancellation signal are preserved.
+- File access outside the normal scope, explicit approval requests, review rules, and commands that cannot be interpreted are reviewed before execution.
+- `additional_permissions` describes the scope to review. Approved commands run with host permissions; the scope is not enforced as an OS access restriction. The extension does not intercept network destinations during execution or create a separate proxy.
+- TUI and RPC approval dialogs offer one-time, session, and saved-rule approval. Full-command permissions can be approved only once. Saved approvals bind to the exact tool, input, working directory, invocation path, policy, and permissions. Policy changes invalidate existing approvals.
+- Direct shell commands entered later by the user are evaluated independently even if repeated denials stopped the model's task.
+
+### Automatic reviewer
+
+- Uses the current model by default; `reviewModel` can select another registered model.
+- Preserves the sources and chronology of accumulated user instructions and instructions supplied by Pi. Tool results are execution evidence. The outer `user` message sent to the review API and user-role messages generated by extensions do not themselves grant authorization.
+- Investigation is limited to read-only file and directory tools.
+- Stops the actual Pi task after three consecutive denials or ten denials in the latest fifty reviews.
+- Errors and timeouts never become approvals. Invalid risk or authorization level responses are also treated as review failures.
+- `/approve` configures the approval method; `/approve-model` selects the secondary model. Changes apply immediately after saving and invalidate pending reviews and saved approvals from the previous policy.
+- After reading a denial reason, the user can authorize the exact operation, target, and content to send in an ordinary message. The next review receives the latest authorization and new facts; no special command is needed. If the user withdraws authorization or requests another target, review is based on the current instructions and actual operation.
+- `/approve retry` lets the user select one exact operation from up to ten recent automatic review denials. Selecting it after checking the target, input, and denial reason triggers one new review of the same operation in the same context. It does not automatically allow the operation or grant session approval. A previous `critical` assessment can be reevaluated, but an operation still assessed as `critical` or subject to an explicit absolute denial remains blocked. The authorization marker does not apply to changed inputs or stale context.
+- A custom `reviewPolicy` replaces only the original organization policy section. Strings such as `{{ extra_policy }}` inside the policy are preserved literally. Risk and authorization criteria are not replaced.
+- Actual model responses must use the structured `outcome` assessment. The existing `decision` interface of a `ReviewProvider` explicitly injected through the SDK remains for compatibility; actual Pi models cannot use that path.
+- Review input includes the current approval policy, path and domain scope, final execution arguments, linked tool calls and results, and the actual approval dialog's questions and answers. Shell environment evidence includes explicit non-secret values and the names of omitted variables; it is not described as the full process environment.
+- Final prepared calls, results, review assessments, and user confirmations are saved in Pi session custom records for extension reloads and active branch restoration. Audit logs still omit raw arguments. Large evidence is limited with omission markers. If user authorization and the full current review target exceed the budget, execution is not automatic.
+- A statement from an ordinary tool that “the user approved” is evidence. Only answers observed by the protected adapter through actual Pi `select`, `confirm`, and `input` APIs are recorded as user confirmations with their questions. Answers to questions marked as password or API key input are masked in the record.
+
+### Context files
+
+- Automatically discovers global instructions in `agentDir` and project instructions from the project root to the current directory.
+- In each directory, chooses `AGENTS.override.md`, then `AGENTS.md`, then `projectDocFallbackFilenames`.
+- Rejects aliases pointing to protected files and does not treat filenames in tool output as instruction sources. Untrusted projects are excluded. Files are reread on refresh.
 
 ### MCP
 
-- Pi에 등록된 서버, `agentDir/mcp.json`, 신뢰한 프로젝트의 `.pi/mcp.json`을 사용합니다. 모드를 다시 연결할 때 기존 연결을 종료하고 새 연결을 만듭니다.
-- 최종 실행 승인은 서버의 실제 도구 등록에 결합합니다. 검토 중 등록 정보가 바뀌거나 호출이 취소되면 실행하지 않습니다.
-- 일반 경로는 검토자 종류와 별개로 Codex의 annotation 우선순위와 승인 모드를 따릅니다. 엄격한 검토 요청·민감 작업·필수 사용자 입력은 새 승인을 요구하고, 읽기 전용 표시나 이전 승인으로 생략하지 않습니다.
-- `codex_requires_user_input`은 모델이 대신 승인하지 않습니다. 빈 승인 폼은 처리하지만, 입력 필드가 있는 일반 폼과 URL 인증 요청은 이 어댑터에서 거부합니다.
-- `node_repl/js` 이름에도 같은 승인 규칙을 적용합니다. 추가 승인 요청은 살아 있는 원래 호출의 도구·연결·실제 입력에 결합하며, 다른 도구나 커넥터를 대신 지목하면 거부합니다.
+- Uses servers registered in Pi, `agentDir/mcp.json`, and trusted projects' `.pi/mcp.json`. Mode reconnection closes existing connections and creates new ones.
+- Final execution approval binds to the server's actual tool registration. Changes to registration during review, or cancellation, prevent execution.
+- The normal path follows Codex's annotation precedence and approval modes regardless of reviewer type. Strict review requests, sensitive operations, and required user input need fresh approval; read-only annotations and previous approvals cannot skip it.
+- The model does not approve `codex_requires_user_input` on the user's behalf. Empty approval forms are handled, but ordinary forms with input fields and URL authentication requests are rejected by this adapter.
+- The same approval rules apply to the `node_repl/js` name. Additional approval requests bind to the original live call's tool, connection, and actual input. Requests naming another tool or connector instead are rejected.
 
-### 실행 범위
+### Execution scope
 
-- 검토 입력의 경로는 문자 그대로 정규화합니다. 별도의 OS 권한 패턴으로 변환하지 않습니다.
-- 시작과 도구 실행 전에 디렉터리 트리나 하드링크를 전수 탐색하지 않습니다.
-- 직접 도구 경로와 해석 가능한 명령의 보호 경로는 승인 전에 거부합니다. 승인된 인터프리터 내부의 간접 접근, 하드링크 별칭, 실행 중 네트워크 변경을 격리하지 않습니다.
+- Review input paths are normalized literally, without conversion to separate OS permission patterns.
+- The extension does not exhaustively scan directory trees or hard links at startup or before tool execution.
+- Direct tool paths and protected paths in interpretable commands are rejected before approval. Indirect access inside approved interpreters, hard-link aliases, and network changes during execution are not isolated.
 
-## Docker에서 Ollama Cloud 검증
+## Ollama Cloud verification in Docker
 
-### 준비
+### Preparation
 
-- 저장소 루트에서 Docker 엔진이 실행 중이어야 합니다. 로컬 Ollama 서버는 설치하지 않습니다.
-- 이미지는 Node 24.14.0, Pi 0.99.1, `pi-ollama-cloud` 0.12.2, `fd` 10.3.0을 고정합니다. 호스트 디렉터리·소켓을 마운트하거나 포트를 공개하지 않으며 Docker의 기본 보안 제한을 유지합니다.
-- 처음 이미지 빌드에만 네트워크가 필요하고, 검증 컨테이너는 네트워크 없이 실행합니다.
+- Run from the repository root with the Docker engine running. No local Ollama server is installed.
+- The image pins Node 24.14.0, Pi 0.99.1, `pi-ollama-cloud` 0.12.2, and `fd` 10.3.0. It does not mount host directories or sockets or publish ports, and retains Docker's default security restrictions.
+- Only the initial image build requires network access. Verification containers run without a network.
 
-### 키 없는 검증
+### Verification without keys
 
 ```sh
 npm run verify:docker -- --mode offline --platform linux/amd64
 ```
 
-ARM Docker 호스트에서 별도 ARM64 결과를 얻으려면 `--platform linux/arm64`로 실행합니다.
+For a separate ARM64 result on an ARM Docker host, run with `--platform linux/arm64`.
 
-### 실모델 검증
+### Live model verification
 
-실행할 셸에 `OLLAMA_API_KEY`를 export해야 합니다. 키는 명령 인자·이미지 빌드 인자·`auth.json`에 쓰지 않으며, 실제 호출에는 계정 사용량이 발생할 수 있습니다.
+Export `OLLAMA_API_KEY` in the shell that will run verification. Do not put the key in command arguments, image build arguments, or `auth.json`. Actual calls may consume account usage.
 
 ```sh
 export OLLAMA_MODEL=glm-5.3
@@ -219,8 +235,8 @@ npm run verify:docker -- --mode live --platform linux/amd64
 npm run verify:docker -- --mode conformance --platform linux/amd64
 ```
 
-- `live`는 실제 주 에이전트와 검토자의 외부 경로 쓰기를 확인합니다.
-- `conformance`는 허용·외부 경로 승인·보호 경로 차단·정책 거부 사례와 배포된 CLI의 공급자 선택 승인을 검사합니다.
-- 사례마다 모델 호출 횟수·시간·출력을 제한하고 자동 공급자 재시도를 끕니다. 관찰 확장은 호출 수와 선택한 모델만 기록하고 응답을 대체하지 않습니다. 웹 도구와 사용량 조회는 비활성화합니다.
-- 키 부재·미지원 모델·서비스 오류·격리 오류는 성공으로 바꾸지 않습니다.
-- 출력의 `imageDigest`를 `--image`에 추가하면 소스와 아키텍처가 일치하는 기존 이미지를 재사용합니다. 소스 수정 후에는 `--image` 없이 다시 빌드합니다.
+- `live` checks external-path writes by the actual main agent and reviewer.
+- `conformance` checks allowed operations, external-path approvals, protected-path blocks, policy denials, and provider selection approval in the distributed CLI.
+- Each case limits model calls, time, and output, and disables automatic provider retries. The observation extension records only call counts and selected models; it does not replace responses. Web tools and usage queries are disabled.
+- Missing keys, unsupported models, service errors, and isolation errors are not treated as success.
+- Supply the output's `imageDigest` through `--image` to reuse an existing image with matching source and architecture. After source changes, rebuild without `--image`.

package/package.json

@@ -1,98 +1,109 @@
 {
-  "name": "pi-codex-auto-review",
-  "version": "0.1.3",
-  "description": "Codex의 ‘Approve for me’에서 영감을 받은 Pi용 자동 실행 승인 검토 확장. 규칙과 Pi의 현재 모델로 도구 실행을 검토하고, 필요한 경우 사용자 승인을 요청합니다.",
-  "license": "Apache-2.0",
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "approval",
-    "auto-review"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/buYoung/pi-codex-auto-review.git"
-  },
-  "homepage": "https://github.com/buYoung/pi-codex-auto-review#readme",
-  "bugs": {
-    "url": "https://github.com/buYoung/pi-codex-auto-review/issues"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": "./dist/index.js",
-    "./startup": "./dist/startup.js"
-  },
-  "bin": {
-    "pi-codex-auto-review": "dist/cli.js"
-  },
-  "pi": {
-    "extensions": [
-      "./dist/index.js"
+    "name": "pi-codex-auto-review",
+    "version": "0.2.0",
+    "description": "Codex의 ‘Approve for me’에서 영감을 받은 Pi용 자동 실행 승인 검토 확장. 규칙과 Pi의 현재 모델로 도구 실행을 검토하고, 필요한 경우 사용자 승인을 요청합니다.",
+    "license": "Apache-2.0",
+    "keywords": [
+        "pi-package",
+        "pi-extension",
+        "approval",
+        "auto-review"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/buYoung/pi-codex-auto-review.git"
+    },
+    "homepage": "https://github.com/buYoung/pi-codex-auto-review#readme",
+    "bugs": {
+        "url": "https://github.com/buYoung/pi-codex-auto-review/issues"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": "./dist/index.js",
+        "./startup": "./dist/startup.js"
+    },
+    "bin": {
+        "pi-codex-auto-review": "dist/cli.js"
+    },
+    "pi": {
+        "extensions": [
+            "./dist/index.js"
+        ]
+    },
+    "scripts": {
+        "prepare": "husky",
+        "check": "biome check .",
+        "check:fix": "biome check --write .",
+        "check:staged": "lint-staged",
+        "release": "node scripts/release.mjs",
+        "build": "node scripts/clean-build.mjs && tsc",
+        "prepack": "node scripts/clean-build.mjs && tsc && node scripts/check-package.mjs",
+        "test:contracts": "node scripts/run-tests.mjs contracts",
+        "test:policy": "node scripts/run-tests.mjs policy",
+        "test:reviewer": "node scripts/run-tests.mjs reviewer",
+        "test:approvals": "node scripts/run-tests.mjs approvals",
+        "test:execution": "node scripts/run-tests.mjs execution",
+        "test:integration": "node scripts/run-tests.mjs integration",
+        "test:e2e": "node scripts/run-tests.mjs e2e",
+        "test:conformance": "node scripts/run-tests.mjs conformance",
+        "verify:guard": "node scripts/verify-guard.mjs",
+        "verify:platform": "node scripts/verify-platform.mjs",
+        "verify:windows": "node scripts/verify-windows.mjs",
+        "verify:docker": "node scripts/verify-docker.mjs"
+    },
+    "lint-staged": {
+        "*": "biome check --no-errors-on-unmatched --files-ignore-unknown=true"
+    },
+    "peerDependencies": {
+        "@earendil-works/pi-ai": ">=0.86.1",
+        "@earendil-works/pi-coding-agent": ">=0.86.1",
+        "@earendil-works/pi-tui": ">=0.86.1"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.5.15",
+        "@earendil-works/pi-ai": "0.99.1",
+        "@earendil-works/pi-coding-agent": "0.99.1",
+        "@earendil-works/pi-tui": "0.99.1",
+        "@inquirer/prompts": "8.5.2",
+        "@sinclair/typebox": "0.34.52",
+        "@types/node": "24.0.0",
+        "husky": "9.1.7",
+        "lint-staged": "16.4.0",
+        "pi-ollama-cloud": "0.12.2",
+        "release-it": "21.0.1",
+        "semver": "7.8.5",
+        "typescript": "6.0.3"
+    },
+    "overrides": {
+        "@earendil-works/pi-ai": "0.99.1",
+        "@earendil-works/pi-agent-core": "0.99.1",
+        "@earendil-works/pi-tui": "0.99.1",
+        "brace-expansion": "5.0.12"
+    },
+    "engines": {
+        "node": ">=22.19.0"
+    },
+    "files": [
+        "dist/**/*.js",
+        "dist/**/*.d.ts",
+        "dist/**/*.js.map",
+        "README.md",
+        "README.ko.md",
+        "LICENSE",
+        "NOTICE",
+        "docs/usage.md",
+        "docs/usage.ko.md",
+        "docs/publishing.md",
+        "docs/publishing.ko.md",
+        "docs/security/dependencies.md",
+        "docs/security/dependencies.ko.md",
+        "docs/testing/auto-review-protection.md",
+        "docs/testing/auto-review-protection.ko.md"
     ]
-  },
-  "scripts": {
-    "release": "node scripts/release.mjs",
-    "build": "node scripts/clean-build.mjs && tsc && node scripts/build-execpolicy.mjs",
-    "prepack": "node scripts/clean-build.mjs && tsc && node scripts/check-package.mjs",
-    "test:contracts": "node scripts/run-tests.mjs contracts",
-    "test:policy": "node scripts/run-tests.mjs policy",
-    "test:reviewer": "node scripts/run-tests.mjs reviewer",
-    "test:approvals": "node scripts/run-tests.mjs approvals",
-    "test:execution": "node scripts/run-tests.mjs execution",
-    "test:integration": "node scripts/run-tests.mjs integration",
-    "test:e2e": "node scripts/run-tests.mjs e2e",
-    "test:conformance": "node scripts/run-tests.mjs conformance",
-    "verify:guard": "node scripts/verify-guard.mjs",
-    "verify:platform": "node scripts/verify-platform.mjs",
-    "verify:windows": "node scripts/verify-windows.mjs",
-    "verify:docker": "node scripts/verify-docker.mjs"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.86.1",
-    "@earendil-works/pi-coding-agent": ">=0.86.1",
-    "@earendil-works/pi-tui": ">=0.86.1"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-ai": "0.99.1",
-    "@earendil-works/pi-coding-agent": "file:vendor/pi-coding-agent-0.99.1-security.1.tgz",
-    "@earendil-works/pi-tui": "0.99.1",
-    "@inquirer/prompts": "8.5.2",
-    "@sinclair/typebox": "0.34.52",
-    "@types/node": "24.0.0",
-    "pi-ollama-cloud": "0.12.2",
-    "release-it": "21.0.1",
-    "semver": "7.8.5",
-    "typescript": "6.0.3"
-  },
-  "overrides": {
-    "@earendil-works/pi-ai": "0.99.1",
-    "@earendil-works/pi-agent-core": "0.99.1",
-    "@earendil-works/pi-tui": "0.99.1",
-    "brace-expansion": "5.0.12"
-  },
-  "engines": {
-    "node": ">=22.19.0"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "dist/**/*.js.map",
-    "dist/native/*/pi-guard-execpolicy*",
-    "dist/native/*/artifact.json",
-    "README.md",
-    "LICENSE",
-    "NOTICE",
-    "docs/usage.md",
-    "docs/publishing.md",
-    "docs/security/dependencies.md",
-    "docs/testing/auto-review-protection.md",
-    "native/execpolicy/LICENSE",
-    "native/execpolicy/NOTICE"
-  ]
 }

package/dist/native/darwin-arm64/artifact.json

@@ -1,5 +0,0 @@
-{
-  "platform": "darwin-arm64",
-  "sourceDigest": "77a7cd21c340d5d5956164cc0ce32970097bc8f4180a2e373df56a1ff79b5088",
-  "sha256": "660d7f76dec67a66b6e62d3e1c43fb01ae3e9b6912ff0b73645e0f87c22cd198"
-}

package/dist/native/linux-x64/artifact.json

@@ -1,5 +0,0 @@
-{
-  "platform": "linux-x64",
-  "sourceDigest": "77a7cd21c340d5d5956164cc0ce32970097bc8f4180a2e373df56a1ff79b5088",
-  "sha256": "a08e8b8579986c6f0d17b6ef964e129ebf036df972b95a8510ea679802bfa1fb"
-}