Session Hooks

Session hooks allow you to intercept and modify tool execution, user prompts, and session lifecycle events. Use hooks to implement custom logic like logging, security controls, or context injection.

Overview

Hook	When It's Called	Can Modify
Pre-Tool Use	Before a tool executes	Tool arguments, permission decision
Post-Tool Use	After a tool executes	Tool result, additional context
User Prompt Submitted	When user sends a message	Nothing (observation only)
Session Start	When session begins	Nothing (observation only)
Session End	When session ends	Nothing (observation only)
Checking Whether Hooks Are Registered	Before session creation	Whether any handlers are configured

Quick Start

var hooks = new SessionHooks()
    .setOnPreToolUse((input, invocation) -> {
        System.out.println("Tool: " + input.getToolName());
        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
    })
    .setOnPostToolUse((input, invocation) -> {
        System.out.println("Result: " + input.getToolResult());
        return CompletableFuture.completedFuture(null);
    });

var session = client.createSession(
    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setModel("gpt-4.1")
        .setHooks(hooks)
).get();

Pre-Tool Use Hook

Called before a tool executes. Use this to:

Approve, deny, or prompt for tool execution
Modify tool arguments
Add context for the LLM
Suppress tool output from being shown

Input

Field	Type	Description
`getToolName()`	`String`	Name of the tool being called
`getToolArgs()`	`JsonNode`	Arguments passed to the tool
`getCwd()`	`String`	Current working directory
`getTimestamp()`	`long`	Timestamp in milliseconds

Output

Field	Type	Description
`setPermissionDecision(String)`	`"allow"`, `"deny"`, `"ask"`	Whether to execute the tool
`setPermissionDecisionReason(String)`	`String`	Reason shown to user/LLM
`setModifiedArgs(JsonNode)`	`JsonNode`	Modified arguments (optional)
`setAdditionalContext(String)`	`String`	Extra context for the LLM
`setSuppressOutput(Boolean)`	`Boolean`	Hide output from display

Example: Security Gate

Block dangerous tool calls:

var hooks = new SessionHooks()
    .setOnPreToolUse((input, invocation) -> {
        String tool = input.getToolName();
        
        // Block file deletion
        if (tool.equals("delete_file")) {
            return CompletableFuture.completedFuture(
                PreToolUseHookOutput.deny("File deletion is not allowed")
            );
        }
        
        // Require confirmation for shell commands
        if (tool.equals("run_terminal_cmd")) {
            return CompletableFuture.completedFuture(PreToolUseHookOutput.ask());
        }
        
        // Allow everything else
        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
    });

Example: Argument Modification

Inject context into tool arguments:

var hooks = new SessionHooks()
    .setOnPreToolUse((input, invocation) -> {
        if (input.getToolName().equals("search_code")) {
            // Add project root to search path
            var mapper = new ObjectMapper();
            var modifiedArgs = mapper.createObjectNode();
            modifiedArgs.put("path", "/my/project/src");
            modifiedArgs.set("query", input.getToolArgs().get("query"));
            
            return CompletableFuture.completedFuture(
                PreToolUseHookOutput.withModifiedArgs("allow", modifiedArgs)
            );
        }
        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
    });

Post-Tool Use Hook

Called after a tool executes. Use this to:

Log tool results
Modify the result shown to the LLM
Add additional context based on results
Suppress output from display

Input

Field	Type	Description
`getToolName()`	`String`	Name of the tool that was called
`getToolArgs()`	`JsonNode`	Arguments that were passed
`getToolResult()`	`JsonNode`	Result from the tool
`getCwd()`	`String`	Current working directory
`getTimestamp()`	`long`	Timestamp in milliseconds

Output

Field	Type	Description
`setModifiedResult(String)`	`String`	Modified result for the LLM
`setAdditionalContext(String)`	`String`	Extra context for the LLM
`setSuppressOutput(Boolean)`	`Boolean`	Hide output from display

Example: Result Logging

Log all tool executions:

var hooks = new SessionHooks()
    .setOnPostToolUse((input, invocation) -> {
        System.out.printf("[%d] %s completed%n", 
            input.getTimestamp(), 
            input.getToolName());
        System.out.println("Result: " + input.getToolResult());
        
        return CompletableFuture.completedFuture(null);
    });

Example: Result Enrichment

Add context to file read results:

var hooks = new SessionHooks()
    .setOnPostToolUse((input, invocation) -> {
        if (input.getToolName().equals("read_file")) {
            String context = "Note: This file was last modified 2 hours ago.";
            return CompletableFuture.completedFuture(
                new PostToolUseHookOutput(null, context, null)
            );
        }
        return CompletableFuture.completedFuture(null);
    });

User Prompt Submitted Hook

Called when the user submits a prompt, before the LLM processes it. This is an observation hook - you cannot modify the prompt.

Input

Field	Type	Description
`prompt()`	`String`	The user's prompt text
`getTimestamp()`	`long`	Timestamp in milliseconds

Output

Return null - this hook is observation-only.

Example: Prompt Logging

var hooks = new SessionHooks()
    .setOnUserPromptSubmitted((input, invocation) -> {
        System.out.println("User asked: " + input.prompt());
        
        // Track prompts for analytics
        analytics.track("user_prompt", Map.of(
            "sessionId", invocation.getSessionId(),
            "promptLength", input.prompt().length()
        ));
        
        return CompletableFuture.completedFuture(null);
    });

Session Start Hook

Called when a session starts (either new or resumed).

Input

Field	Type	Description
`source()`	`String`	`"startup"`, `"resume"`, or `"new"`
`getTimestamp()`	`long`	Timestamp in milliseconds

