> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 権限 ## 権限モード 権限モードは Qoder がツール呼び出しをどのように処理するかを決定します。各モードは「自動化の度合い」と「セキュリティの緩さ」の 2 軸で異なる位置づけになります。 | モード | 適用シナリオ | 動作 | | :-------------------------- | :-------------------- | :------------------------------------------------------------------ | | `default` | 通常のインタラクティブ利用 | 安全な読み取りと内部アクションは自動実行。センシティブな操作は確認を要求します。 | | `accept_edits` | 日常的なコーディング | 作業ディレクトリ内の安全なファイル編集を自動承認。Shell コマンド、外部アクション、センシティブなパスは通常のチェックを通ります。 | | `auto` | 自動化実行、Goal 実行 | プロンプトなし。安全な読み取りとワークスペース内編集を自動承認。リスクのある操作は拒否されるか AI 分類器で判断されます。 | | `bypass_permissions` (YOLO) | 信頼できるローカル実験のみ | すべての承認プロンプトをスキップ。すべてのツール呼び出しが自動許可されます。 | | `dont_ask` | プロンプト不可の headless フロー | 確認しません。本来確認が必要な操作はすべて拒否されます。 | ### Plan モード Plan は独立した**ワークステート**（権限ポリシーではない）であり、上記のどの権限モードとも共存できます。`/plan` コマンドで切り替え（トグル）ます。有効時は Qoder が読み取り専用でコードを探索し提案を出力します。書き込みは計画ファイルに制限されます。終了時にフォローアップの権限モードを選ぶか、直接 Goal 実行に入ることができます。 ### Goal モード Goal は自律実行ステートです。`/goal set <目標>` で入ります — 自動的に `auto` モードに切り替わり、Shift+Tab 切り替えをロックして実行中の中断をゼロにします。Goal は Plan と共存可能です（先に計画、後で実行）。`/goal clear` または `/goal pause` で終了します。 ### モードサイクル切り替え インタラクティブセッションでは、**Shift+Tab** ですべての権限モード間を循環切り替えできます。**Ctrl+Y** で YOLO モードに直接ジャンプできます。 ### 起動パラメータ `--permission-mode` で現在のセッションのデフォルト動作を選択します： ```shell theme={null} qodercli --permission-mode default qodercli --permission-mode accept_edits qodercli --permission-mode plan # 旧バージョン互換：default + Plan ワークステートに入るに変換 qodercli --permission-mode auto qodercli --permission-mode bypass_permissions qodercli --permission-mode yolo # bypass_permissions と同等 qodercli --permission-mode dont_ask # ショートカット qodercli --yolo # --permission-mode bypass_permissions と同等 qodercli --dangerously-skip-permissions # 同上 ``` インタラクティブセッションでは、**Ctrl+Y** で素早く YOLO モードに切り替えることもできます。 複数の命名形式に対応しています（大文字小文字不問）： | 標準値 (snake\_case) | camelCase | エイリアス | | :------------------- | :------------------ | :------------- | | `accept_edits` | `acceptEdits` | — | | `bypass_permissions` | `bypassPermissions` | `yolo`, `YOLO` | | `dont_ask` | `dontAsk` | — | 例： ```shell theme={null} # 以下はすべて同等です qodercli --permission-mode bypass_permissions qodercli --permission-mode bypassPermissions qodercli --permission-mode yolo qodercli --yolo qodercli --dangerously-skip-permissions ``` 非 default モードは信頼済みディレクトリ内でのみ有効になります。現在のディレクトリが信頼されていない場合、Qoder は `default` にフォールバックします。 ## 権限の判定方法 Qoder は各ツール呼び出しの前に権限チェックを行います。結果は常に 3 つのうちいずれかです： * **`allow`**: ツールを即座に実行します。 * **`ask`**: 外部の確認が得られてから実行します。 * **`deny`**: ツール呼び出しをブロックします。 権限はファイルの読み書き、Bash コマンド、Web fetch、MCP ツール、Subagent、その他の組み込みツールに適用されます。 ### 判定順序 Qoder は固定順で権限を評価します： 1. まず `deny` ルールを確認 — 一致すれば即座に拒否。 2. ツール自身の安全チェック（危険コマンド検出、センシティブパス検出など）。 3. `ask` ルール — 一致すれば確認が必要とマークします。 4. ツールレベルの `allow` ルールとモード由来の自動許可動作。 5. 最終結果がまだ `ask` の場合、ランタイム環境が消費方法を決定します。 広い allow ルールがあってもすべての操作が無音で実行されるわけではありません — 安全チェックと ask ルールの方が優先度が高いです。 ### 異なる実行環境での `ask` の消費方法 | 実行環境 | `ask` の行き先 | 説明 | | :---------------------------- | :-------------------------------- | :------------------------------ | | **TUI**（インタラクティブターミナル） | 確認プロンプト | ユーザーがターミナルで許可/拒否を選択します。 | | **Headless**（`-p`/`--prompt`） | 自動拒否 | 人の対話がないため、`ask` は `deny` になります。 | | **SDK**（stdio プロトコル） | ホストに `canUseTool` コールバックを送信 | ホストプログラムが allow/deny を決定します。 | | **ACP**（IDE 統合） | IDE に `requestPermission` RPC を送信 | IDE がプロンプト表示または自動決定します。 | Headless モード（`-p`/`--prompt`）は権限モードと組み合わせ可能です： ```shell theme={null} # Headless + accept_edits：ファイル編集は自動通過、Bash は拒否 qodercli -p "refactor the utils module" --permission-mode accept_edits # Headless + bypass_permissions：すべて許可（信頼シナリオのみ） qodercli -p "run the migration" --yolo # Headless + 精密 allow ルール：特定ツールのみ許可 qodercli -p "check status" --allowed-tools 'Read,Bash(git status)' ``` ## 権限設定 ### 設定ソース（8 層優先度） ルールは複数のソースからマージされ、優先度が低い順に： | 層 | ソース | 説明 | | :- | :---------------- | :--------------------------------------------------------------- | | 1 | `userSettings` | `~/.qoder/settings.json`（ユーザーグローバル） | | 2 | `projectSettings` | `/.qoder/settings.json`（プロジェクトレベル、チーム共有） | | 3 | `localSettings` | `/.qoder/settings.local.json`（マシンローカル、`.gitignore` に追加） | | 4 | `flagSettings` | `--settings ` CLI 引数で指定する追加ファイル | | 5 | `cliArg` | `--allowed-tools` / `--disallowed-tools` コマンドライン引数 | | 6 | `command` | `/allow`、`/deny` セッション内コマンド | | 7 | `session` | ランタイム一時ルール（プロンプトで「今回のセッションで許可」） | 高優先度ソースのルールが低優先度を上書きします。組織ポリシーが `allowManagedPermissionRulesOnly` を有効にしている場合、ポリシー管理ルールのみが使用されます。 **各ソースの設定方法：** * **層 1-3（settings ファイル）**：対応パスの JSON ファイルに `permissions.allow` / `permissions.deny` / `permissions.ask` 配列を記述します。`settings.local.json` はマシン固有の承認ルールに最適で、`.gitignore` に追加することを推奨します。 * **層 4（flagSettings）**：`qodercli --settings ./custom-settings.json` で追加の settings ファイルを指定します。標準 settings.json と同じ形式です。 * **層 5（cliArg）**：`--permission-mode`、`--allowed-tools`、`--disallowed-tools`、`--tools` 等のコマンドライン引数で設定。現在のセッションのみ有効。 * **層 6（command）**：セッション中に `/allow Bash(npm test)` や `/deny WebFetch` と入力。`settings.local.json` に永続化されます。 * **層 7（session）**：プロンプトで「今回のセッションで許可」を選択した一時ルール。プロセス終了で失効。 ### モード設定 **デフォルトモードの設定** — settings で `general.defaultPermissionMode` を設定： ```json theme={null} { "general": { "defaultPermissionMode": "accept_edits" } } ``` サポートされる値： | 値 | 動作 | エイリアス | | -------------------- | --------------------------------------------- | -------------------------- | | `default` | 每回承認を求める | — | | `accept_edits` | ファイル編集を自動承認、Shell コマンドは確認が必要 | `acceptEdits` | | `plan` | 読み取り専用モード（旧バージョン互換：default + Plan ワークステートに変換） | — | | `auto` | AI クラシファイアが操作の安全性を評価 | — | | `bypass_permissions` | すべての権限チェックをスキップ（YOLO） | `yolo`、`bypassPermissions` | | `dont_ask` | 非対話モード、承認が必要な操作は拒否 | `dontAsk` | 大文字小文字を区別しません。すべてのエイリアスが使用可能です。 **YOLO モードの無効化** — 組織管理者が bypass\_permissions モードへの移行を防止できます： ```json theme={null} { "security": { "disableYoloMode": true } } ``` 設定後、`--yolo`、`--permission-mode bypass_permissions`、Ctrl+Y はすべて無効になり、Shift+Tab サイクルもこのモードをスキップします。Sub-agent が bypass を宣言した場合も acceptEdits に降格されます。 **Plan モードの無効化** — Plan ワークフローが不要な場合： ```json theme={null} { "general": { "plan": { "enabled": false } } } ``` 設定後、`/plan` コマンドは使用不可になり、`--permission-mode plan` は default にフォールバックし、EnterPlanMode/ExitPlanMode ツールは登録されません。 **Auto モード分類器設定** — 自然言語ルールで AI 分類器の判断傾向をガイドできます： ```json theme={null} { "autoMode": { "allow": [ "running npm/yarn/pnpm scripts defined in package.json", "creating or editing test files" ], "soft_deny": [ "deleting files outside the test directory", "modifying CI/CD configuration" ], "environment": [ "This is a Node.js monorepo with pnpm workspaces", "The project uses Vitest for testing" ] } } ``` | フィールド | 目的 | | :------------ | :----------------- | | `allow` | 分類器が自動承認に傾く操作の説明 | | `soft_deny` | 分類器が拒否に傾く操作の説明 | | `environment` | 分類器に提供する環境コンテキスト情報 | これらのルールは**ソフトガイダンス**です — 分類器の prompt にリファレンスとして注入され、最終判断は AI 分類器が行います。セキュリティ上、`autoMode` 設定は信頼できるソース（ユーザーグローバル settings と localSettings）からのみ読み取られます。プロジェクト settings は悪意ある権限昇格を防ぐため除外されます。 ### 権限ルール設定 ルールは `allow`、`ask`、`deny` に分類されます： ```json theme={null} { "permissions": { "allow": [ "Read(/src/**)", "Edit(/src/**)", "Bash(npm run test:*)" ], "ask": [ "Bash(npm publish:*)", "WebFetch" ], "deny": [ "Read(*.pem)", "Bash(rm -rf:*)" ] } } ``` ### ルール構文 | 形式 | 意味 | | :------------------ | :---------------------------------------- | | `ToolName` | ツール全体に適用します。 | | `ToolName(content)` | 特定のパス、コマンド、agent type、またはそのツール固有の値に適用します。 | | `*` | すべてのツールに一致します。 | 正規ツール名を使用してください：`Read`、`Edit`、`Write`、`Bash`、`Grep`、`Glob`、`WebFetch`、`WebSearch`、`Agent`、および `mcp__github__create_issue` のような MCP ツール名。 内容に括弧が含まれる場合はエスケープします： ```json theme={null} { "permissions": { "allow": [ "Bash(python -c \"print\\(1\\)\")" ] } } ``` `ToolName(*)` は `ToolName`（ツールレベルルール）と同等です。 ### コマンドラインでの上書き ```shell theme={null} qodercli --allowed-tools 'Read,Grep,Bash(git status)' qodercli --disallowed-tools 'Bash(rm -rf:*),mcp__github__delete_repo' qodercli --tools 'Read,Grep,Edit' ``` `--allowed-tools` と `--disallowed-tools` は settings と同じルール構文を使います。`--tools` は現在の実行で利用可能な組み込みツールセットを制限します（一覧にないツールは拒否されます）。 ## 信頼ディレクトリ Qoder は起動時のカレントワーキングディレクトリ（CWD）を**メイン信頼ディレクトリ**として扱います。信頼ディレクトリ内では： * ファイル読み取りはデフォルトで許可 * ファイル書き込みは `accept_edits` と `auto` モードで自動承認可能 * 非 default 権限モード（auto、bypass 等）が有効になる 現在のディレクトリが信頼されていない場合、Qoder は `default` モードに強制フォールバックします。 ### 信頼範囲の拡張 `--add-dir`、`/add-dir` コマンド、または `permissions.additionalDirectories` で追加の信頼済み作業ディレクトリを指定します： ```shell theme={null} qodercli --add-dir ../shared ``` ```json theme={null} { "permissions": { "additionalDirectories": ["../shared"] } } ``` グローバル settings で `permissions.trustDirectories` を設定して、よく使うディレクトリを永続的に信頼することもできます。 ### 保護パス 一部のパスは、編集すると実行動作、認証情報、ツール動作が変わる可能性があるため保護されています。例：`.git`、`.vscode`、`.idea`、`.husky`、多くの `.qoder` 設定ファイル、`.bashrc`/`.zshrc` 等の shell 起動ファイル、Git 設定、`.mcp.json`、`.ripgreprc`。通常のインタラクティブモードでは明示承認が必要で、`auto` モードでは拒否されます。 ## ファイルアクセスルール パス付き読み取りルールは `Read(...)` を使います。パス付き書き込みルールは `Edit(...)` を使い、`Edit`、`Write`、`NotebookEdit` のファイル書き込みチェックをカバーします。同じパスの `Edit(...)` allow ルールは読み取り権限も暗黙に許可します。 ファイルルールは gitignore 形式で一致します。 | パターン | 意味 | | :--------------- | :-------------------------------------------------------------------------------------- | | `/src/**` | ルールソースのルートディレクトリ基準。project/local settings ではプロジェクトルート基準、user settings では home ディレクトリ基準。 | | `~/Documents/**` | home ディレクトリ基準のパス。 | | `//tmp/data/**` | システムの `/` から始まる絶対パス。絶対パスにはダブルスラッシュを使います。 | | `*.secret` | ルートなしのファイル名パターン。任意の場所で一致可能。 | 例： ```json theme={null} { "permissions": { "allow": [ "Read(/src/**)", "Edit(/src/**)", "Read(~/Documents/specs/**)" ], "ask": [ "Edit(/package.json)", "Read(~/Downloads/**)" ], "deny": [ "Read(*.pem)", "Edit(/.git/**)", "Edit(//etc/**)" ] } } ``` ## Bash ルール `Bash(...)` ルールは完全一致コマンド、コマンド接頭辞、またはワイルドカードパターンに一致できます。 | ルール | 一致内容 | | :--------------------- | :---------------------------------------------- | | `Bash(npm run build)` | `npm run build` に完全一致。 | | `Bash(npm run test:*)` | `npm run test` および `npm run test ` で始まるコマンドに一致。 | | `Bash(git log *)` | glob 形式のワイルドカードで一致。 | | `Bash(git status)` | `git status` に完全一致。 | 例： ```json theme={null} { "permissions": { "allow": [ "Bash(git status)", "Bash(git log:*)", "Bash(npm run test:*)" ], "ask": [ "Bash(npm publish:*)", "Bash(git push:*)" ], "deny": [ "Bash(rm -rf:*)", "Bash(sudo:*)" ] } } ``` Shell の一致は保守的です： * `deny` と `ask` ルールは一般的な wrapper や環境変数プレフィックスを見通すため、`Bash(rm -rf:*)` はラップされた破壊的コマンドも捕捉できます。 * 接頭辞やワイルドカードの `allow` ルールは、各トップレベルコマンド片が独立して許可されない限り、複合コマンドを無音で承認しません。 * 一部の明確に読み取り専用と判断できる shell コマンドは、deny、ask、パスチェックの後で自動許可されます。 * 破壊的削除や force push などの危険なコマンドは、広い allow ルールがあっても確認を強制できます。`auto` モードでは危険な Shell コマンドは拒否されます。 セッションを完全に信頼する場合を除き、`Bash` や `Bash(*)` のような広いルールは避けてください。 ## Web と MCP のルール Web ツールはツールレベルのルールで制御できます。すべての web fetch で確認を求める場合は `ask`、セッションまたはプロジェクトで web access をブロックする場合は `deny` を使います。 ```json theme={null} { "permissions": { "ask": [ "WebFetch" ], "deny": [ "WebSearch" ] } } ``` MCP ツールは完全修飾名を使います： ```text theme={null} mcp____ ``` 対応する MCP パターン： | ルール | 意味 | | :-------------------------- | :------------------------- | | `mcp__github__create_issue` | 1 つの MCP ツール。 | | `mcp__github__*` | `github` MCP server の全ツール。 | | `mcp__github` | `github` MCP server の全ツール。 | | `mcp__*` | すべての MCP ツール。 | 例： ```json theme={null} { "permissions": { "allow": [ "mcp__context7__*" ], "ask": [ "mcp__github__create_issue" ] } } ``` MCP server 設定では、その server のツールに対して `alwaysAllow` も設定できます。1 回の実行で有効にする MCP server を限定したい場合は `--allowed-mcp-server-names` を使います。 ```shell theme={null} qodercli --allowed-mcp-server-names context7,github ``` ## Hook と権限 Qoder の Hook システムは権限判定パイプラインに 2 つのインジェクションポイントを持ち、カスタムスクリプトでツールの許可/拒否動作に影響を与えることができます。 ### 権限に影響する Hook イベント | Hook イベント | トリガータイミング | 権限への影響 | | | | :------------------ | :-------------------------- | :--------------------------------------------------------- | ------ | ---------------------------- | | `PreToolUse` | ツール実行前（権限チェックフェーズ） | \`permissionDecision: "allow" | "deny" | "ask"\` を返してパイプライン結果を直接上書き可能 | | `PermissionRequest` | パイプラインが `ask` を出力した後、プロンプト前 | `decision.behavior` を `allow` または `deny` として返し、ユーザー対話を代替可能 | | | その他の Hook イベント（`PostToolUse`、`SessionStart`、`Stop` 等）は権限判定に関与しません。 ### PreToolUse Hook ツール実行前にトリガーされます。Hook スクリプトはツール名とパラメータを検査し、権限判定を返すことができます： ```json theme={null} { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python ./scripts/check-bash-command.py" } ] } ] } } ``` Hook スクリプトは stdin で JSON 入力（`tool_name`、`tool_input`、`session_id` 等を含む）を受け取り、stdout で JSON 結果を出力します： ```json theme={null} { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Command blocked by security policy" } } ``` `permissionDecision` の値： * `"allow"`: 権限パイプラインをスキップし、直接承認 * `"deny"`: 権限パイプラインをスキップし、直接拒否 * `"ask"`: 通常の権限パイプラインを続行（デフォルト動作） ### PermissionRequest Hook 権限パイプラインが `ask` を出力した後、プロンプト/コールバックの前にトリガーされます。自動化承認システムや外部通知（Slack/メールアラートなど）に適しています： ```json theme={null} { "hooks": { "PermissionRequest": [ { "hooks": [ { "type": "command", "command": "node ./scripts/auto-approve-safe-ops.js" } ] } ] } } ``` 出力形式： ```json theme={null} { "hookSpecificOutput": { "hookEventName": "PermissionRequest", "decision": { "behavior": "allow", "updatedInput": {}, "updatedPermissions": [] } } } ``` ### Hook と権限モードの優先度 Hook の権限判定は権限モードよりも**高い優先度**を持ちます — `bypass_permissions` モードであっても、PreToolUse Hook が `deny` を返せば実行はブロックされます。これにより組織レベルのセキュリティポリシーに対してバイパス不可能な遮断能力を提供します。 実行順序： 1. Hook `PreToolUse` → allow/deny を返した場合ショートサーキット 2. 権限パイプライン（ルール + モード + 安全チェック） 3. 結果が `ask` の場合 → Hook `PermissionRequest` → allow/deny を返した場合ショートサーキット 4. 最終的にランタイム環境が `ask` を消費（プロンプト/拒否/コールバック）