llm.rb 16.0.0 → 17.0.1

data/data/xai.json

@@ -83,7 +83,8 @@
       "modalities": {
         "input": [
           "text",
-          "image"
+          "image",
+          "pdf"
         ],
         "output": [
           "video"
@@ -122,7 +123,8 @@
       "limit": {
         "context": 16000,
         "output": 0
-      }
+      },
+      "canonical_model_id": "xai/grok-imagine-image"
     },
     "grok-imagine-video": {
       "id": "grok-imagine-video",

data/docs/deepdive/advanced/cancellation.md

@@ -14,17 +14,17 @@ the tokens.
 #### How it works
 
 When you want to cancel an active request, tool call, or turn, call
-[`LLM::Agent#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#interrupt!)
+[`LLM::Agent#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#interrupt!-instance_method)
 or
-[`LLM::Context#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#interrupt!)
+[`LLM::Context#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#interrupt!-instance_method)
 from any thread. Three things happen, and the last of them is what
 reaches a turn that is doing nothing in particular:
 
 [`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
 is raised on the thread where
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk-instance_method)
 or
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
 is running, so the caller
 can rescue it and know the request was cancelled.
 
@@ -43,7 +43,7 @@ And when the turn is between two requests - waiting out a retry,
 handing tool returns back to the model, or building the next request -
 there is nothing in flight to close and nothing running to raise into,
 so the interrupt is raised into the frame the turn is running in.
-[`LLM::Agent#run_loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#run_loop)
+[`LLM::Agent#run_loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#run_loop-instance_method)
 records that frame for as long as the turn lasts: the thread when the
 canceller is another thread, and the fiber when the canceller shares the
 turn's thread. That second case is a fiber scheduler - a turn under
@@ -81,6 +81,13 @@ a rate-limited turn waiting out its backoff is a turn that has not been
 stopped until the cancel reaches it, and the request it is waiting to
 make is one nobody asked for any more.
 
+It is also worth saying what is unusual about it. The usual shape of a
+cancel is a request that is aborted: this one reaches a tool that is
+running, and a turn that is between two requests. And a cancel does not
+leave a hole: the call it stopped is closed with an in-band return
+before the next request goes out, so the conversation the model sees
+stays valid and the model is told what happened rather than finding one.
+
 #### Notes
 
 How an interrupt reaches a tool depends on the strategy. The
@@ -95,9 +102,18 @@ reach. The `:sequential` strategy has nothing to raise into: its
 tool runs on the caller's own thread, so a cancel tells the tool
 through its hook alone.
 
+Where the hook runs against the raise is the one thing a tool can
+feel twice. On `:fork` and `:ractor` the hook is written before the
+raise, so a tool that releases a resource in the hook has released it
+by the time the interrupt arrives. On `:thread`, `:fiber` and `:async`
+it runs in the call's `ensure`, after the raise has landed and after
+the tool's own `rescue` - so a tool that cleans up in both places
+cleans up twice, rescue first, and one that cleans up in one place
+should pick the hook.
+
 A cancel is delivered at the point the turn has reached, which can be
 any point of it: inside a stream callback, a compactor, a transformer,
-a guard, or the persistence write a step makes.
+an intercept, or the persistence write a step makes.
 [`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
 sits outside `StandardError`, so neither a bare `rescue` nor a
 `rescue => ex` catches it, and the language is what keeps a cancel from
@@ -107,10 +123,22 @@ does; it is not an `LLM::Error` either, so a rescue of the runtime's
 error superclass does not catch it.
 
 The runtime's own path out of a turn does not swallow an interrupt:
-[`LLM::Context#try`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#try)
+[`LLM::Context#try`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#try-instance_method)
 re-raises anything that is not a retryable failure, and the tracer
 interface has no broad rescues of its own.
 
+A turn can also be reached from outside the code that started it.
+[`LLM.interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM.html#interrupt-class_method)
+finds the turn running under an agent, an agent's own id, or a record's
+id and interrupts it, so a controller, a job, or a socket handler can
+stop a turn it never held a reference to. A turn registers itself through
+[`LLM::Agent.registry`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#registry-class_method)
+while it runs and is forgotten when it ends, so the method answers
+`false` when nothing was registered under that name, which is the
+ordinary race rather than a failure. It takes `attempts:` and `interval:`
+to poll for a turn that has not started yet, and the registry is per
+process, so a cancel that lands in another worker finds nothing.
+
 The names are worth separating.
 [`LLM::Context#interrupt!`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#interrupt!-instance_method)
 and

data/docs/deepdive/advanced/compaction.md

@@ -9,14 +9,14 @@ Long-running conversations consume tokens. Without intervention,
 every turn pushes toward the model's context window limit. Compaction
 drops old messages to keep the conversation alive. The runtime runs
 a compactor automatically before each
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk-instance_method)
 call, trimming the oldest messages when the conversation exceeds a configured size.
 This keeps the context window healthy without manual intervention.
 
 #### How it works
 
 Compactors run automatically before each
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk)
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk-instance_method)
 call.
 [`LLM::Compactor::Truncate`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Truncate.html)
 strategy drops the oldest messages, keeping only the N most recent.
@@ -77,11 +77,11 @@ trade-off is that dropped messages are gone, so information may be
 lost. Set `keep` to a higher number to retain more context.
 
 Both strategies accept
-[`LLM::Stream#on_compaction`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_compaction)
+[`LLM::Stream#on_compaction`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_compaction-instance_method)
 and
-[`LLM::Stream#on_compaction_finish`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_compaction_finish)
+[`LLM::Stream#on_compaction_finish`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_compaction_finish-instance_method)
 stream callbacks so the UI can show progress, but only the `Truncate`
 strategy emits them. `Null` performs no compaction and emits nothing.
 The context's
-[`LLM::Context#compacted?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#compacted?)
+[`LLM::Context#compacted?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#compacted?-instance_method)
 flag is `true` between compaction and the next model response.

data/docs/deepdive/advanced/context.md

@@ -7,7 +7,7 @@
 
 [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
 is the runtime that powers every agent. When you call
-[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk),
+[`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk-instance_method),
 the agent delegates to its internal context. The context manages
 the message history, sends requests to the provider, tracks pending
 tool calls, and feeds results back to the model. Everything an agent
@@ -23,22 +23,22 @@ any workflow where the agent's automatic loop gets in the way.
 
 A context wraps a provider and maintains the conversation state.
 Call
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
 to send input to the model, check
-[`LLM::Context#pending_functions?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions?)
+[`LLM::Context#pending_functions?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions?-instance_method)
 to see if tools were requested, and use
-[`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait)
+[`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait-instance_method)
 to execute them. Each call to
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
 appends
 to the conversation and returns the model's response. The context
 serializes its state with
-[`LLM::Context#to_h`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_h)
+[`LLM::Context#to_h`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_h-instance_method)
 and
-[`LLM::Context#to_json`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_json),
+[`LLM::Context#to_json`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_json-instance_method),
 and restores it
 with
-[`LLM::Context#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#restore).
+[`LLM::Context#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#restore-instance_method).
 This is how the ORM integrations and filesystem
 persistence work under the hood:
 
@@ -120,6 +120,13 @@ and
 are read from the id rather than stored, so they return `nil` when
 the id is not a UUIDv7 string.
 
+A context bound to a record takes that record's id when the record's
+id is a UUIDv7 string, and generates one otherwise - so an agent's
+id is the identity its host already has, and a record with an
+integer primary key, or a row that is not saved yet, still gets a
+UUIDv7 of its own. Pass `id:` to name a context yourself; it must be
+a UUIDv7 string, and anything else raises `LLM::Error`.
+
 #### Why would I use it?
 
 An id gives a conversation or a message a stable name you can log,
@@ -132,6 +139,12 @@ creation order and no separate timestamp column is needed.
 The id is generated once and saved with the runtime state, so it
 survives a save and a restore. A payload written before ids existed
 has none, so its object is restored with a fresh id.
+A UUIDv7 is a constraint rather than a convention: an id that is not
+one is refused with `LLM::Error`, because the id is what carries the
+creation time, and the same string is meant to name a row and the
+conversation bound to it.
+[`LLM::Utils.uuidv7?`](https://r.uby.dev/api-docs/llm.rb/LLM/Utils.html#uuidv7?-instance_method)
+is the check.
 [`LLM::Message#==`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#==-instance_method)
 ignores the id, so a difference in creation time alone does not make
 two messages unequal.
@@ -159,9 +172,9 @@ When you want to control the tool loop yourself, drive
 directly instead of using an agent. Start a conversation, check
 for tool requests, execute them, and feed results back. The full
 loop is under your control. Each call to
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
 appends to the conversation and returns the model's response, and
-[`LLM::Context#pending_functions?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions?)
+[`LLM::Context#pending_functions?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions?-instance_method)
 tells you whether tools were requested.
 From that foundation you can inspect, iterate, or confirm
 per-tool in a single flow:
@@ -201,14 +214,14 @@ recovery that the default tool loop does not expose.
 
 #### Notes
 
-[`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait)
+[`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait-instance_method)
 picks up pending functions, spawns them using the chosen
 strategy, waits for results, and records them back in the context.
 Each strategy is supported: `:sequential`, `:thread`, `:fiber`,
 `:async`, `:fork`, and `:ractor`. Functions are reset after each
-[`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait)
+[`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait-instance_method)
 or
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
 call. Store the array if you need to
 preserve them.
 
@@ -217,10 +230,10 @@ preserve them.
 #### Overview
 
 Pending function calls represent the model's tool requests. After
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
 returns, the context may have pending function
 calls if the model requested tools. These are available through
-[`LLM::Context#pending_functions`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions)
+[`LLM::Context#pending_functions`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions-instance_method)
 which returns an array of
 [`LLM::Function`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html)
 objects. Each function has a name, arguments, and methods for
@@ -229,15 +242,15 @@ execution or cancellation.
 #### How it works
 
 When you want to check whether the model requested tools, call
-[`LLM::Context#pending_functions?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions?)
+[`LLM::Context#pending_functions?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions?-instance_method)
 after each
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
 call. Each pending
 function has a name, arguments, and
 methods for execution or cancellation. Call
-[`LLM::Function#task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#task)
+[`LLM::Function#task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#task-instance_method)
 to execute it or
-[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method)
 to skip it. Iterate over all
 pending functions to inspect or handle them individually:
 
@@ -268,9 +281,9 @@ the model requested.
 #### Notes
 
 Pending functions are reset after each
-[`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait)
+[`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait-instance_method)
 or
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk)
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method)
 call. If you need to preserve them, store the array before
 executing. Functions that are cancelled still count as completed
 from the model's perspective; the model sees a cancellation
@@ -402,7 +415,7 @@ anything else the model supports.
 Call
 [`LLM::Context#prompt`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#prompt-instance_method)
 with a block, then pass the result to
-[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk).
+[`LLM::Context#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#talk-instance_method).
 Inside the block, `system`, `user`, and `developer` append a message
 with the matching role, and `talk` appends one with an explicit
 role. The provider resolves each role to its provider-specific name:
@@ -423,7 +436,7 @@ res = ctx.talk(prompt)
 
 The block receives the prompt object when it takes an argument, and
 otherwise runs in the prompt's context:
-[`LLM::Prompt#to_a`](https://r.uby.dev/api-docs/llm.rb/LLM/Prompt.html#to_a)
+[`LLM::Prompt#to_a`](https://r.uby.dev/api-docs/llm.rb/LLM/Prompt.html#to_a-instance_method)
 returns the messages in order, and two prompts are equal when their
 messages match. Each of `system`, `user`, `developer`, and `talk`
 accepts an `extra:` hash, which is attached to the message it builds,
@@ -495,5 +508,13 @@ model to read, instead of pasting its contents into the prompt.
 Which files a model accepts depends on the provider and the model.
 `ask` is a shorthand over `talk`: it builds the same prompt and returns
 the same `LLM::Response`, so anything that works with `talk` works with
-`ask`. An agent delegates all four methods to the context it wraps.
+`ask`. It also accepts a `stream:` target and a block, the way `talk`
+does. An agent delegates all four methods to the context it wraps.
+
+A file the provider cannot take is refused with
+[`LLM::PromptError`](https://r.uby.dev/api-docs/llm.rb/LLM/PromptError.html),
+raised while the prompt is built rather than by the tool call. The
+message names what was rejected: DeepSeek has no Files API, so a remote
+file raises there, and it reads images only, so anything else raises for
+its own reason.
 

data/docs/deepdive/advanced/{guard.md → intercept.md}

@@ -1,41 +1,41 @@
 
-## Guard
+## Intercept
 
 ### Introduction
 
 #### Overview
 
-[`LLM::Guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html)
-is the superclass for context-level supervisors. A guard is bound
-to a context and inspects each pending tool call before it runs.
-It can let the call through, cancel it, block it with an error, or
-answer for it with a synthesized result. Guards handle policy,
-validation, quotas, cost control, caching, and approval workflows.
+[`LLM::Intercept`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html)
+is the superclass for context-level supervisors. An intercept is bound
+to a context and inspects each pending tool call before it runs. It
+can let the call through, cancel it, block it with an error, or answer
+for it with a synthesized result. Intercepts handle policy, validation,
+quotas, cost control, caching, and approval workflows.
 
 #### How it works
 
-A guard is a subclass of
-[`LLM::Guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html)
+An intercept is a subclass of
+[`LLM::Intercept`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html)
 that implements
-[`LLM::Guard#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html#call-instance_method).
-The guard is stamped onto the functions the context binds, and when a
-function's task runs the guard is checked on the calling thread before
-the tool is handed to the strategy. `call` receives the pending
+[`LLM::Intercept#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html#call-instance_method).
+It is stamped onto the functions the context binds, and when a
+function's task runs the intercept is checked on the calling thread
+before the tool is handed to the strategy. `call` receives the pending
 `function:` and returns an
 [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
-to close that single call, or `nil` to let it run. The guard inspects
-the current conversation through the `messages` helper and reads the
-pending call through the function's own accessors.
+to close that single call, or `nil` to let it run. The intercept
+inspects the current conversation through the `messages` helper and
+reads the pending call through the function's own accessors.
 
-Configure a guard by passing a class through the `guard:` option;
-options given in `guard_options:` are forwarded to `call` as keyword
-arguments:
+Configure an intercept by passing a class through the `intercept:`
+option; options given in `intercept_options:` are forwarded to `call`
+as keyword arguments:
 
 ```ruby
-class RateLimitGuard < LLM::Guard
+class RateLimitIntercept < LLM::Intercept
   def call(function:, limit: 10)
     if messages.count(&:tool_return?) >= limit
-      function.return(error: true, type: "guard_error",
+      function.return(error: true, type: "intercept_error",
                       message: "too many tool calls")
     end
   end
@@ -43,73 +43,77 @@ end
 
 agent = LLM::Agent.new(
   llm,
-  guard: RateLimitGuard,
-  guard_options: {limit: 3}
+  intercept: RateLimitIntercept,
+  intercept_options: {limit: 3}
 )
 agent.talk "Research the market", tools: [FetchNews, FetchStocks]
 ```
 
 #### Why would I use it?
 
-A guard is the one hook that sees every pending tool call and the
-full conversation at once. It can observe what the model is about
-to do, cancel a call that needs approval, block one that violates
-policy, answer a cheap question without running a tool, or stop
-work when a budget is spent. Because the guard runs before the
-tool, anything it intercepts never executes.
+An intercept is the one hook that sees every pending tool call and the
+full conversation at once. It can observe what the model is about to
+do, cancel a call that needs approval, block one that violates policy,
+answer a cheap question without running a tool, or stop work when a
+budget is spent. Because the intercept runs before the tool, anything
+it intercepts never executes.
 
 #### Notes
 
-[`LLM::Guard::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Null.html)
-is the default guard for
+[`LLM::Intercept::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept/Null.html)
+is the default intercept for
 [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html);
 it never blocks tool work.
-[`LLM::Context#guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#guard)
-returns the configured guard class. Because `call` returns an
+[`LLM::Context#intercept`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#intercept-instance_method)
+returns the configured intercept. Because `call` returns an
 [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
-rather than a warning string, a guard can block an individual tool
-call while the rest of the batch still executes. The guard is stamped
-onto every function the context binds, so it runs whenever a task is
-spawned, including tool calls a stream queues itself during a
-streaming turn. A blocked call yields its return without executing.
-
-The runtime creates a guard instance for each batch of tool calls and
-stamps it onto the functions in that batch, so the same instance sees
-every call in a batch. State in an instance variable therefore lasts
-for the batch, but not from one batch to the next. Anything a guard
-needs to remember across batches, like how many calls already ran,
-must come from the conversation (`messages`) or from class-level
-state.
+rather than a warning string, an intercept can block an individual tool
+call while the rest of the batch still executes. It is stamped onto
+every function the context binds, so it runs whenever a task is
+spawned, including tool calls a stream queues itself during a streaming
+turn. A blocked call yields its return without executing.
+
+The runtime builds an intercept instance for each turn and stamps it
+onto the functions of that turn, so the same instance sees every call
+in the turn. State in an instance variable therefore lasts for the
+turn, but not from one turn to the next. Anything an intercept needs to
+remember across turns, like how many calls already ran, must come from
+the conversation (`messages`) or from class-level state.
+
+`intercept:` also takes an instance rather than a class, which is how
+[`LLM::Intercept.multi`](https://r.uby.dev/api-docs/llm.rb/LLM/Intercept.html#multi-class_method)
+is attached: it asks each intercept it holds in turn and stops at the
+first one that answers the call.
 
 ### Inspect
 
 #### Overview
 
-The guard receives the pending
+The intercept receives the pending
 [`LLM::Function`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html)
 and can read what the model is about to do before anything runs.
 The function exposes its `name`, `arguments`, and parameter schema,
-so a guard can base its decision on the actual call rather than on
-the whole conversation. The guard also holds the context, so the
+so an intercept can base its decision on the actual call rather than on
+the whole conversation. The intercept also holds the context, so the
 message history, token usage, and cost are visible too.
 
 #### How it works
 
 When you want to inspect a pending call before it runs, read the
 function's accessors inside `call`.
-[`LLM::Function#name`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#name)
+[`LLM::Function#name`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#name-instance_method)
 is the tool name, and
-[`LLM::Function#arguments`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#arguments)
+[`LLM::Function#arguments`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#arguments-instance_method)
 is an
 [`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
 with the parsed arguments. The full parameter schema is available
 through
-[`LLM::Function#params`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#params).
-Returning `nil` lets the call run, so an inspection-only guard is a
+[`LLM::Function#params`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#params-instance_method).
+Returning `nil` lets the call run, so an inspection-only intercept is a
 pure observer:
 
 ```ruby
-class AuditGuard < LLM::Guard
+class AuditIntercept < LLM::Intercept
   def call(function:)
     warn "pending: #{function.name}(#{function.arguments.inspect})"
     nil  # let it run
@@ -120,14 +124,14 @@ end
 #### Why would I use it?
 
 Inspecting the pending call is the basis for policy, validation,
-and audit. A guard can log every call into a telemetry stream, or
+and audit. An intercept can log every call into a telemetry stream, or
 reject a single call because its arguments violate a rule while
 letting every other call through. The same read underpins the
 richer decisions in the rest of this document.
 
 #### Notes
 
-The guard sees the parsed arguments exactly as the model requested
+The intercept sees the parsed arguments exactly as the model requested
 them. Reading them costs nothing and never executes the tool.
 Returning `nil` means the call proceeds normally.
 
@@ -136,7 +140,7 @@ Returning `nil` means the call proceeds normally.
 #### Overview
 
 Cancelling is distinct from blocking with an error.
-[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method)
 produces a return the model reads as a declined call, not a failed
 one. The conversation stays honest: the model asked for something,
 and the runtime declined it with a reason.
@@ -144,14 +148,14 @@ and the runtime declined it with a reason.
 #### How it works
 
 When you want to cancel a single pending call, call the
-[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method)
 method with a `reason:` and return the result from `call`. The
 pending call never executes, and the rest of the batch still runs.
-A guard can cancel one call in a two-call batch and the other call
-still executes:
+An intercept can cancel one call in a two-call batch and the other
+call still executes:
 
 ```ruby
-class ApprovalGuard < LLM::Guard
+class ApprovalIntercept < LLM::Intercept
   def call(function:)
     if function.name == "delete-file"
       function.cancel(reason: "delete requires human approval")
@@ -183,8 +187,8 @@ reason string is what the model sees, so write it as guidance
 
 #### Overview
 
-Blocking is how a guard enforces policy. A blocked call never runs,
-and the model receives an in-band error explaining why. Unlike a
+Blocking is how an intercept enforces policy. A blocked call never
+runs, and the model receives an in-band error explaining why. Unlike a
 cancellation, an error tells the model the tool could not produce
 a result at all.
 
@@ -197,7 +201,7 @@ model sees them inside the return value. Returning `nil` lets the
 call through:
 
 ```ruby
-class PolicyGuard < LLM::Guard
+class PolicyIntercept < LLM::Intercept
   def call(function:)
     if function.name == "exec"
       function.return(error: true, type: "policy_error",
@@ -223,8 +227,8 @@ call was blocked and can change course.
 
 #### Overview
 
-A guard's return is injected into the conversation as if the tool
-had executed, so a guard can answer for a tool that never runs.
+An intercept's return is injected into the conversation as if the tool
+had executed, so an intercept can answer for a tool that never runs.
 From the model's side, a synthesized result is indistinguishable
 from a real one.
 
@@ -237,7 +241,7 @@ helper. The value you pass becomes the tool's result as-is, so it
 must look like a plausible answer:
 
 ```ruby
-class CacheGuard < LLM::Guard
+class CacheIntercept < LLM::Intercept
   CACHE = {"get-weather:tokyo" => {forecast: "sunny"}}
 
   def call(function:)
@@ -260,7 +264,7 @@ given environment.
 marks a tool as not found, and
 [`LLM::Function#budget_spent`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html)
 reports that the tool budget is exhausted. Both are returns too,
-so they flow back to the model like any tool result. A guard that
+so they flow back to the model like any tool result. An intercept that
 synthesizes a result runs instead of the tool, so side effects the
 tool would have performed, like a database write, are skipped.
 
@@ -268,25 +272,25 @@ tool would have performed, like a database write, are skipped.
 
 #### Overview
 
-A guard can read the accumulated usage and cost of the conversation
-through the context. That makes it the natural place to enforce a
-hard ceiling: stop calling tools once a cost or token budget is
-spent, or once the context window is nearly full.
+An intercept can read the accumulated usage and cost of the
+conversation through the context. That makes it the natural place to
+enforce a hard ceiling: stop calling tools once a cost or token budget
+is spent, or once the context window is nearly full.
 
 #### How it works
 
 When you want to enforce a budget, compare
-[`LLM::Context#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#usage)
+[`LLM::Context#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#usage-instance_method)
 or
 [`LLM::Context#cost`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#cost-instance_method)
 against a limit inside `call`. Pass the limit through
-`guard_options:` so it can be tuned per context. Returning a
+`intercept_options:` so it can be tuned per context. Returning a
 cancellation or an error closes the call before it runs:
 
 ```ruby
-class BudgetGuard < LLM::Guard
+class BudgetIntercept < LLM::Intercept
   def call(function:, limit: 0.05)
-    if ctx.cost.total >= limit
+    if context.cost.total >= limit
       function.cancel(reason: "cost ceiling reached, ask before continuing")
     end
   end
@@ -294,8 +298,8 @@ end
 
 ctx = LLM::Context.new(
   llm,
-  guard: BudgetGuard,
-  guard_options: {limit: 0.01}
+  intercept: BudgetIntercept,
+  intercept_options: {limit: 0.01}
 )
 ```
 
@@ -306,9 +310,9 @@ many tools to call. A cost ceiling keeps a runaway agent from
 spending money, and a quota derived from `messages` (as in the
 rate-limit example above) keeps a single user from exhausting
 shared resources. The same comparison works with
-[`LLM::Context#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#usage)
+[`LLM::Context#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#usage-instance_method)
 against
-[`LLM::Context#context_window`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_window)
+[`LLM::Context#context_window`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_window-instance_method)
 to keep the conversation inside the model's window.
 
 #### Notes
@@ -316,8 +320,8 @@ to keep the conversation inside the model's window.
 The cost reported by
 [`LLM::Context#cost`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#cost-instance_method)
 reflects the conversation so far, so a limit is enforced per call:
-once the ceiling is crossed, the next pending call is declined. The
-guard is not a replacement for
+once the ceiling is crossed, the next pending call is declined. An
+intercept is not a replacement for
 [`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method),
 which caps the number of tool calls in a single turn. The two
-compose: the budget caps call count, and a guard enforces cost.
+compose: the budget caps call count, and an intercept enforces cost.