> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# SessionConfig

> Configure Laravel Copilot SDK sessions with SessionConfig, including tools, MCP, hooks, agents, and lifecycle event handlers.

## 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'])`.

```php theme={null}
use Revolution\Copilot\Enums\ReasoningEffort;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ElicitationContext;
use Revolution\Copilot\Types\InfiniteSessionConfig;
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',

    clientName: 'my-app',

    // 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']];
    },

    // 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',

    // Skill directories
    skillDirectories: [],

    // 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);
```

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.

For cloud execution, see [Cloud Sessions](/en/packages/laravel-copilot-sdk/cloud-sessions); for plugin directories, see [Plugin Directories](/en/packages/laravel-copilot-sdk/plugin-directories).

<Info>
  For the latest updates, see the [GitHub repository](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Session](/en/session.md)
- [Upgrade guide: Laravel 12 to 13](/en/blog/upgrade-12-to-13.md)
- [Resume session](/en/packages/laravel-copilot-sdk/resume.md)
- [Cloud Sessions](/en/packages/laravel-copilot-sdk/cloud-sessions.md)
- [Streaming events](/en/packages/laravel-copilot-sdk/streaming-events.md)