権限モード
権限モードは Qoder がツール呼び出しをどのように処理するかを決定します。各モードは「自動化の度合い」と「セキュリティの緩さ」の 2 軸で異なる位置づけになります。
| モード | 適用シナリオ | 動作 |
|---|---|---|
default | 通常のインタラクティブ利用 | 安全な読み取りと内部アクションは自動実行。センシティブな操作は確認を要求します。 |
accept_edits | 日常的なコーディング | 作業ディレクトリ内の安全なファイル編集を自動承認。Shell コマンド、外部アクション、センシティブなパスは通常のチェックを通ります。 |
auto | 無人実行 | 認可はエージェントが判断します。 |
bypass_permissions (YOLO) | 信頼できるローカル実験のみ | 承認プロンプトをスキップします。一部のパス形状に対する保護は有効なままです(「パス形状」を参照)。 |
dont_ask | プロンプト不可の headless フロー | 確認しません。本来確認が必要な操作はすべて拒否されます。 |
モードサイクル切り替え
インタラクティブセッションでは、Shift+Tab ですべての権限モード間を循環切り替えできます。Ctrl+Y で YOLO モードに直接ジャンプできます。
起動パラメータ
--permission-mode で現在のセッションのデフォルト動作を選択します:
| 標準値 (snake_case) | camelCase | エイリアス |
|---|---|---|
accept_edits | acceptEdits | — |
bypass_permissions | bypassPermissions | yolo, YOLO |
dont_ask | dontAsk | — |
default にフォールバックします。
権限の判定方法
Qoder は各ツール呼び出しの前に権限チェックを行います。結果は常に 3 つのうちいずれかです:
allow: ツールを即座に実行します。ask: 外部の確認が得られてから実行します。deny: ツール呼び出しをブロックします。
判定順序
Qoder は固定順で権限を評価します:
- まず
denyルールを確認 — 一致すれば即座に拒否。 - ツール自身の安全チェック(危険コマンド検出、センシティブパス検出など)。
askルール — 一致すれば確認が必要とマークします。- ツールレベルの
allowルールとモード由来の自動許可動作。 - 最終結果がまだ
askの場合、ランタイム環境が消費方法を決定します。
異なる実行環境での ask の消費方法
| 実行環境 | ask の行き先 | 説明 |
|---|---|---|
| TUI(インタラクティブターミナル) | 確認プロンプト | ユーザーがターミナルで許可/拒否を選択します。 |
Headless(-p/--prompt) | 自動拒否 | 人の対話がないため、ask は deny になります。 |
| SDK(stdio プロトコル) | ホストに canUseTool コールバックを送信 | ホストプログラムが allow/deny を決定します。 |
| ACP(IDE 統合) | IDE に requestPermission RPC を送信 | IDE がプロンプト表示または自動決定します。 |
-p/--prompt)は権限モードと組み合わせ可能です:
権限設定
設定ソース(8 層優先度)
ルールは複数のソースからマージされ、優先度が低い順に:
| 層 | ソース | 説明 |
|---|---|---|
| 1 | userSettings | ~/.qoder/settings.json(ユーザーグローバル) |
| 2 | projectSettings | <project>/.qoder/settings.json(プロジェクトレベル、チーム共有) |
| 3 | localSettings | <project>/.qoder/settings.local.json(マシンローカル、.gitignore に追加) |
| 4 | flagSettings | --settings <path> 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):
qoder --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 を設定:
| 値 | 動作 | エイリアス |
|---|---|---|
default | 每回承認を求める | — |
accept_edits | ファイル編集を自動承認、Shell コマンドは確認が必要 | acceptEdits |
plan | 読み取り専用モード(旧バージョン互換:default + Plan ワークステートに変換) | — |
auto | 認可はエージェントが判断 | — |
bypass_permissions | 権限プロンプトをスキップ(YOLO) | yolo、bypassPermissions |
dont_ask | 非対話モード、承認が必要な操作は拒否 | dontAsk |
--yolo、--permission-mode bypass_permissions、Ctrl+Y はすべて無効になり、Shift+Tab サイクルもこのモードをスキップします。Sub-agent が bypass を宣言した場合も acceptEdits に降格されます。
Plan モードの無効化 — Plan ワークフローが不要な場合:
/plan コマンドは使用不可になり、--permission-mode plan は default にフォールバックし、EnterPlanMode/ExitPlanMode ツールは登録されません。
Auto モード分類器設定 — 自然言語ルールで AI 分類器の判断傾向をガイドできます:
| フィールド | 目的 |
|---|---|
allow | 分類器が自動承認に傾く操作の説明 |
soft_deny | 分類器が拒否に傾く操作の説明 |
environment | 分類器に提供する環境コンテキスト情報 |
autoMode 設定はあなた自身のグローバル settings からのみ読み取られます。ワークスペース配下のファイルは settings.local.json を含めて無視されます:ワークスペース内のファイルはチェックアウトと共に持ち込まれる可能性があり、分類器に allow エントリを追加できるリポジトリは auto モードを承認寄りに傾けられるためです。
ユーザーレベルの AGENTS.md も分類器のコンテキストに注入され、当該セッションの意図を判断する根拠として扱われます。読み取られるのはユーザーレベルのファイルのみです。その内容は意図を示すものであり、承認を与えるものではありません:安全ルールに反する操作は、当該ファイルが認めているように見えてもブロックされます。
分類器を経由せずに裁定される操作
- 読み取り専用ツール(ファイル読み取り、検索、glob)はツール名で承認されます。対象パスは評価されないため、ワークスペース外のパスも承認されます。
- ワークスペース内、および
/add-dirで追加したディレクトリ内の書き込みと編集は、直接承認されます。 - それ以外の操作はすべて分類器に提出されます。上記ディレクトリ外への書き込みも含みます。
auto モードでは、ツール呼び出しの認可はエージェントが判断し、個別の確認は行いません。ブロック判定が連続して上限に達するとサーキットブレーカーが作動します:次の操作は認可ダイアログに切り替わり、上限の警告と直近のブロック理由が示されます。モード自体は引き続き利用でき、一度承認されるとカウントは 0 に戻ります。
auto モードで権限判定が認可ダイアログを生じさせるのは、このサーキットブレーカーのみです。分類器に到達できない、または有効な判定が返らない場合、当該操作はダイアログではなく拒否として扱われます。メッセージにはこれが操作に対する安全判定ではないことが示され、同じ操作を再試行できます。読み取り専用ツールは影響を受けません。利用可能な分類器モデルがない場合は auto モードへの切り替えを拒否します。
なお、ユーザー入力を必要とするツール(AskUserQuestion など)と Plan の開始・終了は常に確認を求めます。セッションが長くなり分類器が全体のコンテキストを読み取れない場合も確認に切り替わります。これらはいずれも権限判定の結果ではありません。
権限ルール設定
ルールは allow、ask、deny に分類されます:
ルール構文
| 形式 | 意味 |
|---|---|
ToolName | ツール全体に適用します。 |
ToolName(content) | 特定のパス、コマンド、agent type、またはそのツール固有の値に適用します。 |
* | すべてのツールに一致します。 |
Read、Edit、Write、Bash、Grep、Glob、WebFetch、WebSearch、Agent、および mcp__github__create_issue のような MCP ツール名。
内容に括弧が含まれる場合はエスケープします:
ToolName(*) は ToolName(ツールレベルルール)と同等です。
コマンドラインでの上書き
--allowed-tools と --disallowed-tools は settings と同じルール構文を使います。--tools は現在の実行で利用可能な組み込みツールセットを制限します(一覧にないツールは拒否されます)。
信頼ディレクトリ
Qoder は起動時のカレントワーキングディレクトリ(CWD)をメイン信頼ディレクトリとして扱います。信頼ディレクトリ内では:
- ファイル読み取りはデフォルトで許可
- ファイル書き込みは
accept_editsとautoモードで自動承認可能 - 非 default 権限モード(auto、bypass 等)が有効になる
default モードに強制フォールバックします。
信頼範囲の拡張
--add-dir、/add-dir コマンド、または permissions.additionalDirectories で追加の信頼済み作業ディレクトリを指定します:
permissions.trustDirectories を設定して、よく使うディレクトリを永続的に信頼することもできます。
保護パス
一部のパスは、編集すると実行動作、認証情報、ツール動作が変わる可能性があるため保護されています。例:.git、.vscode、.idea、.husky、多くの .qoder 設定ファイル、.bashrc/.zshrc 等の shell 起動ファイル、Git 設定、.mcp.json、.ripgreprc。通常のインタラクティブモードでは明示的な承認が必要です。
パス形状
一部のパス表記は、ローカルファイルシステム外のリソースに到達したり、パス比較を回避したりします。これらはルールとは別に、2 つの独立した軸で扱われます。
- ネットワーク上の場所 —— 区切り文字 2 つで始まるパス(
\server\share、//server/share)、拡張 UNC 形式(\?\UNC\server\share)、WebDAV 表記、および/net/<host>/…オートマウントパス。読み取り・検索・書き込み・Shell アクセスはいずれも拒否されます。 - ローカルマウント ——
\wsl$\…、\wsl.localhost\…、\?\C:\…、\?\Volume{…}\…はローカルストレージを指し、通常のルールに従います。\127.0.0.1\shareのようなループバックホストはネットワーク上の場所として扱われます。 - 回避されやすい表記 —— 代替データストリーム(
file.txt:stream)、8.3 短縮名(PROGRA~1)、デバイスパス(\.\…)、末尾のドットや空白、3 つ以上連続するドット、予約デバイス名(CON、NUL、COM1)には明示的な承認が必要です。
ファイルアクセスルール
パス付き読み取りルールは Read(...) を使います。パス付き書き込みルールは Edit(...) を使い、Edit、Write、NotebookEdit のファイル書き込みチェックをカバーします。同じパスの Edit(...) allow ルールは読み取り権限も暗黙に許可します。
ファイルルールは gitignore 形式で一致します。
| パターン | 意味 |
|---|---|
/src/** | ルールソースのルートディレクトリ基準。project/local settings ではプロジェクトルート基準、user settings では home ディレクトリ基準。 |
~/Documents/** | home ディレクトリ基準のパス。 |
//tmp/data/** | システムの / から始まる絶対パス。絶対パスにはダブルスラッシュを使います。ルールパターンの先頭の // は「ファイルシステムのルートからの絶対パス」を意味し、上記のネットワーク上の場所の扱いとは無関係です。 |
*.secret | ルートなしのファイル名パターン。任意の場所で一致可能。 |
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 に完全一致。 |
denyとaskルールは一般的な wrapper や環境変数プレフィックスを見通すため、Bash(rm -rf:*)はラップされた破壊的コマンドも捕捉できます。- 接頭辞やワイルドカードの
allowルールは、各トップレベルコマンド片が独立して許可されない限り、複合コマンドを無音で承認しません。 - 一部の明確に読み取り専用と判断できる shell コマンドは、deny、ask、パスチェックの後で自動許可されます。
- 破壊的削除や force push などの危険なコマンドは、広い allow ルールがあっても確認を強制できます。
Bash や Bash(*) のような広いルールは避けてください。
Web と MCP のルール
Web ツールはツールレベルのルールで制御できます。すべての web fetch で確認を求める場合は ask、セッションまたはプロジェクトで web access をブロックする場合は deny を使います。
| ルール | 意味 |
|---|---|
mcp__github__create_issue | 1 つの MCP ツール。 |
mcp__github__* | github MCP server の全ツール。 |
mcp__github | github MCP server の全ツール。 |
mcp__* | すべての MCP ツール。 |
alwaysAllow も設定できます。1 回の実行で有効にする MCP server を限定したい場合は --allowed-mcp-server-names を使います。
Hook と権限
Qoder の Hook システムは権限判定パイプラインに 2 つのインジェクションポイントを持ち、カスタムスクリプトでツールの許可/拒否動作に影響を与えることができます。
権限に影響する Hook イベント
| Hook イベント | トリガータイミング | 権限への影響 |
|---|---|---|
PreToolUse | ツール実行前(権限チェックフェーズ) | `permissionDecision: "allow" |
PermissionRequest | パイプラインが ask を出力した後、プロンプト前 | decision.behavior を allow または deny として返し、ユーザー対話を代替可能 |
PostToolUse、SessionStart、Stop 等)は権限判定に関与しません。
PreToolUse Hook
ツール実行前にトリガーされます。Hook スクリプトはツール名とパラメータを検査し、権限判定を返すことができます:
tool_name、tool_input、session_id 等を含む)を受け取り、stdout で JSON 結果を出力します:
permissionDecision の値:
"allow": 権限パイプラインをスキップし、直接承認"deny": 権限パイプラインをスキップし、直接拒否"ask": 通常の権限パイプラインを続行(デフォルト動作)
PermissionRequest Hook
権限パイプラインが ask を出力した後、プロンプト/コールバックの前にトリガーされます。自動化承認システムや外部通知(Slack/メールアラートなど)に適しています:
Hook と権限モードの優先度
Hook の権限判定は権限モードよりも高い優先度を持ちます — bypass_permissions モードであっても、PreToolUse Hook が deny を返せば実行はブロックされます。これにより組織レベルのセキュリティポリシーに対してバイパス不可能な遮断能力を提供します。
実行順序:
- Hook
PreToolUse→ allow/deny を返した場合ショートサーキット - 権限パイプライン(ルール + モード + 安全チェック)
- 結果が
askの場合 → HookPermissionRequest→ allow/deny を返した場合ショートサーキット - 最終的にランタイム環境が
askを消費(プロンプト/拒否/コールバック)