Output

Return null - this hook is observation-only.

Example: Session Initialization

var hooks = new SessionHooks()
    .setOnSessionStart((input, invocation) -> {
        System.out.println("Session started: " + invocation.getSessionId());
        System.out.println("Source: " + input.source());
        
        // Initialize session-specific resources
        sessionResources.put(invocation.getSessionId(), new ResourceManager());
        
        return CompletableFuture.completedFuture(null);
    });

Session End Hook

Called when a session ends.

Input

Field	Type	Description
`reason()`	`String`	Why the session ended
`getTimestamp()`	`long`	Timestamp in milliseconds

Output

Return null - this hook is observation-only.

Example: Session Cleanup

var hooks = new SessionHooks()
    .setOnSessionEnd((input, invocation) -> {
        System.out.println("Session ended: " + input.reason());
        
        // Clean up session resources
        var resources = sessionResources.remove(invocation.getSessionId());
        if (resources != null) {
            resources.close();
        }
        
        return CompletableFuture.completedFuture(null);
    });

Complete Example

Combining multiple hooks for comprehensive session control:

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.json.PermissionHandler;
import com.github.copilot.sdk.json.PreToolUseHookOutput;
import com.github.copilot.sdk.json.SessionConfig;
import com.github.copilot.sdk.json.SessionHooks;
import java.util.concurrent.CompletableFuture;

public class HooksExample {
    public static void main(String[] args) throws Exception {
        try (var client = new CopilotClient()) {
            client.start().get();
            
            var hooks = new SessionHooks()
                // Security: control tool execution
                .setOnPreToolUse((input, invocation) -> {
                    System.out.println("→ " + input.getToolName());
                    
                    // Deny dangerous operations
                    if (input.getToolName().contains("delete")) {
                        return CompletableFuture.completedFuture(
                            PreToolUseHookOutput.deny("Deletion not allowed")
                        );
                    }
                    
                    return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
                })
                
                // Logging: track tool results
                .setOnPostToolUse((input, invocation) -> {
                    System.out.println("← " + input.getToolName() + " completed");
                    return CompletableFuture.completedFuture(null);
                })
                
                // Analytics: track user prompts
                .setOnUserPromptSubmitted((input, invocation) -> {
                    System.out.println("User: " + input.prompt());
                    return CompletableFuture.completedFuture(null);
                })
                
                // Lifecycle: initialization and cleanup
                .setOnSessionStart((input, invocation) -> {
                    System.out.println("Session started (" + input.source() + ")");
                    return CompletableFuture.completedFuture(null);
                })
                .setOnSessionEnd((input, invocation) -> {
                    System.out.println("Session ended: " + input.reason());
                    return CompletableFuture.completedFuture(null);
                });
            
            var session = client.createSession(
                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
                    .setModel("gpt-4.1")
                    .setHooks(hooks)
            ).get();
            
            var response = session.sendAndWait("List files in /tmp").get();
            System.out.println(response.getData().content());
            
            session.close();
        }
    }
}

Hook Invocation Object

All hook handlers receive a HookInvocation object as the second parameter:

Method	Description
`getSessionId()`	The session ID where the hook was triggered

This allows you to correlate hooks with specific sessions when managing multiple concurrent sessions.

Checking Whether Hooks Are Registered

Use hasHooks() to quickly verify that at least one hook handler is configured:

var hooks = new SessionHooks()
    .setOnPreToolUse((input, invocation) ->
        CompletableFuture.completedFuture(PreToolUseHookOutput.allow()));

if (hooks.hasHooks()) {
    var session = client.createSession(
        new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setHooks(hooks)
    ).get();
}

Error Handling

If a hook throws an exception, the SDK logs the error and continues with default behavior:

Pre-tool hooks default to allowing execution
Post-tool hooks have no effect on the result
Lifecycle hooks are observation-only

To handle errors gracefully in your hooks:

.setOnPreToolUse((input, invocation) -> {
    try {
        // Your logic here
        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
    } catch (Exception e) {
        logger.error("Hook error", e);
        // Fail-safe: deny if something goes wrong
        return CompletableFuture.completedFuture(
            PreToolUseHookOutput.deny("Internal error")
        );
    }
})

Next Steps

📖 Documentation - Core concepts, events, session management
📖 Advanced Usage - Tools, BYOK, MCP Servers, Custom Agents
📖 MCP Servers - Integrate external tools via Model Context Protocol
📖 API Javadoc - Complete API reference

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Session Hooks

Overview

Quick Start

Pre-Tool Use Hook

Input

Output

Example: Security Gate

Example: Argument Modification

Post-Tool Use Hook

Input

Output

Example: Result Logging

Example: Result Enrichment

User Prompt Submitted Hook

Input

Output

Example: Prompt Logging

Session Start Hook

Input

Output

Example: Session Initialization

Session End Hook

Input

Output

Example: Session Cleanup

Complete Example

Hook Invocation Object

Checking Whether Hooks Are Registered

Error Handling

See Also

Next Steps

FilesExpand file tree

hooks.md

Latest commit

History

hooks.md

File metadata and controls

Session Hooks

Overview

Quick Start

Pre-Tool Use Hook

Input

Output

Example: Security Gate

Example: Argument Modification

Post-Tool Use Hook

Input

Output

Example: Result Logging

Example: Result Enrichment

User Prompt Submitted Hook

Input

Output

Example: Prompt Logging

Session Start Hook

Input

Output

Example: Session Initialization

Session End Hook

Input

Output

Example: Session Cleanup

Complete Example

Hook Invocation Object

Checking Whether Hooks Are Registered

Error Handling

See Also

Next Steps