Session hooks

With hooks, you can insert logic at each stage of a Copilot session lifecycle. You can add tool execution control, audit logging, prompt enrichment, and error handling without changing core implementation. This is separate from the declarative hooks in custom agent definitions and from file-based hook loading. For per-agent configuration, see Custom agents.

File-based hook discovery

hookDirectories lets you specify explicit roots for discovering file-based hooks. This is for discovery only and does not grant the agent general file access permissions. Explicit roots remain available even when enableConfigDiscovery or enableFileHooks is disabled. Relative paths are resolved once, against the effective workingDirectory at the time they are specified.

Omitted or null: other discovery sources are left unchanged
[]: clears only the explicit SDK roots

Hook source disable settings and Managed Settings still apply. enableFileHooks controls repository-sourced file hooks (.github/hooks/ and roots from trusted repository settings). It does not disable explicit hookDirectories or PHP callback hooks.

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    workingDirectory: '/workspace/project',
    enableFileHooks: false,
    hookDirectories: ['../shared-hooks'],
);

Hook flow

Basic usage

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionHooks;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookInput;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookOutput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\SessionEndHookInput;
use Revolution\Copilot\Types\Hooks\SessionEndHookOutput;
use Revolution\Copilot\Types\Hooks\SessionStartHookInput;
use Revolution\Copilot\Types\Hooks\SessionStartHookOutput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookInput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookOutput;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: 'Summarize the key points of this README');
    dump($response->content());
}, config: [
    'model' => 'gpt-5',
    'hooks' => new SessionHooks(
        onSessionStart: function (SessionStartHookInput $input): ?SessionStartHookOutput {
            return new SessionStartHookOutput(
                additionalContext: "Project root: {$input->cwd}",
            );
        },

        onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
            if (str_starts_with($input->prompt, '/fix')) {
                return new UserPromptSubmittedHookOutput(
                    modifiedPrompt: 'Fix the current error and summarize what changed.',
                );
            }

            return null;
        },

        onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
            $blocked = ['bash', 'shell', 'delete_file'];

            if (in_array($input->toolName, $blocked, true)) {
                return new PreToolUseHookOutput(
                    permissionDecision: 'deny',
                    permissionDecisionReason: "{$input->toolName} is not allowed in this environment",
                );
            }

            return new PreToolUseHookOutput(permissionDecision: 'allow');
        },

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: 'If needed, explore related files and compare them.',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: 'Retrying due to a temporary model error.',
                );
            }

            return null;
        },

        onSessionEnd: function (SessionEndHookInput $input): ?SessionEndHookOutput {
            if ($input->reason !== 'complete') {
                return new SessionEndHookOutput(
                    sessionSummary: "Session ended with reason: {$input->reason}",
                );
            }

            return null;
        },
    ),
]);

Available hooks

Hook	Trigger timing	Primary use
`onSessionStart`	Session start (`new` / `resume` / `startup`)	Inject initial context, override config
`onUserPromptSubmitted`	User prompt submission	Prompt enrichment, template expansion, input filtering
`onPreToolUse`	Before tool execution	Allow/deny/ask, modify args, suppress output
`onPostToolUse`	After tool execution	Modify result, mask secrets, audit logging
`onErrorOccurred`	Error inside session	Retry, notify user, classify errors
`onSessionEnd`	Session end	Cleanup, metrics, summary

Returning null keeps default behavior.

Blocking prompts

onUserPromptSubmitted can reject a prompt by returning decision: 'block'. When a prompt is rejected, no model turn starts and the user message is not recorded. If you specify reason, it is included in a transient session.warning event with warningType: "policy_blocked".

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: 'This prompt is not allowed.',
        );
    }

    return null;
},

Typical use cases

1) Permission control

Use onPreToolUse with allow-list policies.
Require human approval for destructive actions with permissionDecision: 'ask'.
Use permissionDecisionReason for explicit denial reasons.
See Tools for tool name candidates such as view, glob, and bash.

2) Auditing and compliance

Combine lifecycle hooks to collect audit events.
Persist collected records by session ID.

3) Prompt enrichment

Add project context in onSessionStart (language, framework, conventions).
Expand shortcuts such as /fix and /test in onUserPromptSubmitted.

4) Result filtering

Mask API keys, tokens, and passwords in onPostToolUse.
Summarize oversized results and return details only when needed.

5) Error recovery

Retry only when errorContext is model_call and recoverable=true.
Provide concise user notifications for non-recoverable paths.

6) Session metrics

Record start time in onSessionStart.
Update counters in onPreToolUse and onUserPromptSubmitted.
Emit duration, tool counts, and termination reason in onSessionEnd.

Hook input and output types

Common input (`BaseHookInput`)

Property	Type	Description
`sessionId`	`string`	Related runtime session ID. The child session for child tool hooks, and the parent session ID for subagent start/stop hooks
`timestamp`	`int`	Hook timestamp (Unix ms)
`cwd`	`string`	Current working directory
`agentId`	`?string`	Actor ID of the subagent running the hook
`agentType`	`?string`	Subagent type
`parentAgentId`	`?string`	Immediate parent actor ID

