清除上下文与终止式工具

session.rpc.history.clearContext 用于宿主管理上下文或交接任务。它保留 session 身份、system/developer 消息、配置和事件日志，只移除面向模型的对话内容。

调用前提

clearContext 是 tool-handler primitive，不能当作任何时间都可调用的 UI 清空按钮。runtime 会拒绝没有正在执行 tool call、seed prompt 为空或 remote session 上的调用。

成功后，必填 prompt 成为新上下文的第一条用户消息，并发出 session.context_cleared，包含清除消息数量与初始消息。

使用 terminal tool

官方示例在 defineTool 中设置：

const clearContextTool = defineTool("clear_context", {
    description: "Clear the conversation and start a fresh context window",
    parameters: z.object({ prompt: z.string() }),
    isTerminal: true,
    defer: "never",
    handler: async ({ prompt }) => {
        const { messagesCleared } =
            await session.rpc.history.clearContext({ prompt });
        return `Cleared ${messagesCleared} messages.`;
    },
});

此片段要求已从 SDK 导入 defineTool，从 zod 导入 z，并让闭包中的 session 指向注册该工具的会话。将工具加入 session 的 tools，按应用的权限策略处理调用。

设置 isTerminal: true 是为了在成功清除后结束当前 agent turn，避免 agent 在新的窗口里先额外调用模型、再开始 seed turn。

terminal 只在成功时结束轮次

工具失败、拒绝、超时或参数校验错误时，不会因为 isTerminal 而结束处理；结果仍展示给模型，使其有机会恢复或重试。普通工具不应随意设为 terminal。

各语言选项为 Node.js isTerminal、Python is_terminal、Go IsTerminal、.NET CopilotToolOptions.IsTerminal、Java fluent/annotation 的 isTerminal，以及 Rust with_is_terminal(true)。

与删除、恢复区分

清除模型上下文不删除事件日志，也不改变 session ID。释放资源用 disconnect，永久删除用 deleteSession；它们的作用见会话持久化。