thunc 0.2.1__tar.gz → 0.2.2__tar.gz

{thunc-0.2.1 → thunc-0.2.2}/CHANGELOG.md

@@ -3,6 +3,75 @@
 All notable changes to thunc. The full notes for each release are on the
 [releases page](https://github.com/Eltarras/thunc/releases).
 
+## 0.2.2 (beta)
+
+**Agents that use their tools reliably, and faster calls.** Agents on Claude Code make native tool
+calls instead of writing each action as JSON text, a failed step is retried instead of ending the
+run, and the agent's tools fill gaps a benchmark found. In that tool-use benchmark
+(`live_tests/bench_tooluse.py`, 8 tasks, Claude Sonnet 5.5, 3 runs each), agents on Claude Code went
+from 12 of 24 runs passing to 24 of 24, from 99 to 10 seconds a task, and from $0.084 to $0.022 a
+task; Claude Code itself took 11 seconds and $0.069. The API backends also reuse their connections,
+Codex answers return sooner, and `thunc run --profile` shows where a program's time goes.
+
+### Behavior changes
+
+Nothing is removed, but these defaults change:
+
+- **Agents on `claude-code` make native tool calls** (see Added). With a `claude` CLI too old for
+  them, or with MCP servers turned off by a policy, a run falls back to the text protocol with a
+  warning. `protocol="text"` keeps the old way.
+- **`list` and `search` leave out what git ignores** in a git repository (build output, caches,
+  vendored code). A folder named explicitly is still listed and searched.
+- **Long command output keeps its start and its end** (the first error and the summary), not only
+  the end.
+- **The `claude-code` backend loads none of your Claude Code settings** (`--setting-sources ""`):
+  no `CLAUDE.md`, settings or hooks reach thunc's calls, plain function calls included, so an
+  agent's `workdir` can't give it instructions unless `follow=` asks for them.
+
+### Added
+
+- **Native calls on `claude-code`**: the agent's tools are an MCP server that one `claude -p`
+  process per run calls; thunc carries out each call with its own tools, permissions and run
+  record. The CLI runs in the agent's `workdir`. `protocol="text"` keeps the old way, and durable
+  runs on Claude Code still use it. When Claude Code can't start native calls (an older CLI, or MCP
+  servers turned off by a policy), a run falls back to the text protocol with a warning and a
+  `fallback` entry in its record; `protocol="native"` raises instead.
+- **`run` takes `cwd`**, a folder inside `workdir` to run the command in.
+- **The `shell` permission** runs command lines through the system shell, so pipes, `&&`, `cd`
+  and redirects work. Off by default; it can't be combined with `!run:` rules.
+- **`search` takes `glob`** (`*.py` by file name, `src/**/*.ts` by path) to limit the files
+  searched.
+- **`thunc run --profile`**: runs a script (or `-m module`) and prints a performance report to
+  stderr when it ends: per function, calls, cache hits, retries, failures, total/mean/p95/max time
+  and the split between model time and thunc's own; for agents, steps and time in each tool; and
+  the share of wall time spent in thunc, with the overlap from `thunc.map`.
+
+### Changed
+
+- **A failed step is retried.** A timeout, lost connection, rate limit, server error or CLI call
+  that ended in an error (`thunc.errors.TransientError`) is retried twice in an agent run, with a
+  note in the run record, before the run fails. A text-protocol step on Claude Code or Codex may
+  take 120 seconds before it's retried, instead of the whole `timeout`.
+- **The `anthropic` and `openai` backends reuse their connections.** One SDK client is shared by
+  every call in the process (`thunc.map`'s threads and agent runs included), instead of a new
+  client, and so a new TCP and TLS handshake, for each call. A new client is made when the API key,
+  the SDK's environment variables (`ANTHROPIC_*`, `OPENAI_*`) or the process change. In a local
+  benchmark with 60 ms of connection setup, 20 calls in a row went from 1.47 s to 68 ms.
+- **Agents on the text protocol can act several times per reply.** On Codex and `protocol="text"`
+  (and on Claude Code when it falls back to the text protocol), a reply can be a JSON array of
+  independent actions (reading three files) instead of one. They run in order, at most 16 per reply,
+  and every result comes back together, as with native tool calls. Each turn resends the whole
+  transcript and, on the CLI backends, starts the CLI, so fewer turns save both. A single JSON
+  action works as before. On Codex, with `live_tests/eval_prompts.py` (default prompt, 5 runs of
+  each task), every run batched its first reads: replies went from 6.0 / 4.8 / 5.0 to 5.0 / 3.0 /
+  3.6 (fix / review / analysis) and the mean time from 37 / 27 / 27 s to 29 / 19 / 21 s, with the
+  same work done and 30/30 passing.
+- **The `codex` backend returns as soon as the answer arrives.** It reads Codex's JSON events as
+  they come (`codex exec --json`) instead of waiting for the process to exit and reading the answer
+  from a file. Codex takes about 0.4 s to shut down after answering; that now happens in the
+  background. Over 8 alternating pairs of real calls the new way was faster every time, by a median
+  of 0.67 s on a call of about 4 s. Every agent turn on Codex is one call, so the saving repeats.
+
 ## 0.2.1 (beta)
 
 **Durable agents with Temporal.** An optional `thunc[temporal]` runtime records each model turn

{thunc-0.2.1 → thunc-0.2.2}/CONTRIBUTING.md

@@ -16,34 +16,59 @@ Thanks for helping. thunc is in beta, so feedback on the API is as useful as cod
 
 ```bash
 git clone https://github.com/Eltarras/thunc && cd thunc
-python3 -m venv .venv && .venv/bin/pip install -e ".[anthropic,openai,dev]"
+python3 -m venv .venv && .venv/bin/pip install -e ".[anthropic,openai,temporal-test,dev]"
 ```
 
-The README's [Development](README.md#development) section lists the commands for tests and checks.
+`temporal-test` installs the pinned Temporal SDK the durable-run tests use. Without it the tests in
+`tests/temporal/` are skipped and everything else still runs. The README's
+[Development](README.md#development) section lists the commands for live tests.
 
 ## Before you open a PR
 
-CI runs these on Python 3.10 to 3.14, and all must pass:
+CI runs these on Python 3.10 to 3.14 on Linux, and all must pass. Run each on its own and check
+its exit code:
 
 ```bash
 .venv/bin/pytest
-.venv/bin/ruff check . && .venv/bin/ruff format --check .
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
 .venv/bin/mypy --strict thunc
+.venv/bin/mypy --strict --platform win32 thunc
+```
+
+CI also runs the offline tests on Windows (Python 3.13), since the agent lock, command handling and
+paths have Windows-only code. If you touch `thunc/temporal/`, run the integration tests against a
+real local Temporal service too (they download it once and make no model calls):
+
+```bash
+THUNC_TEMPORAL_TESTS=1 .venv/bin/pytest -c pytest-temporal.ini tests/temporal
 ```
 
 ## Ground rules
 
 - **Standard library only in the core.** A provider SDK is an optional extra in `pyproject.toml`,
-  imported inside its backend function, never at module level.
+  imported inside its backend function, never at module level. The same goes for Temporal:
+  only `thunc/temporal/` imports `temporalio`, and `thunc.call`, `@thunc.function` and
+  `agent.run()` must keep working without it.
 - **Tests in `tests/` never call a real model.** Use the `fake` fixture in `tests/conftest.py`,
-  which returns scripted replies and records the prompts. Real calls belong in `live_tests/`,
-  which CI doesn't run.
+  which returns scripted replies and records the prompts. Tests of native tool calls replace only
+  the SDK client and use the SDK's real types. Real calls belong in `live_tests/`, which CI
+  doesn't run.
+- **Agent permissions are a safety boundary.** A change to `permissions.py`, `tools.py` or the
+  effect journal in `thunc/temporal/effects.py` needs a test that fails when the rule is broken.
+  Check it by breaking the rule on purpose and watching the test fail.
+- **Durable runs replay.** Workflow code in `thunc/temporal/workflows.py` stays deterministic;
+  model calls, tools and file access happen in activities. A file or memory change goes through
+  the intent and receipt journal, and a command whose outcome is uncertain is never rerun
+  automatically. Before changing orchestration or the saved state format, version it and replay
+  saved histories (see the [Temporal guide](examples/temporal/README.md)).
 - **User data stays out of the instructions.** Inputs are sent separately from the prompt
   (see `_build_prompt` in `thunc/core.py`). Don't add code paths that paste inputs into
   instructions.
 - **Failures are loud.** When no valid answer arrives, raise `ThuncError`; never return a
   default value.
-- **Update the README** when you change the public API or the supported return types.
+- **Update the README** when you change the public API or the supported return types, and the
+  [Temporal guide](examples/temporal/README.md) when you change durable runs.
 - **One change per PR**, with a description of what it does and how you tested it.
 
 ## Adding a backend
@@ -58,7 +83,14 @@ CI runs these on Python 3.10 to 3.14, and all must pass:
    `thunc/config.py` if needed.
 3. Add an optional extra for its SDK in `pyproject.toml`, and add the extra to the CI install.
 4. Add offline tests with a stubbed SDK module, like the existing ones in `tests/test_backends.py`.
-5. Run `THUNC_BACKEND=<name> .venv/bin/pytest live_tests` against the real service, and say in
+5. Agents work on any text backend through the JSON text protocol. For native tool calls, add a
+   `Conversation` for the API in `thunc/native.py`, add the backend to `native.NATIVE`, and pick
+   the class where `thunc/agent.py` builds the conversation. Test it like `tests/test_native.py`.
+   A CLI that can call MCP tools can get native calls the way Claude Code does
+   (`thunc/claude_code.py`, tested with a fake CLI in `tests/test_claude_code_agent.py`).
+   Raise `TransientError` for failures worth asking again, so agent runs retry them.
+   Agents and durable runs refuse typed backends.
+6. Run `THUNC_BACKEND=<name> .venv/bin/pytest live_tests` against the real service, and say in
    the PR that you did.
 
 ## Known issues
@@ -73,8 +105,7 @@ model is asked again instead of thunc guessing:
 - Quoted numbers (`"4"` for an `int`), labels in the wrong case (`Bug` for `bug`), prose around
   JSON, Python-style values (`['a']`, `None`), trailing commas, curly quotes, non-ASCII digits.
 - Unquoted text for `str | None`, and exclamations like `Yes!` for a `bool`.
-- Several `<think>` blocks in a row, several lines of prose before a fence, `~~~`, indented or
-  four-backtick fences.
+- Several `<think>` blocks in a row, `~~~`, indented or four-backtick fences.
 - A one-key object whose key is a field of the expected dataclass: `{"customer": {...}}` for an
   `Order` with a `customer` field is an `Order` with a bad customer, not a wrapper.
 - A reply after the closing fence (for example a reasoning paragraph): it could be a second answer.
@@ -86,7 +117,11 @@ no reliable way to tell them from a real one. Only an empty reply is retried.
 **Open: behavior that might change.**
 
 - `thunc.map` loses every result when one item fails, and returns coroutines for `async` functions.
-- Backend errors (timeouts, connection failures) are never retried; only bad replies are.
+- Backend errors (timeouts, connection failures) are never retried by `thunc.call`; only bad
+  replies are. Local agent runs retry a step that failed with a `TransientError` twice, and durable
+  runs retry transient provider failures.
+- Several lines of prose before a code fence are read as a preamble, though `_unfence` in
+  `thunc/schema.py` documents one line, and no test pins either behavior.
 - A union takes the first option that accepts the reply as JSON, in the order written: `3` for
   `float | int` is `3.0`. An unquoted label is only tried after that, so `2` for
   `Literal["2"] | int` is the int `2`, not the label.
@@ -109,10 +144,38 @@ no reliable way to tell them from a real one. Only an empty reply is retried.
 - A list of dataclasses passed as an input is shown to the model as Python reprs, not JSON.
 - A string return annotation naming a class defined after the function raises `NameError` when
   the decorator runs.
-- `make_dataclass` classes, and `Annotated` fields on Python 3.10, aren't supported.
+- On Python 3.10 and 3.11, a `make_dataclass` class whose field types are strings naming anything
+  but builtins (`"Item"`, `"Annotated[int, 'x']"`) raises `NameError`: before 3.12 its module is
+  `types`, not the caller's.
+- `Annotated[...]` works on dataclass fields but not as a return type.
 - The Python 3.10 fallback for string annotations (`_hints` and `resolve_strings` in
   `thunc/schema.py`) can be removed when 3.10 support is dropped.
 
+**Open: agents and durable runs.**
+
+- Durable runs on `claude-code` use the JSON text protocol, not native calls: the MCP path keeps
+  one CLI process for the whole run, which a durable step can't snapshot. The text protocol is the
+  weaker one: in `live_tests/bench_tooluse.py` on Sonnet 5.5 it passed 12 of 24 runs, and 20 of 24
+  with step retries (measured before action arrays), against 24 of 24 for native calls.
+- The `shell` permission isn't tested on Windows: its test is skipped there, so `cmd /c` has never
+  run in CI.
+- With `shell`, a file read with `cat` doesn't count as read for `edit`, which refuses until the
+  agent reads it with `read` (the no-blind-overwrite rule). Agents work around it with a short
+  `read`, at the cost of a step.
+- The agent loops on the Claude and OpenAI APIs have no live tool-use benchmark yet (only
+  `live_tests/eval_prompts.py`); their `max_tokens`, effort and stop-reason handling were reviewed
+  from the code only (`live_tests/bench_tooluse_report.md`, finding 7).
+- Durable agents can't use `tools=` yet: the effects of the program's own functions can't be
+  journaled.
+- Durable runs have no garbage collection: the journal, transcript artifacts and request-ID
+  tombstones are kept forever. There's no context summarization either, so a long run fails once
+  its saved state passes 16 MiB.
+- A durable workspace can only restart on the same volume and absolute paths; nothing moves it
+  between hosts.
+- A hard worker kill can leave a command's subprocesses running.
+- Durable runs aren't tested on Windows (the code is only type-checked for it), and there are no
+  live provider tests for durable runs yet.
+
 ## Reporting bugs
 
 Open an [issue](https://github.com/Eltarras/thunc/issues) with:

{thunc-0.2.1 → thunc-0.2.2}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.5
 Name: thunc
-Version: 0.2.1
+Version: 0.2.2
 Summary: think + function: call an LLM like a typed Python function.
 Project-URL: Homepage, https://eltarras.github.io/thunc/
+Project-URL: Documentation, https://eltarras.github.io/thunc/docs/
 Project-URL: Repository, https://github.com/Eltarras/thunc
 Project-URL: Issues, https://github.com/Eltarras/thunc/issues
 Author: Hussein Eltarras
@@ -32,20 +33,24 @@ Requires-Dist: pytest-asyncio>=0.24; extra == 'temporal-test'
 Requires-Dist: temporalio==1.34.0; extra == 'temporal-test'
 Description-Content-Type: text/markdown
 
-![thunc: call an LLM like a typed Python function](https://raw.githubusercontent.com/Eltarras/thunc/main/.github/social-preview.png)
-
-[![CI](https://github.com/Eltarras/thunc/actions/workflows/ci.yml/badge.svg)](https://github.com/Eltarras/thunc/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/thunc)](https://pypi.org/project/thunc/)
-[![Website](https://img.shields.io/badge/website-eltarras.github.io%2Fthunc-f5b14c)](https://eltarras.github.io/thunc/)
+![A thunc function returning list[Item] is called with "2 oat lattes and a croissant pls. oh, one more latte!" and returns two Item dataclasses: oat latte ×3 and croissant ×1.](https://raw.githubusercontent.com/Eltarras/thunc/main/.github/demo-function.gif)
 
 **think + function.** Call an LLM like a typed Python function.
 
-> **Status: beta (v0.2).** Expect bugs; the API may change. Feedback and issues are welcome.
+[![PyPI](https://img.shields.io/pypi/v/thunc)](https://pypi.org/project/thunc/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/thunc/)
+[![CI](https://github.com/Eltarras/thunc/actions/workflows/ci.yml/badge.svg)](https://github.com/Eltarras/thunc/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/Eltarras/thunc/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-eltarras.github.io%2Fthunc-9b481b)](https://eltarras.github.io/thunc/docs/)
+
+```bash
+pip install thunc
+```
 
 ```python
 import thunc
 
-thunc.configure(backend="claude-code")
+thunc.configure(backend="claude-code")  # or "codex", "anthropic", "openai"
 
 
 @thunc.function
@@ -57,26 +62,43 @@ def urgency(ticket: str) -> int:
 urgency("I was charged twice!")  # -> 4, a checked int
 ```
 
-The answer is parsed into the declared type. If it doesn't fit, the model is asked again, and
-after that `thunc.ThuncError` is raised. The library uses the standard library only and needs
-Python 3.10+.
+The docstring is the prompt and the return annotation is the type. The answer is parsed into that
+type; if it doesn't fit, the model is asked again, and after that `thunc.ThuncError` is raised. No
+dependencies, Python 3.10+.
+
+It also runs [agents](#agents): typed functions that can read, edit and test your code before they
+answer.
 
-It runs on the Claude API, the OpenAI API, a local model (LM Studio, or any server that speaks the
-OpenAI API), or your Claude Code or Codex login.
+The [docs](https://eltarras.github.io/thunc/docs/) cover everything below, a page per topic.
 
-## Install
+## Quickstart
+
+No API key needed if you have Claude Code or Codex installed: thunc can use their login.
 
 ```bash
-pip install thunc               # standard library only
-pip install "thunc[anthropic]"  # adds the Claude API backend
-pip install "thunc[openai]"     # adds the OpenAI API backend
-pip install "thunc[temporal]"   # adds durable agents on Temporal
+pip install thunc
+THUNC_BACKEND=claude-code python3 -c 'import thunc; print(thunc.call("Say hello in five words or fewer."))'
 ```
 
-## Try it
+Swap in the backend you have:
+
+| You have | Set | Install |
+|---|---|---|
+| [Claude Code](https://claude.com/claude-code), logged in | `THUNC_BACKEND=claude-code` | `pip install thunc` |
+| [Codex](https://github.com/openai/codex), logged in | `THUNC_BACKEND=codex` | `pip install thunc` |
+| An Anthropic API key | `ANTHROPIC_API_KEY` | `pip install "thunc[anthropic]"` |
+| An OpenAI API key | `OPENAI_API_KEY` | `pip install "thunc[openai]"` |
+| A local model (LM Studio) | `OPENAI_BASE_URL` (see **Local models** below) | `pip install "thunc[openai]"` |
+
+With an API key set, thunc picks that backend on its own, so `THUNC_BACKEND` isn't needed. In code,
+`thunc.configure(backend=...)` does the same. Durable agents on Temporal add
+`pip install "thunc[temporal]"`.
+
+> **Beta (v0.2).** The API may still change. Bug reports and feedback are welcome in
+> [issues](https://github.com/Eltarras/thunc/issues).
 
-Clone the repo and run the examples from its root. No install is needed; the examples run through
-your local [Claude Code](https://claude.com/claude-code) login:
+**More examples.** Clone the repo and run them from its root, with no install, through your
+Claude Code login:
 
 ```bash
 git clone https://github.com/Eltarras/thunc && cd thunc
@@ -85,9 +107,6 @@ python3 -m examples.support_inbox
 THUNC_BACKEND=codex python3 -m examples.log_triage
 ```
 
-With an API key instead, install the SDK and pick the backend: `THUNC_BACKEND=openai` with
-`OPENAI_API_KEY`, or `THUNC_BACKEND=anthropic` with `ANTHROPIC_API_KEY`.
-
 ## Two ways to write a prompt
 
 | | When | |
@@ -184,7 +203,8 @@ or takes `--cache-dir`; it can't see a `configure(cache_dir=...)` in your code.
   `pip install "thunc[openai]"`. The default model is `gpt-5.5`. `OPENAI_BASE_URL` points it at
   any server that speaks the OpenAI Responses API.
 - `claude-code` and `codex` call your local CLI login, and are meant for cheap testing.
-  Both run with their own tools turned off, so the model can only answer. `codex` also ignores
+  Both run with their own tools turned off, so the model can only answer; an agent on
+  `claude-code` gets only its thunc tools, as native calls (see Agents). `codex` also ignores
   `~/.codex/config.toml` (your MCP servers, plugins, `notify` command and model settings); your
   login still works. Pick the model with `configure(model=...)` or `model=`.
 - `jev` is TypeSafe's [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev)
@@ -198,7 +218,7 @@ or takes `--cache-dir`; it can't see a `configure(cache_dir=...)` in your code.
   CLI always uses `jev-latest`), and an answer that fails `ensure=` isn't retried, since Jev would
   give the same one. It's only used when you choose it: `backend="jev"` or `THUNC_BACKEND=jev`.
   Setup (install the CLI, log in, check it works): the
-  [Jev guide](https://eltarras.github.io/thunc/jev.html).
+  [Jev guide](https://eltarras.github.io/thunc/docs/jev.html).
 
 **Local models:** the `openai` backend works with a local server through `OPENAI_BASE_URL`. This
 has been tested with [LM Studio](https://lmstudio.ai) running `openai/gpt-oss-20b`:
@@ -214,6 +234,31 @@ giving it alone.
 The backend can also be set with `THUNC_BACKEND`. With none set, `ANTHROPIC_API_KEY` (or a
 `configure(api_key=...)` alone) selects `anthropic`, and otherwise `OPENAI_API_KEY` selects `openai`.
 
+**Profiling:** run your program with `thunc run --profile` to see where the time went when it ends:
+
+```bash
+thunc run --profile support_inbox.py --limit 20   # a script and its arguments
+thunc run --profile -m myapp.triage               # a module, as with python -m
+```
+
+The report goes to stderr: per function, the calls, cache hits, retries and failures, the total,
+mean, p95 and slowest time, and how much of it was the model and how much thunc's own work
+(building the prompt, parsing, the cache). Agent runs get their steps, model time and time in each
+tool. It also says what share of the program's wall time was spent in thunc, and how much calls
+overlapped under `thunc.map`. Without `--profile`, `thunc run` just runs the program, and nothing
+is recorded. The program's exit code is passed through.
+
+```
+CALLS
+FUNCTION  CALLS  CACHED  RETRIES  FAILED  TOTAL   MEAN    P95    MAX  MODEL  LOCAL
+urgency      11       1        1       0  1.70s  155ms  309ms  309ms  1.69s   12ms
+
+In thunc:      774ms of 980ms wall time (79%); the rest was the program's own code
+Model time:    1.69s, 99% of the time in calls (anthropic/default model 1.69s)
+Concurrency:   calls overlapped 2.2x on average (thunc.map or threads)
+Slowest:       urgency took 309ms
+```
+
 **Type checking:** signatures and return types are visible to mypy and Pyright. mypy reports
 empty bodies; turn that off with `disable_error_code = ["empty-body"]`.
 
@@ -221,6 +266,8 @@ empty bodies; turn that off with `disable_error_code = ["empty-body"]`.
 
 > **New in 0.2.** Agents are new; their API may change in a later release as feedback comes in.
 
+![An agent allowed to write src/** and run pytest is asked to run the tests and fix any problems. pytest shows 1 failure; it reads src/pricing.py, fixes one line, reruns pytest (3 passed) and returns True.](https://raw.githubusercontent.com/Eltarras/thunc/main/.github/demo-agent.gif)
+
 An agent is a typed function that can look around before it answers. Give it a name and a working
 directory, declare its tasks the way you write `@thunc.function`, and call them from Python:
 
@@ -253,9 +300,15 @@ repo.call(f"Where is {setting} set?", returns=str)
 Each call is one run. The model takes one step at a time (list a folder, search, read or edit a
 file) and ends by calling `finish` with a value of the return type, which is checked like any thunc
 result. It runs on the Claude and OpenAI APIs through their own tool calls (the
-model can make several at once, and the fixed part of the prompt is cached), and on Claude Code and
-Codex by replying with one JSON action at a time. `protocol="text"` uses the second way on an API
-too, for example with a server behind `OPENAI_BASE_URL` that has no function calling.
+model can make several at once, and the fixed part of the prompt is cached). On Claude Code the
+calls are native too: the agent's tools are an MCP server that one `claude -p` process per run
+calls, while thunc carries out each call with its own tools, permissions and records. If Claude Code
+can't start them (an older `claude` CLI, or MCP servers turned off by a policy), the run uses the
+text protocol below instead, with a warning, and so do later runs in the process;
+`protocol="native"` fails instead. On Codex the model replies with JSON actions as text: one at a
+time, or several independent ones (reading three files) as a JSON array, which saves turns.
+`protocol="text"` uses that way on any backend, for example with a server behind `OPENAI_BASE_URL`
+that has no function calling. (Durable runs on Claude Code use it too.)
 The `jev` backend only answers typed questions and cannot run agents, even for a task returning
 `bool` or `Literal[...]`. An agent run using it raises `ThuncError` before creating any run files
 or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
@@ -272,25 +325,29 @@ or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
   | `write:docs/**`, `write` | create and edit matching files (all files with no path); also lets it read them |
   | `read:src/**` | read only these; any `read:` rule replaces the read-everything default |
   | `run:pytest`, `run:git log`, `run` | run commands that start with these words (`run:git log` allows `git log --oneline`, not `git push`); `run` alone allows any |
+  | `shell` | run any command line in a shell (`sh -c`, or `cmd /c` on Windows), so pipes, `&&`, `cd` and redirects work; off by default, and it can't be combined with `!run:` rules |
   | `!read:.env*`, `!write:...`, `!run:git push`, `!memory` | deny; a deny always wins, and `!read` also stops writing |
 
   `*` stays within one folder, `**` crosses folders, and paths are relative to `workdir`. The agent
   is told its permissions, and an action they don't allow is refused with the reason, after which
   the run carries on. Bad rules fail when the agent is declared.
-- **Tools:** `list`, `read` and `search`; `write` (create a file, or replace one) and `edit`
-  (replace text that appears exactly once) when a write rule allows it; `run` when a run rule
-  allows it; and `remember`. Every path
-  must stay inside `workdir`: `..`, absolute paths and symlinks that point outside are refused, and
-  the rules are checked on where a link really leads. Files the agent may not read are left out of
-  `list` and `search`.
+- **Tools:** `list`, `read` and `search` (a regular expression, optionally limited with a `glob`
+  such as `*.py`); `write` (create a file, or replace one) and `edit` (replace text that appears
+  exactly once) when a write rule allows it; `run` when a run or shell rule allows it; and
+  `remember`. Every path must stay inside `workdir`: `..`, absolute paths and symlinks that point
+  outside are refused, and the rules are checked on where a link really leads. Files the agent may
+  not read are left out of `list` and `search`, and so is what git ignores, in a git repository
+  (build output, caches, vendored code); a folder named explicitly is still listed and searched.
 - **No blind overwrites.** A file is only replaced or edited after the agent read it in the same
   run, and only if it hasn't changed on disk since. There is no undo, so run agents that write in a
   git repository with a clean tree, and review their changes with `git diff`.
-- **Commands** run in `workdir` without a shell, so `&&`, pipes, redirects and `$VARIABLES` don't
-  work (the agent is told). They get a minimal environment: `PATH`, `HOME`, the locale and
-  temp-folder variables, and whatever you pass in `env=`, so your API keys don't reach them. Each
-  has a time limit (`command_timeout=120` seconds) that also stops the processes it started, and
-  the agent sees the exit code and the output, its end kept when it's long.
+- **Commands** run in `workdir`, or in a folder inside it given as `cwd`. Without the `shell`
+  permission there's no shell, so `&&`, pipes, `cd`, redirects and `$VARIABLES` don't work (the
+  agent is told). They get a minimal environment: `PATH`, `HOME`, the locale and temp-folder
+  variables, and whatever you pass in `env=`, so your API keys don't reach them. Each has a time
+  limit (`command_timeout=120` seconds) that also stops the processes it started, and the agent
+  sees the exit code and the output: the start and the end when it's long, since the first error is
+  often at the start and the summary at the end.
 - **A permitted command can do anything its program can.** `run:pytest` runs the project's code,
   which can read or change any file your user account can, whatever the read and write rules say.
   Permissions limit which tools the model uses; they aren't a sandbox. For untrusted input, run the
@@ -341,24 +398,29 @@ or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
 
 - **Failures are loud.** A run that hits `max_steps`, never gives a valid value, or loses its
   backend raises `thunc.AgentError` (a `ThuncError`), whose `.run` is the record up to that point.
-  With tracing on, each run is also one line with every model reply.
+  A step that fails for a reason asking again may fix (a timeout, a lost connection, a rate limit,
+  a server error, a CLI call that ended in an error) is retried twice, after 2 and 4 seconds, and
+  each retry is in the run's record. A text-protocol step on Claude Code or Codex may take 120
+  seconds before it's retried. With tracing on, each run is also one line with every model reply.
 
 **How the prompt was tested.** `python -m live_tests.eval_prompts --backend anthropic` runs three
 small tasks (fix a bug, review a diff, answer a question about a repo) with three versions of the
-system prompt: bare (no working method), the default, and the task's preset. Five runs of each on
-4 October 2026:
+system prompt: bare (no working method), the default, and the task's preset. Five runs of each, on
+the Claude API on 4 October 2026 and on Claude Code on 5 October 2026:
 
-| | Claude API (Opus 5.5, native calls) | Claude Code (text protocol) |
+| | Claude API (Opus 5.5, native calls) | Claude Code (Sonnet 5.5, native calls) |
 |---|---|---|
 | Passed | 45/45: every task, every version | 45/45 |
-| Steps (bare / default / preset) | fix 4.0 / 4.0 / 4.0, review 2.0 / 2.4 / 2.8, analysis 3.0 / 3.0 / 3.0 | fix 5.2 / 6.0 / 6.0, review 2.2 / 2.0 / 3.8, analysis 4.2 / 3.8 / 4.2 |
+| Steps (bare / default / preset) | fix 4.0 / 4.0 / 4.0, review 2.0 / 2.4 / 2.8, analysis 3.0 / 3.0 / 3.0 | fix 4.0 / 4.0 / 4.0, review 2.0 / 2.0 / 2.0, analysis 3.0 / 2.8 / 2.6 |
 | Cost | $0.76 for all 45 runs (cache reads were 257,553 of 312,294 input tokens) | |
 
 Every version passed every time, so these tasks are too easy to tell the versions apart: the result
-says the prompt does no harm, not that it helps. The one difference is that the review preset reads
-more of the code before answering. Each review flagged the renamed function as a minor issue
-(outside code importing the old name breaks), never as blocking. Harder tasks are needed to measure
-more.
+says the prompt does no harm, not that it helps. On the API, the review preset read more of the code
+before answering, and each review flagged the renamed function as a minor issue (outside code
+importing the old name breaks), never as blocking. On Claude Code, only the review preset flagged
+it (2 of 5 runs, as minor). On the text protocol these tasks took more steps (fix 5.2 / 6.0 / 6.0
+on Claude Code before native calls). For harder tasks that do tell harnesses apart, see the tool-use
+benchmark in `live_tests/bench_tooluse.py` and its report.
 
 ## Durable agents with Temporal
 
@@ -428,15 +490,17 @@ thunc/
   permissions.py the agent's permission rules
   runs.py        thunc.Run and AgentError: what a run did
   native.py      how a run talks to its backend: native tool calls or the text protocol
+  claude_code.py native tool calls on Claude Code, through an MCP server (mcp_relay.py)
   store.py       the agent's folder: memory, settings, run records, the lock
   prompts.py     the agent's system prompt
-  __main__.py    the thunc command: thunc cache list / clear
+  __main__.py    the thunc command: thunc run [--profile], thunc cache list / clear
+  profiling.py   thunc run --profile: timing records and the report
   core.py        thunc.call, thunc.map, tracing
   cache.py       the answer cache: saving, listing, clearing
   schema.py      return types: describe, parse, validate
   config.py      settings and backend selection
   backends.py    anthropic, openai, claude-code, codex, jev
-  errors.py      ThuncError
+  errors.py      ThuncError, and TransientError for failures worth asking again
 tests/           offline: a fake backend, never a real model
 live_tests/      against a real model: hello, a yes/no decision, labels and ratings, messy text to a dict
 examples/
@@ -452,12 +516,14 @@ examples/
 ## Development
 
 ```bash
-python3 -m venv .venv && .venv/bin/pip install -e ".[anthropic,openai,dev]"
+python3 -m venv .venv && .venv/bin/pip install -e ".[anthropic,openai,temporal-test,dev]"
 .venv/bin/pytest                    # offline tests (these run in CI)
+THUNC_TEMPORAL_TESTS=1 .venv/bin/pytest -c pytest-temporal.ini tests/temporal   # a real local Temporal service; no model calls
 .venv/bin/pytest live_tests         # real model calls through your Claude Code login; costs quota
 THUNC_BACKEND=anthropic .venv/bin/pytest live_tests   # the same, through the Claude API (needs ANTHROPIC_API_KEY)
 THUNC_BACKEND=openai .venv/bin/pytest live_tests      # the same, through the OpenAI API (needs OPENAI_API_KEY)
-.venv/bin/ruff check . && .venv/bin/mypy --strict thunc
+.venv/bin/ruff check . && .venv/bin/ruff format --check .
+.venv/bin/mypy --strict thunc && .venv/bin/mypy --strict --platform win32 thunc
 ```
 
 ## License