fuzzy selectors for models and reasoning levels

1 files changed, 20 insertions, 0 deletions

diff --git a/docs/libpanto-bindings.md b/docs/libpanto-bindings.md
index 8d803d1..2872fde 100644
--- a/docs/libpanto-bindings.md
+++ b/docs/libpanto-bindings.md
@@ -170,6 +170,26 @@ Consequences, and why this exact shape:
   `error`. (`error.StreamExhausted` is *not* used — exhaustion is `null`, not
   an error; we reserve errors for failures.)
 
+### `Stream.reopen()` — retry a failed turn after a config swap
+
+When `next()` surfaces a **terminal** error at the provider-open boundary
+(e.g. an HTTP 400 because the chosen reasoning/thinking mode is unsupported by
+the model), the conversation is left untouched — the user prompt that `run()`
+appended is intact and no assistant message was committed. `reopen()` resets
+that failed stream back to its turn-open state so the embedder can:
+
+1. catch the error from `next()`,
+2. change the agent config (`set_config`), and
+3. call `reopen()` and resume `next()` — re-running the SAME turn against the
+   new config **without re-appending the user message**.
+
+This is the binding-portable alternative to calling `run()` again (which would
+append a duplicate prompt and persist it). It errors if the stream has not
+failed. Exposed at every layer: Zig `Stream.reopen() !void`, C
+`panto_stream_reopen(PantoStream*) -> PantoStatus`, Go `(*Stream).Reopen()
+error`, Lua `stream:reopen()`. No embedder is privileged: the panto CLI's
+adaptive-thinking fallback is built entirely on this public method.
+
 ### `Event` spans the whole turn, not one HTTP response
 
 Verified from the code: `Agent.runStep` wraps **multiple** `streamStep` calls