fix(app): match new session prompt sizing to chat

Co-authored-by: MrMushrooooom <MrMushrooooom@users.noreply.github.com>
Co-authored-by: Jack <jack@anoma.ly>

packages/ai/src/cache-policy.ts

@@ -11,7 +11,7 @@
 // Manual `cache: CacheHint` placements on individual parts are preserved and
 // count against the four-breakpoint budget; auto only fills remaining slots.
 import { CacheHint, type CachePolicy, type CachePolicyObject } from "./schema/options.js"
-import { LLMRequest, Message, ToolDefinition, type ContentPart } from "./schema/messages.js"
+import { LLMRequest, Message, ToolDefinition, type ContentPart, type ToolEntry } from "./schema/messages.js"
 
 const AUTO: CachePolicyObject = {
   tools: true,
@@ -50,18 +50,24 @@ interface Budget {
   remaining: number
 }
 
-const markLastTool = (
-  tools: ReadonlyArray<ToolDefinition>,
-  hint: CacheHint,
-  budget: Budget,
-): ReadonlyArray<ToolDefinition> => {
-  if (tools.length === 0) return tools
-  const last = tools.length - 1
-  if (tools[last]!.cache || budget.remaining === 0) return tools
+const markLastTool = (tools: ReadonlyArray<ToolEntry>, hint: CacheHint, budget: Budget): ReadonlyArray<ToolEntry> => {
+  const target = tools.at(-1)
+  if (target === undefined) return tools
+  if (target.type === "namespace") {
+    const nested = markLastTool(target.tools, hint, budget)
+    return nested === target.tools ? tools : [...tools.slice(0, -1), { ...target, tools: nested }]
+  }
+  if (target.cache || budget.remaining === 0) return tools
   budget.remaining -= 1
-  return tools.map((tool, i) => (i === last ? new ToolDefinition({ ...tool, cache: hint }) : tool))
+  return [...tools.slice(0, -1), new ToolDefinition({ ...target, cache: hint })]
 }
 
+const countToolHints = (tools: ReadonlyArray<ToolEntry>): number =>
+  tools.reduce(
+    (count, tool) => count + (tool.type === "tool" ? (tool.cache === undefined ? 0 : 1) : countToolHints(tool.tools)),
+    0,
+  )
+
 const markSystemBoundaries = (system: LLMRequest["system"], hint: CacheHint, budget: Budget): LLMRequest["system"] => {
   if (system.length === 0) return system
   let changed = false
@@ -122,7 +128,7 @@ const markMessages = (
 }
 
 const countHints = (request: LLMRequest) =>
-  request.tools.reduce((count, tool) => count + (tool.cache === undefined ? 0 : 1), 0) +
+  countToolHints(request.tools) +
   request.system.reduce((count, part) => count + (part.cache === undefined ? 0 : 1), 0) +
   request.messages.reduce(
     (count, message) =>

packages/ai/src/llm.ts

@@ -12,9 +12,10 @@ import {
   LanguageModel,
   SystemPart,
   ToolChoice,
-  ToolDefinition,
+  ToolEntry,
   type ContentPart,
   type LanguageModelProviderOptions,
+  type ToolEntryInput,
 } from "./schema/index.js"
 import { make as makeTool, toDefinitions, type ToolSchema } from "./tool.js"
 
@@ -27,7 +28,7 @@ export type RequestInput<SelectedLanguageModel extends LanguageModel = LanguageM
   readonly system?: string | SystemPart | ReadonlyArray<SystemPart>
   readonly prompt?: string | ContentPart | ReadonlyArray<ContentPart>
   readonly messages?: ReadonlyArray<Message | Message.Input>
-  readonly tools?: ReadonlyArray<ToolDefinition.Input>
+  readonly tools?: ReadonlyArray<ToolEntryInput>
   readonly toolChoice?: ToolChoice.Input
   readonly generation?: GenerationOptions.Input
   readonly providerOptions?: NoInfer<LanguageModelProviderOptions<SelectedLanguageModel>>
@@ -56,7 +57,7 @@ export const request = <const SelectedLanguageModel extends LanguageModel>(
     ...rest,
     system: SystemPart.content(requestSystem),
     messages: [...(messages?.map(Message.make) ?? []), ...(prompt === undefined ? [] : [Message.user(prompt)])],
-    tools: tools?.map(ToolDefinition.make) ?? [],
+    tools: tools?.map(ToolEntry.make) ?? [],
     toolChoice: requestToolChoice ? ToolChoice.make(requestToolChoice) : undefined,
     generation: requestGeneration === undefined ? undefined : GenerationOptions.make(requestGeneration),
     providerOptions: requestProviderOptions,

packages/ai/src/protocols/anthropic-messages.ts

@@ -1067,10 +1067,11 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
   // messages. Tools live highest in the cache hierarchy, so when callers
   // over-mark we keep their tool hints and shed the message-tail ones first.
   const breakpoints = Cache.newBreakpoints(ANTHROPIC_BREAKPOINT_CAP)
+  const flattened = ProviderShared.flattenToolRequest(request)
   const tools =
-    request.tools.length === 0
+    flattened.tools.length === 0
       ? undefined
-      : request.tools.map((tool) =>
+      : flattened.tools.map((tool) =>
           lowerTool(
             breakpoints,
             tool,
@@ -1088,7 +1089,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
           text: part.text,
           cache_control: cacheControl(breakpoints, part.cache),
         }))
-  const messages = yield* lowerMessages(request, breakpoints)
+  const messages = yield* lowerMessages(flattened.request, breakpoints)
   if (breakpoints.dropped > 0) {
     yield* Effect.logWarning(
       `Anthropic Messages: dropped ${breakpoints.dropped} cache breakpoint(s); the API allows at most ${ANTHROPIC_BREAKPOINT_CAP} per request.`,

packages/ai/src/protocols/bedrock-converse.ts

@@ -415,7 +415,10 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
 
 // System prompts share the cache-point convention: emit the text block, then
 // optionally a positional `cachePoint` marker.
-const lowerSystem = (breakpoints: BedrockCache.Breakpoints, system: ReadonlyArray<LLMRequest["system"][number]>) => {
+const lowerSystem = (
+  breakpoints: BedrockCache.Breakpoints,
+  system: ReadonlyArray<LLMRequest["system"][number]>,
+) => {
   const content = system
     .filter((part) => part.text.length > 0)
     .flatMap((part) => textWithCache(breakpoints, part.text, part.cache))
@@ -424,21 +427,22 @@ const lowerSystem = (breakpoints: BedrockCache.Breakpoints, system: ReadonlyArra
 
 const fromRequest = Effect.fn("BedrockConverse.fromRequest")(function* (request: LLMRequest) {
   const toolChoice = request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined
+  const flattened = ProviderShared.flattenToolRequest(request)
   const generation = request.generation
   // Bedrock-Claude shares Anthropic's 4-breakpoint cap. Spend the budget in
   // tools → system → messages order to favour the highest-impact prefixes.
   const breakpoints = BedrockCache.breakpoints()
   const toolConfig = (() => {
-    if (request.tools.length === 0) return undefined
+    if (flattened.tools.length === 0) return undefined
     return {
-      tools: lowerTools(request.model.compatibility?.toolSchema, breakpoints, request.tools),
+      tools: lowerTools(request.model.compatibility?.toolSchema, breakpoints, flattened.tools),
       // Converse has no native "none". Keep definitions stable for prompt
       // caching and omit only the unsupported choice.
       toolChoice,
     }
   })()
   const system = lowerSystem(breakpoints, request.system)
-  const messages = yield* lowerMessages(request, breakpoints)
+  const messages = yield* lowerMessages(flattened.request, breakpoints)
   if (breakpoints.dropped > 0) {
     yield* Effect.logWarning(
       `Bedrock Converse: dropped ${breakpoints.dropped} cache breakpoint(s); the API allows at most ${BedrockCache.BEDROCK_BREAKPOINT_CAP} per request.`,

packages/ai/src/protocols/gemini.ts

@@ -465,7 +465,8 @@ function mapSafetySettings(value: unknown) {
 }
 
 const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMRequest) {
-  const hasTools = request.tools.length > 0
+  const flattened = ProviderShared.flattenToolRequest(request)
+  const hasTools = flattened.tools.length > 0
   const generation = request.generation
   const options = resolveOptions(request)
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
@@ -483,7 +484,7 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
 
   return {
     cachedContent: options.cachedContent,
-    contents: yield* lowerMessages(request),
+    contents: yield* lowerMessages(flattened.request),
     safetySettings: options.safetySettings,
     serviceTier: options.serviceTier,
     systemInstruction:
@@ -491,7 +492,7 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
     tools: hasTools
       ? [
           {
-            functionDeclarations: request.tools.map((tool) =>
+            functionDeclarations: flattened.tools.map((tool) =>
               lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
             ),
           },

packages/ai/src/protocols/mistral-chat.ts

@@ -414,10 +414,11 @@ export const fromRequest = Effect.fn("MistralChat.fromRequest")(function* (reque
         tool: (name) => ({ type: "function" as const, function: { name } }),
       })
     : undefined
+  const flattened = ProviderShared.flattenToolRequest(request)
   return {
     model: request.model.id,
-    messages: yield* lowerMessages(request),
-    tools: request.tools.length > 0 ? request.tools.map(lowerTool) : undefined,
+    messages: yield* lowerMessages(flattened.request),
+    tools: flattened.tools.length > 0 ? flattened.tools.map(lowerTool) : undefined,
     tool_choice: toolChoice,
     stream: true as const,
     max_tokens: request.generation?.maxTokens,

packages/ai/src/protocols/open-responses.ts

@@ -189,6 +189,7 @@ export const InputItem = Schema.Union([
     id: Schema.optionalKey(Schema.String),
     call_id: Schema.String,
     name: Schema.String,
+    namespace: Schema.optional(Schema.String),
     arguments: Schema.String,
   }),
   Schema.Struct({
@@ -315,6 +316,7 @@ export const StreamItem = Schema.StructWithRest(
     id: Schema.optional(Schema.String),
     call_id: Schema.optional(Schema.String),
     name: Schema.optional(Schema.String),
+    namespace: Schema.optional(Schema.String),
     arguments: Schema.optional(Schema.String),
     encrypted_content: optionalNull(Schema.String),
   }),
@@ -488,6 +490,7 @@ const lowerToolCall = (part: ToolCallPart, providerMetadataKey: string): OpenRes
     ...(id === undefined ? {} : { id }),
     call_id: part.id,
     name: part.name,
+    namespace: part.namespace,
     arguments: ProviderShared.encodeJson(part.input),
   }
 }
@@ -807,14 +810,15 @@ export const fromRequestWithAdapter = Effect.fn("OpenResponses.fromRequestWithAd
   request: LLMRequest,
   adapter: ProviderAdapter,
 ) {
+  const projected = ProviderShared.flattenToolRequest(request)
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
   return {
-    ...(yield* lowerConversation(request, adapter)),
+    ...(yield* lowerConversation(projected.request, adapter)),
     ...lowerGeneration(request),
     tools:
-      request.tools.length === 0
+      projected.tools.length === 0
         ? undefined
-        : yield* Effect.forEach(request.tools, (tool) =>
+        : yield* Effect.forEach(projected.tools, (tool) =>
             lowerTool(
               adapter.name,
               tool,
@@ -1094,11 +1098,20 @@ const onOutputItemAdded = (state: ParserState, event: NormalizedEvent): StepResu
       tools: ToolStream.start(state.tools, item.id, {
         id: item.call_id,
         name: item.name ?? "",
+        namespace: item.namespace,
         input: item.arguments ?? "",
         providerMetadata: metadata,
       }),
     },
-    [...events, LLMEvent.toolInputStart({ id: item.call_id, name: item.name ?? "", providerMetadata: metadata })],
+    [
+      ...events,
+      LLMEvent.toolInputStart({
+        id: item.call_id,
+        name: item.name ?? "",
+        namespace: item.namespace,
+        providerMetadata: metadata,
+      }),
+    ],
   ]
 }
 
@@ -1217,7 +1230,12 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
     const registered = state.tools[item.id] !== undefined
     const tools = registered
       ? state.tools
-      : ToolStream.start(state.tools, item.id, { id: item.call_id, name: item.name, providerMetadata: metadata })
+      : ToolStream.start(state.tools, item.id, {
+          id: item.call_id,
+          name: item.name,
+          namespace: item.namespace,
+          providerMetadata: metadata,
+        })
     const result =
       item.arguments === undefined
         ? yield* ToolStream.finish(state.id, tools, item.id)
@@ -1228,7 +1246,15 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
     const resultEvents =
       registered || finished.length === 0
         ? finished
-        : [LLMEvent.toolInputStart({ id: item.call_id, name: item.name, providerMetadata: metadata }), ...finished]
+        : [
+            LLMEvent.toolInputStart({
+              id: item.call_id,
+              name: item.name,
+              namespace: item.namespace,
+              providerMetadata: metadata,
+            }),
+            ...finished,
+          ]
     const lifecycle = resultEvents.length ? Lifecycle.stepStart(state.lifecycle, events) : state.lifecycle
     events.push(...resultEvents)
     return [

packages/ai/src/protocols/openai-chat.ts

@@ -736,6 +736,7 @@ export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (
     )
   const generation = request.generation
   const toolSchemaCompatibility = request.model.compatibility?.toolSchema
+  const flattened = ProviderShared.flattenToolRequest(request)
   const provider = String(request.model.provider)
   const baseURL = request.model.route.endpoint.baseURL
   const detectedMaxTokensField = detectMaxTokensField(provider, baseURL)
@@ -748,16 +749,16 @@ export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (
   const zaiToolStream =
     request.model.compatibility?.zaiToolStream ?? detectZaiToolStream(provider, baseURL, request.model.id)
   const hasHistory = hasToolHistory(request.messages)
-  const hasActiveTools = request.tools.length > 0
+  const hasActiveTools = flattened.tools.length > 0
   return {
     model: request.model.id,
-    messages: yield* lowerMessages(request, options),
+    messages: yield* lowerMessages(flattened.request, options),
     tools:
-      request.tools.length === 0
+      flattened.tools.length === 0
         ? hasHistory
           ? []
           : undefined
-        : request.tools.map((tool) =>
+        : flattened.tools.map((tool) =>
             lowerTool(
               tool,
               ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility),

packages/ai/src/protocols/openai-responses.ts

@@ -5,7 +5,7 @@ import { Auth } from "../route/auth.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { HttpTransport } from "../route/transport/index.js"
-import type { LLMRequest, JsonSchema, ToolDefinition } from "../schema/index.js"
+import type { LLMRequest, JsonSchema, ToolDefinition, ToolEntry } from "../schema/index.js"
 import { OpenResponses } from "./open-responses.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { OpenAIImage } from "./utils/openai-image.js"
@@ -75,7 +75,18 @@ const OpenAIResponsesHostedToolItem = Schema.Union([
   ),
 ])
 
-const OpenAIResponsesTools = Schema.Union([OpenResponses.Tool, OpenAIResponsesImageGenerationTool])
+const OpenAIResponsesNamespace = Schema.Struct({
+  type: Schema.tag("namespace"),
+  name: Schema.String,
+  description: Schema.String,
+  tools: Schema.Array(OpenResponses.Tool),
+})
+
+const OpenAIResponsesTools = Schema.Union([
+  OpenResponses.Tool,
+  OpenAIResponsesNamespace,
+  OpenAIResponsesImageGenerationTool,
+])
 
 const OpenAIResponsesToolChoice = Schema.Union([
   OpenResponses.ToolChoice,
@@ -128,13 +139,33 @@ const lowerTool = Effect.fn("OpenAIResponses.lowerTool")(function* (tool: ToolDe
   return yield* OpenResponses.lowerTool(NAME, tool, inputSchema)
 })
 
-const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tools: ReadonlyArray<ToolDefinition>) =>
+// Native namespaces hold only function tools, so deeper levels flatten into
+// the leaf names the same way non-native protocols flatten the whole tree.
+const lowerToolEntry = Effect.fn("OpenAIResponses.lowerToolEntry")(function* (
+  tool: ToolEntry,
+  compatibility: Parameters<typeof ToolSchemaProjection.modelCompatibility>[1],
+) {
+  if (tool.type === "tool")
+    return yield* lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, compatibility))
+  // OpenAI requires a namespace description; fall back to a generic one so a
+  // missing description never blocks the request.
+  return {
+    type: "namespace" as const,
+    name: tool.name,
+    description: tool.description ?? `Tools in the ${tool.name} namespace.`,
+    tools: yield* Effect.forEach(ProviderShared.flattenTools(tool.tools), (leaf) =>
+      OpenResponses.lowerTool(NAME, leaf, ToolSchemaProjection.modelCompatibility(leaf.inputSchema, compatibility)),
+    ),
+  }
+})
+
+const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tools: ReadonlyArray<ToolEntry>) =>
   ProviderShared.matchToolChoice(NAME, toolChoice, {
     auto: () => "auto" as const,
     none: () => "none" as const,
     required: () => "required" as const,
     tool: (name) =>
-      tools.some((tool) => tool.name === name && nativeImageTool(tool) !== undefined)
+      tools.some((tool) => tool.type === "tool" && tool.name === name && nativeImageTool(tool) !== undefined)
         ? ({ type: "image_generation" } as const)
         : { type: "function" as const, name },
   })
@@ -153,9 +184,7 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
     tools:
       request.tools.length === 0
         ? undefined
-        : yield* Effect.forEach(request.tools, (tool) =>
-            lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
-          ),
+        : yield* Effect.forEach(request.tools, (tool) => lowerToolEntry(tool, toolSchemaCompatibility)),
     tool_choice:
       OpenResponses.allowedToolChoice(request) ??
       (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined),

packages/ai/src/protocols/shared.ts

@@ -9,11 +9,14 @@ import {
   UnsupportedOperationError,
   AIError,
   HttpContext,
+  LLMRequest,
+  Message,
+  ToolDefinition,
   type ContentPart,
-  type LLMRequest,
   type MediaPart,
   type ProviderID,
   type TextPart,
+  type ToolEntry,
   type ToolResultPart,
 } from "../schema/index.js"
 import { isRecord } from "../utils/record.js"
@@ -46,6 +49,7 @@ export const promptCacheKey = (request: LLMRequest): string | undefined => {
 export interface ToolAccumulator {
   readonly id: string
   readonly name: string
+  readonly namespace?: string
   readonly input: string
 }
 
@@ -279,6 +283,38 @@ export const unsupportedOperation = (input: {
     }),
   })
 
+/**
+ * Lower namespaces to flat definitions for protocols without a native
+ * namespace construct. Leaf names join their namespace path with `_` because
+ * `.` is not broadly accepted in provider tool names.
+ */
+export const flattenTools = (tools: ReadonlyArray<ToolEntry>, path: ReadonlyArray<string> = []) => {
+  const flat = tools.flatMap((tool): ReadonlyArray<ToolDefinition> => {
+    if (tool.type === "namespace") return flattenTools(tool.tools, [...path, tool.name])
+    if (path.length === 0) return [tool]
+    return [new ToolDefinition({ ...tool, name: [...path, tool.name].join("_") })]
+  })
+  return [...new Map(flat.map((tool) => [tool.name, tool])).values()]
+}
+
+export const flattenToolRequest = (request: LLMRequest) => {
+  const messages = request.messages.map((message) => {
+    const content = message.content.map((part) => {
+      if ((part.type !== "tool-call" && part.type !== "tool-result") || part.namespace === undefined) return part
+      return { ...part, name: `${part.namespace}_${part.name}`, namespace: undefined }
+    })
+    return content.every((part, index) => part === message.content[index])
+      ? message
+      : new Message({ ...message, content })
+  })
+  return {
+    tools: flattenTools(request.tools),
+    request: messages.every((message, index) => message === request.messages[index])
+      ? request
+      : LLMRequest.update(request, { messages }),
+  }
+}
+
 export const imageResponse = Effect.fn("ProviderShared.imageResponse")(function* (
   route: string,
   name: string,

packages/ai/src/protocols/utils/tool-stream.ts

@@ -55,6 +55,7 @@ const inputStart = (tool: PendingTool) =>
   LLMEvent.toolInputStart({
     id: tool.id,
     name: tool.name,
+    namespace: tool.namespace,
     providerExecuted: tool.providerExecuted ? true : undefined,
     providerMetadata: tool.providerMetadata,
   })
@@ -63,6 +64,7 @@ const inputDelta = (tool: PendingTool, text: string) =>
   LLMEvent.toolInputDelta({
     id: tool.id,
     name: tool.name,
+    namespace: tool.namespace,
     text,
     input: Option.getOrElse(parsePartialInput(tool.input), () => ({})),
   })
@@ -85,6 +87,7 @@ const toolCall = (route: string, tool: PendingTool, inputOverride?: string) => {
         LLMEvent.toolCall({
           id: tool.id,
           name: tool.name,
+          namespace: tool.namespace,
           input,
           providerExecuted: tool.providerExecuted ? true : undefined,
           providerMetadata: tool.providerMetadata,
@@ -94,7 +97,12 @@ const toolCall = (route: string, tool: PendingTool, inputOverride?: string) => {
 }
 
 const finishEvents = (tool: PendingTool, event: ToolCall): ReadonlyArray<LLMEvent> => [
-  LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
+  LLMEvent.toolInputEnd({
+    id: tool.id,
+    name: tool.name,
+    namespace: tool.namespace,
+    providerMetadata: tool.providerMetadata,
+  }),
   event,
 ]
 
@@ -150,6 +158,7 @@ export const appendOrStart = <K extends StreamKey>(
   const tool = {
     id,
     name,
+    namespace: current?.namespace,
     input: `${current?.input ?? ""}${delta.text}`,
     providerExecuted: current?.providerExecuted,
     providerMetadata: current?.providerMetadata,

packages/ai/src/route/client.ts

@@ -487,10 +487,14 @@ export function make<Body, Prepared, Frame, Event, State>(
 }
 
 const prepareRequest = (request: LLMRequest) => {
-  const original = applyCachePolicy(resolveRequestOptions(request))
+  const original = resolveRequestOptions(request)
   const sanitized = LLMRequest.update(original, sanitizeSurrogates({ ...LLMRequest.input(original), model: undefined }))
-  const tools = [...new Map(sanitized.tools.map((tool) => [tool.name, tool])).values()]
-  const resolved = tools.length === sanitized.tools.length ? sanitized : LLMRequest.update(sanitized, { tools })
+  // Deduplicate per sibling level; a tool and a namespace may share a name.
+  const dedupe = (tools: LLMRequest["tools"]): LLMRequest["tools"] =>
+    [...new Map(tools.map((tool) => [`${tool.type}:${tool.name}`, tool])).values()].map((tool) =>
+      tool.type === "tool" ? tool : { ...tool, tools: dedupe(tool.tools) },
+    )
+  const resolved = applyCachePolicy(LLMRequest.update(sanitized, { tools: dedupe(sanitized.tools) }))
   const headers = resolved.model.route.headers?.({ request: resolved })
   return headers === undefined
     ? resolved

packages/ai/src/schema/events.ts

@@ -155,6 +155,7 @@ export const ToolInputStart = Schema.Struct({
   type: Schema.tag("tool-input-start"),
   id: ToolCallID,
   name: Schema.String,
+  namespace: Schema.optional(Schema.String),
   providerExecuted: Schema.optional(Schema.Boolean),
   providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.ToolInputStart" })
@@ -164,6 +165,7 @@ export const ToolInputDelta = Schema.Struct({
   type: Schema.tag("tool-input-delta"),
   id: ToolCallID,
   name: Schema.String,
+  namespace: Schema.optional(Schema.String),
   text: Schema.String,
   /** Best-effort parse of all input fragments received through this delta. */
   input: Schema.optional(Schema.Unknown),
@@ -174,6 +176,7 @@ export const ToolInputEnd = Schema.Struct({
   type: Schema.tag("tool-input-end"),
   id: ToolCallID,
   name: Schema.String,
+  namespace: Schema.optional(Schema.String),
   providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "LLM.Event.ToolInputEnd" })
 export type ToolInputEnd = Schema.Schema.Type<typeof ToolInputEnd>
@@ -183,6 +186,7 @@ export const ToolInputError = Schema.Struct({
   type: Schema.tag("tool-input-error"),
   id: ToolCallID,
   name: Schema.String,
+  namespace: Schema.optional(Schema.String),
   raw: Schema.String,
 }).annotate({ identifier: "LLM.Event.ToolInputError" })
 export type ToolInputError = Schema.Schema.Type<typeof ToolInputError>
@@ -191,6 +195,7 @@ export const ToolCall = Schema.Struct({
   type: Schema.tag("tool-call"),
   id: ToolCallID,
   name: Schema.String,
+  namespace: Schema.optional(Schema.String),
   input: Schema.Unknown,
   providerExecuted: Schema.optional(Schema.Boolean),
   providerMetadata: Schema.optional(ProviderMetadata),
@@ -201,6 +206,7 @@ export const ToolResult = Schema.Struct({
   type: Schema.tag("tool-result"),
   id: ToolCallID,
   name: Schema.String,
+  namespace: Schema.optional(Schema.String),
   result: ToolResultValue,
   output: Schema.optional(ToolOutput),
   providerExecuted: Schema.optional(Schema.Boolean),
@@ -212,6 +218,7 @@ export const ToolError = Schema.Struct({
   type: Schema.tag("tool-error"),
   id: ToolCallID,
   name: Schema.String,
+  namespace: Schema.optional(Schema.String),
   message: Schema.String,
   error: Schema.optional(Schema.Defect()),
   providerMetadata: Schema.optional(ProviderMetadata),
@@ -385,6 +392,7 @@ interface ContentAssembly {
 
 interface ToolInputAssembly {
   readonly name: string
+  readonly namespace?: string
   readonly text: string
   readonly providerMetadata?: ProviderMetadata
 }
@@ -522,12 +530,17 @@ const reduceToolInputStart = (state: ResponseState, event: ToolInputStart): Resp
   ...state,
   toolInputs: {
     ...state.toolInputs,
-    [event.id]: { name: event.name, text: "", providerMetadata: event.providerMetadata },
+    [event.id]: {
+      name: event.name,
+      namespace: event.namespace,
+      text: "",
+      providerMetadata: event.providerMetadata,
+    },
   },
 })
 
 const reduceToolInputDelta = (state: ResponseState, event: ToolInputDelta): ResponseState => {
-  const current = state.toolInputs[event.id] ?? { name: event.name, text: "" }
+  const current = state.toolInputs[event.id] ?? { name: event.name, namespace: event.namespace, text: "" }
   return {
     ...state,
     toolInputs: { ...state.toolInputs, [event.id]: { ...current, text: current.text + event.text } },
@@ -535,7 +548,7 @@ const reduceToolInputDelta = (state: ResponseState, event: ToolInputDelta): Resp
 }
 
 const reduceToolInputEnd = (state: ResponseState, event: ToolInputEnd): ResponseState => {
-  const current = state.toolInputs[event.id] ?? { name: event.name, text: "" }
+  const current = state.toolInputs[event.id] ?? { name: event.name, namespace: event.namespace, text: "" }
   return {
     ...state,
     toolInputs: {
@@ -543,6 +556,7 @@ const reduceToolInputEnd = (state: ResponseState, event: ToolInputEnd): Response
       [event.id]: {
         ...current,
         name: event.name,
+        namespace: event.namespace,
         providerMetadata: event.providerMetadata ?? current.providerMetadata,
       },
     },
@@ -553,6 +567,7 @@ const toolCallContent = (event: ToolCall): ContentPart =>
   ToolCallPart.make({
     id: event.id,
     name: event.name,
+    namespace: event.namespace,
     input: event.input,
     ...(event.providerExecuted === undefined ? {} : { providerExecuted: event.providerExecuted }),
     ...(event.providerMetadata === undefined ? {} : { providerMetadata: event.providerMetadata }),
@@ -562,6 +577,7 @@ const toolResultContent = (event: ToolResult): ContentPart =>
   ToolResultPart.make({
     id: event.id,
     name: event.name,
+    namespace: event.namespace,
     result: event.result,
     ...(event.providerExecuted === undefined ? {} : { providerExecuted: event.providerExecuted }),
     ...(event.providerMetadata === undefined ? {} : { providerMetadata: event.providerMetadata }),

packages/ai/src/schema/messages.ts

@@ -135,6 +135,7 @@ export const ToolCallPart = Object.assign(
     type: Schema.Literal("tool-call"),
     id: Schema.String,
     name: Schema.String,
+    namespace: Schema.optional(Schema.String),
     input: Schema.Unknown,
     providerExecuted: Schema.optional(Schema.Boolean),
     cache: Schema.optional(CacheHint),
@@ -152,6 +153,7 @@ export const ToolResultPart = Object.assign(
     type: Schema.Literal("tool-result"),
     id: Schema.String,
     name: Schema.String,
+    namespace: Schema.optional(Schema.String),
     result: ToolResultValue,
     providerExecuted: Schema.optional(Schema.Boolean),
     cache: Schema.optional(CacheHint),
@@ -168,6 +170,7 @@ export const ToolResultPart = Object.assign(
       type: "tool-result",
       id: input.id,
       name: input.name,
+      namespace: input.namespace,
       result: ToolResultValue.make(input.result, input.resultType),
       providerExecuted: input.providerExecuted,
       cache: input.cache,
@@ -266,7 +269,7 @@ export namespace Message {
     make({ role: "tool", content: ["type" in result ? result : ToolResultPart.make(result)] })
 }
 
-export class ToolDefinition extends Schema.Class<ToolDefinition>("LLM.ToolDefinition")({
+const toolDefinitionFields = {
   name: Schema.String,
   description: Schema.String,
   inputSchema: JsonSchema,
@@ -274,15 +277,71 @@ export class ToolDefinition extends Schema.Class<ToolDefinition>("LLM.ToolDefini
   cache: Schema.optional(CacheHint),
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
   native: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
-}) {}
+}
+
+export type ToolDefinitionInput = Schema.Struct.Type<typeof toolDefinitionFields>
+
+export class ToolDefinition extends Schema.Class<ToolDefinition>("LLM.ToolDefinition")({
+  type: Schema.Literal("tool"),
+  ...toolDefinitionFields,
+}) {
+  constructor(input: ToolDefinitionInput) {
+    super({ ...input, type: "tool" })
+  }
+}
 
 export namespace ToolDefinition {
-  export type Input = ToolDefinition | ConstructorParameters<typeof ToolDefinition>[0]
+  export type Input = ToolDefinition | ToolDefinitionInput
 
   /** Normalize tool definition input into the canonical `ToolDefinition` class. */
   export const make = (input: Input) => (input instanceof ToolDefinition ? input : new ToolDefinition(input))
 }
 
+export type ToolNamespace = {
+  readonly type: "namespace"
+  readonly name: string
+  readonly description?: string
+  readonly tools: ReadonlyArray<ToolEntry>
+}
+
+export type ToolNamespaceInput = Omit<ToolNamespace, "type" | "tools"> & {
+  readonly tools: ReadonlyArray<ToolEntryInput>
+}
+export type ToolNamespaceEntryInput = ToolNamespaceInput & { readonly type: "namespace" }
+
+export const ToolNamespace: Schema.Codec<ToolNamespace> & {
+  readonly make: (input: ToolNamespace | ToolNamespaceInput) => ToolNamespace
+} = Object.assign(
+  Schema.Struct({
+    type: Schema.Literal("namespace"),
+    name: Schema.String,
+    description: Schema.optional(Schema.UndefinedOr(Schema.String)),
+    tools: Schema.Array(Schema.suspend((): Schema.Codec<ToolEntry> => ToolEntry)),
+  }).annotate({ identifier: "LLM.ToolNamespace" }),
+  {
+    make: (input: ToolNamespace | ToolNamespaceInput): ToolNamespace => ({
+      ...input,
+      type: "namespace",
+      tools: input.tools.map(ToolEntry.make),
+    }),
+  },
+)
+
+export type ToolEntry = ToolDefinition | ToolNamespace
+export type ToolEntryInput = ToolDefinition.Input | ToolNamespaceEntryInput
+export const ToolEntry: Schema.Codec<ToolEntry> & {
+  readonly make: (input: ToolEntryInput) => ToolEntry
+} = Object.assign(
+  Schema.Union([ToolDefinition, ToolNamespace]).pipe(
+    Schema.toTaggedUnion("type"),
+    Schema.annotate({ identifier: "LLM.ToolEntry" }),
+  ),
+  {
+    make: (input: ToolEntryInput): ToolEntry =>
+      "type" in input && input.type === "namespace" ? ToolNamespace.make(input) : ToolDefinition.make(input),
+  },
+)
+
 export class ToolChoice extends Schema.Class<ToolChoice>("LLM.ToolChoice")({
   type: Schema.Literals(["auto", "none", "required", "tool"]),
   name: Schema.optional(Schema.String),
@@ -312,7 +371,7 @@ const requestSchema = Schema.Struct({
   model: LanguageModelSchema,
   system: Schema.Array(SystemPart),
   messages: Schema.Array(Message),
-  tools: Schema.Array(ToolDefinition),
+  tools: Schema.Array(ToolEntry),
   toolChoice: Schema.optional(ToolChoice),
   generation: Schema.optional(GenerationOptions),
   providerOptions: Schema.optional(ProviderOptions),

packages/ai/src/tool-history.ts

@@ -37,7 +37,13 @@ function missingToolResults(calls: Iterable<ToolCallPart>) {
   return new Message({
     role: "tool",
     content: [...calls].map((call) =>
-      ToolResultPart.make({ id: call.id, name: call.name, result: MISSING_TOOL_RESULT, resultType: "error" }),
+      ToolResultPart.make({
+        id: call.id,
+        name: call.name,
+        namespace: call.namespace,
+        result: MISSING_TOOL_RESULT,
+        resultType: "error",
+      }),
     ),
   })
 }
@@ -47,7 +53,7 @@ function normalizeToolMessage(message: Message, pending: Map<string, ToolCallPar
     if (part.type !== "tool-result" || part.providerExecuted === true) return part
     const call = pending.get(part.id)
     if (call) pending.delete(part.id)
-    return normalizeToolResult(part, call?.name ?? part.name)
+    return normalizeToolResult(part, call)
   })
   if (content.length === 0) return undefined
   if (content.every((part, index) => part === message.content[index])) return message
@@ -61,8 +67,11 @@ function normalizeToolMessage(message: Message, pending: Map<string, ToolCallPar
   })
 }
 
-function normalizeToolResult(part: ToolResultPart, name: string): ToolResultPart {
-  const named = part.name === name ? part : { ...part, name }
+function normalizeToolResult(part: ToolResultPart, call: ToolCallPart | undefined): ToolResultPart {
+  const named =
+    call === undefined || (part.name === call.name && part.namespace === call.namespace)
+      ? part
+      : { ...part, name: call.name, namespace: call.namespace }
   if (named.result.type === "text" && named.result.value === "")
     return { ...named, result: { type: "text", value: EMPTY_TOOL_OUTPUT } }
   if (named.result.type === "error" && named.result.value === "")

packages/ai/src/tool-runtime.ts

@@ -21,10 +21,11 @@ export interface DispatchResult extends ToolSettlement {
 
 /** Execute one canonical tool call without owning provider IO or continuation. */
 export const dispatch = (tools: Tools, call: ToolCallPart): Effect.Effect<DispatchResult> => {
-  const tool = tools[call.name]
-  if (!tool) return Effect.succeed(result(call, { type: "error", value: `Unknown tool: ${call.name}` }))
+  const name = call.namespace === undefined ? call.name : `${call.namespace}.${call.name}`
+  const tool = tools[name]
+  if (!tool) return Effect.succeed(result(call, { type: "error", value: `Unknown tool: ${name}` }))
   if (!tool.execute)
-    return Effect.succeed(result(call, { type: "error", value: `Tool has no execute handler: ${call.name}` }))
+    return Effect.succeed(result(call, { type: "error", value: `Tool has no execute handler: ${name}` }))
 
   return decodeAndExecute(tool, call).pipe(
     Effect.map((value) => result(call, value)),
@@ -38,7 +39,11 @@ const decodeAndExecute = (tool: AnyTool, call: ToolCallPart): Effect.Effect<Tool
   tool._decode(call.input).pipe(
     Effect.mapError((error) => new ToolFailure({ message: `Invalid tool input: ${error.message}` })),
     Effect.flatMap((decoded) =>
-      tool.execute!(decoded, { id: call.id, name: call.name }).pipe(
+      tool.execute!(decoded, {
+        id: call.id,
+        name: call.name,
+        namespace: call.namespace,
+      }).pipe(
         Effect.flatMap((value) =>
           tool._encode(value).pipe(
             Effect.mapError(
@@ -71,6 +76,7 @@ const result = (call: ToolCallPart, value: ToolResultValueType | ToolSettlement,
             LLMEvent.toolError({
               id: call.id,
               name: call.name,
+              namespace: call.namespace,
               message: String(settlement.result.value),
               error,
               providerMetadata: call.providerMetadata,
@@ -78,6 +84,7 @@ const result = (call: ToolCallPart, value: ToolResultValueType | ToolSettlement,
             LLMEvent.toolResult({
               id: call.id,
               name: call.name,
+              namespace: call.namespace,
               result: settlement.result,
               providerMetadata: call.providerMetadata,
             }),
@@ -86,6 +93,7 @@ const result = (call: ToolCallPart, value: ToolResultValueType | ToolSettlement,
             LLMEvent.toolResult({
               id: call.id,
               name: call.name,
+              namespace: call.namespace,
               result: settlement.result,
               output: settlement.output,
               providerMetadata: call.providerMetadata,

packages/ai/src/tool.ts

@@ -16,6 +16,7 @@ export type ToolSchema<T> = Schema.Codec<T, any, never, never>
 export interface ToolExecuteContext {
   readonly id: ToolCallPart["id"]
   readonly name: ToolCallPart["name"]
+  readonly namespace?: ToolCallPart["namespace"]
 }
 
 export type ToolExecute<Parameters extends ToolSchema<any>, Success extends ToolSchema<any>> = (

packages/ai/test/cache-policy.test.ts

@@ -215,6 +215,35 @@ describe("applyCachePolicy", () => {
     }),
   )
 
+  it.effect("deduplicates tools before counting cache hints", () =>
+    Effect.gen(function* () {
+      const manual = new CacheHint({ type: "ephemeral" })
+      const duplicate = (description: string) => ({
+        name: "lookup",
+        description,
+        inputSchema: { type: "object" },
+        cache: manual,
+      })
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: anthropicModel,
+          tools: [
+            duplicate("first"),
+            duplicate("second"),
+            duplicate("third"),
+            duplicate("fourth"),
+            { name: "lookup", description: "final", inputSchema: { type: "object" } },
+          ],
+          cache: { tools: true },
+        }),
+      )
+
+      expect(prepared.body.tools).toEqual([
+        expect.objectContaining({ name: "lookup", description: "final", cache_control: { type: "ephemeral" } }),
+      ])
+    }),
+  )
+
   it.effect("auto policy preserves manual CacheHints on other parts", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
@@ -281,6 +310,30 @@ describe("applyCachePolicy", () => {
     }),
   )
 
+  test("marks the final leaf inside a tool namespace", () => {
+    const request = LLM.request({
+      model: anthropicModel,
+      tools: [
+        {
+          type: "namespace",
+          name: "crm",
+          tools: [
+            { name: "lookup", description: "lookup", inputSchema: {} },
+            { name: "orders", description: "orders", inputSchema: {} },
+          ],
+        },
+      ],
+      cache: { tools: true },
+    })
+    const applied = applyCachePolicy(request)
+    const namespace = applied.tools[0]
+
+    expect(namespace?.type).toBe("namespace")
+    if (namespace?.type !== "namespace") throw new Error("Expected namespace")
+    expect(namespace.tools[0]).not.toHaveProperty("cache")
+    expect(namespace.tools[1]).toHaveProperty("cache", { type: "ephemeral" })
+  })
+
   it.effect("ttlSeconds in the policy flows through to wire markers", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(

packages/ai/test/compile.test.ts

@@ -1,8 +1,16 @@
 import { describe, expect, test } from "bun:test"
 import { Effect, Ref, Schema } from "effect"
 import { HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
-import { LLM, LLMRequest, Message, ToolCallPart, ToolDefinition, mergeProviderOptions } from "../src/index.js"
-import { AnthropicMessages, OpenAIChat } from "../src/protocols.js"
+import {
+  LLM,
+  LLMRequest,
+  Message,
+  ToolCallPart,
+  ToolDefinition,
+  ToolNamespace,
+  mergeProviderOptions,
+} from "../src/index.js"
+import { AnthropicMessages, OpenAIChat, OpenAIResponses } from "../src/protocols.js"
 import { Auth, LLMClient } from "../src/route.js"
 import { compileRequest } from "../src/route/client.js"
 import { it } from "./lib/effect.js"
@@ -106,6 +114,58 @@ describe("request option precedence", () => {
     }),
   )
 
+  it.effect("deduplicates tools within each namespace", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model: OpenAIResponses.route.model({ id: "gpt-5.4" }),
+          tools: [
+            ToolDefinition.make({ name: "crm", description: "Top-level CRM tool", inputSchema: {} }),
+            ToolNamespace.make({
+              name: "crm",
+              description: "CRM tools",
+              tools: [
+                ToolDefinition.make({ name: "lookup", description: "old", inputSchema: {} }),
+                ToolDefinition.make({ name: "search", description: "search", inputSchema: {} }),
+                ToolDefinition.make({ name: "lookup", description: "new", inputSchema: {} }),
+              ],
+            }),
+            ToolNamespace.make({
+              name: "support",
+              description: "Support tools",
+              tools: [ToolDefinition.make({ name: "lookup", description: "support", inputSchema: {} })],
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.tools).toEqual([
+        {
+          type: "function",
+          name: "crm",
+          description: "Top-level CRM tool",
+          parameters: {},
+          strict: false,
+        },
+        {
+          type: "namespace",
+          name: "crm",
+          description: "CRM tools",
+          tools: [
+            { type: "function", name: "lookup", description: "new", parameters: {}, strict: false },
+            { type: "function", name: "search", description: "search", parameters: {}, strict: false },
+          ],
+        },
+        {
+          type: "namespace",
+          name: "support",
+          description: "Support tools",
+          tools: [{ type: "function", name: "lookup", description: "support", parameters: {}, strict: false }],
+        },
+      ])
+    }),
+  )
+
   it.effect("normalizes tool history before protocol lowering", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(

packages/ai/test/llm.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test"
-import { CacheHint, LLM, LLMResponse } from "../src/index.js"
+import { Schema } from "effect"
+import { CacheHint, LLM, LLMResponse, ToolEntry, ToolNamespace } from "../src/index.js"
 import * as OpenAIChat from "../src/protocols/openai-chat.js"
 import * as OpenAIResponses from "../src/protocols/openai-responses.js"
 import {
@@ -17,6 +18,52 @@ const chatRoute = OpenAIChat.route
 const responsesRoute = OpenAIResponses.route
 
 describe("llm constructors", () => {
+  test("normalizes recursive tool namespaces", () => {
+    const request = LLM.request({
+      model: LanguageModel.make({ id: "fake-model", provider: "fake", route: responsesRoute }),
+      tools: [
+        {
+          type: "namespace",
+          name: "crm",
+          description: "Customer management",
+          tools: [
+            { name: "lookup", description: "Look up a customer", inputSchema: { type: "object" } },
+            {
+              type: "namespace",
+              name: "orders",
+              tools: [{ name: "list", description: "List orders", inputSchema: { type: "object" } }],
+            },
+          ],
+        },
+      ],
+    })
+
+    expect(request.tools[0]).toEqual({
+      type: "namespace",
+      name: "crm",
+      description: "Customer management",
+      tools: [
+        expect.objectContaining({ type: "tool", name: "lookup" }),
+        {
+          type: "namespace",
+          name: "orders",
+          description: undefined,
+          tools: [expect.objectContaining({ type: "tool", name: "list" })],
+        },
+      ],
+    })
+    expect(request.tools[0]).toEqual(
+      ToolNamespace.make({
+        name: "crm",
+        description: "Customer management",
+        tools: request.tools[0]!.type === "namespace" ? request.tools[0].tools : [],
+      }),
+    )
+    expect(Schema.decodeUnknownSync(ToolEntry)(Schema.encodeUnknownSync(ToolEntry)(request.tools[0]))).toEqual(
+      request.tools[0],
+    )
+  })
+
   test("builds canonical schema classes from ergonomic input", () => {
     const request = LLM.request({
       id: "req_1",

packages/ai/test/provider/explicit-compaction.test.ts

@@ -1,6 +1,6 @@
 import { expect } from "bun:test"
 import { Effect, Schema } from "effect"
-import { LLM, LLMRequest, Message } from "../../src/index.js"
+import { LLM, LLMRequest, Message, ToolDefinition } from "../../src/index.js"
 import { LLMClient, Route } from "../../src/route/client.js"
 import { Auth } from "../../src/route/auth.js"
 import { Endpoint } from "../../src/route/endpoint.js"
@@ -134,7 +134,12 @@ for (const model of [
         [
           LLMRequest.update(request, {
             tools: [
-              { name: "unsupported", description: "Generation only", inputSchema: {}, native: { unsupported: {} } },
+              ToolDefinition.make({
+                name: "unsupported",
+                description: "Generation only",
+                inputSchema: {},
+                native: { unsupported: {} },
+              }),
             ],
           }),
           "InvalidRequest",

packages/ai/test/provider/open-responses-lifecycle.test.ts

@@ -326,7 +326,6 @@ describe("Open Responses basic-item lifecycles", () => {
       ])
     }),
   )
-
   it.effect("mints an id for a done-only tool that never had one", () =>
     Effect.gen(function* () {
       const events = yield* collect(
@@ -357,9 +356,16 @@ describe("Open Responses basic-item lifecycles", () => {
       const events = yield* collect({ type: "response.output_item.done", item }, completed)
       const providerMetadata = { "openai-compatible": { itemId: "fc_1" } }
       expect(events.filter((event) => event.type.startsWith("tool-"))).toEqual([
-        { type: "tool-input-start", id: "call_1", name: "lookup", providerMetadata },
-        { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata },
-        { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" }, providerMetadata },
+        { type: "tool-input-start", id: "call_1", name: "lookup", namespace: undefined, providerMetadata },
+        { type: "tool-input-end", id: "call_1", name: "lookup", namespace: undefined, providerMetadata },
+        {
+          type: "tool-call",
+          id: "call_1",
+          name: "lookup",
+          namespace: undefined,
+          input: { query: "weather" },
+          providerMetadata,
+        },
       ])
       expect(events.filter(LLMEvent.is.finish)).toEqual([
         {

packages/ai/test/provider/openai-compatible-responses.test.ts

@@ -171,6 +171,66 @@ describe("Open Responses-compatible route", () => {
     }),
   )
 
+  it.effect("flattens tool namespaces", () =>
+    Effect.gen(function* () {
+      const model = configure({ apiKey: "test-key", baseURL: "https://responses.example.test/v1" }).model(
+        "example-model",
+      )
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          tools: [
+            {
+              type: "namespace",
+              name: "acme",
+              tools: [
+                {
+                  type: "namespace",
+                  name: "billing",
+                  tools: [ToolDefinition.make({ name: "lookup", description: "Lookup billing", inputSchema: {} })],
+                },
+                ToolDefinition.make({ name: "users", description: "Lookup users", inputSchema: {} }),
+              ],
+            },
+          ],
+        }),
+      )
+
+      expect(prepared.body.tools).toEqual([
+        {
+          type: "function",
+          name: "acme_billing_lookup",
+          description: "Lookup billing",
+          parameters: {},
+          strict: false,
+        },
+        { type: "function", name: "acme_users", description: "Lookup users", parameters: {}, strict: false },
+      ])
+    }),
+  )
+
+  it.effect("flattens tool namespaces in history", () =>
+    Effect.gen(function* () {
+      const model = configure({ apiKey: "test-key", baseURL: "https://responses.example.test/v1" }).model(
+        "example-model",
+      )
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant({ type: "tool-call", id: "call_1", name: "lookup", namespace: "crm", input: {} }),
+            Message.tool({ id: "call_1", name: "lookup", namespace: "crm", result: "done", resultType: "text" }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.input).toEqual([
+        { type: "function_call", call_id: "call_1", name: "crm_lookup", namespace: undefined, arguments: "{}" },
+        { type: "function_call_output", call_id: "call_1", output: "done" },
+      ])
+    }),
+  )
+
   it.effect("lowers canonical parallel tool control", () =>
     Effect.gen(function* () {
       const model = configure({

packages/ai/test/provider/openai-responses.test.ts

@@ -12,6 +12,7 @@ import {
   LanguageModel,
   ToolCallPart,
   ToolDefinition,
+  ToolNamespace,
   ToolResultPart,
   TransportError,
   Usage,
@@ -143,6 +144,94 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
+  it.effect("lowers tool namespaces without flattening leaf names", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          prompt: "Find a customer and their orders.",
+          tools: [
+            ToolNamespace.make({
+              name: "crm",
+              description: "Customer management",
+              tools: [
+                ToolDefinition.make({ name: "lookup", description: "Look up a customer", inputSchema: {} }),
+                ToolDefinition.make({ name: "orders", description: "List customer orders", inputSchema: {} }),
+              ],
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.tools).toEqual([
+        {
+          type: "namespace",
+          name: "crm",
+          description: "Customer management",
+          tools: [
+            { type: "function", name: "lookup", description: "Look up a customer", parameters: {}, strict: false },
+            { type: "function", name: "orders", description: "List customer orders", parameters: {}, strict: false },
+          ],
+        },
+      ])
+    }),
+  )
+
+  it.effect("flattens nested levels within a native tool namespace", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          tools: [
+            {
+              type: "namespace",
+              name: "crm",
+              description: "Customer management",
+              tools: [
+                {
+                  type: "namespace",
+                  name: "orders",
+                  description: "Order management",
+                  tools: [ToolDefinition.make({ name: "list", description: "List orders", inputSchema: {} })],
+                },
+              ],
+            },
+          ],
+        }),
+      )
+
+      expect(prepared.body.tools).toEqual([
+        {
+          type: "namespace",
+          name: "crm",
+          description: "Customer management",
+          tools: [{ type: "function", name: "orders_list", description: "List orders", parameters: {}, strict: false }],
+        },
+      ])
+    }),
+  )
+
+  it.effect("defaults tool namespace descriptions", () =>
+    Effect.gen(function* () {
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          tools: [
+            {
+              type: "namespace",
+              name: "crm",
+              tools: [ToolDefinition.make({ name: "lookup", description: "Look up a customer", inputSchema: {} })],
+            },
+          ],
+        }),
+      )
+
+      expect(prepared.body.tools).toEqual([
+        expect.objectContaining({ type: "namespace", name: "crm", description: "Tools in the crm namespace." }),
+      ])
+    }),
+  )
+
   it.effect("rejects invalid hosted image generation options locally", () =>
     Effect.gen(function* () {
       const error = yield* compileRequest(
@@ -2130,6 +2219,71 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
+  it.effect("preserves tool namespaces through streaming and history replay", () =>
+    Effect.gen(function* () {
+      const item = {
+        type: "function_call",
+        id: "fc_1",
+        call_id: "call_1",
+        namespace: "crm",
+        name: "lookup",
+        arguments: "",
+      }
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents(
+              { type: "response.output_item.added", output_index: 0, item },
+              {
+                type: "response.function_call_arguments.delta",
+                output_index: 0,
+                item_id: "fc_1",
+                delta: '{"id":"123"}',
+              },
+              {
+                type: "response.output_item.done",
+                output_index: 0,
+                item: { ...item, arguments: '{"id":"123"}' },
+              },
+              { type: "response.completed", response: { id: "resp_1" } },
+            ),
+          ),
+        ),
+      )
+
+      const toolEvents = response.events.filter((event) => event.type.startsWith("tool-"))
+      expect(toolEvents).toEqual([
+        expect.objectContaining({ type: "tool-input-start", name: "lookup", namespace: "crm" }),
+        expect.objectContaining({ type: "tool-input-delta", name: "lookup", namespace: "crm" }),
+        expect.objectContaining({ type: "tool-input-end", name: "lookup", namespace: "crm" }),
+        expect.objectContaining({ type: "tool-call", name: "lookup", namespace: "crm", input: { id: "123" } }),
+      ])
+      expect(response.message.content).toEqual([
+        expect.objectContaining({ type: "tool-call", name: "lookup", namespace: "crm", input: { id: "123" } }),
+      ])
+
+      const prepared = yield* compileRequest(
+        LLM.request({
+          model,
+          messages: [
+            response.message,
+            Message.tool({ id: "call_1", name: "lookup", namespace: "crm", result: { customer: "Ada" } }),
+          ],
+        }),
+      )
+      expect(prepared.body.input).toEqual([
+        {
+          type: "function_call",
+          id: "fc_1",
+          call_id: "call_1",
+          namespace: "crm",
+          name: "lookup",
+          arguments: '{"id":"123"}',
+        },
+        { type: "function_call_output", call_id: "call_1", output: '{"customer":"Ada"}' },
+      ])
+    }),
+  )
   it.effect("routes reasoning summary events by output index", () =>
     Effect.gen(function* () {
       const response = yield* LLMClient.generate(request).pipe(

packages/ai/test/tool-history.test.ts

@@ -15,13 +15,7 @@ describe("tool history normalization", () => {
       Message.assistant(toolCall("trailing")),
     ])
 
-    expect(normalized.map((message) => message.role)).toEqual([
-      "assistant",
-      "tool",
-      "tool",
-      "user",
-      "assistant",
-    ])
+    expect(normalized.map((message) => message.role)).toEqual(["assistant", "tool", "tool", "user", "assistant"])
     expect(normalized[1]?.content[0]).toMatchObject({ type: "tool-result", id: "first", name: "first" })
     expect(normalized[2]?.content).toEqual([
       { type: "tool-result", id: "second", name: "second", result: { type: "error", value: "Tool result missing" } },
@@ -74,4 +68,13 @@ describe("tool history normalization", () => {
 
     expect(normalizeToolHistory([orphan, hosted])).toEqual([orphan, hosted])
   })
+
+  test("uses a matching call as the complete tool identity", () => {
+    const normalized = normalizeToolHistory([
+      Message.assistant(ToolCallPart.make({ id: "call_1", name: "lookup", input: {} })),
+      Message.tool(ToolResultPart.make({ id: "call_1", name: "wrong", namespace: "stale", result: "done" })),
+    ])
+
+    expect(normalized[1]?.content[0]).toMatchObject({ name: "lookup", namespace: undefined })
+  })
 })

packages/ai/test/tool-runtime.test.ts

@@ -7,6 +7,7 @@ import {
   LLMEvent,
   LLMRequest,
   LLMResponse,
+  ToolCallPart,
   ToolChoice,
   ToolOutput,
   toDefinitions,
@@ -36,6 +37,27 @@ const baseRequest = LLM.request({
 })
 const weatherFailureCause = new Error("weather lookup denied")
 
+test("dispatches namespaced calls by qualified identity", async () => {
+  let context: ToolExecuteContext | undefined
+  const lookup = Tool.make({
+    description: "Look up a customer.",
+    parameters: Schema.Struct({}),
+    success: Schema.String,
+    execute: (_, value) => {
+      context = value
+      return Effect.succeed("customer")
+    },
+  })
+  const call = ToolCallPart.make({ id: "call_1", namespace: "crm", name: "lookup", input: {} })
+  const result = await Effect.runPromise(
+    ToolRuntime.dispatch({ "crm.lookup": lookup, lookup: schema_only_weather }, call),
+  )
+
+  expect(result.result).toEqual({ type: "text", value: "customer" })
+  expect(context).toEqual({ id: "call_1", namespace: "crm", name: "lookup" })
+  expect(result.events).toEqual([expect.objectContaining({ type: "tool-result", namespace: "crm", name: "lookup" })])
+})
+
 const get_weather = Tool.make({
   description: "Get current weather for a city.",
   parameters: Schema.Struct({ city: Schema.String }),

packages/app/src/new-session/layout.ts

@@ -1,2 +1,2 @@
-/** Inline new-session content width — keep in sync with session composer `placement === "inline"`. */
-export const NEW_SESSION_CONTENT_WIDTH = "w-full max-w-[720px] px-0"
+/** Keep the prompt width and side padding in sync with SessionComposerRegion. */
+export const NEW_SESSION_CONTENT_WIDTH = "w-full px-3 md:max-w-[1000px] md:mx-auto"

packages/app/src/new-session/view.tsx

@@ -54,9 +54,9 @@ export function NewSessionView(props: {
         data-component="new-session"
         class="relative flex-1 min-h-0 overflow-hidden rounded-[10px] bg-v2-background-bg-base shadow-[var(--v2-elevation-raised)]"
       >
-        <div class="absolute inset-x-0 top-[25.375%] flex justify-center px-6">
+        <div class="absolute inset-x-0 top-[25.375%] flex justify-center">
           <div class={NEW_SESSION_CONTENT_WIDTH}>
-            <Wordmark class="h-auto w-full text-v2-background-bg-inverse" />
+            <Wordmark class="mx-auto h-auto w-full max-w-[720px] text-v2-background-bg-inverse" />
             <div class="mt-8 flex flex-col gap-8">
               <Composer model={props.composer} />
               <Show when={props.project.empty()}>

packages/console/app/src/routes/zen/util/handler.ts

@@ -1109,6 +1109,8 @@ export async function handler(
     authInfo = authInfo!
 
     const cost = centsToMicroCents(totalCostInCent)
+    // Keep period bounds and persisted timestamps on one snapshot when a queued write crosses a reset boundary.
+    const trackedAt = new Date()
 
     // For hot workspaces, batch balance/usage updates through Redis to avoid
     // row-level lock contention on BillingTable/UserTable. Returns the amount
@@ -1149,7 +1151,7 @@ export async function handler(
           if (billingSource === "subscription") {
             const plan = authInfo.billing.subscription!.plan
             const black = BlackData.getLimits({ plan })
-            const week = getWeekBounds(new Date())
+            const week = getWeekBounds(trackedAt)
             const rollingWindowSeconds = black.rollingWindow * 3600
             return [
               db
@@ -1157,11 +1159,17 @@ export async function handler(
                 .set({
                   fixedUsage: sql`
               CASE
+                WHEN ${SubscriptionTable.timeFixedUpdated} >= ${week.end} THEN ${SubscriptionTable.fixedUsage}
                 WHEN ${SubscriptionTable.timeFixedUpdated} >= ${week.start} THEN ${SubscriptionTable.fixedUsage} + ${cost}
                 ELSE ${cost}
               END
             `,
-                  timeFixedUpdated: sql`now()`,
+                  timeFixedUpdated: sql`
+              CASE
+                WHEN ${SubscriptionTable.timeFixedUpdated} > ${trackedAt} THEN ${SubscriptionTable.timeFixedUpdated}
+                ELSE ${trackedAt}
+              END
+            `,
                   rollingUsage: sql`
               CASE
                 WHEN UNIX_TIMESTAMP(${SubscriptionTable.timeRollingUpdated}) >= UNIX_TIMESTAMP(now()) - ${rollingWindowSeconds} THEN ${SubscriptionTable.rollingUsage} + ${cost}
@@ -1185,8 +1193,8 @@ export async function handler(
           }
           if (billingSource === "lite") {
             const lite = LiteData.getLimits()
-            const week = getWeekBounds(new Date())
-            const month = getMonthlyBounds(new Date(), authInfo.lite!.timeCreated)
+            const week = getWeekBounds(trackedAt)
+            const month = getMonthlyBounds(trackedAt, authInfo.lite!.timeCreated)
             const rollingWindowSeconds = lite.rollingWindow * 3600
             const quotaCost = Math.round(cost * modelInfo.costMultiplier)
             return [
@@ -1195,18 +1203,30 @@ export async function handler(
                 .set({
                   monthlyUsage: sql`
               CASE
+                WHEN ${LiteTable.timeMonthlyUpdated} >= ${month.end} THEN ${LiteTable.monthlyUsage}
                 WHEN ${LiteTable.timeMonthlyUpdated} >= ${month.start} THEN ${LiteTable.monthlyUsage} + ${quotaCost}
                 ELSE ${quotaCost}
               END
             `,
-                  timeMonthlyUpdated: sql`now()`,
+                  timeMonthlyUpdated: sql`
+              CASE
+                WHEN ${LiteTable.timeMonthlyUpdated} > ${trackedAt} THEN ${LiteTable.timeMonthlyUpdated}
+                ELSE ${trackedAt}
+              END
+            `,
                   weeklyUsage: sql`
               CASE
+                WHEN ${LiteTable.timeWeeklyUpdated} >= ${week.end} THEN ${LiteTable.weeklyUsage}
                 WHEN ${LiteTable.timeWeeklyUpdated} >= ${week.start} THEN ${LiteTable.weeklyUsage} + ${quotaCost}
                 ELSE ${quotaCost}
               END
             `,
-                  timeWeeklyUpdated: sql`now()`,
+                  timeWeeklyUpdated: sql`
+              CASE
+                WHEN ${LiteTable.timeWeeklyUpdated} > ${trackedAt} THEN ${LiteTable.timeWeeklyUpdated}
+                ELSE ${trackedAt}
+              END
+            `,
                   rollingUsage: sql`
               CASE
                 WHEN UNIX_TIMESTAMP(${LiteTable.timeRollingUpdated}) >= UNIX_TIMESTAMP(now()) - ${rollingWindowSeconds} THEN ${LiteTable.rollingUsage} + ${quotaCost}

packages/core/src/aisdk.ts

@@ -416,8 +416,9 @@ function callOptions(
   modelID: ID,
   optionKey: string,
 ): LanguageModelV3CallOptions {
+  const flattened = ProviderShared.flattenToolRequest(request)
   return {
-    prompt: prompt(request),
+    prompt: prompt(flattened.request),
     maxOutputTokens: request.generation?.maxTokens,
     temperature: request.generation?.temperature,
     stopSequences: request.generation?.stop === undefined ? undefined : [...request.generation.stop],
@@ -426,7 +427,7 @@ function callOptions(
     presencePenalty: request.generation?.presencePenalty,
     frequencyPenalty: request.generation?.frequencyPenalty,
     seed: request.generation?.seed,
-    tools: request.tools.map(tool),
+    tools: flattened.tools.map(tool),
     toolChoice: toolChoice(request.toolChoice),
     headers: request.http?.headers,
     providerOptions: requestProviderOptions(request.providerOptions, packageName, modelID, optionKey),

packages/core/src/plugin/provider/github-copilot.ts

@@ -1,11 +1,11 @@
 import type { IntegrationOAuthMethodRegistration } from "@opencode-ai/plugin/effect/integration"
+import type { SessionRequestKind } from "@opencode-ai/plugin/effect/session"
 import { Effect, Option, Schema, Semaphore, Stream } from "effect"
 import { Catalog } from "../../catalog.js"
 import { Credential } from "../../credential.js"
 import { Bus } from "../../bus.js"
 import { CopilotModels } from "../../github-copilot/models.js"
 import { App } from "../../app.js"
-import { Agent } from "../../agent.js"
 import { Integration } from "../../integration.js"
 import { Model } from "../../model.js"
 import { define } from "@opencode-ai/plugin/effect/plugin"
@@ -259,7 +259,7 @@ export const GithubCopilotPlugin = define({
           const session = yield* ctx.session
             .get({ sessionID: evt.sessionID })
             .pipe(Effect.orElseSucceed(() => undefined))
-          const interaction = interactionType(evt.agent, session?.parentID !== undefined)
+          const interaction = interactionType(evt.kind, session?.parentID !== undefined)
           evt.headers["X-Interaction-Type"] = interaction
           if (interaction !== "conversation-agent") evt.headers["x-initiator"] = "agent"
         }),
@@ -391,9 +391,9 @@ function applyHeaders(
 
 // Mirrors the Copilot client's X-Interaction-Type vocabulary: the agent loop is the default,
 // nested sessions are subagents, and title/compaction are the two utility overrides.
-export function interactionType(agent: Agent.ID, child: boolean) {
-  if (agent === Agent.ID.make("title")) return "conversation-background"
-  if (agent === Agent.ID.make("compaction")) return "conversation-compaction"
+export function interactionType(kind: SessionRequestKind, child: boolean) {
+  if (kind === "title") return "conversation-background"
+  if (kind === "compaction") return "conversation-compaction"
   if (child) return "conversation-subagent"
   return "conversation-agent"
 }

packages/core/src/session/compaction.ts

@@ -396,6 +396,7 @@ export const layer = Layer.effect(
         messages: history.messages,
       })
       const prepared = yield* input.prepare({
+        kind: "compaction",
         scope: {
           session: context.session,
           agentID: Agent.ID.make("compaction"),

packages/core/src/session/generate.ts

@@ -38,6 +38,7 @@ export const generate = Effect.fn("SessionGenerate.generate")(function* (input:
       messages: history.messages,
     })
     const prepared = yield* context.prepare({
+      kind: "generate",
       scope: { session: selection.session, agentID: selection.agent.id, model, tools: selection.tools },
       transcript: {
         system: transcript.system,

packages/core/src/session/model-request.ts

@@ -2,6 +2,7 @@ export * as SessionModelRequest from "./model-request.js"
 
 import { HttpOptions, LanguageModel, LLM, LLMRequest, Message, SystemPart } from "@opencode-ai/ai"
 import type { StreamOptions } from "@opencode-ai/ai/route"
+import type { SessionRequestKind } from "@opencode-ai/plugin/effect/session"
 import type { Agent } from "@opencode-ai/schema/agent"
 import type { Model } from "@opencode-ai/schema/model"
 import type { Content } from "@opencode-ai/schema/tool"
@@ -59,6 +60,8 @@ export interface Prepared {
 }
 
 interface PrepareInput {
+  /** Which Session flow issues this request; request hooks receive it alongside the Session identity. */
+  readonly kind: SessionRequestKind
   readonly scope: {
     readonly session: SessionSchema.Info
     readonly agentID: Agent.ID
@@ -197,6 +200,7 @@ interface HookScope {
   readonly sessionID: SessionSchema.ID
   readonly agent: Agent.ID
   readonly model: Model.Ref
+  readonly kind: SessionRequestKind
 }
 
 const sessionHeaders = (session: Pick<SessionSchema.Info, "id" | "parentID" | "projectID">, app: App.Info) => ({
@@ -325,7 +329,7 @@ export const layer = Layer.effect(
       )
       const request = yield* applyModelHooks(
         hooks,
-        { sessionID: session.id, agent: input.scope.agentID, model: resolved.ref },
+        { sessionID: session.id, agent: input.scope.agentID, model: resolved.ref, kind: input.kind },
         LLM.request({
           model,
           http: {
@@ -356,6 +360,7 @@ export const layer = Layer.effect(
             sessionID: session.id,
             agent: input.scope.agentID,
             model: resolved.ref,
+            kind: input.kind,
           })
         : undefined
       const options: StreamOptions = {

packages/core/src/session/runner/llm.ts

@@ -217,6 +217,7 @@ const layer = Layer.effect(
           messages: loaded.messages,
         })
         const prepared = yield* context.prepare({
+          kind: "primary",
           scope: { session: loaded.session, agentID: loaded.agent.id, model: loaded.model, tools: loaded.tools },
           transcript: {
             system: transcript.system,

packages/core/src/session/title.ts

@@ -64,6 +64,7 @@ export const layer = Layer.effect(
           : Effect.void,
       )
       const prepared = yield* context.prepare({
+        kind: "title",
         scope: { session: input.session, agentID: input.agent.id, model: input.model },
         transcript: {
           system: input.agent.system ? [SystemPart.make(input.agent.system)] : [],

packages/core/src/tool/runtime.ts

@@ -18,6 +18,7 @@ const jsonSchemas = Effect.runSync(
 )
 
 export const definition = (tool: Tool.Info<any, any>): ToolDefinition => ({
+  type: "tool",
   name: effectiveName(tool),
   description: tool.description,
   inputSchema: inputJsonSchema(tool.input),

packages/core/test/plugin/provider-azure.test.ts

@@ -281,6 +281,7 @@ describe("AzurePlugin", () => {
             sessionID: Session.ID.make("ses_azure"),
             agent: Agent.ID.make("build"),
             model,
+            kind: "primary",
             request: new Request("https://test-resource.openai.azure.com/openai/v1/responses", {
               headers: { "api-key": "stored-token", "x-keep": "yes" },
             }),
@@ -295,6 +296,7 @@ describe("AzurePlugin", () => {
             sessionID: Session.ID.make("ses_foundry"),
             agent: Agent.ID.make("build"),
             model,
+            kind: "primary",
             request: new Request("https://test-resource.services.ai.azure.com/anthropic/v1/messages", {
               headers: { "x-api-key": "stored-token" },
             }),

packages/core/test/plugin/provider-github-copilot.test.ts

@@ -19,6 +19,7 @@ import {
 } from "@opencode-ai/core/plugin/provider/github-copilot"
 import { Provider } from "@opencode-ai/core/provider"
 import { Integration } from "@opencode-ai/core/integration"
+import type { SessionRequestKind } from "@opencode-ai/plugin/effect/session"
 import { fakeSelectorSdk } from "../fixture/selector"
 import { testEffect } from "../lib/effect"
 import { PluginTestLayer } from "./fixture"
@@ -44,12 +45,13 @@ const sessions = Effect.fn(function* () {
   return { parent: parent.id, child: child.id }
 })
 
-const modelRequest = Effect.fn(function* (sessionID: Session.ID, agent: string) {
+const modelRequest = Effect.fn(function* (sessionID: Session.ID, kind: SessionRequestKind, agent = "build") {
   const hooks = yield* PluginHooks.Service
   return yield* hooks.trigger("session", "model.request", {
     sessionID,
     agent: Agent.ID.make(agent),
     model: Model.Ref.make({ providerID: Provider.ID.githubCopilot, id: Model.ID.make("gpt-5.4") }),
+    kind,
     headers: {},
   })
 })
@@ -154,6 +156,7 @@ describe("GithubCopilotPlugin", () => {
         sessionID: Session.ID.make("ses_test"),
         agent: Agent.ID.make("build"),
         model: Model.Ref.make({ providerID: Provider.ID.githubCopilot, id: Model.ID.make("claude-sonnet-4.5") }),
+        kind: "primary",
         request: new Request("https://api.githubcopilot.com/v1/messages", {
           method: "POST",
           headers: { "Content-Type": "application/json", "x-api-key": "token" },
@@ -171,7 +174,7 @@ describe("GithubCopilotPlugin", () => {
   it.effect("classifies main-loop steps as agent interactions", () =>
     Effect.gen(function* () {
       yield* addPlugin()
-      const event = yield* modelRequest((yield* sessions()).parent, "build")
+      const event = yield* modelRequest((yield* sessions()).parent, "primary")
       expect(event.headers).toEqual({ "X-Interaction-Type": "conversation-agent" })
     }),
   )
@@ -179,7 +182,7 @@ describe("GithubCopilotPlugin", () => {
   it.effect("classifies child-session steps as subagent interactions", () =>
     Effect.gen(function* () {
       yield* addPlugin()
-      const event = yield* modelRequest((yield* sessions()).child, "build")
+      const event = yield* modelRequest((yield* sessions()).child, "primary")
       expect(event.headers).toEqual({ "X-Interaction-Type": "conversation-subagent", "x-initiator": "agent" })
     }),
   )
@@ -192,14 +195,22 @@ describe("GithubCopilotPlugin", () => {
     }),
   )
 
-  it.effect("classifies compaction requests", () =>
+  it.effect("classifies compaction requests by kind rather than agent", () =>
     Effect.gen(function* () {
       yield* addPlugin()
-      const event = yield* modelRequest((yield* sessions()).child, "compaction")
+      const event = yield* modelRequest((yield* sessions()).child, "compaction", "build")
       expect(event.headers).toEqual({ "X-Interaction-Type": "conversation-compaction", "x-initiator": "agent" })
     }),
   )
 
+  it.effect("does not classify by agent name", () =>
+    Effect.gen(function* () {
+      yield* addPlugin()
+      const event = yield* modelRequest((yield* sessions()).parent, "primary", "compaction")
+      expect(event.headers).toEqual({ "X-Interaction-Type": "conversation-agent" })
+    }),
+  )
+
   it.effect("ignores other providers' model requests", () =>
     Effect.gen(function* () {
       yield* addPlugin()
@@ -208,6 +219,7 @@ describe("GithubCopilotPlugin", () => {
         sessionID: (yield* sessions()).parent,
         agent: Agent.ID.make("build"),
         model: Model.Ref.make({ providerID: Provider.ID.make("openai"), id: Model.ID.make("gpt-5.4") }),
+        kind: "primary",
         headers: {},
       })
       expect(event.headers).toEqual({})
@@ -236,6 +248,14 @@ describe("GithubCopilotPlugin", () => {
     }),
   )
 
+  it.effect("classifies session generation requests as agent interactions", () =>
+    Effect.gen(function* () {
+      yield* addPlugin()
+      const event = yield* modelRequest((yield* sessions()).parent, "generate")
+      expect(event.headers).toEqual({ "X-Interaction-Type": "conversation-agent" })
+    }),
+  )
+
   it.effect("creates the bundled Copilot SDK for the GitHub Copilot package", () =>
     Effect.gen(function* () {
       const aisdk = yield* AISDK.Service

packages/core/test/plugin/provider-openai.test.ts

@@ -48,6 +48,7 @@ const request = Effect.fn(function* (providerID: Provider.ID, baseURL: string) {
     sessionID: Session.ID.make("ses_test"),
     agent: Agent.ID.make("build"),
     model: Model.Ref.make({ providerID, id: Model.ID.make("gpt-5.5") }),
+    kind: "primary",
     baseURL,
     headers: {},
   })
@@ -226,6 +227,7 @@ describe("OpenAIPlugin", () => {
       const program = Effect.gen(function* () {
         const requests = yield* SessionModelRequest.Service
         return yield* requests.prepare({
+          kind: "primary",
           scope: {
             session: Session.Info.make({
               id: sessionID,

packages/core/test/session-model-request-hooks.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect } from "bun:test"
+import { OpenAIChat } from "@opencode-ai/ai/protocols"
+import { Agent } from "@opencode-ai/schema/agent"
+import { Money } from "@opencode-ai/schema/money"
+import { Session } from "@opencode-ai/schema/session"
+import type { SessionRequestKind } from "@opencode-ai/plugin/effect/session"
+import { Location } from "@opencode-ai/core/location"
+import { PluginHooks } from "@opencode-ai/core/plugin/hooks"
+import { Project } from "@opencode-ai/core/project"
+import { AbsolutePath } from "@opencode-ai/core/schema"
+import { SessionModelRequest } from "@opencode-ai/core/session/model-request"
+import { SessionModelTransport } from "@opencode-ai/core/session/model-transport"
+import { SessionRunnerModel } from "@opencode-ai/core/session/runner/model"
+import { DateTime, Effect } from "effect"
+import { HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import { testEffect } from "./lib/effect"
+import { PluginTestLayer } from "./plugin/fixture"
+
+const it = testEffect(PluginTestLayer)
+
+const KINDS: ReadonlyArray<SessionRequestKind> = ["primary", "compaction", "title", "generate"]
+
+const session = Session.Info.make({
+  id: Session.ID.make("ses_hook_kind"),
+  projectID: Project.ID.global,
+  cost: Money.USD.zero,
+  tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+  time: { created: DateTime.makeUnsafe(0), updated: DateTime.makeUnsafe(0) },
+  location: Location.Ref.make({ directory: AbsolutePath.make("/project") }),
+})
+const model = SessionRunnerModel.resolved(OpenAIChat.route.model({ id: "gpt-5.5", provider: "test" }), {
+  capabilities: { tools: true, input: ["text"], output: ["text"] },
+  cost: [],
+  limit: { context: 200_000, output: 32_000 },
+})
+const transport = SessionModelTransport.Service.of({
+  bind: () => ({ execute: () => Effect.die("unused WebSocket execution") }),
+  close: () => Effect.void,
+  closeAll: Effect.void,
+})
+
+describe("SessionModelRequest HTTP hooks", () => {
+  it.effect("tags every Session request kind on http.request and http.response", () =>
+    Effect.gen(function* () {
+      const hooks = yield* PluginHooks.Service
+      const seen: Array<{ hook: string; kind: SessionRequestKind; agent: Agent.ID }> = []
+      yield* hooks.register("session", "http.request", (event) =>
+        Effect.sync(() => {
+          seen.push({ hook: "request", kind: event.kind, agent: event.agent })
+        }),
+      )
+      yield* hooks.register("session", "http.response", (event) =>
+        Effect.sync(() => {
+          seen.push({ hook: "response", kind: event.kind, agent: event.agent })
+        }),
+      )
+      const requests = yield* SessionModelRequest.Service.pipe(Effect.provide(SessionModelRequest.layer))
+
+      for (const kind of KINDS) {
+        const prepared = yield* requests.prepare({
+          kind,
+          scope: { session, agentID: Agent.ID.make("build"), model },
+          transcript: { system: [], messages: [] },
+        })
+        const http = prepared.options.http
+        if (!http) throw new Error(`Expected HTTP middleware for ${kind}`)
+        yield* http(HttpClientRequest.post("https://example.test/v1/chat/completions"), (request) =>
+          Effect.succeed(HttpClientResponse.fromWeb(request, new Response("{}", { status: 200 }))),
+        )
+      }
+
+      expect(seen).toEqual(
+        KINDS.flatMap((kind) => [
+          { hook: "request", kind, agent: Agent.ID.make("build") },
+          { hook: "response", kind, agent: Agent.ID.make("build") },
+        ]),
+      )
+    }).pipe(Effect.provideService(SessionModelTransport.Service, transport)),
+  )
+})

packages/core/test/tool-schema.test.ts

@@ -27,6 +27,7 @@ test("tools are structural values", async () => {
   const tool: Info = config
 
   expect(definition(tool)).toEqual({
+    type: "tool",
     name: "foreign",
     description: "Foreign tool",
     inputSchema: {
@@ -142,6 +143,7 @@ test("portable schemas validate and describe typed tools", async () => {
   }
 
   expect(definition(tool)).toEqual({
+    type: "tool",
     name: "portable",
     description: "Portable tool",
     inputSchema: { type: "object", properties: { count: { type: "string" } } },
@@ -161,6 +163,7 @@ test("Zod schemas validate, transform, and describe typed tools", async () => {
   }
 
   expect(definition(tool)).toEqual({
+    type: "tool",
     name: "zod",
     description: "Zod tool",
     inputSchema: {
@@ -317,6 +320,7 @@ test("raw JSON schemas validate and decode tool input", async () => {
   }
 
   expect(definition(tool)).toEqual({
+    type: "tool",
     name: "raw",
     description: "Raw tool",
     inputSchema: input,
@@ -400,6 +404,7 @@ test("missing external input schemas fall back to an empty schema", () => {
   } as unknown as Info
 
   expect(definition(tool)).toEqual({
+    type: "tool",
     name: "external",
     description: "External tool",
     inputSchema: {},

packages/plugin/src/effect/session.ts

@@ -30,10 +30,17 @@ export interface SessionContext {
   providerOptions: Record<string, unknown>
 }
 
+/**
+ * Why a Session request is being made. Auxiliary requests share the Session's
+ * hook identity but need to be told apart from the agent loop.
+ */
+export type SessionRequestKind = "primary" | "compaction" | "title" | "generate"
+
 export interface SessionModelRequest {
   readonly sessionID: Session.ID
   readonly agent: Agent.ID
   readonly model: Model.Ref
+  readonly kind: SessionRequestKind
   baseURL?: string
   headers: Record<string, string>
 }
@@ -42,6 +49,7 @@ export interface SessionHttpRequest {
   readonly sessionID: Session.ID
   readonly agent: Agent.ID
   readonly model: Model.Ref
+  readonly kind: SessionRequestKind
   request: Request
 }
 
@@ -49,6 +57,7 @@ export interface SessionHttpResponse {
   readonly sessionID: Session.ID
   readonly agent: Agent.ID
   readonly model: Model.Ref
+  readonly kind: SessionRequestKind
   readonly request: Request
   response: Response
 }

packages/plugin/src/promise/session.ts

@@ -30,10 +30,17 @@ export interface SessionContext {
   providerOptions: Record<string, unknown>
 }
 
+/**
+ * Why a Session request is being made. Auxiliary requests share the Session's
+ * hook identity but need to be told apart from the agent loop.
+ */
+export type SessionRequestKind = "primary" | "compaction" | "title" | "generate"
+
 export interface SessionModelRequest {
   readonly sessionID: Session.ID
   readonly agent: Agent.ID
   readonly model: Model.Ref
+  readonly kind: SessionRequestKind
   baseURL?: string
   headers: Record<string, string>
 }
@@ -42,6 +49,7 @@ export interface SessionHttpRequest {
   readonly sessionID: Session.ID
   readonly agent: Agent.ID
   readonly model: Model.Ref
+  readonly kind: SessionRequestKind
   request: Request
 }
 
@@ -49,6 +57,7 @@ export interface SessionHttpResponse {
   readonly sessionID: Session.ID
   readonly agent: Agent.ID
   readonly model: Model.Ref
+  readonly kind: SessionRequestKind
   readonly request: Request
   response: Response
 }

packages/tui/src/component/dialog-model.tsx

@@ -99,11 +99,15 @@ export function DialogModel(props: { providerID?: string }) {
             return false
           return true
         }),
+      connected(),
     )
 
     if (needle) {
       return prioritizeFavorites(
-        fuzzysort.go(needle, modelOptions, { keys: ["title", "category"] }).map((item) => item.obj),
+        sortModelOptions(
+          fuzzysort.go(needle, modelOptions, { keys: ["title", "category"] }).map((item) => item.obj),
+          false,
+        ),
         favoritePriority,
       )
     }
@@ -179,15 +183,24 @@ export function prioritizeFavorites<T extends { value: { providerID: string; mod
 }
 
 export function sortModelOptions<
-  T extends { providerID?: string; providerName?: string; releaseDate: string | number; title: string },
->(options: T[]) {
+  T extends {
+    providerID?: string
+    providerName?: string
+    releaseDate: string | number
+    title: string
+    footer?: string
+  },
+>(options: T[], grouped = true) {
   return options.toSorted((a, b) => {
-    const provider = Number(a.providerID !== "opencode") - Number(b.providerID !== "opencode")
+    const provider = grouped ? Number(a.providerID !== "opencode") - Number(b.providerID !== "opencode") : 0
     if (provider !== 0) return provider
 
-    const name = (a.providerName ?? "").localeCompare(b.providerName ?? "")
+    const name = grouped ? (a.providerName ?? "").localeCompare(b.providerName ?? "") : 0
     if (name !== 0) return name
 
+    const free = Number(b.footer === "Free") - Number(a.footer === "Free")
+    if (free !== 0) return free
+
     const release = Number(b.releaseDate) - Number(a.releaseDate)
     if (release !== 0) return release
 

packages/tui/test/cli/cmd/tui/model-options.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test"
+import { go } from "fuzzysort"
 import { prioritizeFavorites, sortModelOptions } from "../../../../src/component/dialog-model"
 
 describe("prioritizeFavorites", () => {
@@ -23,6 +24,20 @@ describe("prioritizeFavorites", () => {
 })
 
 describe("sortModelOptions", () => {
+  test.each(["browse", "search", "provider"])("orders %s results free-first, then newest-first", (mode) => {
+    const options = [
+      { providerID: "opencode", title: "Claude Haiku 3", releaseDate: 1 },
+      { providerID: "anthropic", title: "Claude Haiku 4.5", releaseDate: 2 },
+      { providerID: "anthropic", title: "Claude Haiku Free", releaseDate: 0, footer: "Free" },
+    ].map((item) => ({ ...item, providerID: mode === "provider" ? "anthropic" : item.providerID }))
+    const matches = mode === "search" ? go("haik", options, { key: "title" }).map((item) => item.obj) : options
+    expect(sortModelOptions(matches, mode === "provider").map((item) => item.title)).toEqual([
+      "Claude Haiku Free",
+      "Claude Haiku 4.5",
+      "Claude Haiku 3",
+    ])
+  })
+
   test("orders opencode models before other providers", () => {
     const sorted = sortModelOptions([
       { providerID: "openai", providerName: "OpenAI", releaseDate: 3, title: "GPT 5" },

packages/www/src/docs/content/build/plugins/effect.mdx

@@ -1104,7 +1104,8 @@ effect: (ctx) =>
   }),
 ```
 
-Modify model request settings and optionally scope the hook to one provider.
+Modify model request settings and optionally scope the hook to one provider. The event carries the same `kind` as
+the HTTP hooks below.
 
 ```ts
 effect: (ctx) =>
@@ -1119,14 +1120,18 @@ effect: (ctx) =>
 ```
 
 Modify native provider requests or responses. Their bodies are one-shot streams; clone or replace a body before reading
-it.
+it. Both hooks run for every request a session issues; `event.kind` is `"primary"`, `"compaction"`, `"title"`, or
+`"generate"` depending on which flow issued it.
 
 ```ts
 effect: (ctx) =>
   Effect.gen(function* () {
     const session = ctx.session
     yield* session.hook("http.request", (event) =>
-      Effect.sync(() => event.request.headers.set("x-session-id", event.sessionID)),
+      Effect.sync(() => {
+        event.request.headers.set("x-session-id", event.sessionID)
+        if (event.kind === "title") event.request.headers.set("x-priority", "background")
+      }),
     )
     yield* session.hook("http.response", (event) =>
       Effect.sync(() => {

packages/www/src/docs/content/build/plugins/index.mdx

@@ -1139,7 +1139,8 @@ Generation options depend on the selected protocol and model:
 
 #### Model request
 
-Modify model request settings and optionally scope the hook to one provider.
+Modify model request settings and optionally scope the hook to one provider. The event carries the same `kind`
+as the HTTP hooks below.
 
 ```ts
 await ctx.session.hook(
@@ -1156,9 +1157,14 @@ await ctx.session.hook(
 Modify native provider requests or responses. Their bodies are one-shot streams; clone or replace a body before reading
 it.
 
+Both hooks run for every request a session issues. `event.kind` says which flow issued it: `"primary"` for the agent
+loop, `"compaction"` for checkpoint summaries, `"title"` for title generation, and `"generate"` for transient
+`ctx.session.generate` calls. Use it instead of the agent ID to tell auxiliary requests apart.
+
 ```ts
 await ctx.session.hook("http.request", (event) => {
   event.request.headers.set("x-session-id", event.sessionID)
+  if (event.kind === "title") event.request.headers.set("x-priority", "background")
 })
 
 await ctx.session.hook("http.response", (event) => {