context overflow prevention

README.md

@@ -45,6 +45,7 @@ All implementations read `model.cfg` (or `.bantam.cfg`, which takes priority if
    api_key=your_api_key_here
    stream=true
    context_window=200000
+   max_tool_res=15000
    reasoning_effort=high
    ```
 
@@ -133,6 +134,7 @@ Using these rules, everyone can build their own copy of Bantam from scratch in l
    - Sanitize tool arguments to filter out non-printable and space-like Unicode characters (protecting against indirect prompt injection), and validate JSON arguments. If invalid, format a tool-error response so the LLM can self-correct.
    - Execute tool action (`shell_exec` or `write_file`).
    - Sanitize the tool result output to strip any non-printable and space-like Unicode characters (leaving only ASCII space, tab, newline, and printable Unicode characters).
+   - If the sanitized result is larger than `max_tool_res` bytes, spill it to a unique file under `$TMPDIR/bantam/toolres` and replace the content appended to `messages` with a short instruction naming the file, its byte length, and how to read it partially (e.g. `tail -c +OFFSET <file> | head -c LENGTH`); every spilled file is deleted when the round ends (i.e. when the model emits a final response with no tool calls).
    - Output a trace log of the result (`[tool result: name]`).
    - Append tool result message (`role: "tool"`, `tool_call_id`, `content`: result string) to `messages`.
    - Loop back to step 1.
@@ -154,6 +156,7 @@ If the API rejects the request with an `Invalid assistant message: content or to
 - `shell_timeout` (timeout in seconds for `shell_exec` commands, default 120; falls back to `BANTAM_SHELL_TIMEOUT` env var)
 - `max_al_iterations` (max tool-call loop iterations per `AL()` invocation, default 1000; falls back to `BANTAM_MAX_AL_ITERATIONS` env var)
 - `context_window` (context window size in tokens, auto-discovered from `/models` API if available, fallback to this setting, default 200000; falls back to `BANTAM_CONTEXT_WINDOW` env var)
+- `max_tool_res` (maximum number of bytes of a tool result that may be sent into the model context directly, default 15000; larger results are written to a unique file under `$TMPDIR/bantam/toolres` and replaced by a short instruction naming the file and its byte length so it can be read in parts, and the file is deleted once the round ends; falls back to `BANTAM_MAX_TOOL_RES` env var)
 - `reasoning_effort` (reasoning effort level, forwarded to chat completions API, default `high`; falls back to `BANTAM_REASONING_EFFORT` env var)
 
 - `bantam_tools_dir` (optional path to a directory of extra shell tools; the Go port appends `"Extra shell tools can be found at <dir>"` to the system prompt at startup when set. When unset in the config file, it falls back to the `BANTAM_TOOLS_DIR` environment variable; if neither is set, nothing is appended. Note: this is an agent-internal hint, not forwarded to the API.)
@@ -204,6 +207,7 @@ MicroBantam (`mb`) is a compressed Perl 5 reference implementation of the same a
 - Line editing, Ctrl+J multi-line prompts and history (plain single-line prompts)
 - Fibonacci backoff network retries (a failed request aborts with an `API error` message)
 - `/compact` context summarization
+- `max_tool_res` tool-result spilling (oversized results are sent to the model verbatim)
 
 ### Running MicroBantam
 
@@ -326,6 +330,10 @@ Set the `bantam_tools_dir` key in the config file (`.bantam.cfg` if present, els
 
 Set the `bantam_skills_dir` key in the config file (`.bantam.cfg` if present, else `model.cfg`) or the `BANTAM_SKILLS_DIR` environment variable to a directory where each subdirectory is a skill containing a `SKILL.md` file. When defined, the Go port appends `Skills may be discovered and invoked from <dir>` to the system prompt at startup, and you (or the agent) can run a skill with `/skill <name> [prompt]`. The config file key takes precedence over the environment variable; if neither is set, `/skill` accepts an absolute path to a skill directory or `SKILL.md` file instead.
 
+### What happens when a tool result is too large for the context?
+
+Bantam never stuffs an arbitrarily large tool result into the context window. The `max_tool_res` configuration parameter (default `15000`, config-file key takes precedence over the `BANTAM_MAX_TOOL_RES` environment variable) sets the maximum number of bytes of a tool result that may be sent to the model directly. When a result exceeds that limit, the Go port writes the full output to a unique file under `$TMPDIR/bantam/toolres` and replaces the result in the conversation with a short note naming that file and stating its total byte length. The agent is then expected to read the file with `shell_exec`, paging through it with byte offsets (e.g. `tail -c +OFFSET <file> | head -c LENGTH`) rather than loading everything at once. Every file spilled during a round is deleted as soon as the round ends, i.e. when the model emits its final response with no pending tool calls. The built-in system prompt also advertises this behaviour to the model at startup.
+
 ### Is there any common config place for Bantam?
 
 No, loading the config file (`.bantam.cfg` if present, else `model.cfg`) is deliberately only supported from the current working directory. This allows natural separation of configs per project. In case there's no config file inside the project, Bantam will use the `openrouter/free` model from Kilo Code with the temperature 0.7.