SessionConfig

You can configure many behaviors with the SessionConfig class. Use it with Copilot::run(prompt: '...', config: $config) or Copilot::start(function (CopilotSession $session) { ... }, config: $config). If you only need simple options like a model ID, you can pass an array instead of using SessionConfig: Copilot::run(prompt: '...', config: ['model' => 'auto']).

use Revolution\Copilot\Enums\ReasoningEffort;
use Revolution\Copilot\Enums\UIAutoModeSwitchResponse;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\AutoModeSwitchRequest;
use Revolution\Copilot\Types\ElicitationContext;
use Revolution\Copilot\Types\ExitPlanModeRequest;
use Revolution\Copilot\Types\ExitPlanModeResult;
use Revolution\Copilot\Types\InfiniteSessionConfig;
use Revolution\Copilot\Types\McpAuthRequest;
use Revolution\Copilot\Types\McpAuthToken;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverride;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideLimits;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideSupports;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;
use Revolution\Copilot\Types\SystemMessageConfig;
use Revolution\Copilot\Types\UserInputRequest;

$config = new SessionConfig(
    // Model to use
    model: 'auto',

    // Fixed session ID when creating a new session
    sessionId: 'session-123',

    // Name for a new local session (the runtime rejects it when combined with cloud).
    // Named sessions are persisted immediately, so you can list and resume them before any turn runs.
    // Must not be empty, have leading or trailing whitespace, control characters, or double quotes.
    // Maximum 100 UTF-16 code units.
    name: 'issue-triage',

    clientName: 'my-app',

    // Mark this as a human-driven session to enable user message analytics telemetry (SDK default: false).
    // Automated messages are excluded. Ignored for cloud sessions and when resuming a running session.
    interactiveUser: true,

    // Reasoning level (only for supported models)
    reasoningEffort: ReasoningEffort::HIGH,

    // Override model capabilities. Deep-merged with runtime defaults.
    // modelCapabilities: new ModelCapabilitiesOverride(
    //     supports: new ModelCapabilitiesOverrideSupports(vision: true, reasoningEffort: true),
    //     limits: new ModelCapabilitiesOverrideLimits(max_prompt_tokens: 200000),
    // ),
    // Array format is also supported
    // modelCapabilities: ['supports' => ['vision' => true]],

    // Override config directory
    configDirectory: '',

    // Enable auto-discovery of MCP settings and skill directories
    // Auto-detects .mcp.json and .vscode/mcp.json from the working directory,
    // then merges them with explicitly provided mcpServers and skillDirectories.
    // Explicit values win on name conflicts.
    enableConfigDiscovery: true,

    // Custom tools
    tools: [...],

    // System message
    systemMessage: new SystemMessageConfig(
        content: 'You are a helpful assistant for Laravel developers.',
    ),

    // Replace mode (fully replace the system prompt)
    // systemMessage: new SystemMessageConfig(
    //     mode: 'replace',
    //     content: 'Entire custom system prompt',
    // ),

    // Customize mode (override by section)
    // systemMessage: new SystemMessageConfig(
    //     mode: 'customize',
    //     sections: [
    //         'tone' => new SectionOverride(action: SectionOverrideAction::REPLACE, content: 'Always respond in Japanese.'),
    //         'safety' => new SectionOverride(action: SectionOverrideAction::REMOVE),
    //         'custom_instructions' => new SectionOverride(action: SectionOverrideAction::APPEND, content: 'Additional instructions here.'),
    //     ],
    //     content: 'Optional extra content like append mode',
    // ),

    // Custom provider
    provider: new ProviderConfig(),

    // Per-session GitHub token (multi-tenant support)
    // Specifies a token per session, separate from the client-level github_token
    gitHubToken: $user->github_token,

    onPermissionRequest: function (array $request) {
        // Handle permission requests
    },

    onUserInputRequest: function (UserInputRequest $request) {
        // Handle user input requests (ask_user)
    },

    // Elicitation request handler
    // Lets you receive form-based UI dialog requests from the agent
    onElicitationRequest: function (ElicitationContext $context) {
        // Handle elicitation request
        return ['action' => 'accept', 'content' => ['field' => 'value']];
    },

    // Supply a token from the host when an MCP server requests OAuth authentication
    onMcpAuthRequest: function (McpAuthRequest $request, array $context): ?McpAuthToken {
        $accessToken = $credentialProvider->tokenFor($request->serverName);

        return $accessToken === null
            ? null
            : new McpAuthToken(accessToken: $accessToken, tokenType: 'Bearer');
    },

    // Exit plan mode request handler
    // When set, the SDK answers over reverse RPC. When omitted, requests are approved automatically.
    onExitPlanModeRequest: function (ExitPlanModeRequest $request) {
        // Review the plan, then approve or reject it
        return new ExitPlanModeResult(approved: true, selectedAction: $request->recommendedAction);
    },

    // Auto mode switch request handler
    // Decide whether to switch to auto mode when a rate limit is reached. Defaults to "no" when omitted.
    onAutoModeSwitchRequest: function (AutoModeSwitchRequest $request) {
        // Return "yes", "yes_always", "no", or a UIAutoModeSwitchResponse case
        return UIAutoModeSwitchResponse::Yes;
    },

    // Session hooks
    hooks: [],

    // Working directory
    workingDirectory: '',

    // Enable streaming
    streaming: true,

    // Whether to include sub-agent streaming events in the main stream (default: true)
    includeSubAgentStreamingEvents: true,

    // Allowed built-in tools
    availableTools: ['read_file', 'write_file'],

    // Or excluded tools
    excludedTools: ['shell'],

    // MCP server configuration
    mcpServers: [
        'github' => [
            'type' => 'http',
            'url' => 'https://api.githubcopilot.com/mcp/',
        ],
    ],

    // Custom agents
    customAgents: [
        [
            'name' => 'reviewer',
            'displayName' => 'Code Reviewer',
            'description' => 'Reviews code for best practices',
            'prompt' => 'You are an expert code reviewer.',
        ],
    ],

    // Default agent configuration. Applied to the built-in agent when no custom agent is selected.
    // excludedTools: list of tools to exclude from the default agent.
    // Custom sub-agents can still use excluded tools.
    defaultAgent: ['excludedTools' => ['tool_name']],

    // Agent activated at session start. Must match customAgents.name.
    agent: 'reviewer',

    // Explicit discovery roots for skills, agents, hooks, and instruction files
    skillDirectories: [],
    agentDirectories: [],
    hookDirectories: [],
    instructionDirectories: [],

    // Request the read-only GitHub cache store
    enableGitHubCacheStore: true,

    // Disabled skills
    disabledSkills: [],

    // Infinite session configuration (enabled by default)
    infiniteSessions: new InfiniteSessionConfig(
        enabled: true,
        backgroundCompactionThreshold: 0.80, // Start compaction at 80% context usage
        bufferExhaustionThreshold: 0.95,     // Block at 95% until compaction finishes
    ),

    // Disable infinite sessions
    // infiniteSessions: new InfiniteSessionConfig(enabled: false),

    // Register event handlers before the session creation RPC.
    // Use this to avoid missing early events such as session.start.
    // Equivalent to calling $session->on($handler) later, but earlier in the lifecycle.
    onEvent: function (SessionEvent $event) {
        // Receive all session events
    },
);

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

