{"meta":{"title":"Context clearing and terminal tools","intro":"Use session.history.clearContext when a host needs to replace the current conversation context without replacing the session. Typical uses include handoffs and host-managed context lifecycle policies.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos","title":"How-tos"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"Features"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/context-management","title":"Context management"}],"documentType":"article"},"body":"# Context clearing and terminal tools\n\nUse session.history.clearContext when a host needs to replace the current conversation context without replacing the session. Typical uses include handoffs and host-managed context lifecycle policies.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\nContext clearing is different from creating a new session: it preserves the session identity, system and developer messages, configuration, and event log while removing the model-facing conversation.\n\n> [!IMPORTANT]\n> `clearContext` is a tool-handler primitive. The runtime rejects calls made without a tool call in flight, calls with an empty seed prompt, and calls on remote sessions.\n\n## Define a context-clearing tool\n\nA successful context-clearing tool should be terminal. Otherwise, the agent loop may make another model call against the newly cleared window before starting the seeded turn.\n\n```typescript\nimport { approveAll, CopilotClient, defineTool } from \"@github/copilot-sdk\";\nimport type { CopilotSession } from \"@github/copilot-sdk\";\nimport { z } from \"zod\";\n\nconst client = new CopilotClient();\nlet session: CopilotSession;\n\nsession = await client.createSession({\n  onPermissionRequest: approveAll,\n  tools: [\n    defineTool(\"clear_context\", {\n      description: \"Clear the conversation and start a fresh context window\",\n      parameters: z.object({ prompt: z.string() }),\n      isTerminal: true,\n      defer: \"never\",\n      handler: async ({ prompt }) => {\n        const { messagesCleared } =\n          await session.rpc.history.clearContext({ prompt });\n        return `Cleared ${messagesCleared} messages.`;\n      },\n    }),\n  ],\n});\n```\n\nThe required `prompt` becomes the first user message in the fresh context. A successful clear emits `session.context_cleared` with the number of removed messages and the initial message.\n\n## Terminal-tool behavior\n\n`isTerminal` ends the current agent turn only when the tool succeeds. A failure, denial, rejection, timeout, or input-validation error remains visible to the model so it can recover or retry.\n\nThe option follows each language's naming conventions:\n\n| SDK | Tool option |\n|---|---|\n| Node.js | `isTerminal` |\n| Python | `is_terminal` |\n| Go | `IsTerminal` |\n| .NET | `CopilotToolOptions.IsTerminal` |\n| Java | `ToolDefinition.isTerminal(true)` or `@CopilotTool(isTerminal = true)` |\n| Rust | `with_is_terminal(true)` |\n\nUse terminality only for tools whose successful completion should end the turn. Ordinary tools should leave it unset."}