failure retries scheme

1 files changed, 10 insertions, 5 deletions

diff --git a/libpanto/src/tool_source.zig b/libpanto/src/tool_source.zig
index 4b9e104..bf1f5a1 100644
--- a/libpanto/src/tool_source.zig
+++ b/libpanto/src/tool_source.zig
@@ -77,11 +77,16 @@ pub const ToolSource = struct {
         /// slot. The source decides internal scheduling — sequential,
         /// coroutine fan-out, worker pool, etc.
         ///
-        /// On any uncaught error returned from this function (i.e. the
-        /// fn itself returning an error rather than recording one in a
-        /// `results[i]` slot), libpanto treats the *entire batch* as
-        /// failed: it frees any `ok` slots already filled and aborts the
-        /// turn with that error.
+        /// Two failure modes, both normally model-visible:
+        ///   - Per-call: record `.{ .err = e }` in a `results[i]` slot.
+        ///     That call gets an error `ToolResult`; siblings are
+        ///     unaffected.
+        ///   - Whole-batch: return an error from this function. libpanto
+        ///     frees any `ok` slots already filled and maps the error onto
+        ///     *every* member call as an error `ToolResult`.
+        /// In both cases the agent loop continues so the model can react.
+        /// Only hard host failures (`error.Canceled`, `error.OutOfMemory`)
+        /// abort the whole turn and propagate to the embedder.
         invoke_batch: *const fn (
             ctx: *anyopaque,
             calls: []const Call,