Discovery roots

skillDirectories, agentDirectories, hookDirectories, and instructionDirectories are discovery-only roots for skills, custom agents, file hooks, and custom instructions. They do not grant the agent general file access. To add regular file access locations, use additionalDirectories. You can set discovery roots whether or not enableConfigDiscovery is enabled. The SDK resolves relative paths once, against the effective workingDirectory at the time you set them. The roots do not move if the working directory changes later. Omitting a key or passing null leaves the default discovery sources unchanged. Passing [] clears only the roots the SDK set explicitly. Per-source disable settings and Managed Settings for skills, agents, hooks, and instructions still apply. When resuming a session, use ResumeSessionConfig. It is almost the same as SessionConfig, but has small differences. In ResumeSessionConfig, specify only the options you want to change. All other settings are inherited from the original session start. The SDK sends the same session options in both the create and resume RPC payloads. This includes BYOK providers and models, memory, enableMcpApps, interactiveUser, enableGitHubCacheStore, discovery roots, and handlers such as onMcpAuthRequest, onExitPlanModeRequest, and onAutoModeSwitchRequest. When resuming, pass them in ResumeSessionConfig or in an array with the same keys. Closures and provider objects are not persisted, so supply them again on every resume.

Canvas providers

Canvas support is experimental.

Declare canvases with canvases and handle open and action requests with a canvasHandler. The runtime calls your handler over reverse RPC when the agent opens a canvas or invokes one of its actions. Set requestCanvasRenderer: true to opt in as a renderer, so the runtime exposes canvas agent tools to the model for this connection. It is off by default so SDK callers that cannot display canvases stay clean.

