權限請求

預設行為(`deny-all`)

當 config/copilot.php 的 permission_approve 為 "deny-all"(預設)時,Copilot::run() 與 Copilot::start() 中的權限請求會自動拒絕。以文字生成為主的用途通常不需要權限,因此這是一個安全的預設值。

// config/copilot.php
'permission_approve' => env('COPILOT_PERMISSION_APPROVE', 'deny-all'),

可設定的值

值	行為
`"deny-all"`	全部自動拒絕(預設)
`"approve-safety"`	僅拒絕 `shell` 與 `write`,其他自動核准
`"approve-all"`	全部自動核准
`false`	無處理器。`onPermissionRequest` 為必填(與官方 SDK 相同)

// .env
COPILOT_PERMISSION_APPROVE="approve-safety"

若接受使用者輸入的提示,使用 "approve-safety" 與 "approve-all" 是危險的。請務必使用 false 或 "deny-all"。即使是唯讀權限,也可能讀取 Laravel 專案的程式碼。

`PermissionHandler::approveAll()`

PermissionHandler::approveAll() 會自動核准所有請求。

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
);

$response = Copilot::run(prompt: 'Hello', config: $config);

`PermissionHandler::approveSafety()`

PermissionHandler::approveSafety() 僅拒絕高風險權限(shell, write),其他自動核准。

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveSafety(),
);

$response = Copilot::run(prompt: 'Hello', config: $config);

即便如此也未必完全安全。若要嚴格控制,請實作自訂處理器,並依據 $request['kind'] 進行判斷。

`PermissionHandler::denyAll()`

PermissionHandler::denyAll() 拒絕所有請求。

use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::denyAll(),
);

直接使用 Client 時

若直接使用 CopilotClient,與官方 SDK 一樣,必須指定 onPermissionRequest。

use Revolution\Copilot\Client;
use Revolution\Copilot\Support\PermissionHandler;

$client = new Client([
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
    'env' => null,
]);
$client->start();

// onPermissionRequest 為必填
$session = $client->createSession([
    'onPermissionRequest' => PermissionHandler::approveSafety(),
]);

// 若省略會拋出 InvalidArgumentException
// $session = $client->createSession([]); // Error!

自訂處理器

若要依請求類型個別控制核准或拒絕,請傳入 closure。 $request 與 $invocation 是如下的陣列。

use Illuminate\Support\Facades\Artisan;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionRequestResultKind;
use Revolution\Copilot\Types\SessionConfig;

use function Laravel\Prompts\{confirm, note, spin, text};

Artisan::command('copilot:chat', function () {
    $config = new SessionConfig(
        onPermissionRequest: function (array $request, array $invocation) {
            $confirm = confirm(
                label: 'Do you accept the requested permissions?',
            );
            if ($confirm) {
                return PermissionRequestResultKind::approveOnce();
            } else {
                return PermissionRequestResultKind::reject();
            }
        },
    );

    Copilot::start(function (CopilotSession $session) use ($config) {
        while (true) {
            $prompt = text(
                label: 'Enter your prompt',
                placeholder: 'Ask me anything...',
                required: true,
                hint: 'Ctrl+C to exit',
            );

            $response = spin(
                callback: fn () => $session->sendAndWait($prompt),
                message: 'Waiting for Copilot response...',
            );

            note($response->content());
        }
    }, config: $config);
});

`$request`

除了 kind 與 toolCallId 之外的欄位會隨 kind 而變化。

kind: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool" | "memory" | "hook"

[
  "kind" => "shell",
  "toolCallId" => "toolu_...",
  "fullCommandText" => "...",
  "intention" => "Run copilot:ping to test permission request",
  "commands" => [
    [
      "identifier" => "bash",
      "readOnly" => false,
    ]
  ]
  "possiblePaths" => [],
  "possibleUrls" => [],
  "hasWriteFileRedirection" => false,
  "canOfferSessionApproval" => false,
]

當 $request['managedApprovalRequired'] 為 true 時，表示依組織的 Managed Settings，此請求無法自動核准。此時 PermissionHandler::approveAll() 會回傳 no-result，交由 Copilot CLI 端的標準流程處理。

`$invocation`

[
  "sessionId" => "...",
  // 僅在較新的 CLI 執行期中選擇性包含
  "promptRequest" => [
    "kind" => "read",
    "managedApprovalRequired" => false,
  ],
]

Prompt 脈絡（`promptRequest`）

在較新的 CLI 執行期中，$invocation['promptRequest'] 可能包含面向使用者的 prompt 脈絡。自訂 handler 可依此值判斷是否需要人工回應。當以下條件全部符合時，PermissionHandler::approveAll() 會優先採用 promptRequest['managedApprovalRequired']。

