세션 훅

hooks를 사용하면 Copilot 세션의 각 라이프사이클에 처리를 끼워 넣을 수 있습니다. 도구 실행 제어, 감사 로그, 프롬프트 보강, 에러 처리 등을 코어 구현을 변경하지 않고 추가할 수 있습니다.

훅의 흐름

기본 사용법

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: '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: '현재 에러를 수정하고 변경점을 요약해줘.',
                );
            }

            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}은 이 환경에서 허용되지 않습니다",
                );
            }

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

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: '필요하다면 관련 파일도 탐색해서 비교해주세요.',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: '일시적인 모델 에러로 재시도합니다.',
                );
            }

            return null;
        },

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

            return null;
        },
    ),
]);

사용 가능한 훅

Hook	발화 타이밍	주요 용도
`onSessionStart`	세션 시작(`new` / `resume` / `startup`)	초기 컨텍스트 주입, 설정 오버라이드
`onUserPromptSubmitted`	사용자 프롬프트 전송 시	프롬프트 보강, 템플릿 확장, 입력 필터
`onPreToolUse`	도구 실행 전	허용/거부/확인 요청, 인자 수정, 출력 억제
`onPostToolUse`	도구 실행 후	결과 수정, 민감정보 마스킹, 감사 로그
`onErrorOccurred`	세션 내 에러 발생 시	재시도, 알림, 에러 분류
`onSessionEnd`	세션 종료 시	정리, 메트릭, 종료 요약

null을 반환하면 기본 동작이 계속됩니다.

대표적인 사용 사례

1) Permission control(실행 제어)

onPreToolUse에서 허용 도구를 allow-list 방식으로 설정
파괴적 조작은 permissionDecision: 'ask'로 사람에게 승인 요청
permissionDecisionReason으로 거부 이유를 명시
toolName의 후보는 Tools의 목록에서 확인(예: view, glob, bash)

2) Auditing / compliance(감사)

라이프사이클 훅을 조합해 감사 이벤트를 수집
수집 데이터는 세션 ID 단위로 영속화

3) Prompt enrichment(입력 보강)

onSessionStart에서 프로젝트 정보(언어, FW, 규약)를 additionalContext에 추가
onUserPromptSubmitted에서 단축키(/fix, /test)를 확장

4) Result filtering(결과 정형화)

onPostToolUse에서 API key / token / password 등을 마스킹
너무 긴 결과는 요약하고 필요 시에만 상세를 반환

5) Error recovery(장애 복구)

onErrorOccurred에서 model_call이면서 recoverable=true일 때만 retry
비복구 계열은 userNotification으로 사용자에게 간결하게 알림

6) Session metrics(계측)

onSessionStart에서 시작 시각을 기록
onPreToolUse / onUserPromptSubmitted에서 카운터 업데이트
onSessionEnd에서 소요 시간, 도구 횟수, 종료 이유를 출력

Hook input / output 타입

공통 입력(`BaseHookInput`)

프로퍼티	타입	설명
`timestamp`	`int`	훅 발화 시각(Unix ms)
`cwd`	`string`	현재 작업 디렉터리

`PreToolUseHookInput`

프로퍼티	타입	설명
`toolName`	`string`	실행 예정 도구명
`toolArgs`	`mixed`	실행 예정 인자

`PreToolUseHookOutput`

프로퍼티	타입	설명
`permissionDecision`	`?string`	`allow` / `deny` / `ask`
`permissionDecisionReason`	`?string`	거부/확인 시 이유
`modifiedArgs`	`mixed`	덮어쓴 인자
`additionalContext`	`?string`	추가 컨텍스트
`suppressOutput`	`?bool`	도구 출력을 억제

`PostToolUseHookInput`

프로퍼티	타입	설명
`toolName`	`string`	실행된 도구명
`toolArgs`	`mixed`	실행 시 인자
`toolResult`	`ToolResultObject\|array`	도구 결과

`PostToolUseHookOutput`

프로퍼티	타입	설명
`modifiedResult`	`ToolResultObject\|array\|null`	수정된 결과
`additionalContext`	`?string`	추가 컨텍스트
`suppressOutput`	`?bool`	도구 결과 표시를 억제