use Revolution\Copilot\Support\CanvasError;
use Revolution\Copilot\Support\CanvasHandler;
use Revolution\Copilot\Types\CanvasDeclaration;
use Revolution\Copilot\Types\Rpc\CanvasAction;
use Revolution\Copilot\Types\Rpc\CanvasProviderInvokeActionRequest;
use Revolution\Copilot\Types\Rpc\CanvasProviderOpenRequest;
use Revolution\Copilot\Types\Rpc\CanvasProviderOpenResult;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    canvases: [
        new CanvasDeclaration(
            id: 'editor',
            displayName: 'Editor',
            description: 'Opens and edits project files.',
            actions: [
                new CanvasAction(name: 'format', description: 'Format the open file.'),
            ],
        ),
    ],
    canvasHandler: new class extends CanvasHandler
    {
        public function open(CanvasProviderOpenRequest $request): CanvasProviderOpenResult|array
        {
            return new CanvasProviderOpenResult(
                url: 'https://app.example.test/canvas/'.$request->instanceId,
                title: 'Project editor',
            );
        }

        public function invoke(CanvasProviderInvokeActionRequest $request): mixed
        {
            if ($request->actionName !== 'format') {
                throw CanvasError::noHandler();
            }

            return ['formatted' => true];
        }
    },
    requestCanvasRenderer: true,
);

Related options:

requestExtensions: true opts in to the extension surface. The runtime then wires extension management tools into sessions on this connection. Off by default.
extensionInfo: new ExtensionInfo(source: 'github-app', name: 'my-extension') sets a stable extension ID for canvas providers on this connection. The runtime uses ${source}:${name} instead of the per-connection ID. You can also pass an array.

When resuming, pass canvases and canvasHandler again. The canvasHandler runs only inside the PHP process. The SDK sends only the declaration metadata in the RPC payload. ResumeSessionConfig also accepts openCanvases, a snapshot of the canvases that were open when the session stopped. The runtime uses it to rehydrate canvas state, so you do not need to reopen them. Get the current open canvases with $session->openCanvases(). The SDK keeps this list in sync with session.canvas.opened and session.canvas.closed events.

Session filesystem providers

Skill and filesystem callbacks

Use skillProvider to load skills from an application-owned source. The callbacks belong to that session and are not serialized to the Copilot runtime. Cloud sessions do not support custom skill providers.

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

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    skillProvider: [
        'listSkills' => fn (SkillProviderCallOptions $options) => [
            ['name' => 'deployment', 'description' => 'Safe application deployments'],
        ],
        'readSkill' => fn (string $name, SkillProviderCallOptions $options) =>
            $name === 'deployment' ? '# Deployment checklist' : null,
    ],
);

SkillProviderCallOptions::$signal exposes the callback’s cancellation token. Cancellation is cooperative. Your callbacks should observe the signal and cancel pending work themselves. You can implement Revolution\Copilot\Contracts\SkillProvider instead of using the callback array. sessionFsProvider uses the same session-scoped configuration. The text callbacks are readFile(path) and writeFile(path, content, mode). To support binary files, provide both readFileBytes(path) and writeFileBytes(path, bytes, mode), or implement SessionFsBinaryProvider. These callbacks receive and return the original bytes. The SDK handles base64 encoding on the JSON-RPC wire. Keep filesystem access scoped to the paths your application intends to expose.

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

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    sessionFsProvider: [
        'readFile' => fn (string $path) => Storage::disk('local')->get($path),
        'writeFile' => fn (string $path, string $content, ?int $mode = null) =>
            Storage::disk('local')->put($path, $content),
        'readFileBytes' => fn (string $path) => Storage::disk('local')->get($path),
        'writeFileBytes' => fn (string $path, string $bytes, ?int $mode = null) =>
            Storage::disk('local')->put($path, $bytes),
    ],
);

Delegate all session state with `sessionFs`

Set the client option sessionFs (alias session_fs) to move the whole Copilot CLI session state, including session-state files and the per-session SQLite database, into your own storage. When you set it, every session config must provide a createSessionFsProvider factory. The SDK calls the factory for both createSession() and resumeSession(), after the session ID is known and before the request is sent to the runtime.

use Revolution\Copilot\Client;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$client = new Client(['sessionFs' => [
    'initialCwd' => '/workspace',
    'sessionStatePath' => '/session-state',
    'conventions' => 'posix', // or windows
    'capabilities' => ['sqlite' => true, 'binary' => true], // optional
]]);

