shellbent 0.1.0__tar.gz

shellbent-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

shellbent-0.1.0/CONFIGURATIONS.md

@@ -0,0 +1,15 @@
+# Configurations
+
+| Config file | Model class | The agent gets |
+|---|---|---|
+| `bash.yaml` | `BashModel` | bash, default mini-swe-agent prompt (baseline) |
+| `tools.yaml` | `ToolsModel` | bash + search, default prompt |
+| `minimal.yaml` | either | bash (+ search), short prompt that names no tool |
+| `minimal-directive.yaml` | `ToolsModel` | as minimal, the search description says to use it instead of grep |
+| `minimal-reason.yaml` | either | as minimal, every call states why this tool and why not the others |
+| `minimal-reason-nogrep.yaml` | `ToolsModel` | as reason, grep and rg refused in bash |
+| `minimal-reason-read.yaml` | `ToolsModel` | bash + read, with reasons |
+| `minimal-reason-read-nocat.yaml` | `ToolsModel` | as reason-read, cat, head, nl and sed -n refused in bash |
+| `minimal-search-read.yaml` | `ToolsModel` | bash + search + read, short prompt |
+
+Each yaml says what it changes and why in its header comment. `thesis_tools/model.py` documents the reason fields, the blocking and the rate-limit keys.

shellbent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Posztos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shellbent-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: shellbent
+Version: 0.1.0
+Summary: mini-swe-agent 2.4.6 model classes and named tools for a thesis on agent tool surfaces
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mini-swe-agent==2.4.6
+Requires-Dist: ripgrep-bin==15.2.0; sys_platform == 'linux'

shellbent-0.1.0/README.md