`UserPromptSubmittedHookInput`

프로퍼티	타입	설명
`prompt`	`string`	사용자 입력 프롬프트

`UserPromptSubmittedHookOutput`

프로퍼티	타입	설명
`modifiedPrompt`	`?string`	수정된 프롬프트
`additionalContext`	`?string`	보완 컨텍스트
`suppressOutput`	`?bool`	응답 표시 억제

`SessionStartHookInput`

프로퍼티	타입	설명
`source`	`string`	`startup` / `resume` / `new`
`initialPrompt`	`?string`	초기 프롬프트

`SessionStartHookOutput`

프로퍼티	타입	설명
`additionalContext`	`?string`	세션 초기 컨텍스트
`modifiedConfig`	`?array`	세션 설정의 부분 오버라이드

`SessionEndHookInput`

프로퍼티	타입	설명
`reason`	`string`	`complete` / `error` / `abort` / `timeout` / `user_exit`
`finalMessage`	`?string`	최종 메시지
`error`	`?string`	종료 시 에러

`SessionEndHookOutput`

프로퍼티	타입	설명
`suppressOutput`	`?bool`	최종 출력 억제
`cleanupActions`	`?array`	실행한 정리 정보
`sessionSummary`	`?string`	세션 요약

`ErrorOccurredHookInput`

프로퍼티	타입	설명
`error`	`string`	에러 메시지
`errorContext`	`?string`	`model_call` / `tool_execution` / `system` / `user_input` 중 하나
`recoverable`	`bool`	복구 가능한지

`ErrorOccurredHookOutput`

프로퍼티	타입	설명
`suppressOutput`	`?bool`	에러 표시 억제
`errorHandling`	`?string`	`retry` / `skip` / `abort`
`retryCount`	`?int`	재시도 횟수
`userNotification`	`?string`	사용자에게 보내는 통지문

ToolResultObject

도구 실행 결과의 표준 객체입니다.

프로퍼티	타입	설명
`textResultForLlm`	`?string`	LLM에 전달할 텍스트 결과
`resultType`	`?string`	`success` / `failure` / `rejected` / `denied`
`resultForAssistant`	`?array`	어시스턴트용 결과 데이터

베스트 프랙티스

무거운 동기 처리를 훅 내에서 직접 너무 많이 실행하지 마세요. 필요하다면 비동기화합니다.
변경이 불필요한 경우 null을 반환해 기본 동작에 맡깁니다.
permissionDecision은 가능한 한 명시합니다.
크리티컬 에러는 너무 억제하지 말고 로그/통지 경로를 확보합니다.
세션 단위의 상태는 session id 기반으로 관리하고 onSessionEnd에서 정리합니다.

최신 정보는 GitHub 저장소를 참고하세요.

GitHub Copilot

SDK

AI SDK

VOICEVOX

스타터 킷

피드·RSS

미들웨어

세션 훅

세션 훅

훅의 흐름

기본 사용법

사용 가능한 훅

대표적인 사용 사례

1) Permission control(실행 제어)

2) Auditing / compliance(감사)

3) Prompt enrichment(입력 보강)

4) Result filtering(결과 정형화)

5) Error recovery(장애 복구)

6) Session metrics(계측)

Hook input / output 타입

공통 입력(`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

베스트 프랙티스

​세션 훅

​훅의 흐름

​기본 사용법

​사용 가능한 훅

​대표적인 사용 사례

​1) Permission control(실행 제어)

​2) Auditing / compliance(감사)

​3) Prompt enrichment(입력 보강)

​4) Result filtering(결과 정형화)

​5) Error recovery(장애 복구)

​6) Session metrics(계측)

​Hook input / output 타입

​공통 입력(BaseHookInput)

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​베스트 프랙티스

세션 훅

훅의 흐름

기본 사용법

사용 가능한 훅

대표적인 사용 사례

1) Permission control(실행 제어)

2) Auditing / compliance(감사)

3) Prompt enrichment(입력 보강)

4) Result filtering(결과 정형화)

5) Error recovery(장애 복구)

6) Session metrics(계측)

Hook input / output 타입

공통 입력(`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

베스트 프랙티스