$session = $client->createSession(new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    createSessionFsProvider: fn (CopilotSession $session) => new MySessionFsProvider($session->id()),
));

With the Copilot facade, set session_fs in config/copilot.php. initialCwd, sessionStatePath, and conventions (posix or windows) are required. Missing fields or an invalid conventions value throw an InvalidArgumentException. createSessionFsProvider is a Closure. It also works with arrays, fromArray(), and toArray() on SessionConfig and ResumeSessionConfig. The provider it returns can be an object or an array of callables. Each optional capability has its own interface:

Interface	Adds
`SessionFsProvider`	`readFile`, `writeFile`
`SessionFsBinaryProvider`	`readFileBytes`, `writeFileBytes` (required by `capabilities.binary`)
`SessionFsFilesystemProvider`	`appendFile`, `exists`, `stat`, `mkdir`, `readdir`, `readdirWithTypes`, `rm`, `rename`
`SessionFsSqliteCapableProvider`	`sqlite()` returning a `SessionFsSqliteProvider` (`query`, `exists`). Required by `capabilities.sqlite`
`SessionFsSqliteTransactionProvider`	`transaction()` on the SQLite provider

If the provider does not meet the declared capabilities, the SDK throws an InvalidArgumentException. Calling an operation the provider does not support returns an UNKNOWN error. Providers signal failures by throwing. An exception whose code is ENOENT (or errno 2) becomes ENOENT. Anything else becomes UNKNOWN. Throw SessionFsSqliteTransactionFailure from transaction() to report an errorClass (busyOrLocked, fatal, or postCommitAmbiguous). Without the client sessionFs option, the SDK never calls createSessionFsProvider, and the existing sessionFsProvider (readFile and writeFile) keeps working.

Empty mode for multi-tenant apps

Set the client mode to empty to disable, by default, features that depend on the Copilot CLI host environment or on cross-session state. The default is copilot-cli, which keeps the existing behavior. In empty mode, you must set one persistence target: base_directory, session_fs, or an external server url.

// config/copilot.php
'mode' => env('COPILOT_MODE', 'copilot-cli'),
'base_directory' => storage_path('app/copilot'),

Every session in empty mode must set availableTools. Use ToolSet to build source-qualified tool filters (builtin:, custom:, mcp:). BuiltInTools::Isolated allows only built-in tools confined to a single session, with no host filesystem, environment, network, or cross-session access.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\BuiltInTools;
use Revolution\Copilot\Support\ToolSet;

$response = Copilot::run(
    prompt: 'Summarize this text.',
    config: [
        'availableTools' => (new ToolSet)
            ->addBuiltIn(BuiltInTools::Isolated)
            ->addCustom('lookup_order')
            ->addMcp('search'),
    ],
);

Tool names must match /^[a-zA-Z0-9_-]+$/ or be the wildcard *. Otherwise ToolSet throws an InvalidArgumentException. Empty mode applies safe defaults to session telemetry, persistent MCP OAuth token storage, embedding retrieval and cache, instruction discovery, file hooks, host git operations, the session store, the GitHub cache store, skills, memory, and experimental mode. Session options you set explicitly take precedence over these defaults. systemMessage in replace mode is used as is. Other modes remove the environment_context section. The SDK also sets COPILOT_DISABLE_KEYTAR=1 for the CLI process.

GitHub cache store

Set enableGitHubCacheStore: true to request the read-only GitHub cache store. The CLI registers the github_sql tool only when its GITHUB_CACHE_STORE feature flag is enabled.

$config = new SessionConfig(enableGitHubCacheStore: true);

For cloud execution, see Cloud Sessions; for plugin directories, see Plugin Directories.

For the latest updates, see the GitHub repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

SessionConfig

SessionConfig

Discovery roots

Canvas providers

Session filesystem providers

Skill and filesystem callbacks

Delegate all session state with `sessionFs`

Empty mode for multi-tenant apps

GitHub cache store

​SessionConfig

​Discovery roots

​Canvas providers

​Session filesystem providers

​Skill and filesystem callbacks

​Delegate all session state with sessionFs

​Empty mode for multi-tenant apps

​GitHub cache store

SessionConfig

Discovery roots

Canvas providers

Session filesystem providers

Skill and filesystem callbacks

Delegate all session state with `sessionFs`

Empty mode for multi-tenant apps

GitHub cache store