세션 훅

hooks를 사용하면 Copilot 세션의 각 라이프사이클에 처리를 끼워 넣을 수 있습니다. 도구 실행 제어, 감사 로그, 프롬프트 보강, 에러 처리 등을 코어 구현을 변경하지 않고 추가할 수 있습니다. 이는 커스텀 에이전트 정의 내의 선언형 hooks나 파일 기반 훅 로드와는 별개의 기능입니다. 에이전트 단위 설정은 커스텀 에이전트를 참조하세요.

파일 기반 훅 검색

hookDirectories에는 파일 기반 훅을 검색할 명시적인 루트를 지정할 수 있습니다. 이는 검색 전용이며, 에이전트에 일반적인 파일 접근 권한을 부여하지 않습니다. enableConfigDiscovery나 enableFileHooks가 비활성화되어 있어도 명시적 루트는 사용할 수 있습니다. 상대 경로는 지정 시점의 유효한 workingDirectory를 기준으로 한 번만 해석됩니다.

생략 또는 null: 다른 검색 소스를 변경하지 않습니다
[]: 명시한 SDK 루트만 비웁니다

훅의 소스 비활성화 설정이나 Managed Settings는 계속 적용됩니다. enableFileHooks는 리포지토리 유래의 파일 훅(.github/hooks/나 신뢰된 리포지토리 설정의 루트)을 제어합니다. 명시적인 hookDirectories나 PHP 콜백의 hooks는 비활성화하지 않습니다.

use Revolution\Copilot\Types\SessionConfig;

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

훅의 흐름

기본 사용법

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을 반환하면 기본 동작이 계속됩니다.

프롬프트 차단

onUserPromptSubmitted는 decision: 'block'을 반환해 프롬프트를 거부할 수 있습니다. 거부된 경우 모델 턴은 시작되지 않으며, 사용자 메시지도 기록되지 않습니다. reason을 지정하면 그 내용이 warningType: "policy_blocked"인 일시적 session.warning 이벤트에 포함됩니다.

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: '이 프롬프트는 허용되지 않습니다.',
        );
    }

    return 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`)

프로퍼티	타입	설명
`sessionId`	`string`	관련된 런타임 세션 ID. 자식 도구의 훅에서는 자식 세션, 서브에이전트의 시작/정지 훅에서는 부모 세션 ID
`timestamp`	`int`	훅 발화 시각(Unix ms)
`cwd`	`string`	현재 작업 디렉터리
`agentId`	`?string`	훅을 실행하는 서브에이전트의 액터 ID
`agentType`	`?string`	서브에이전트의 종류
`parentAgentId`	`?string`	직속 부모 액터 ID

agentId / agentType / parentAgentId는 서브에이전트가 액터가 되는 훅에서 사용할 수 있습니다. 루트 에이전트의 훅에는 포함되지 않습니다. 오래된 런타임에서는 정보가 없을 경우 필드 자체가 생략됩니다. 따라서 모두 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`

프로퍼티	타입	설명
`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`	응답 표시 억제
`decision`	`?string`	`block`으로 프롬프트를 거부하고, 모델 턴과 사용자 메시지 기록을 억제
`reason`	`?string`	거부 이유. `session.warning` 이벤트에 포함됨

`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`	종료 시 에러. 런타임이 에러 객체를 전달하는 경우, `message`가 문자열이면 그 값, 그렇지 않으면 객체의 JSON 문자열

`SessionEndHookOutput`

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

`ErrorOccurredHookInput`

프로퍼티	타입	설명
`error`	`string`	에러 메시지. 런타임이 에러 객체를 전달하는 경우, `message`가 문자열이면 그 값, 그렇지 않으면 객체의 JSON 문자열
`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

베스트 프랙티스