Skip to content
Python

Bound tool results, steer edits, keep compacted turns readable (OPE-186)

Devika Verma65ba394393af
diff --git a/coworker/agent.py b/coworker/agent.py
index 29fde87a..7e904188 100644
--- a/coworker/agent.py
+++ b/coworker/agent.py
@@ -188,6 +188,14 @@ def _skill_dirs(workspace: Optional[Path]) -> list[Path]:
return dirs
+def _is_within(path: Path, root: Path) -> bool:
+ try:
+ Path(path).resolve().relative_to(Path(root).resolve())
+ return True
+ except (ValueError, OSError):
+ return False
+
+
def build_engine(
*,
agent: Agent,
@@ -199,6 +207,11 @@ def build_engine(
allowed_commands: Optional[list[str]] = None,
max_iterations: Optional[int] = None,
model_settings: Optional[dict[str, Any]] = None,
+ # OPE-186: explicit tool-result byte cap (None = config, then the 10,000 default;
+ # 0 = off) and where bounded results' full text is spilled (None = the session's
+ # scratch root if there is one, else a per-process temp directory).
+ tool_result_max_bytes: Optional[int] = None,
+ tool_result_spill_dir: Optional[str | Path] = None,
memory_store: Optional[MemoryStore] = None,
# Twentieth pass: the project key memory loads/saves under. Defaults to the
# workspace path; the manager passes the resolved key (binding > git > path)
@@ -262,6 +275,30 @@ def build_engine(
else:
root_list = []
+ # OPE-186: bounded tool results keep their full text in a spill file the model can
+ # read, and the compaction transcript is written there too. Prefer the session's
+ # scratch root (already one of the agent's folders). Otherwise the folder joins the
+ # session's directories read-only, BEFORE the tools are built, so read_file can open
+ # it (2026-09-14: the first trial spilled under the run's log folder and read_file
+ # answered "path escapes the session's directories"). The workspace itself is never
+ # written to, so a repository or task tree stays clean.
+ if tool_result_spill_dir is not None:
+ spill_dir: Optional[Path] = Path(tool_result_spill_dir).expanduser().resolve()
+ else:
+ scratch = next((r.path for r in root_list if r.label == "scratch"), None)
+ if scratch is not None:
+ spill_dir = Path(scratch) / "tool-output"
+ else:
+ import os
+ import tempfile
+
+ spill_dir = (
+ Path(tempfile.gettempdir()) / "openworker" / f"tool-output-{os.getpid()}"
+ ).resolve()
+ # Registered, not created: the folder appears on disk only when something is spilled.
+ if root_list and not any(_is_within(spill_dir, r.path) for r in root_list):
+ root_list.append(RootDir(path=spill_dir, writable=False, label="tool-output"))
+
workspace_trusted = bool(ws and WorkspaceTrustStore().is_trusted(ws))
config = load_config(ws, workspace_trusted=workspace_trusted)
# OPE-177: the configured per-reply output ceiling rides `model_settings`, which
@@ -534,6 +571,12 @@ def build_engine(
)
return "\n\n".join(parts)
+ cap = (
+ tool_result_max_bytes
+ if tool_result_max_bytes is not None
+ else config.tool_result_max_bytes
+ )
+
engine = TurnEngine(
provider=provider,
registry=registry,
@@ -541,6 +584,8 @@ def build_engine(
model=model,
instructions=instructions,
approver=approver,
+ tool_result_max_bytes=cap,
+ tool_result_spill_dir=spill_dir,
# Stop kills the in-flight foreground shell command, not just the loop.
interrupt_hooks=[executor.interrupt_now] if executor is not None else None,
max_iterations=(
@@ -557,6 +602,11 @@ def build_engine(
team_approver=team_approver,
items_approver=items_approver,
)
+ # OPE-186 change 3: a configured compaction cap makes the summariser fire earlier
+ # than the built-in 250,000-token cap. The window still comes from the model matrix.
+ if config.compaction_cap_tokens:
+ _cap_tokens = int(config.compaction_cap_tokens)
+ engine.compaction_settings = lambda: {"cap_tokens": _cap_tokens}
engine.executor = executor # type: ignore[attr-defined]
engine.todo = todo # type: ignore[attr-defined]
engine.agent_name = agent.name # type: ignore[attr-defined]
diff --git a/coworker/agents/cowork.py b/coworker/agents/cowork.py
index d72ddc6f..2669390e 100644
--- a/coworker/agents/cowork.py
+++ b/coworker/agents/cowork.py
@@ -25,7 +25,10 @@ COWORK_INSTRUCTIONS = (
"no todo list means the user sees nothing happening. Keep exactly one item in_progress and "
"update statuses as you finish each step. NEVER inline a multi-line script in a shell "
"command (no heredocs): write it to a file with write_file, then run that file — the "
- "script stays reviewable and the approval prompt stays short. Be outcome-oriented — "
+ "script stays reviewable and the approval prompt stays short. To change an existing "
+ "file, read it and edit it in place with replace_in_file or apply_patch rather than "
+ "rewriting the whole file; reserve write_file for new files or full rewrites. "
+ "Be outcome-oriented — "
"clarify the goal, do the "
"work in small reversible steps, and finish with the actual artifact plus a short summary "
"of what you produced and where. When your deliverable is a file, end the reply with a "
diff --git a/coworker/catalog.py b/coworker/catalog.py
index cdf4fae3..c910f37b 100644
--- a/coworker/catalog.py
+++ b/coworker/catalog.py
@@ -51,6 +51,51 @@ class Capability:
# -- capability builders --------------------------------------------------------
# These reproduce, exactly, what the Code and Cowork agent factories assembled by hand.
+# OPE-186 change 2: aisuite's file tools describe themselves in one generic line each
+# ("Write a UTF-8 text file under the configured root."), so nothing tells the model when
+# to rewrite a file and when to edit it. In one long multi-task session Kimi K3 chose
+# write_file 1,812 times against 609 targeted edits, and every whole-file body it wrote
+# rode along in the conversation on every later turn. Building the guidance into the
+# tool description is the usual remedy; these descriptions do that.
+EDIT_TOOL_GUIDANCE: dict[str, str] = {
+ "write_file": (
+ "Create a NEW file, or replace an existing file's ENTIRE content when most of it "
+ "changes. For a small or medium change to an existing file do not rewrite it: read "
+ "it, then use replace_in_file (exact text swap) or apply_patch (multi-line edit). "
+ "The whole `content` you pass stays in the conversation on every later turn, so "
+ "whole-file rewrites of large files are expensive."
+ ),
+ "replace_in_file": (
+ "Edit an existing file in place: replace `old` (an exact, unique text fragment, "
+ "whitespace included) with `new`. Prefer this over write_file for changing part of "
+ "a file; read the file first so `old` matches exactly. Set expected_replacements "
+ "when the fragment appears more than once."
+ ),
+ "apply_patch": (
+ "Apply a Codex-style patch (*** Begin Patch / *** Update File: path / @@ hunks of "
+ "' ' context, '-' removed and '+' added lines / *** End Patch) for targeted "
+ "multi-line edits to one or more existing files, or to add or delete files. Prefer "
+ "this over write_file for edits that touch several places."
+ ),
+ "apply_unified_diff": (
+ "Apply a standard unified diff (the format of `diff -u` or `git diff`) to existing "
+ "files. Use it when you already have the change as a diff."
+ ),
+}
+
+
+def _describe_edit_tools(tools: list) -> list:
+ """Give the file tools descriptions that say WHEN to use each (the registry builds the
+ schema the model sees from the docstring)."""
+ for t in tools:
+ text = EDIT_TOOL_GUIDANCE.get(getattr(t, "__name__", ""))
+ if text:
+ try:
+ t.__doc__ = text
+ except (AttributeError, TypeError):
+ pass
+ return tools
+
def _code_files(context: AgentContext) -> list:
"""Repo-oriented files: line-numbered/windowed `read_file`. Our `grep` and windowed
@@ -63,11 +108,13 @@ def _code_files(context: AgentContext) -> list:
file_kwargs = (
{"roots": context.roots} if context.roots else {"root": ws, "allow_write": True}
)
- files = [
- t
- for t in ai.toolkits.files(**file_kwargs)
- if getattr(t, "__name__", "") not in replaced
- ]
+ files = _describe_edit_tools(
+ [
+ t
+ for t in ai.toolkits.files(**file_kwargs)
+ if getattr(t, "__name__", "") not in replaced
+ ]
+ )
return [*files, *file_tools(ws, roots=context.roots)]
@@ -82,11 +129,13 @@ def _files(context: AgentContext) -> list:
{"roots": context.roots} if context.roots else {"root": ws, "allow_write": True}
)
replaced = {"search_files", "read_file", "read_file_lines"}
- files = [
- t
- for t in ai.toolkits.files(**file_kwargs)
- if getattr(t, "__name__", "") not in replaced
- ]
+ files = _describe_edit_tools(
+ [
+ t
+ for t in ai.toolkits.files(**file_kwargs)
+ if getattr(t, "__name__", "") not in replaced
+ ]
+ )
return [*files, *file_tools(ws, roots=context.roots)]
diff --git a/coworker/compaction.py b/coworker/compaction.py
index 678682a5..1958dc7c 100644
--- a/coworker/compaction.py
+++ b/coworker/compaction.py
@@ -98,6 +98,10 @@ class CompactionState:
created_at: float = 0.0
model_used: str = ""
trimmed: bool = False # True when this state came from the no-summary trim fallback
+ # OPE-186 change 3: where the verbatim transcript of the compacted turns was written
+ # (empty when the engine had nowhere to write it). Named in the compacted block so the
+ # model can read back anything the summary dropped.
+ transcript_path: str = ""
def as_dict(self) -> dict[str, Any]:
return {
@@ -109,6 +113,7 @@ class CompactionState:
"created_at": self.created_at,
"model_used": self.model_used,
"trimmed": self.trimmed,
+ "transcript_path": self.transcript_path,
}
@classmethod
@@ -124,6 +129,7 @@ class CompactionState:
created_at=float(raw.get("created_at", 0.0)),
model_used=str(raw.get("model_used", "")),
trimmed=bool(raw.get("trimmed", False)),
+ transcript_path=str(raw.get("transcript_path", "") or ""),
)
@@ -517,10 +523,54 @@ def compacted_block(state: CompactionState) -> str:
"their intent is covered by the summary above)"
]
parts += [f"- {u}" for u in state.user_messages]
+ if state.transcript_path:
+ parts += [
+ "",
+ "The verbatim transcript of the compacted turns (every message, tool call and "
+ f"tool result, without your private reasoning) is saved at {state.transcript_path}. "
+ "If a detail you need is missing from the summary, read that file (read_file, "
+ "or run_shell with grep / sed -n) instead of guessing.",
+ ]
parts += ["", CONTINUATION_CONTRACT, "</compacted-history>"]
return "\n".join(parts)
+def render_transcript(messages: list[dict[str, Any]], upto: int) -> str:
+ """The canonical messages before index `upto`, rendered as readable Markdown for the
+ transcript file: role, the assistant's visible text and tool calls (name + arguments),
+ every tool result in full, notices. Private reasoning sidecars are left out: they are
+ the model's own thinking, not session facts, and they are the bulkiest part."""
+ lines = [
+ "# Compacted transcript",
+ "",
+ f"Messages 0 to {max(0, upto - 1)} of this session, verbatim, written when they were "
+ "summarised into the compacted history block.",
+ "",
+ ]
+ for i, m in enumerate(messages[:upto]):
+ role = str(m.get("role") or "")
+ if role == "system":
+ continue
+ if role == "notice":
+ lines += [f"## [{i}] notice: {m.get('kind', '')}", "", str(m.get("content") or ""), ""]
+ continue
+ lines.append(f"## [{i}] {role}")
+ content = m.get("content")
+ if isinstance(content, str) and content:
+ lines += ["", content]
+ elif content:
+ lines += ["", json.dumps(content, default=str, ensure_ascii=False)]
+ for tc in m.get("tool_calls") or []:
+ fn = tc.get("function") if isinstance(tc, dict) else None
+ name = (fn or {}).get("name") if fn else (tc.get("name") if isinstance(tc, dict) else "")
+ args = (fn or {}).get("arguments") if fn else (tc.get("arguments") if isinstance(tc, dict) else "")
+ if not isinstance(args, str):
+ args = json.dumps(args, default=str, ensure_ascii=False)
+ lines += ["", f"tool call: {name}", "```", str(args), "```"]
+ lines.append("")
+ return "\n".join(lines)
+
+
def apply_to_outbound(
messages: list[dict[str, Any]], state: Optional[CompactionState]
) -> list[dict[str, Any]]:
diff --git a/coworker/config.py b/coworker/config.py
index f98f2c76..262ad159 100644
--- a/coworker/config.py
+++ b/coworker/config.py
@@ -51,6 +51,16 @@ class Config:
# session — changing it mid-conversation restarts the prompt cache. Environment
# override: COWORKER_REASONING_EFFORT.
reasoning_effort: Optional[str] = None
+ # OPE-186: bound every tool result before it enters the conversation. A result whose
+ # serialised form exceeds this many bytes is stored as head + marker + tail, with the
+ # full text in a spill file the model can read. Unset = 10,000;
+ # 0 = off. Environment override: COWORKER_TOOL_RESULT_MAX_BYTES.
+ tool_result_max_bytes: Optional[int] = None
+ # OPE-186 change 3: cap on the auto-compaction trigger, in tokens. The engine compacts
+ # at min(80% of the model's window, this cap); the built-in cap is 250,000, which on a
+ # 1M-window model fired once in 445 long sessions. Lower it (e.g. 60000) to
+ # summarise long sessions earlier. Environment override: COWORKER_COMPACTION_CAP_TOKENS.
+ compaction_cap_tokens: Optional[int] = None
allowed_commands: list[str] = field(
default_factory=lambda: list(DEFAULT_ALLOWED_COMMANDS)
)
@@ -100,6 +110,8 @@ _FIELDS = {
"max_iterations",
"max_output_tokens",
"reasoning_effort",
+ "tool_result_max_bytes",
+ "compaction_cap_tokens",
"allowed_commands",
"auto_allow",
"allowed_domains",
@@ -152,6 +164,19 @@ def workspace_allowed_commands(workspace: str | Path) -> list[str]:
MAX_OUTPUT_TOKENS_ENV = "COWORKER_MAX_OUTPUT_TOKENS"
REASONING_EFFORT_ENV = "COWORKER_REASONING_EFFORT"
+TOOL_RESULT_MAX_BYTES_ENV = "COWORKER_TOOL_RESULT_MAX_BYTES"
+COMPACTION_CAP_TOKENS_ENV = "COWORKER_COMPACTION_CAP_TOKENS"
+
+
+def _nonnegative_int(value: Any, source: str) -> Optional[int]:
+ """`tool_result_max_bytes`: an integer >= 0 (0 turns bounding off); bools rejected."""
+ if value is None:
+ return None
+ if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+ raise ValueError(
+ f"tool_result_max_bytes must be an integer >= 0, got {value!r} ({source})"
+ )
+ return value
def _effort_level(value: Any, source: str) -> Optional[str]:
@@ -217,4 +242,31 @@ def load_config(
raw_effort = os.environ.get(REASONING_EFFORT_ENV)
if raw_effort is not None and raw_effort.strip():
cfg.reasoning_effort = _effort_level(raw_effort, REASONING_EFFORT_ENV)
+ cfg.tool_result_max_bytes = _nonnegative_int(cfg.tool_result_max_bytes, "config.toml")
+ raw_cap = (os.environ.get(TOOL_RESULT_MAX_BYTES_ENV) or "").strip()
+ if raw_cap:
+ try:
+ parsed_cap: Any = int(raw_cap)
+ except ValueError:
+ parsed_cap = raw_cap
+ cfg.tool_result_max_bytes = _nonnegative_int(parsed_cap, TOOL_RESULT_MAX_BYTES_ENV)
+ if cfg.compaction_cap_tokens is not None and (
+ isinstance(cfg.compaction_cap_tokens, bool)
+ or not isinstance(cfg.compaction_cap_tokens, int)
+ or cfg.compaction_cap_tokens <= 0
+ ):
+ raise ValueError(
+ f"compaction_cap_tokens must be a positive integer, got {cfg.compaction_cap_tokens!r} (config.toml)"
+ )
+ raw_comp = (os.environ.get(COMPACTION_CAP_TOKENS_ENV) or "").strip()
+ if raw_comp:
+ try:
+ parsed_comp = int(raw_comp)
+ except ValueError:
+ parsed_comp = 0
+ if parsed_comp <= 0:
+ raise ValueError(
+ f"compaction_cap_tokens must be a positive integer, got {raw_comp!r} ({COMPACTION_CAP_TOKENS_ENV})"
+ )
+ cfg.compaction_cap_tokens = parsed_comp
return cfg
diff --git a/coworker/engine.py b/coworker/engine.py
index 47492d12..f282c1b2 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -19,12 +19,14 @@ import json
import time
from dataclasses import dataclass, replace
from enum import Enum
+from pathlib import Path
from typing import Any, AsyncIterator, Awaitable, Callable, Optional
from . import compaction as _compaction
from . import provenance
from . import session_facts
from . import toolchain as _toolchain
+from . import toolresult
from .events import Event, EventType
# §8.4 retry guard: the reviewer pauses for the rest of the turn after this many denials
@@ -143,6 +145,11 @@ class TurnEngine:
# Called (thread-safe, best-effort) when the user stops the turn — e.g. the
# executor's kill for a running shell command.
interrupt_hooks: Optional[list[Callable[[], None]]] = None,
+ # OPE-186 change 1: bound every tool result before it enters the conversation
+ # (head + marker + tail; full text in a spill file). None = the module default
+ # (10,000 bytes), 0 = off. See coworker/toolresult.py.
+ tool_result_max_bytes: Optional[int] = None,
+ tool_result_spill_dir: Optional[Path] = None,
) -> None:
self.provider = provider
self.registry = registry
@@ -251,6 +258,14 @@ class TurnEngine:
# the card and in the reviewer's request. Runtime-only, like `_ask_replies`: a
# restart costs context (more cards), never correctness.
self._agent_files = provenance.SessionFiles(permissions.workspace_root)
+ self._tool_result_max_bytes = (
+ toolresult.DEFAULT_TOOL_RESULT_MAX_BYTES
+ if tool_result_max_bytes is None
+ else int(tool_result_max_bytes)
+ )
+ self._tool_result_spill_dir = (
+ Path(tool_result_spill_dir) if tool_result_spill_dir is not None else None
+ )
# Completed tool calls so far, so a fact can say how many steps back the write was.
self._step = 0
self._last_context_tokens: Optional[int] = None
@@ -817,6 +832,25 @@ class TurnEngine:
except Exception:
continue
if state is not None:
+ # OPE-186 change 3: keep the compacted turns readable. The verbatim transcript
+ # up to the boundary goes to a file next to the spilled tool results, and the
+ # compacted block tells the model where it is, so a detail the summary dropped
+ # costs one read instead of being lost.
+ if self._tool_result_spill_dir is not None:
+ try:
+ self._tool_result_spill_dir.mkdir(parents=True, exist_ok=True)
+ path = (
+ self._tool_result_spill_dir
+ / f"compacted-transcript-upto-{state.boundary_index:04d}.md"
+ )
+ path.write_text(
+ _compaction.render_transcript(self.messages, state.boundary_index),
+ encoding="utf-8",
+ errors="replace",
+ )
+ state.transcript_path = str(path)
+ except OSError:
+ pass
self.compaction_state = state
self._last_context_tokens = None # stale once the outbound view shrank
return "Context compacted — earlier turns were summarized"
@@ -1604,6 +1638,15 @@ class TurnEngine:
**({"approval_note": origin["note"]} if origin.get("note") else {}),
**({"approval_grant": origin["grant"]} if origin.get("grant") else {}),
}
+ # OPE-186 change 1: what the model sees (and re-reads on every later turn) is
+ # bounded here, once, for every tool. Provenance above recorded the full result.
+ result = toolresult.bound_tool_result(
+ result,
+ max_bytes=self._tool_result_max_bytes,
+ spill_dir=self._tool_result_spill_dir,
+ step=self._step,
+ tool_name=tool_call.name,
+ )
message = _tool_result_message(tool_call, result)
if display:
message["_display"] = display
diff --git a/coworker/toolresult.py b/coworker/toolresult.py
new file mode 100644
index 00000000..69b06e8d
--- /dev/null
+++ b/coworker/toolresult.py
@@ -0,0 +1,120 @@
+"""Bound every tool result before it enters the conversation (OPE-186, change 1).
+
+A tool result is re-sent to the model on every later turn, so one oversized result taxes
+the whole rest of the session. The shell tool used to keep the LAST 20,000 characters of
+its output and drop the beginning; every other tool was unbounded (a `read_file` of a
+486,000-character file was seen in one long session).
+
+Rule, applied in one place for all tools (`TurnEngine._record_result`): if the result, as
+it would be serialised into the tool message, exceeds `max_bytes`, the full text is written
+to a spill file and the oversized field is replaced by its head, a marker naming the file
+and the omitted byte count, and its tail. Head-plus-tail at 10,000 bytes is a common shape;
+another is to keep the full output on disk and hand the model only the path.
+Head AND tail because a build log needs both its first error and its final verdict.
+
+The marker carries no timestamp, so a bounded result is byte-identical on every later
+request and never disturbs the provider's prompt cache. Structured results stay valid
+JSON: only the largest string field(s) are bounded, everything else is untouched.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+DEFAULT_TOOL_RESULT_MAX_BYTES = 10_000
+# Bytes set aside for the marker line and JSON escaping when sizing head + tail.
+_MARKER_RESERVE = 400
+# Never shrink a field below this many bytes of head + tail, whatever the budget says.
+_MIN_KEEP = 1_000
+_SAFE_NAME = re.compile(r"[^A-Za-z0-9_.-]+")
+
+
+def serialize_result(result: Any) -> str:
+ """Exactly what `_tool_result_message` puts in the message content."""
+ return result if isinstance(result, str) else json.dumps(result, default=str)
+
+
+def _nbytes(text: str) -> int:
+ return len(text.encode("utf-8"))
+
+
+def head_tail(text: str, keep_bytes: int, *, spill_path: Optional[Path], total_bytes: int) -> str:
+ """First half of `keep_bytes`, a marker, last half. Cuts are byte-based and decoded
+ with errors ignored so a multi-byte character split at the boundary is dropped, never
+ corrupted."""
+ keep = max(int(keep_bytes), _MIN_KEEP)
+ raw = text.encode("utf-8")
+ half = keep // 2
+ head = raw[:half].decode("utf-8", errors="ignore")
+ tail = raw[-half:].decode("utf-8", errors="ignore") if half else ""
+ omitted = max(0, len(raw) - _nbytes(head) - _nbytes(tail))
+ where = (
+ f"full text saved to {spill_path} (read it with read_file, or "
+ f"run_shell: sed -n '1,200p' \"{spill_path}\")"
+ if spill_path is not None
+ else "full text not saved"
+ )
+ marker = f"\n[... {omitted} bytes omitted here; this result was {total_bytes} bytes; {where} ...]\n"
+ return head + marker + tail
+
+
+def bound_tool_result(
+ result: Any,
+ *,
+ max_bytes: Optional[int],
+ spill_dir: Optional[Path],
+ step: int,
+ tool_name: str,
+) -> Any:
+ """Return `result` unchanged when it fits, else a bounded copy. `max_bytes` None or
+ <= 0 disables bounding. Spill files are written only when `spill_dir` is given."""
+ if not max_bytes or max_bytes <= 0:
+ return result
+ text = serialize_result(result)
+ if _nbytes(text) <= max_bytes:
+ return result
+
+ safe_tool = _SAFE_NAME.sub("_", tool_name or "tool")[:40] or "tool"
+
+ def spill(name: str, payload: str) -> Optional[Path]:
+ if spill_dir is None:
+ return None
+ try:
+ spill_dir.mkdir(parents=True, exist_ok=True)
+ path = spill_dir / name
+ path.write_text(payload, encoding="utf-8", errors="replace")
+ return path
+ except OSError:
+ return None
+
+ if isinstance(result, dict):
+ out: dict[str, Any] = dict(result)
+ # Bound the largest string field, re-measure, repeat for the next largest if the
+ # whole message is still over budget (a result can carry two big fields).
+ for _ in range(4):
+ key = max(
+ (k for k, v in out.items() if isinstance(v, str)),
+ key=lambda k: _nbytes(out[k]),
+ default=None,
+ )
+ if key is None or _nbytes(out[key]) < _MIN_KEEP:
+ break
+ others = _nbytes(serialize_result({k: v for k, v in out.items() if k != key}))
+ budget = max_bytes - others - _MARKER_RESERVE
+ original = out[key]
+ path = spill(f"{step:04d}-{safe_tool}-{_SAFE_NAME.sub('_', key)[:30]}.txt", original)
+ bounded = head_tail(original, budget, spill_path=path, total_bytes=_nbytes(original))
+ # JSON escaping (newlines, quotes) grows the serialised size; tighten once.
+ over = _nbytes(serialize_result({**out, key: bounded})) - max_bytes
+ if over > 0:
+ bounded = head_tail(original, budget - over, spill_path=path, total_bytes=_nbytes(original))
+ out[key] = bounded
+ if _nbytes(serialize_result(out)) <= max_bytes:
+ break
+ return out
+
+ path = spill(f"{step:04d}-{safe_tool}.txt", text)
+ return head_tail(text, max_bytes - _MARKER_RESERVE, spill_path=path, total_bytes=_nbytes(text))
diff --git a/coworker/tools/shell.py b/coworker/tools/shell.py
index 0404511d..0f1554f7 100644
--- a/coworker/tools/shell.py
+++ b/coworker/tools/shell.py
@@ -142,7 +142,11 @@ class LocalExecutor(Executor):
env: Optional[dict[str, str]] = None,
shell_path: Optional[str] = None,
default_timeout: float = _DEFAULT_TIMEOUT,
- max_output_chars: int = 20_000,
+ # Memory safety net only (OPE-186): what the MODEL sees is bounded by the engine's
+ # tool-result cap (head + marker + tail, full text in a spill file), which needs
+ # the whole output to spill. This tail-keep cap now only stops a runaway command
+ # from filling memory; it used to be 20,000 and silently dropped the beginning.
+ max_output_chars: int = 2_000_000,
) -> None:
self.cwd = str(Path(cwd).expanduser().resolve())
self.default_timeout = default_timeout
diff --git a/tests/test_compaction_transcript.py b/tests/test_compaction_transcript.py
new file mode 100644
index 00000000..89ac3e32
--- /dev/null
+++ b/tests/test_compaction_transcript.py
@@ -0,0 +1,127 @@
+"""OPE-186 change 3: the summariser can fire earlier (configurable cap), and the compacted
+turns stay readable: the verbatim transcript is written to a file the model is told about
+in the compacted block. Scripted provider, tiny forced window, no network."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from coworker import compaction as C
+from coworker.config import COMPACTION_CAP_TOKENS_ENV, load_config
+from coworker.engine import TurnEngine
+from coworker.events import EventType
+from coworker.permissions import PermissionEngine
+from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient
+from coworker.tools import ToolRegistry
+
+SUMMARY = "## Primary request and intent\nkeep building the report"
+
+
+class CompactingProvider(ProviderClient):
+ def __init__(self, turns):
+ self._turns = list(turns)
+
+ def complete(self, *, model, messages, tools=None, **settings):
+ if messages and "compacting an AI coworker" in str(messages[0].get("content", "")):
+ return AssistantTurn(text=SUMMARY, finish_reason="stop")
+ return self._turns.pop(0)
+
+ def capabilities(self, model):
+ return ModelCapabilities()
+
+
+def _history(turns=8, bulk=1500):
+ msgs = [{"role": "system", "content": "be helpful"}]
+ for i in range(turns):
+ msgs.append({"role": "user", "content": f"request {i}", "ts": 1.0})
+ msgs.append(
+ {
+ "role": "assistant",
+ "content": f"answer {i} " + "x" * bulk,
+ "ts": 1.0,
+ "reasoning": "private thinking " + "r" * 200,
+ "tool_calls": [{"id": f"c{i}", "function": {"name": "run_shell", "arguments": '{"command": "ls -la"}'}}],
+ }
+ )
+ msgs.append({"role": "tool", "tool_call_id": f"c{i}", "content": f"listing {i}: file_{i}.txt", "ts": 1.0})
+ return msgs
+
+
+def _collect(engine):
+ async def go():
+ return [e async for e in engine.run("continue")]
+
+ return asyncio.run(go())
+
+
+def test_compaction_writes_transcript_and_tells_the_model(tmp_path):
+ spill = tmp_path / "spill"
+ engine = TurnEngine(
+ provider=CompactingProvider([AssistantTurn(text="done", finish_reason="stop")]),
+ registry=ToolRegistry(),
+ permissions=PermissionEngine(workspace_root=tmp_path),
+ model="gpt-5.5",
+ messages=_history(),
+ tool_result_spill_dir=spill,
+ )
+ engine.compaction_settings = lambda: {"cap_tokens": 400, "threshold_pct": 0.8, "context_window": 100_000}
+ events = _collect(engine)
+ assert any(e.type == EventType.COMPACTED for e in events)
+ state = engine.compaction_state
+ assert state is not None and state.transcript_path
+ files = list(spill.glob("compacted-transcript-upto-*.md"))
+ assert len(files) == 1 and str(files[0]) == state.transcript_path
+ text = files[0].read_text(encoding="utf-8")
+ # Verbatim content of the compacted turns: text, tool calls with arguments, results.
+ assert "request 0" in text and "answer 0" in text
+ assert "tool call: run_shell" in text and '"command": "ls -la"' in text
+ assert "listing 0: file_0.txt" in text
+ # Private reasoning is not written out.
+ assert "private thinking" not in text
+ # The compacted block the model receives names the file.
+ out = engine._outbound_messages()
+ assert state.transcript_path in out[1]["content"]
+ assert "read that file" in out[1]["content"]
+ # The record round-trips with the path.
+ assert C.CompactionState.from_dict(state.as_dict()).transcript_path == state.transcript_path
+
+
+def test_no_spill_dir_means_no_transcript_and_no_mention(tmp_path):
+ engine = TurnEngine(
+ provider=CompactingProvider([AssistantTurn(text="done", finish_reason="stop")]),
+ registry=ToolRegistry(),
+ permissions=PermissionEngine(workspace_root=tmp_path),
+ model="gpt-5.5",
+ messages=_history(),
+ )
+ engine.compaction_settings = lambda: {"cap_tokens": 400, "threshold_pct": 0.8, "context_window": 100_000}
+ _collect(engine)
+ state = engine.compaction_state
+ assert state is not None and state.transcript_path == ""
+ assert "saved at" not in engine._outbound_messages()[1]["content"]
+
+
+def test_compaction_cap_config_and_env(tmp_path, monkeypatch):
+ (tmp_path / ".coworker").mkdir()
+ (tmp_path / ".coworker" / "config.toml").write_text("compaction_cap_tokens = 60000\n", encoding="utf-8")
+ monkeypatch.delenv(COMPACTION_CAP_TOKENS_ENV, raising=False)
+ cfg = load_config(tmp_path, global_path=tmp_path / "no-global.toml")
+ assert cfg.compaction_cap_tokens == 60000 # a workspace config.toml may set it
+ monkeypatch.setenv(COMPACTION_CAP_TOKENS_ENV, "80000")
+ cfg = load_config(tmp_path, global_path=tmp_path / "no-global.toml")
+ assert cfg.compaction_cap_tokens == 80000
+ monkeypatch.setenv(COMPACTION_CAP_TOKENS_ENV, "0")
+ try:
+ load_config(tmp_path, global_path=tmp_path / "no-global.toml")
+ except ValueError as exc:
+ assert "compaction_cap_tokens" in str(exc)
+ else:
+ raise AssertionError("a zero cap must be rejected")
+
+
+def test_render_transcript_is_readable_and_skips_system():
+ text = C.render_transcript(_history(turns=2), upto=7)
+ assert text.startswith("# Compacted transcript")
+ assert "be helpful" not in text # system prompt is not part of the compacted span
+ assert "## [1] user" in text and "## [2] assistant" in text and "## [3] tool" in text
diff --git a/tests/test_edit_tool_guidance.py b/tests/test_edit_tool_guidance.py
new file mode 100644
index 00000000..ba7366a8
--- /dev/null
+++ b/tests/test_edit_tool_guidance.py
@@ -0,0 +1,42 @@
+"""OPE-186 change 2: the file tools tell the model WHEN to use each (rewrite vs edit in
+place), and the Cowork prompt says the same. The schema the model sees is built from the
+tool's docstring by the registry, so that is what is checked here."""
+
+from __future__ import annotations
+
+from coworker.agents import AgentContext
+from coworker.agents.cowork import COWORK_INSTRUCTIONS
+from coworker.catalog import EDIT_TOOL_GUIDANCE, expand
+from coworker.tools import ToolRegistry
+
+
+def _descriptions(capability: str, tmp_path) -> dict[str, str]:
+ context = AgentContext(workspace=str(tmp_path), executor=None, todo=None, roots=None)
+ registry = ToolRegistry()
+ registry.register_all(expand([capability], context))
+ return {
+ name: registry.get(name).schema["function"]["description"] # type: ignore[union-attr]
+ for name in registry.names()
+ }
+
+
+def test_files_capability_describes_when_to_rewrite_and_when_to_edit(tmp_path):
+ d = _descriptions("files", tmp_path)
+ assert "NEW file" in d["write_file"] and "replace_in_file" in d["write_file"]
+ assert "in place" in d["replace_in_file"] and "Prefer this over write_file" in d["replace_in_file"]
+ assert "*** Begin Patch" in d["apply_patch"]
+ assert "unified diff" in d["apply_unified_diff"]
+ # The generic aisuite one-liner is gone from every edit tool.
+ for name in EDIT_TOOL_GUIDANCE:
+ assert d[name] != "Write a UTF-8 text file under the configured root."
+
+
+def test_code_files_capability_gets_the_same_guidance(tmp_path):
+ d = _descriptions("code_files", tmp_path)
+ for name, text in EDIT_TOOL_GUIDANCE.items():
+ assert d[name] == text
+
+
+def test_cowork_prompt_steers_edits_to_in_place_tools():
+ assert "edit it in place with replace_in_file or apply_patch" in COWORK_INSTRUCTIONS
+ assert "reserve write_file for new files or full rewrites" in COWORK_INSTRUCTIONS
diff --git a/tests/test_tool_result_cap.py b/tests/test_tool_result_cap.py
new file mode 100644
index 00000000..aa93e9f7
--- /dev/null
+++ b/tests/test_tool_result_cap.py
@@ -0,0 +1,173 @@
+"""OPE-186 change 1: every tool result is bounded before it enters the conversation.
+
+Unit tests for `coworker.toolresult` and an engine round trip with a scripted provider
+(no network). The contract: a result that fits is untouched byte-for-byte; an oversized
+result keeps its head and tail, names a spill file holding the full text, stays valid
+JSON when it was a dict, and is deterministic (no timestamps) so later requests carry an
+identical prefix for the provider's prompt cache.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+
+import aisuite as ai
+
+from coworker import toolresult
+from coworker.engine import TurnEngine
+from coworker.events import EventType
+from coworker.permissions import PermissionEngine
+from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient, ToolCall
+from coworker.tools import ToolRegistry
+
+
+def _bounded(result, *, max_bytes=10_000, spill: Path | None, step=7, tool="run_shell"):
+ return toolresult.bound_tool_result(
+ result, max_bytes=max_bytes, spill_dir=spill, step=step, tool_name=tool
+ )
+
+
+def _size(x) -> int:
+ return len(toolresult.serialize_result(x).encode("utf-8"))
+
+
+def test_small_result_is_returned_unchanged(tmp_path):
+ result = {"command": "ls", "exit_code": 0, "output": "a\nb\n", "truncated": False}
+ out = _bounded(result, spill=tmp_path)
+ assert out is result # same object, not a copy
+ assert not list(tmp_path.iterdir()) # nothing spilled
+
+
+def test_large_shell_output_keeps_head_and_tail_and_spills_full_text(tmp_path):
+ lines = "\n".join(f"line{i:05d}" for i in range(4000)) # ~44 KB
+ result = {"command": "make", "cwd": "/app", "exit_code": 1, "output": lines, "truncated": False}
+ out = _bounded(result, spill=tmp_path)
+ assert out is not result and out["exit_code"] == 1 and out["command"] == "make"
+ assert _size(out) <= 10_000
+ assert out["output"].startswith("line00000") # the head survives
+ assert out["output"].rstrip().endswith("line03999") # and the tail
+ assert "bytes omitted here" in out["output"] and "run_shell: sed -n" in out["output"]
+ spilled = list(tmp_path.iterdir())
+ assert len(spilled) == 1 and spilled[0].name == "0007-run_shell-output.txt"
+ assert spilled[0].read_text(encoding="utf-8") == lines # complete, untouched
+ assert str(spilled[0]) in out["output"] # the marker names the file
+ # Still a well-formed message: the model gets JSON it can parse.
+ json.loads(toolresult.serialize_result(out))
+
+
+def test_read_file_content_is_bounded_the_same_way(tmp_path):
+ content = "\n".join(f"{i:>6}\t{'x' * 80}" for i in range(3000))
+ result = {"path": "big.py", "start_line": 1, "end_line": 3000, "total_lines": 3000, "content": content}
+ out = _bounded(result, spill=tmp_path, tool="read_file")
+ assert _size(out) <= 10_000 and out["path"] == "big.py" and out["total_lines"] == 3000
+ assert "bytes omitted here" in out["content"]
+ assert (tmp_path / "0007-read_file-content.txt").read_text(encoding="utf-8") == content
+
+
+def test_plain_string_result_is_bounded(tmp_path):
+ text = "y" * 50_000
+ out = _bounded(text, spill=tmp_path, tool="web_fetch")
+ assert isinstance(out, str) and len(out.encode()) <= 10_000
+ assert out.startswith("yyyy") and out.endswith("yyyy") and "bytes omitted" in out
+ assert (tmp_path / "0007-web_fetch.txt").read_text(encoding="utf-8") == text
+
+
+def test_multibyte_text_is_cut_safely(tmp_path):
+ text = "é☃𝄞" * 20_000 # 1-, 3- and 4-byte characters
+ out = _bounded(text, spill=tmp_path)
+ out.encode("utf-8") # no lone surrogates / broken sequences
+ assert len(out.encode()) <= 10_000
+
+
+def test_deterministic_and_cache_stable(tmp_path):
+ result = {"output": "z" * 30_000, "exit_code": 0}
+ a = _bounded(result, spill=tmp_path)
+ b = _bounded(result, spill=tmp_path)
+ assert a == b # identical text both times: no timestamps, no counters
+
+
+def test_disabled_with_zero_or_none(tmp_path):
+ result = {"output": "z" * 30_000}
+ assert _bounded(result, max_bytes=0, spill=tmp_path) is result
+ assert _bounded(result, max_bytes=None, spill=tmp_path) is result
+
+
+def test_two_big_fields_are_both_bounded(tmp_path):
+ result = {"stdout": "a" * 20_000, "stderr": "b" * 20_000, "exit_code": 2}
+ out = _bounded(result, spill=tmp_path)
+ assert _size(out) <= 10_000
+ assert "bytes omitted" in out["stdout"] and "bytes omitted" in out["stderr"]
+ assert sorted(p.name for p in tmp_path.iterdir()) == ["0007-run_shell-stderr.txt", "0007-run_shell-stdout.txt"]
+
+
+def test_without_spill_dir_marker_says_so(tmp_path):
+ out = _bounded({"output": "q" * 30_000}, spill=None)
+ assert "full text not saved" in out["output"]
+
+
+# -- engine round trip --------------------------------------------------------------------
+
+
+class _Scripted(ProviderClient):
+ def __init__(self, turns):
+ self._turns = list(turns)
+
+ def complete(self, *, model, messages, tools=None, **settings):
+ return self._turns.pop(0)
+
+ def capabilities(self, model):
+ return ModelCapabilities()
+
+
+def _run(engine, prompt):
+ async def go():
+ return [ev async for ev in engine.run(prompt)]
+
+ return asyncio.run(go())
+
+
+def test_engine_bounds_tool_results_and_keeps_the_rest_of_the_message(tmp_path):
+ low = ai.ToolMetadata(category="search", risk_level="low", requires_approval=False)
+
+ def big_out():
+ """Return a very large result."""
+ return {"output": "\n".join(f"row{i}" for i in range(6000)), "exit_code": 0}
+
+ registry = ToolRegistry()
+ registry.register(big_out, metadata=low)
+ permissions = PermissionEngine(workspace_root=tmp_path)
+ spill = tmp_path / "spill"
+ engine = TurnEngine(
+ provider=_Scripted([
+ AssistantTurn(tool_calls=[ToolCall(id="c1", name="big_out", arguments={})], finish_reason="tool_calls"),
+ AssistantTurn(text="done", finish_reason="stop"),
+ ]),
+ registry=registry,
+ permissions=permissions,
+ model="gpt-5.5",
+ approver=None,
+ tool_result_max_bytes=10_000,
+ tool_result_spill_dir=spill,
+ )
+ events = _run(engine, "go")
+ assert [e for e in events if e.type == EventType.TOOL_FINISHED][0].data["status"] == "ok"
+ tool_msgs = [m for m in engine.messages if m.get("role") == "tool"]
+ assert len(tool_msgs) == 1
+ content = tool_msgs[0]["content"]
+ assert len(content.encode()) <= 10_000
+ parsed = json.loads(content)
+ assert parsed["exit_code"] == 0 and parsed["output"].startswith("row0")
+ assert "bytes omitted here" in parsed["output"]
+ files = list(spill.iterdir())
+ assert len(files) == 1 and files[0].read_text(encoding="utf-8").endswith("row5999")
+
+
+def test_engine_default_cap_is_ten_thousand_and_zero_disables(tmp_path):
+ registry = ToolRegistry()
+ permissions = PermissionEngine(workspace_root=tmp_path)
+ e1 = TurnEngine(provider=_Scripted([]), registry=registry, permissions=permissions, model="m")
+ assert e1._tool_result_max_bytes == toolresult.DEFAULT_TOOL_RESULT_MAX_BYTES == 10_000
+ e2 = TurnEngine(provider=_Scripted([]), registry=registry, permissions=permissions, model="m", tool_result_max_bytes=0)
+ assert e2._tool_result_max_bytes == 0