Documentation Index
Fetch the complete documentation index at: https://kawax.biz/llms.txt
Use this file to discover all available pages before exploring further.
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.
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.
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.
| Property | Type | Description |
|---|
timestamp | int | Hook timestamp (Unix ms) |
cwd | string | Current working directory |
| Property | Type | Description |
|---|
toolName | string | Tool name to execute |
toolArgs | mixed | Planned tool arguments |
| 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 |
| Property | Type | Description |
|---|
prompt | string | User prompt |
UserPromptSubmittedHookOutput
| Property | Type | Description |
|---|
modifiedPrompt | ?string | Modified prompt |
additionalContext | ?string | Additional context |
suppressOutput | ?bool | Suppress response output |
| 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 |
| Property | Type | Description |
|---|
reason | string | complete / error / abort / timeout / user_exit |
finalMessage | ?string | Final message |
error | ?string | Final error |
SessionEndHookOutput
| Property | Type | Description |
|---|
suppressOutput | ?bool | Suppress final output |
cleanupActions | ?array | Cleanup details |
sessionSummary | ?string | Session summary |
| Property | Type | Description |
|---|
error | string | Error message |
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 |
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.