agentId / agentType / parentAgentId are available on hooks where a subagent is the actor. They are not included in root agent hooks. Older runtimes omit the fields entirely when the information is unavailable. As a result, any of them can be null.

onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
    if ($input->agentId !== null) {
        logger()->info('Subagent tool use', [
            'agentId' => $input->agentId,
            'agentType' => $input->agentType,
            'parentAgentId' => $input->parentAgentId,
            'tool' => $input->toolName,
        ]);
    }

    return null;
},

`PreToolUseHookInput`

Property	Type	Description
`toolName`	`string`	Tool name to execute
`toolArgs`	`mixed`	Planned tool arguments

`PreToolUseHookOutput`

Property	Type	Description
`permissionDecision`	`?string`	`allow` / `deny` / `ask`
`permissionDecisionReason`	`?string`	Reason for deny/ask
`modifiedArgs`	`mixed`	Overridden tool arguments
`additionalContext`	`?string`	Additional context
`suppressOutput`	`?bool`	Suppress tool output

`PostToolUseHookInput`

Property	Type	Description
`toolName`	`string`	Executed tool name
`toolArgs`	`mixed`	Runtime tool arguments
`toolResult`	`ToolResultObject\|array`	Tool result

`PostToolUseHookOutput`

Property	Type	Description
`modifiedResult`	`ToolResultObject\|array\|null`	Modified result
`additionalContext`	`?string`	Additional context
`suppressOutput`	`?bool`	Suppress result output

`UserPromptSubmittedHookInput`

Property	Type	Description
`prompt`	`string`	User prompt

`UserPromptSubmittedHookOutput`

Property	Type	Description
`modifiedPrompt`	`?string`	Modified prompt
`additionalContext`	`?string`	Additional context
`suppressOutput`	`?bool`	Suppress response output
`decision`	`?string`	`block` rejects the prompt and prevents the model turn and recording of the user message
`reason`	`?string`	Rejection reason. Included in the `session.warning` event

`SessionStartHookInput`

Property	Type	Description
`source`	`string`	`startup` / `resume` / `new`
`initialPrompt`	`?string`	Initial prompt

`SessionStartHookOutput`

Property	Type	Description
`additionalContext`	`?string`	Initial session context
`modifiedConfig`	`?array`	Partial session config override

`SessionEndHookInput`

Property	Type	Description
`reason`	`string`	`complete` / `error` / `abort` / `timeout` / `user_exit`
`finalMessage`	`?string`	Final message
`error`	`?string`	Final error. If the runtime passes an error object, this is its `message` when that is a string, otherwise the object’s JSON string

`SessionEndHookOutput`

Property	Type	Description
`suppressOutput`	`?bool`	Suppress final output
`cleanupActions`	`?array`	Cleanup details
`sessionSummary`	`?string`	Session summary

`ErrorOccurredHookInput`

Property	Type	Description
`error`	`string`	Error message. If the runtime passes an error object, this is its `message` when that is a string, otherwise the object’s JSON string
`errorContext`	`string`	One of `model_call`, `tool_execution`, `system`, or `user_input`
`recoverable`	`bool`	Whether it is recoverable

`ErrorOccurredHookOutput`

Property	Type	Description
`suppressOutput`	`?bool`	Suppress error output
`errorHandling`	`?string`	`retry` / `skip` / `abort`
`retryCount`	`?int`	Retry count
`userNotification`	`?string`	Message shown to user

ToolResultObject

Standard object for tool execution results.

Property	Type	Description
`textResultForLlm`	`?string`	Text result passed to the LLM
`resultType`	`?string`	`success` / `failure` / `rejected` / `denied`
`resultForAssistant`	`?array`	Assistant-facing result data

Best practices

Avoid heavy sync work inside hooks. Offload when needed.
Return null when no customization is required.
Make permissionDecision explicit whenever possible.
Do not over-suppress critical errors. Keep logs and notifications.
Manage session state by session ID and clean up in onSessionEnd.

For the latest updates, see the GitHub repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Session hooks

Session hooks

File-based hook discovery

Hook flow

Basic usage

Available hooks

Blocking prompts

Typical use cases

1) Permission control

2) Auditing and compliance

3) Prompt enrichment

4) Result filtering

5) Error recovery

6) Session metrics

Hook input and output types

Common input (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Best practices

​Session hooks

​File-based hook discovery

​Hook flow

​Basic usage

​Available hooks

​Blocking prompts

​Typical use cases

​1) Permission control

​2) Auditing and compliance

​3) Prompt enrichment

​4) Result filtering

​5) Error recovery

​6) Session metrics

​Hook input and output types

​Common input (BaseHookInput)

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​Best practices

Session hooks

File-based hook discovery

Hook flow

Basic usage

Available hooks

Blocking prompts

Typical use cases

1) Permission control

2) Auditing and compliance

3) Prompt enrichment

4) Result filtering

5) Error recovery

6) Session metrics

Hook input and output types

Common input (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Best practices