promptRequest['kind'] 為 commands / read / write / url / workflow 其中之一
promptRequest['managedApprovalRequired'] 為 boolean

如此一來，即使 $request['managedApprovalRequired'] 仍保留為來自政策的標記，只要 prompt 上不需要人工回應，即可自動核准。 $request 中的原始標記仍會保留。若為沒有 promptRequest 的舊版 CLI、不支援的類型，或沒有有效的 boolean 值，則與以往相同，依 $request['managedApprovalRequired'] 判斷。

use Revolution\Copilot\Support\PermissionRequestResultKind;

onPermissionRequest: function (array $request, array $invocation) {
    $prompt = $invocation['promptRequest'] ?? null;

    if (is_array($prompt) && ($prompt['managedApprovalRequired'] ?? null) === true) {
        // 因需要人工回應，交由 CLI 端的標準流程處理
        return PermissionRequestResultKind::noResult();
    }

    return PermissionRequestResultKind::approveOnce();
},

Response

權限判斷結果以陣列回傳。使用 PermissionRequestResultKind 類別可讓程式碼更易讀。

return PermissionRequestResultKind::approveOnce();
return PermissionRequestResultKind::reject();

協定細節

在 Protocol v3(目前的預設)中,權限請求並非以 JSON-RPC 請求形式,而是以 Session Event(permission.requested)形式傳遞。 SDK 會在內部處理此事件,並透過 session.permissions.handlePendingPermissionRequest RPC 回應。 SessionConfig 的使用方式並未改變。 只要在 onPermissionRequest 傳入處理器,協定差異即由 SDK 吸收處理。

PermissionRequestResultKind

雖然也可以直接回傳 ['kind' => 'approve-once'] 這樣的格式,但使用 PermissionRequestResultKind 會更清楚。

use Revolution\Copilot\Support\PermissionRequestResultKind;

$confirm = confirm(
    label: 'Do you accept the requested permissions?',
);

if ($confirm) {
    return PermissionRequestResultKind::approveOnce();
} else {
    return PermissionRequestResultKind::reject();
}

可用方法

方法	值	說明
`approveOnce()`	`approve-once`	僅本次請求核准
`approveForSession()`	`approve-for-session`	於此 Session 期間核准所有同類請求
`approveForLocation()`	`approve-for-location`	核准來自此位置(檔案路徑等)的所有同類請求
`reject()`	`reject`	拒絕請求
`userNotAvailable()`	`user-not-available`	使用者無法回應的狀態(非互動式環境等)
`noResult()`	`no-result`	處理器無法傳回結果時(略過 RPC 呼叫)

若想使用 Laravel\Prompts\select,可透過 PermissionRequestResultKind::select() 取得選項清單。

use Revolution\Copilot\Support\PermissionRequestResultKind;
use function Laravel\Prompts\select;

$select = select(
    label: 'Do you accept the requested permissions?',
    options: PermissionRequestResultKind::select(),
);

return ['kind' => $select];

no-result

當處理器無法傳回結果時(例如非互動式環境),可回傳 no-result。回傳 no-result 會略過 RPC 呼叫,並套用 Copilot CLI 端的預設拒絕行為。

return PermissionRequestResultKind::noResult();
// 或 ['kind' => 'no-result']

最新資訊請參閱 GitHub 儲存庫。

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

權限請求

權限請求

預設行為(`deny-all`)

可設定的值

`PermissionHandler::approveAll()`

`PermissionHandler::approveSafety()`

`PermissionHandler::denyAll()`

直接使用 Client 時

自訂處理器

`$request`

`$invocation`

Prompt 脈絡（`promptRequest`）

Response

協定細節

PermissionRequestResultKind

可用方法

no-result

​權限請求

​預設行為(deny-all)

​可設定的值

​PermissionHandler::approveAll()

​PermissionHandler::approveSafety()

​PermissionHandler::denyAll()

​直接使用 Client 時

​自訂處理器

​$request

​$invocation

​Prompt 脈絡（promptRequest）

​Response

​協定細節

​PermissionRequestResultKind

​可用方法

​no-result

權限請求

預設行為(`deny-all`)

可設定的值

`PermissionHandler::approveAll()`

`PermissionHandler::approveSafety()`

`PermissionHandler::denyAll()`

直接使用 Client 時

自訂處理器

`$request`

`$invocation`

Prompt 脈絡（`promptRequest`）

Response

協定細節

PermissionRequestResultKind

可用方法

no-result