@@ -0,0 +1,22 @@
+# shellbent
+
+Coding agents using open-weight LLMs seem to be (s)hellbent on using shell commands for searching and reading code instead of named tools. This is the repo we use for the experiments in my master's thesis at TU Wien.
+
+It adds named tools and model classes to [mini-swe-agent](https://github.com/SWE-agent/mini-swe-agent) 2.4.6, without forking it. Each configuration is a config file plus a model class, listed in [CONFIGURATIONS.md](CONFIGURATIONS.md).
+
+## Usage
+
+With Pier, pinned to a commit:
+
+```
+--ak 'extra_python_packages=["git+https://github.com/alexander-posztos/shellbent.git@<sha>"]'
+--ak config_file=tools.yaml --ak model_class=thesis_tools.model.ToolsModel
+```
+
+## Tools
+
+`search` and `read` are Python ports of [pi](https://github.com/earendil-works/pi)'s grep and read tools. They run in the task container as shell commands, so trajectories look the same as in stock mini-swe-agent.
+
+## License
+
+MIT

shellbent-0.1.0/bash.yaml

@@ -0,0 +1,11 @@
+# config for the baseline (bash only). Pier loads it on top of mini.yaml with
+#   --ak config_file=bash.yaml --ak model_class=thesis_tools.model.BashModel
+# the only change is the retry block, since the inference provider caps requests per minute per key and
+# mini doesn't retry RateLimitError on its own.
+#
+# model_class can't be set in yaml. Pier appends its own -c model.model_class after this file,
+# and for openai/ models that defaults to litellm_response, so the CLI flag is the only way to win.
+model:
+  model_kwargs:
+    num_retries: 15
+    retry_strategy: exponential_backoff_retry

shellbent-0.1.0/minimal-directive.yaml

@@ -0,0 +1,35 @@
+# config for the tools condition with a tool_directive set. Same as minimal.yaml
+# except model.tool_directive, which goes in front of the search tool's description. The agent block must
+# stay byte-identical to minimal.yaml (tests/test_model.py checks that), the prompt is the control.
+#
+# why: with minimal.yaml GLM never picked the search tool (free choice, named grep then), and every production agent that ships a
+# search tool next to a shell tool steers with an explicit sentence (Claude Code, Codex, Gemini CLI,
+# OpenCode). Wording follows the OpenAI Codex guide: one directive, in the tool, naming the shell habit.
+model:
+  tool_directive: Use this tool for every content search instead of running grep or rg through bash.
+  model_kwargs:
+    num_retries: 15
+    retry_strategy: exponential_backoff_retry
+  format_error_template: |
+    {% if finish_reason is defined and (finish_reason == "length" or (finish_reason == "tool_calls" and not has_tool_calls)) -%}
+    Your previous response reached the output token limit (finish_reason={{ finish_reason }}) before you produced a tool call, so it was cut off. Respond more concisely and finish with a tool call.
+    {%- else -%}
+    Tool call error:
+
+    <error>
+    {{error}}
+    </error>
+
+    Every response must contain at least one tool call. To finish, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call.
+    {%- endif %}
+agent:
+  instance_template: |
+    Please solve this issue: {{task}}
+
+    Use your tools to inspect the repository and implement the fix. Every call runs in a fresh subshell, so directory changes and environment variables do not persist between calls.
+
+    When you are done, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call. You cannot continue after it.
+
+    <system_information>
+    {{system}} {{release}} {{version}} {{machine}}
+    </system_information>

shellbent-0.1.0/minimal-reason-nogrep.yaml

@@ -0,0 +1,42 @@
+# leave-one-out configuration: minimal-reason.yaml plus model.block_grep, so grep and rg are rejected as commands in bash
+# (allowed as a filter after a pipe), which leaves the search tool as the offered way to search (sed, awk and python are not blocked). One sentence in the
+# instance_template says so up front; a blocked command is not run, the agent just gets the same text back (exit
+# code 127). Everything else is byte-identical to minimal-reason.yaml (tests/test_model.py checks that).
+#
+# why: with grep available the models never pick the search tool (about 2% of calls, 19 Oct 2026), and their stated
+# reasons are post-hoc. Taking grep away shows whether the tool is usable at all: same pass rate means habit,
+# a drop means the tool is worse than grep, and the reasons then say why.
+model:
+  block_grep: true
+  reason_prompt: One sentence on why you chose to use this tool for this step. Do not describe what the step does.
+  reason_against_prompt: One sentence on why you did not choose the {tool} tool for this step.
+  model_kwargs:
+    num_retries: 15
+    retry_strategy: exponential_backoff_retry
+  format_error_template: |
+    {% if finish_reason is defined and (finish_reason == "length" or (finish_reason == "tool_calls" and not has_tool_calls)) -%}
+    Your previous response reached the output token limit (finish_reason={{ finish_reason }}) before you produced a tool call, so it was cut off. Respond more concisely and finish with a tool call.
+    {%- else -%}
+    Tool call error:
+
+    <error>
+    {{error}}
+    </error>
+
+    Every response must contain at least one tool call. To finish, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call.
+    {%- endif %}
+agent:
+  instance_template: |
+    Please solve this issue: {{task}}
+
+    Use your tools to inspect the repository and implement the fix. Every call runs in a fresh subshell, so directory changes and environment variables do not persist between calls.
+
+    grep and rg are currently not available as commands for you. Use the search tool to find text in files.
+
+    Every tool has a why_this_tool field and, for each other tool you have, a why_not_<tool> field. Fill why_this_tool with one sentence on why you chose that tool for the step and each why_not_<tool> field with one sentence on why you did not choose that tool. Do not describe what the step does, the command already says that.
+
+    When you are done, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call. You cannot continue after it.
+
+    <system_information>
+    {{system}} {{release}} {{version}} {{machine}}
+    </system_information>

shellbent-0.1.0/minimal-reason-read-nocat.yaml

@@ -0,0 +1,44 @@
+# leave-one-out configuration for the read tool: minimal-reason-read.yaml plus model.block_read, so cat, head, nl and sed -n
+# are rejected as commands in bash (allowed as a filter after a pipe; cat that writes and sed that edits stay
+# allowed), which leaves the read tool as the offered way to read files (python, awk and the like are not blocked). One sentence in the instance_template says so
+# up front; a blocked command is not run, the agent just gets the same text back (exit code 127). Everything else
+# is byte-identical to minimal-reason-read.yaml (tests/test_model.py checks that).
+#
+# why: same test as minimal-reason-nogrep.yaml for the search tool. Taking the bash readers away shows whether the
+# read tool is usable at all: same pass rate means habit, a drop means the tool is worse than cat, and the reasons
+# then say why.
+model:
+  tools: [read]
+  block_read: true
+  reason_prompt: One sentence on why you chose to use this tool for this step. Do not describe what the step does.
+  reason_against_prompt: One sentence on why you did not choose the {tool} tool for this step.
+  model_kwargs:
+    num_retries: 15
+    retry_strategy: exponential_backoff_retry
+  format_error_template: |
+    {% if finish_reason is defined and (finish_reason == "length" or (finish_reason == "tool_calls" and not has_tool_calls)) -%}
+    Your previous response reached the output token limit (finish_reason={{ finish_reason }}) before you produced a tool call, so it was cut off. Respond more concisely and finish with a tool call.
+    {%- else -%}
+    Tool call error:
+
+    <error>
+    {{error}}
+    </error>
+
+    Every response must contain at least one tool call. To finish, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call.
+    {%- endif %}
+agent:
+  instance_template: |
+    Please solve this issue: {{task}}
+
+    Use your tools to inspect the repository and implement the fix. Every call runs in a fresh subshell, so directory changes and environment variables do not persist between calls.
+
+    Every tool has a why_this_tool field and, for each other tool you have, a why_not_<tool> field. Fill why_this_tool with one sentence on why you chose that tool for the step and each why_not_<tool> field with one sentence on why you did not choose that tool. Do not describe what the step does, the command already says that.
+
+    cat, head, nl and sed -n are currently not available as commands for you. Use the read tool to read files.
+
+    When you are done, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call. You cannot continue after it.
+
+    <system_information>
+    {{system}} {{release}} {{version}} {{machine}}
+    </system_information>

shellbent-0.1.0/minimal-reason-read.yaml

@@ -0,0 +1,40 @@
+# read tool configuration: minimal-reason.yaml with model.tools set to [read], so the surface is bash plus the read tool
+# (no search tool) and the reason fields are on both. Everything else is byte-identical to minimal-reason.yaml
+# (tests/test_model.py checks that). No tool_directive: the read tool is offered as a free choice, like the search
+# tool in minimal-reason.yaml.
+#
+# why: Cito (20 Oct 2026) asked for at least one more basic tool built and piloted like the search tool, so the
+# adoption question ("why do agents not use an available tool") is not a finding about one tool. read is the most
+# used file operation after search (cat, head, sed -n in the bash-only trajectories), so it is the second tool.
+model:
+  tools: [read]
+  reason_prompt: One sentence on why you chose to use this tool for this step. Do not describe what the step does.
+  reason_against_prompt: One sentence on why you did not choose the {tool} tool for this step.
+  model_kwargs:
+    num_retries: 15
+    retry_strategy: exponential_backoff_retry
+  format_error_template: |
+    {% if finish_reason is defined and (finish_reason == "length" or (finish_reason == "tool_calls" and not has_tool_calls)) -%}
+    Your previous response reached the output token limit (finish_reason={{ finish_reason }}) before you produced a tool call, so it was cut off. Respond more concisely and finish with a tool call.
+    {%- else -%}
+    Tool call error:
+
+    <error>
+    {{error}}
+    </error>
+
+    Every response must contain at least one tool call. To finish, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call.
+    {%- endif %}
+agent:
+  instance_template: |
+    Please solve this issue: {{task}}
+
+    Use your tools to inspect the repository and implement the fix. Every call runs in a fresh subshell, so directory changes and environment variables do not persist between calls.
+
+    Every tool has a why_this_tool field and, for each other tool you have, a why_not_<tool> field. Fill why_this_tool with one sentence on why you chose that tool for the step and each why_not_<tool> field with one sentence on why you did not choose that tool. Do not describe what the step does, the command already says that.
+
+    When you are done, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call. You cannot continue after it.
+
+    <system_information>
+    {{system}} {{release}} {{version}} {{machine}}
+    </system_information>

shellbent-0.1.0/minimal-reason.yaml

@@ -0,0 +1,51 @@
+# config for the reactivity pilot: minimal.yaml plus model.reason_prompt and reason_against_prompt, which put a
+# required `why_this_tool` and one `why_not_<tool>` per other tool first in every tool (bash in BashModel, bash and
+# search in ToolsModel), and one paragraph in the instance_template that says what goes into them. Everything else
+# must stay byte-identical to minimal.yaml (tests/test_model.py checks that), so the fields and that paragraph are
+# the only difference to the configuration without them.
+#
+# why: stated reasons are the raw material for the tool-choice categorisation, but asking for an explanation can
+# itself change the choice (Fox, Ericsson & Best 2011). Run the same tasks with minimal.yaml and this file first,
+# and compare search-tool share and resolve rate, before the parameter goes into every configuration.
+#
+# wording: two pilots on 18 Oct 2026 ("One sentence on why you chose this tool for this step." and "Explain in one
+# sentence why you chose this tool over the other available tools for this step.", field named `reason`) only
+# produced step labels like "Find ResolveContext definition"; not one of 3,000+ reasons compared tools. A parameter
+# description alone is too weak, so the field is now named why_this_tool, the description asks for one sentence
+# per tool (chosen and not chosen), and the instance_template repeats the instruction. A call that leaves a field
+# out, blank or misnamed is refused with exit 127 (see model.refuse_reason_gaps); until 9 Nov 2026 it got a format
+# error, which killed GLM trials after 3 in a row.
+# 19 Oct 2026: the reason against each other tool moved from a "<chosen tool>: <reason>. <other tool>: <reason
+# against>." skeleton in why_this_tool into its own why_not_<tool> field (reason_against_prompt), because GLM 5.3
+# swapped the two labels in 73 of 547 coded calls. BashModel has a single tool, so it gets why_this_tool only.
+model:
+  reason_prompt: One sentence on why you chose to use this tool for this step. Do not describe what the step does.
+  reason_against_prompt: One sentence on why you did not choose the {tool} tool for this step.
+  model_kwargs:
+    num_retries: 15
+    retry_strategy: exponential_backoff_retry
+  format_error_template: |
+    {% if finish_reason is defined and (finish_reason == "length" or (finish_reason == "tool_calls" and not has_tool_calls)) -%}
+    Your previous response reached the output token limit (finish_reason={{ finish_reason }}) before you produced a tool call, so it was cut off. Respond more concisely and finish with a tool call.
+    {%- else -%}
+    Tool call error:
+
+    <error>
+    {{error}}
+    </error>
+
+    Every response must contain at least one tool call. To finish, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call.
+    {%- endif %}
+agent:
+  instance_template: |
+    Please solve this issue: {{task}}
+
+    Use your tools to inspect the repository and implement the fix. Every call runs in a fresh subshell, so directory changes and environment variables do not persist between calls.
+
+    Every tool has a why_this_tool field and, for each other tool you have, a why_not_<tool> field. Fill why_this_tool with one sentence on why you chose that tool for the step and each why_not_<tool> field with one sentence on why you did not choose that tool. Do not describe what the step does, the command already says that.
+
+    When you are done, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call. You cannot continue after it.
+
+    <system_information>
+    {{system}} {{release}} {{version}} {{machine}}
+    </system_information>

shellbent-0.1.0/minimal-search-read.yaml

@@ -0,0 +1,44 @@
+# free-choice configuration with both named tools: minimal.yaml with model.tools set to [search, read], so the surface is bash
+# plus search plus read, no reason fields, no directive, no blocking. The prompt is byte-identical to minimal.yaml
+# (tests/test_model.py checks that). Used with --ak model_class=thesis_tools.model.ToolsModel.
+#
+# why: the question "does the agent keep using bash when both tools are offered and nothing nudges it" needs a configuration
+# with nothing else changed. Qwen's reason fields never moved adoption (2.8% with and without), so they are left out.
+#
+# min_request_interval is run infrastructure, not part of the configuration: 8 parallel trials under a quota of 1,500 requests
+# per hour is 8 * 3600 / 1500 = 19.2 s between calls per trial. Adjust for other n or quotas, drop it without a quota.
+#
+# mini-swe-agent's default instance_template is 3 KB of bash examples and formatting rules from before native tool calling.
+# we replace it with a short one that names no tool, the tools are only described by their schemas.
+#
+# model_kwargs is the retry block from bash.yaml. format_error_template is the one from tools.yaml without
+# the bash specific text.
+model:
+  tools: [search, read]
+  min_request_interval: 19.2
+  model_kwargs:
+    num_retries: 15
+    retry_strategy: exponential_backoff_retry
+  format_error_template: |
+    {% if finish_reason is defined and (finish_reason == "length" or (finish_reason == "tool_calls" and not has_tool_calls)) -%}
+    Your previous response reached the output token limit (finish_reason={{ finish_reason }}) before you produced a tool call, so it was cut off. Respond more concisely and finish with a tool call.
+    {%- else -%}
+    Tool call error:
+
+    <error>
+    {{error}}
+    </error>
+
+    Every response must contain at least one tool call. To finish, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call.
+    {%- endif %}
+agent:
+  instance_template: |
+    Please solve this issue: {{task}}
+
+    Use your tools to inspect the repository and implement the fix. Every call runs in a fresh subshell, so directory changes and environment variables do not persist between calls.
+
+    When you are done, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call. You cannot continue after it.
+
+    <system_information>
+    {{system}} {{release}} {{version}} {{machine}}
+    </system_information>

shellbent-0.1.0/minimal.yaml

@@ -0,0 +1,35 @@
+# config for the minimal-prompt run, the same file is used for both model classes. Pier loads it on top of mini.yaml with
+#   --ak config_file=minimal.yaml --ak model_class=thesis_tools.model.<BashModel|ToolsModel>
+#
+# mini-swe-agent's default instance_template is 3 KB of bash examples and formatting rules from before native tool calling.
+# we replace it with a short one that names no tool, the tools are only described by their schemas.
+#
+# model_kwargs is the retry block from bash.yaml. format_error_template is the one from tools.yaml without
+# the bash specific text.
+model:
+  model_kwargs:
+    num_retries: 15
+    retry_strategy: exponential_backoff_retry
+  format_error_template: |
+    {% if finish_reason is defined and (finish_reason == "length" or (finish_reason == "tool_calls" and not has_tool_calls)) -%}
+    Your previous response reached the output token limit (finish_reason={{ finish_reason }}) before you produced a tool call, so it was cut off. Respond more concisely and finish with a tool call.
+    {%- else -%}
+    Tool call error:
+
+    <error>
+    {{error}}
+    </error>
+
+    Every response must contain at least one tool call. To finish, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call.
+    {%- endif %}
+agent:
+  instance_template: |
+    Please solve this issue: {{task}}
+
+    Use your tools to inspect the repository and implement the fix. Every call runs in a fresh subshell, so directory changes and environment variables do not persist between calls.
+
+    When you are done, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the only bash command in that call. You cannot continue after it.
+
+    <system_information>
+    {{system}} {{release}} {{version}} {{machine}}
+    </system_information>

shellbent-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "shellbent"
+version = "0.1.0"
+description = "mini-swe-agent 2.4.6 model classes and named tools for a thesis on agent tool surfaces"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "mini-swe-agent==2.4.6",
+    "ripgrep-bin==15.2.0; sys_platform == 'linux'",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# The import package keeps its original name, so model_class=thesis_tools.model.* in existing launchers stays valid.
+[tool.hatch.build.targets.wheel]
+packages = ["thesis_tools"]

shellbent-0.1.0/tests/test_model.py

@@ -0,0 +1,225 @@
+import json
+import re
+import subprocess
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+import yaml
+from minisweagent.exceptions import FormatError
+
+from minisweagent.models.utils.actions_toolcall import BASH_TOOL
+
+import litellm
+
+from thesis_tools.model import BLOCKED_GREP, BLOCKED_READ, BashModel, ToolsModel, rate_limit_wait, runs_grep, runs_read
+from thesis_tools.read import READ_TOOL
+from thesis_tools.search import SEARCH_TOOL
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_tool_surface():
+    assert [t["function"]["name"] for t in BashModel(model_name="x").tools] == ["bash"]
+    assert [t["function"]["name"] for t in ToolsModel(model_name="x").tools] == [
+        "bash",
+        "search",
+    ]
+    assert ToolsModel(model_name="x", tools=["read"]).tools == (BASH_TOOL, READ_TOOL)
+    assert ToolsModel(model_name="x", tools=["search", "read"]).tools == (BASH_TOOL, SEARCH_TOOL, READ_TOOL)
+
+
+def test_tool_directive():
+    free = ToolsModel(model_name="x").tools[1]["function"]["description"]
+    assert free == SEARCH_TOOL["function"]["description"]
+    steered = ToolsModel(model_name="x", tool_directive="Use me. ").tools[1][
+        "function"
+    ]["description"]
+    assert steered == "Use me. " + free
+    assert (
+        SEARCH_TOOL["function"]["description"] == free
+    )  # the module constant is untouched
+
+
+def test_reason_prompt():
+    # without the prompt the schemas are the module constants, nothing is added
+    assert BashModel(model_name="x").tools == (BASH_TOOL,)
+    assert ToolsModel(model_name="x").tools[1] is SEARCH_TOOL
+
+    for tool in ToolsModel(model_name="x", reason_prompt=" Why? ").tools:
+        params = tool["function"]["parameters"]
+        assert list(params["properties"])[0] == "why_this_tool"  # first, so the model writes it before the action
+        assert params["properties"]["why_this_tool"] == {"type": "string", "description": "Why?"}
+        assert params["required"][0] == "why_this_tool"
+    bash = BashModel(model_name="x", reason_prompt="Why?").tools[0]["function"]["parameters"]
+    assert bash["required"] == ["why_this_tool", "command"]
+    # with reason_against_prompt every tool gets one why_not_<other> field after why_this_tool, a single tool none
+    kw = dict(model_name="x", reason_prompt="Why?", reason_against_prompt="Why not {tool}?")
+    assert list(BashModel(**kw).tools[0]["function"]["parameters"]["properties"]) == ["why_this_tool", "command"]
+    bash, search = (t["function"]["parameters"] for t in ToolsModel(**kw).tools)
+    assert bash["required"][:3] == ["why_this_tool", "why_not_search", "command"]
+    assert bash["properties"]["why_not_search"]["description"] == "Why not search?"
+    assert list(search["properties"])[:2] == ["why_this_tool", "why_not_bash"]
+    assert search["required"][:2] == ["why_this_tool", "why_not_bash"]
+    # the module constants are untouched
+    assert "why_this_tool" not in BASH_TOOL["function"]["parameters"]["properties"]
+    assert "why_this_tool" not in SEARCH_TOOL["function"]["parameters"]["properties"]
+
+
+def response(*calls):
+    """A litellm-shaped response with one tool call per (name, args) pair."""
+    tool_calls = [
+        SimpleNamespace(id=f"c{i}", function=SimpleNamespace(name=name, arguments=json.dumps(args)))
+        for i, (name, args) in enumerate(calls)
+    ]
+    return SimpleNamespace(choices=[SimpleNamespace(message=SimpleNamespace(tool_calls=tool_calls), finish_reason="stop")])
+
+
+def test_reason_gap_is_refused():
+    # a missing, blank or misnamed reason field: the call is refused with exit 127, the other calls of the response run
+    kw = dict(model_name="x", reason_prompt="Why?", reason_against_prompt="Why not {tool}?")
+    full = {"why_this_tool": "a.", "why_not_search": "b.", "command": "ls"}
+    for model in (BashModel(model_name="x", reason_prompt="Why?"), ToolsModel(**kw)):
+        for args in ({"command": "ls"}, {"why_this_tool": " ", "why_not_search": "b.", "command": "ls"}):
+            out, code = refused(model._parse_actions(response(("bash", args)))[0])
+            assert code == 127 and "missing why_this_tool" in out
+    model = ToolsModel(**kw)
+    ok, bad = model._parse_actions(response(("bash", full), ("bash", {"why_this_tool": "a.", "why_not_bash": "b.", "command": "ls"})))
+    assert ok["command"] == "ls"
+    assert refused(bad) == ("Nothing in this bash call was run. It is missing why_not_search. The bash tool has no "
+                            "why_not_bash argument. Send the call again with every why_ argument filled in.\n", 127)
+    assert "thesis_tools.search" not in model._parse_actions(response(("search", {"pattern": "x"})))[0]["command"]
+    # after 3 refused responses in a row the gap runs anyway, until a clean response resets the count
+    model = ToolsModel(**kw)
+    gap = response(("bash", {"command": "ls"}))
+    assert [model._parse_actions(gap)[0]["command"] == "ls" for _ in range(5)] == [False, False, False, True, True]
+    assert model._parse_actions(response(("bash", full)))[0]["command"] == "ls"
+    assert model._parse_actions(gap)[0]["command"] != "ls"
+    # without a reason prompt nothing is checked
+    assert ToolsModel(model_name="x")._parse_actions(gap)[0]["command"] == "ls"
+
+
+def test_runs_grep():
+    blocked = ["grep -rn foo src", "cd /x && grep -n foo a.py | head", "rg foo", "git grep foo", "find . | xargs grep foo",
+               "ls || grep foo", "sleep 5; grep -c BUILD /tmp/log", "egrep foo a", "cat > p.py <<'EOF'\nx = 1\nEOF\ngrep x p.py",
+               "ps aux | grep -v grep; grep x a"]
+    allowed = ["ps aux | grep -c rustc", "git log --grep=foo", "cat a | grep foo | grep -v bar", "./rg foo", "my_grep x",
+               "python3 -c 'import re; re.search(1,2)'", "cat > s.sh <<'EOF'\ngrep -rn foo .\nEOF", "python3 - <<EOF\n  grep\nEOF",
+               "ps aux | grep x | grep -v grep", "ps -ef | grep -v grep | grep -E java", 'tsc 2>&1 | grep -E x; echo "grep-exit: $?"']
+    assert [c for c in blocked if not runs_grep(c)] == []
+    assert [c for c in allowed if runs_grep(c)] == []
+
+
+def refused(action):
+    """Runs a blocked action's command in bash and returns (output, exit code)."""
+    result = subprocess.run(["bash", "-lc", action["command"]], capture_output=True, text=True)
+    return result.stdout, result.returncode
+
+
+def test_block_grep_is_a_failed_command():
+    model = ToolsModel(model_name="x", block_grep=True)
+    assert model._parse_actions(response(("bash", {"command": "ps aux | grep x"})))[0]["command"] == "ps aux | grep x"
+    assert "thesis_tools.search" in model._parse_actions(response(("search", {"pattern": "grep"})))[0]["command"]
+    # the blocked call fails like a missing program, the other calls of the response still run
+    ls, grep = model._parse_actions(response(("bash", {"command": "ls"}), ("bash", {"command": "grep -rn x ."})))
+    assert ls["command"] == "ls" and grep["tool_call_id"] == "c1"
+    assert refused(grep) == (BLOCKED_GREP + "\n", 127)
+    assert ToolsModel(model_name="x")._parse_actions(response(("bash", {"command": "grep -rn x ."})))[0]["command"]
+
+
+def test_runs_read():
+    blocked = ["cat a.py", "cd src && cat -n a.py", "head -20 a.py", "head -n 5 a.py | grep x", "nl a.py",
+               "sed -n '10,20p' a.py", "sed -ne 10p a.py", "sed -En '/x/p' a.py", "sed --quiet 1p a", "ls; cat a",
+               "cat a 2>&1", "cat > p.py <<'EOF'\nx = 1\nEOF\npython3 p.py; cat /tmp/out.log", "xargs cat < l"]
+    allowed = ["ls | head -5", "git log | tail -3", "tail -30 a.py", "cat <<'EOF' > a.py\nx\nEOF", "cat > a.py", "cat a > b",
+               "sed -i 's/a/b/' a.py", "sed -n -i 's/a/b/' a.py", "sed 's/a/b/' a.py", "./cat x", "my_cat x",
+               "echo category", "git commit -m 'more tests'", "python3 - <<'PY'\ns = open('a').read()\nhead = s[:5]\nPY",
+               'javac -cp "$(cat cp.txt)" A.java', "perl -pe \"$(cat fix.pl)\" a", "git cat-file -p HEAD"]
+    assert [c for c in blocked if not runs_read(c)] == []
+    assert [c for c in allowed if runs_read(c)] == []
+
+
+def test_block_read_is_a_failed_command():
+    kw = dict(model_name="x", tools=["read"], block_read=True, format_error_template="bad: {{error}}")
+    model = ToolsModel(**kw)
+    assert "thesis_tools.read" in model._parse_actions(response(("read", {"path": "cat"})))[0]["command"]
+    assert model._parse_actions(response(("bash", {"command": "grep -rn x ."})))[0]["command"]  # only block_read is on
+    # the blocked command itself never runs, only the message comes back
+    assert refused(model._parse_actions(response(("bash", {"command": "cat 'a b.py'"})))[0]) == (BLOCKED_READ + "\n", 127)
+    # a search call on a read-only surface is an unknown tool to mini, not a dispatch
+    with pytest.raises(FormatError):
+        model._parse_actions(response(("search", {"pattern": "x"})))
+
+
+def test_minimal_yamls_share_the_prompt():
+    base = yaml.safe_load((ROOT / "minimal.yaml").read_text())
+    for name, key in [("minimal-directive.yaml", "tool_directive"), ("minimal-reason.yaml", "reason_prompt"),
+                      ("minimal-reason-nogrep.yaml", "block_grep"), ("minimal-reason-read.yaml", "tools"),
+                      ("minimal-reason-read-nocat.yaml", "block_read"), ("minimal-search-read.yaml", "tools")]:
+        other = yaml.safe_load((ROOT / name).read_text())
+        if name not in ("minimal-directive.yaml", "minimal-search-read.yaml"):  # the reason configurations add exactly one paragraph about the field, the blocked ones one more
+            lines = other["agent"]["instance_template"].splitlines()
+            extra = [l for l in lines if "why_this_tool" in l or "not available as commands" in l]
+            assert len(extra) == (2 if key.startswith("block_") else 1)
+            reason = yaml.safe_load((ROOT / "minimal-reason.yaml").read_text())["model"]
+            assert all(other["model"][k] == reason[k] for k in ("reason_prompt", "reason_against_prompt"))
+            kept = re.sub(r"\n{3,}", "\n\n", "\n".join(l for l in lines if l not in extra)) + "\n"
+            assert kept == base["agent"]["instance_template"]
+            assert {k: v for k, v in other["agent"].items() if k != "instance_template"} == {
+                k: v for k, v in base["agent"].items() if k != "instance_template"}
+        else:
+            assert other["agent"] == base["agent"]
+        assert other["model"]["format_error_template"] == base["model"]["format_error_template"]
+        assert other["model"][key]
+    for name in ("minimal-reason-read.yaml", "minimal-reason-read-nocat.yaml"):
+        assert yaml.safe_load((ROOT / name).read_text())["model"]["tools"] == ["read"]
+    search_read = yaml.safe_load((ROOT / "minimal-search-read.yaml").read_text())["model"]
+    assert search_read["tools"] == ["search", "read"]
+    assert not any(k in search_read for k in ("reason_prompt", "tool_directive", "block_grep", "block_read"))
+
+
+def rate_limit(message="Rate limit exceeded. Request limit (375/hour) (Retry after 591s).", headers=None):
+    return litellm.exceptions.RateLimitError(message, llm_provider="openai", model="x", headers=headers)
+
+
+def test_rate_limit_wait():
+    assert rate_limit_wait(rate_limit()) == 591  # the message text
+    assert rate_limit_wait(rate_limit(headers={"Retry-After": "30"})) == 30  # the header wins when present
+    assert rate_limit_wait(rate_limit(headers={"retry-after": "1.5"})) == 1.5
+    assert rate_limit_wait(rate_limit("Rate limit exceeded.")) == 60  # neither: the default
+
+
+def test_query_sleeps_out_the_rate_limit(monkeypatch):
+    calls, sleeps = [], []
+    monkeypatch.setattr("thesis_tools.model.time.sleep", sleeps.append)
+    monkeypatch.setattr("thesis_tools.model.time.monotonic", lambda: 1000.0)
+    def completion(**kw):
+        calls.append(kw)
+        if len(calls) < 3:
+            raise rate_limit(f"Request limit (375/hour) (Retry after {len(calls)}0s).")
+        return "response"
+    monkeypatch.setattr("thesis_tools.model.litellm.completion", completion)
+    assert BashModel(model_name="x")._query([]) == "response"
+    assert sleeps == [15, 25]  # Retry-After plus 5 s of slack, once per 429
+    assert len(calls) == 3 and calls[0]["tools"] == (BASH_TOOL,)
+    # the total wait is capped, then the error ends the trial as before
+    calls.clear(), sleeps.clear()
+    with pytest.raises(litellm.exceptions.RateLimitError):
+        BashModel(model_name="x", max_rate_limit_wait=20)._query([])
+    assert sleeps == [15]
+
+
+def test_query_paces_requests(monkeypatch):
+    now, sleeps = [1000.0], []
+    monkeypatch.setattr("thesis_tools.model.time.monotonic", lambda: now[0])
+    monkeypatch.setattr("thesis_tools.model.time.sleep", lambda s: (sleeps.append(s), now.__setitem__(0, now[0] + s)))
+    monkeypatch.setattr("thesis_tools.model.litellm.completion", lambda **kw: "response")
+    model = BashModel(model_name="x", min_request_interval=19.2)
+    model._query([])  # the first call never waits
+    now[0] += 4  # the model answered and the command ran for 4 s
+    model._query([])
+    assert sleeps == [pytest.approx(15.2)]  # 19.2 s from the start of the previous call
+    now[0] += 30
+    model._query([])
+    assert len(sleeps) == 1  # already past the interval, no wait
+    assert BashModel(model_name="x").config.min_request_interval == 0  # the older configs are unpaced