paimon 0.2.0__tar.gz → 0.2.2__tar.gz

paimon-0.2.2/MANIFEST.in

@@ -0,0 +1,7 @@
+prune tests
+prune docs
+prune scripts
+prune .github
+exclude .gitignore
+exclude .python-version
+exclude uv.lock

{paimon-0.2.0 → paimon-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paimon
-Version: 0.2.0
+Version: 0.2.2
 Summary: A minimal code agent built on pydantic-ai + textual
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -38,7 +38,13 @@ uvx paimon
 
 The first launch asks for a provider, model, API base and key, and saves them to `~/.config/paimon/default/config.json`. Then just type what you want done.
 
-While it runs: `Shift+Tab` switches how much the agent may do on its own (**read**: ask before writing files or running commands, except clearly read-only ones like `ls` or `git status`, which run without asking, **edit**: edits inside the working directory go through, **yolo**: never ask), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette (switch provider or profile, new, fork or resume session, show the model's thinking, compact the context), `Ctrl+C` quits.
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read**: ask before writing files or running commands, except clearly read-only ones like `ls` or `git status`, which run without asking, **edit**: edits inside the working directory go through, **yolo**: never ask; the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette (switch provider or profile, new, fork or resume session, show the model's thinking, compact the context), `Ctrl+C` quits.
+
+`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission.
+
+Paimon can open panes itself: ask for two independent things and it starts a second agent in its own tab, with the same tools, working directory and permission mode. Its permission prompts appear in that tab, so `Ctrl+G` is how you unblock it. Those sessions belong to the one that started them, so they stay out of `paimon sessions` and end when it does.
+
+It can also leave a command running in a tab of its own, for a dev server, a watcher or a long build that would otherwise hold up a turn. It asks first, every time, whatever the mode says about read-only commands. The tab streams the output and stops the command when you close it or quit. Programs that buffer their output when it is not going to a terminal print in blocks there rather than line by line; that is what a pipe costs, and Paimon does not emulate a terminal.
 
 Write `@path/to/file` in a prompt to hand a file to the agent.
 
@@ -76,7 +82,7 @@ paimon log a1b2c3    # what a session did, one line per event
 ## Other ways to run it
 
 ```bash
-paimon --mode edit                  # start in a less cautious permission mode
+paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
 paimon --strict                     # ask before every command, even read-only ones
 paimon --web                        # the same UI in a browser (--port, default 8000)
 paimon -p "what does cli.py do?"    # one answer on stdout, no UI
@@ -85,7 +91,7 @@ paimon --model zai:glm-4.7          # this model for this run only
 paimon --profile work               # a separately configured account
 ```
 
-`-p` never stops to ask, so anything the current mode would prompt for is refused instead (recognized read-only commands still run in read mode); pass `--mode edit` or `--mode yolo` if the run needs to change files. Add `--output-format result` for a single JSON object with the outcome (or `json` for one event per line), and `--timeout`/`--max-tool-calls` to bound an unattended run.
+`-p` never stops to ask, and the default mode is `yolo`, so it can already write files and run commands; pass `--mode read` or `--mode edit` to keep the guardrails, in which case anything the mode would prompt for is refused instead (recognized read-only commands still run in read mode). Add `--output-format result` for a single JSON object with the outcome (or `json` for one event per line), and `--timeout`/`--max-tool-calls` to bound an unattended run.
 
 ## Configuration
 

{paimon-0.2.0 → paimon-0.2.2}/README.md

@@ -26,7 +26,13 @@ uvx paimon
 
 The first launch asks for a provider, model, API base and key, and saves them to `~/.config/paimon/default/config.json`. Then just type what you want done.
 
-While it runs: `Shift+Tab` switches how much the agent may do on its own (**read**: ask before writing files or running commands, except clearly read-only ones like `ls` or `git status`, which run without asking, **edit**: edits inside the working directory go through, **yolo**: never ask), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette (switch provider or profile, new, fork or resume session, show the model's thinking, compact the context), `Ctrl+C` quits.
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read**: ask before writing files or running commands, except clearly read-only ones like `ls` or `git status`, which run without asking, **edit**: edits inside the working directory go through, **yolo**: never ask; the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette (switch provider or profile, new, fork or resume session, show the model's thinking, compact the context), `Ctrl+C` quits.
+
+`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission.
+
+Paimon can open panes itself: ask for two independent things and it starts a second agent in its own tab, with the same tools, working directory and permission mode. Its permission prompts appear in that tab, so `Ctrl+G` is how you unblock it. Those sessions belong to the one that started them, so they stay out of `paimon sessions` and end when it does.
+
+It can also leave a command running in a tab of its own, for a dev server, a watcher or a long build that would otherwise hold up a turn. It asks first, every time, whatever the mode says about read-only commands. The tab streams the output and stops the command when you close it or quit. Programs that buffer their output when it is not going to a terminal print in blocks there rather than line by line; that is what a pipe costs, and Paimon does not emulate a terminal.
 
 Write `@path/to/file` in a prompt to hand a file to the agent.
 
@@ -64,7 +70,7 @@ paimon log a1b2c3    # what a session did, one line per event
 ## Other ways to run it
 
 ```bash
-paimon --mode edit                  # start in a less cautious permission mode
+paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
 paimon --strict                     # ask before every command, even read-only ones
 paimon --web                        # the same UI in a browser (--port, default 8000)
 paimon -p "what does cli.py do?"    # one answer on stdout, no UI
@@ -73,7 +79,7 @@ paimon --model zai:glm-4.7          # this model for this run only
 paimon --profile work               # a separately configured account
 ```
 
-`-p` never stops to ask, so anything the current mode would prompt for is refused instead (recognized read-only commands still run in read mode); pass `--mode edit` or `--mode yolo` if the run needs to change files. Add `--output-format result` for a single JSON object with the outcome (or `json` for one event per line), and `--timeout`/`--max-tool-calls` to bound an unattended run.
+`-p` never stops to ask, and the default mode is `yolo`, so it can already write files and run commands; pass `--mode read` or `--mode edit` to keep the guardrails, in which case anything the mode would prompt for is refused instead (recognized read-only commands still run in read mode). Add `--output-format result` for a single JSON object with the outcome (or `json` for one event per line), and `--timeout`/`--max-tool-calls` to bound an unattended run.
 
 ## Configuration
 

paimon-0.2.2/README.zh-CN.md

@@ -0,0 +1,104 @@
+# Paimon
+
+![Paimon](https://automaton-media.com/wp-content/uploads/2020/10/20201019-140524-header.jpg)
+
+[English](README.md) | 简体中文
+
+Paimon 是一个终端里的 coding agent。它读写当前目录下的文件、执行命令，在做任何改动前会先询问。它也支持无头运行，可以被更强的 agent 作为执行者调用。
+
+## 安装
+
+```bash
+uv tool install paimon   # 或者：pip install paimon
+```
+
+## 快速开始
+
+```bash
+paimon
+```
+
+或者不安装直接运行：
+
+```bash
+uvx paimon
+```
+
+首次启动会询问 provider、模型、API base 和 key，并保存到 `~/.config/paimon/default/config.json`。之后输入要完成的任务即可。
+
+运行时：`Shift+Tab` 切换 agent 的自主程度（**read**：写文件或执行命令前先询问，`ls`、`git status` 这类明确只读的命令除外，会直接执行，**edit**：工作目录内的编辑直接执行，**yolo**：从不询问，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板（切换 provider 或 profile、新建、分叉或恢复会话、显示模型思考、压缩上下文），`Ctrl+C` 退出。
+
+`Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane。
+
+Paimon 自己也能开 pane：让它同时做两件互不相干的事，它会在新 tab 里起第二个 agent，工具、工作目录和权限模式都和当前会话一样。它的授权确认弹在它自己的 tab 里，用 `Ctrl+G` 过去处理。这些会话属于开它们的那个会话，不会出现在 `paimon sessions` 里，也随它一起结束。
+
+它也能把一条命令留在单独的 tab 里跑，比如开发服务器、文件监视或者很长的构建，不占着当前回合。这类命令一律先确认，不管当前模式对只读命令怎么规定。tab 里流式显示输出，关掉 tab 或退出时命令随之停止。输出不是终端时很多程序会按块缓冲，所以 tab 里可能一阵子不出东西再一次性出来：这是用管道代替终端的代价，Paimon 不做终端模拟。
+
+在提示中写 `@path/to/file` 可以把文件提供给 agent。
+
+## 当作 subagent 使用
+
+前沿模型擅长制定计划和验收结果，中间的执行步骤往往比较机械。让 Paimon 使用成本较低的模型执行，由 Claude Code 或 Codex 制定计划并检查结果，只在必要的环节为前沿模型付费。用一个 profile 单独保存该模型的账号：
+
+```bash
+paimon login --profile glm --model zai:glm-4.7 --api-key-env ZAI_API_KEY
+paimon --profile glm -p "apply the plan in PLAN.md" --mode edit --output-format result
+```
+
+自带的 skill 会向调用方 agent 说明这套流程（先用 `paimon status --json` 检查、单次运行、读取唯一一行 result 对象、用其中的 `session_id` 续跑、用 `paimon log` 查看运行过程）：
+
+```bash
+paimon install-skill                  # 安装到 Claude Code（~/.claude/skills/paimon）
+paimon install-skill --target codex   # 安装到 Codex；--dest DIR 安装到任意目录
+npx skills add aisk/paimon            # 通过 skills.sh 安装同一个 skill
+```
+
+## 会话
+
+每次对话都会保存。退出时 Paimon 会打印恢复该会话的命令：
+
+```bash
+paimon -r            # 从当前目录的会话中选择
+paimon -r a1b2c3     # 按 id 恢复
+paimon -c            # 恢复最近一个会话
+paimon sessions      # 列出会话（--json 输出机器可读格式）
+paimon log a1b2c3    # 查看会话做了什么，每个事件一行
+```
+
+`paimon log` 的每行输出都带一个稳定的序号；`--after SEQ`、`--turns N`、`--tail N` 缩小范围，`--json` 和 `--full` 输出原始记录。
+
+## 其他运行方式
+
+```bash
+paimon --mode read                  # 以更谨慎的权限模式启动（默认为 yolo）
+paimon --strict                     # 每条命令都先询问，包括只读命令
+paimon --web                        # 在浏览器中使用同一套 UI（--port，默认 8000）
+paimon -p "what does cli.py do?"    # 直接在 stdout 输出回答，不启动 UI
+cat log.txt | paimon -p "summarize this"
+paimon --model zai:glm-4.7          # 仅本次运行使用该模型
+paimon --profile work               # 单独配置的另一个账号
+```
+
+`-p` 不会停下来询问，默认模式是 `yolo`，因此已经可以修改文件和执行命令；传 `--mode read` 或 `--mode edit` 可以保留确认护栏，此时当前模式需要确认的操作会被直接拒绝（识别为只读的命令在 read 模式下仍会执行）。加 `--output-format result` 输出一个包含结果的 JSON 对象（`json` 则每行输出一个事件），用 `--timeout`/`--max-tool-calls` 为无人值守的运行设置上限。
+
+## 配置
+
+`~/.config/paimon/<name>/config.json` 保存每个 profile 的模型设置（不传 `--profile` 时为 `default`）。两个可选配置项可以改变它的行为：自动放行只读命令，以及在接近上下文上限时原地总结长对话。
+
+```json
+{
+  "safe_commands": false,
+  "compaction": {
+    "enabled": true,
+    "context_window": 128000,
+    "reserve_tokens": 16384,
+    "keep_recent_tokens": 20000
+  }
+}
+```
+
+`safe_commands`（默认 `true`）允许 read 和 edit 模式不经询问执行一小组固定的、明确只读的命令（`ls`、`cat`、`git status` 等）；`--strict` 可在单次运行中关闭它。被识别的命令可以用 `&&`、`;` 或管道串联，也包括 `cd 目录 && …`（目录须留在工作目录内，且整条命令都以 `&&` 连接）。重定向、`$()`/反引号替换和后台 `&` 仍会询问。
+
+**这是防止 agent 失误的护栏，不是安全边界。** 被识别的命令仍然通过 `PATH` 查找，仍可能顺着符号链接读到工作目录之外；而且哪怕是纯读取，也会把文件内容带进模型上下文，只读不等于保密安全。需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
+
+会话存放在 `~/.local/share/paimon/sessions/`（`PAIMON_DATA_HOME` 可覆盖）。安装 [delta](https://github.com/dandavison/delta) 后文件改动的展示效果更好。

{paimon-0.2.0 → paimon-0.2.2}/paimon/agent.py

@@ -32,10 +32,20 @@ from pydantic_ai.models import Model, ModelRequestParameters
 
 from . import compaction, retry, tools
 from .config import Config
-from .llm import build_model
+from .llm import build_model, user_agent
 from .mentions import expand_mentions
 from .prompt import build_system_prompt
-from .session import Session, SessionIncompleteError, is_summary_message
+from .session import (
+    Session,
+    SessionIncompleteError,
+    agents_message,
+    agents_text,
+    is_agents_message,
+    is_summary_message,
+)
+
+# Transient compaction failures tolerated in one turn before it is left off.
+_MAX_COMPACTION_FAILURES = 3
 
 
 # ---- Events yielded by Agent.run -------------------------------------------
@@ -128,12 +138,24 @@ class CompactionNotice:
     """A compaction checkpoint encountered while replaying history."""
 
 
+@dataclass
+class AgentsNotice:
+    """A status line about the agents this session started.
+
+    Not replay-only: it is written into the history at the top of a turn, so
+    it is both yielded live and rebuilt when the session is resumed.
+    """
+
+    text: str
+
+
 # Everything ``Agent.run`` and ``replay_events`` can yield. Renderers dispatch
 # on isinstance; the alias exists so a type checker can flag an unhandled one.
 AgentEvent = (
     TextDelta | ReasoningDelta | ToolStart | ToolEnd | TodosUpdate
     | SessionHandoff | RequestStats | TurnEnd | ContextCompacted
     | ContextCompactionFailed | ModelRetry | UserInput | CompactionNotice
+    | AgentsNotice
 )
 
 
@@ -156,15 +178,22 @@ def replay_events(messages: list[ModelMessage]) -> list[AgentEvent]:
     Lets a UI render resumed history through the same code path as live turns.
     """
     events: list[AgentEvent] = []
+    # write_todos calls whose arguments never made a todo update: they were
+    # rejected live as a normal tool error, so they replay as one.
+    rejected_todos: set[str] = set()
     for message in messages:
         if is_summary_message(message):
             events.append(CompactionNotice())
             continue
+        if is_agents_message(message):
+            events.append(AgentsNotice(agents_text(message)))
+            continue
         if isinstance(message, ModelRequest):
             for part in message.parts:
                 if isinstance(part, UserPromptPart) and isinstance(part.content, str) and part.content:
                     events.append(UserInput(part.content))
-                elif isinstance(part, ToolReturnPart) and part.tool_name != "write_todos":
+                elif isinstance(part, ToolReturnPart) and (part.tool_name != "write_todos"
+                                                           or part.tool_call_id in rejected_todos):
                     events.append(ToolEnd(part.tool_call_id, part.tool_name,
                                           str(part.content or "(no output)")))
         elif isinstance(message, ModelResponse):
@@ -175,9 +204,13 @@ def replay_events(messages: list[ModelMessage]) -> list[AgentEvent]:
                     events.append(TextDelta(part.content))
                 elif isinstance(part, ToolCallPart):
                     args = _parse_args(part.args)
-                    if part.tool_name == "write_todos":
-                        events.append(TodosUpdate(args.get("todos") or []))
+                    todos = (tools.normalize_todos(args.get("todos"))
+                             if part.tool_name == "write_todos" else None)
+                    if todos is not None:
+                        events.append(TodosUpdate(todos))
                     else:
+                        if part.tool_name == "write_todos":
+                            rejected_todos.add(part.tool_call_id)
                         events.append(ToolStart(part.tool_call_id, part.tool_name, args))
     return events
 
@@ -215,13 +248,26 @@ class Agent:
     """
 
     def __init__(self, session: Session, system_prompt: str, *, cwd: Optional[Path] = None,
-                 confirm: Optional[ConfirmFn] = None, mode: str = "read",
+                 confirm: Optional[ConfirmFn] = None, mode: str = "yolo",
                  config: Optional[Config] = None,
-                 toolset: Optional[dict[str, tools.Tool]] = None):
+                 toolset: Optional[dict[str, tools.Tool]] = None,
+                 model_override: Optional[str] = None):
         self.cwd = Path(cwd or Path.cwd())
         self.confirm = confirm
         self.mode = mode
         self.config = config or Config.load()
+        # Per-agent model choice. One Config instance is shared by every agent
+        # in the process, so writing config.model would repoint all of them;
+        # this overrides the model for this agent alone, credentials included
+        # (they come from the config either way).
+        self.model_override = model_override
+        # Set by the UI when this agent may start and talk to other agents.
+        # None everywhere else (headless, tests), where the agent tools refuse
+        # rather than pretend.
+        self.supervisor = None
+        # Per-agent tool state, kept off the tool functions so one agent's
+        # shell overflow files stay invisible to the next one.
+        self.tool_context = tools.ToolContext()
         self.todos: list[dict] = []
         self.session = session
         self.system_prompt = system_prompt
@@ -234,44 +280,62 @@ class Agent:
 
     @classmethod
     def open(cls, cwd: Optional[Path] = None, *, session: Optional[Session] = None,
-             confirm: Optional[ConfirmFn] = None, mode: str = "read",
+             confirm: Optional[ConfirmFn] = None, mode: str = "yolo",
              config: Optional[Config] = None,
              append_system_prompt: Optional[str] = None,
-             toolset: Optional[dict[str, tools.Tool]] = None) -> "Agent":
+             toolset: Optional[dict[str, tools.Tool]] = None,
+             model_override: Optional[str] = None,
+             parent: Optional[str] = None) -> "Agent":
         """Start a new session, or resume ``session``, and take its lock.
 
         ``append_system_prompt`` is added to the end of a new session's system
         prompt and persisted with it, so a resumed session keeps it. Resuming
         with it set raises ``ValueError``: the persisted prompt is immutable.
+        ``parent`` marks the new session as a subagent's, which keeps it out of
+        the session listings its parent shows up in.
 
-        Raises ``SessionBusyError`` when another process holds the session and
-        ``SessionIncompleteError`` when a resumed log has no system prompt
-        snapshot — both ``SessionError``, and neither leaves a lock held.
+        Raises ``SessionBusyError`` when the session is already open (here or
+        in another process) and ``SessionIncompleteError`` when a resumed log
+        has no system prompt snapshot — both ``SessionError``, and neither
+        leaves a lock held.
         """
         cwd = Path(cwd or Path.cwd())
         if session is not None and append_system_prompt:
             raise ValueError("append_system_prompt only applies to a new session")
+        is_new = session is None
         if session is None:
-            session = Session.create(cwd)
-            session.lock()
-            system_prompt = build_system_prompt(cwd)
-            if append_system_prompt:
-                system_prompt += f"\n\n{append_system_prompt.strip()}"
-            session.append_system_prompt(system_prompt)
-        else:
-            session.lock()
-            system_prompt = session.system_prompt()
-            if system_prompt is None:
-                session.unlock()
-                raise SessionIncompleteError("Session does not contain a persisted system prompt")
-        return cls(session, system_prompt, cwd=cwd, confirm=confirm, mode=mode,
-                   config=config, toolset=toolset)
+            session = Session.create(cwd, parent)
+        session.lock()
+        # Everything after the lock can fail — a full disk while writing the
+        # prompt, a message the current pydantic-ai cannot parse — and no
+        # Agent is returned to unlock it, so the lock is released here.
+        try:
+            if is_new:
+                system_prompt = build_system_prompt(cwd)
+                if append_system_prompt:
+                    system_prompt += f"\n\n{append_system_prompt.strip()}"
+                session.append_system_prompt(system_prompt)
+            else:
+                system_prompt = session.system_prompt()
+                if system_prompt is None:
+                    raise SessionIncompleteError("Session does not contain a persisted system prompt")
+            return cls(session, system_prompt, cwd=cwd, confirm=confirm, mode=mode,
+                       config=config, toolset=toolset, model_override=model_override)
+        except BaseException:
+            session.unlock()
+            raise
+
+    @property
+    def model_name(self) -> Optional[str]:
+        """The model this agent talks to: its own override, else the config's."""
+        return self.model_override or self.config.model
 
     def _model(self) -> Model:
         """The configured model, rebuilt when login changes the config."""
-        if not self.config.model:
+        name = self.model_name
+        if not name:
             raise RuntimeError("No model configured; log in first")
-        key = (self.config.model, self.config.api_base, self.config.api_key)
+        key = (name, self.config.api_base, self.config.api_key)
         if self._cached_model is None or self._cached_model[0] != key:
             self._cached_model = (key, build_model(*key))
         return self._cached_model[1]
@@ -299,13 +363,17 @@ class Agent:
         if not force:
             if not self.config.compaction_enabled:
                 return None
-            window = compaction.context_window(self.config.model,
+            window = compaction.context_window(self.model_name,
                                                self.config.compaction_context_window)
-            tokens_before = self.count_context_tokens()
+            # Nothing to compare against, so counting would be wasted work: an
+            # unknown window disables auto-compaction outright.
+            if window is None:
+                return None
+            tokens_before = await self.count_context_tokens()
             if not compaction.should_compact(tokens_before, window, self.config.compaction_reserve_tokens):
                 return None
         else:
-            tokens_before = self.count_context_tokens()
+            tokens_before = await self.count_context_tokens()
 
         result = await compaction.compact(
             self.history,
@@ -322,12 +390,19 @@ class Agent:
         # append-message invariant (see _append_message) still holds afterwards.
         self.session.append_compaction(result.summary, result.kept_messages, result.tokens_before)
         self.history = result.messages
-        result.tokens_after = self.count_context_tokens()
+        result.tokens_after = await self.count_context_tokens()
         return result
 
-    def count_context_tokens(self) -> int:
-        """Estimate the tokens of everything the next request would send."""
-        return compaction.count_tokens(self.history, self.tool_schemas, self.system_prompt)
+    async def count_context_tokens(self) -> int:
+        """Estimate the tokens of everything the next request would send.
+
+        Off the event loop: the count serializes the whole history, which is
+        hundreds of kilobytes on a long session.  It runs at the top of every
+        model step, and every agent shares one loop, so counting inline stalls
+        every other agent's streaming output for as long as it takes.
+        """
+        return await asyncio.to_thread(
+            compaction.count_tokens, list(self.history), self.tool_schemas, self.system_prompt)
 
     async def compact_now(self) -> Optional[compaction.CompactionResult]:
         """Compact on demand; None when the history is too short to be worth it."""
@@ -343,8 +418,17 @@ class Agent:
                                persist: Callable[[], None]) -> AsyncIterator[AgentEvent]:
         # Reports itself as TodosUpdate alone — no ToolStart/ToolEnd — which is
         # also the shape replay_events produces for it, so no renderer has to
-        # special-case the name.
-        self.todos = args.get("todos") or []
+        # special-case the name. A malformed argument is the exception: it
+        # renders as a normal failed tool call, live and on replay alike.
+        todos = tools.normalize_todos(args.get("todos"))
+        if todos is None:
+            yield ToolStart(call.tool_call_id, call.tool_name, args)
+            slot.content = ("Error: 'todos' must be an array of "
+                            "{content, status} objects.")
+            persist()
+            yield ToolEnd(call.tool_call_id, call.tool_name, slot.content)
+            return
+        self.todos = todos
         slot.content = tools.render_todos(self.todos)
         persist()
         yield TodosUpdate(list(self.todos))
@@ -362,12 +446,7 @@ class Agent:
             persist()
             yield ToolEnd(call.tool_call_id, call.tool_name, slot.content)
             return
-        needs_confirm = tools.gate(call.tool_name, args, self.mode, self.cwd,
-                                   self.toolset) == "confirm"
-        allowed = not needs_confirm or (
-            await self.confirm(call.tool_name, args) if self.confirm else False
-        )
-        if not allowed:
+        if not await self._permitted(call.tool_name, args):
             slot.content = "User denied this operation."
             persist()
             yield ToolEnd(call.tool_call_id, call.tool_name, slot.content, denied=True)
@@ -378,9 +457,52 @@ class Agent:
         yield ToolEnd(call.tool_call_id, call.tool_name, slot.content)
         yield SessionHandoff(prompt_text)
 
+    async def _permitted(self, name: str, args: dict) -> bool:
+        """Gate a tool the loop runs itself, the way run_tool gates the rest.
+
+        The enforcement point for everything in _AGENT_HANDLED: without a
+        confirm hook a call that needs one is denied, so a headless agent
+        cannot walk around the permission mode here either.
+        """
+        if tools.gate(name, args, self.mode, self.cwd, self.toolset,
+                      safe_commands=self.config.safe_commands,
+                      ctx=self.tool_context) != "confirm":
+            return True
+        return await self.confirm(name, args) if self.confirm else False
+
+    async def _run_supervised(self, call: ToolCallPart, args: dict, slot: ToolReturnPart,
+                              persist: Callable[[], None]) -> AsyncIterator[AgentEvent]:
+        """The job tools: starting agents and commands, and reporting on both.
+
+        They act on the pool of jobs the UI is running, which no stateless tool
+        function can reach, and the supervisor is the one thing that knows
+        whether a given job is busy \u2014 so they are dispatched from here. Most of
+        them are not gated at all (they only reach jobs this same agent
+        started); run_background is, because it starts a process.
+        """
+        yield ToolStart(call.tool_call_id, call.tool_name, args)
+        if self.supervisor is None:
+            slot.content = ("Error: this only works in the interactive UI; "
+                            "do the work yourself instead.")
+        elif not await self._permitted(call.tool_name, args):
+            slot.content = "User denied this operation."
+            persist()
+            yield ToolEnd(call.tool_call_id, call.tool_name, slot.content, denied=True)
+            return
+        else:
+            slot.content = await self.supervisor.handle(call.tool_name, args, caller=self)
+        persist()
+        yield ToolEnd(call.tool_call_id, call.tool_name, slot.content)
+
     _AGENT_HANDLED = {
         "write_todos": _run_write_todos,
         "start_new_session": _run_start_new_session,
+        "spawn_agent": _run_supervised,
+        "send_to_agent": _run_supervised,
+        "run_background": _run_supervised,
+        "read_job": _run_supervised,
+        "wait_for_job": _run_supervised,
+        "stop_job": _run_supervised,
     }
 
     async def run(self, user_input: str, *, expand: bool = True) -> AsyncIterator[AgentEvent]:
@@ -391,17 +513,34 @@ class Agent:
         stdin, where a line like ``@foo.py`` is data rather than a mention).
         """
         prompt = expand_mentions(user_input, self.cwd) if expand else user_input
+        # Agents this session started report in here, at the top of the next
+        # turn, rather than by interrupting whatever the user is typing. It has
+        # to be a persisted message: an event the model never sees would defeat
+        # the point, which is to get it to call read_job.
+        summary = self.supervisor.status_summary(self) if self.supervisor is not None else None
+        if summary:
+            self._append_message(agents_message(summary))
+            yield AgentsNotice(summary)
         self._append_message(ModelRequest(parts=[UserPromptPart(content=prompt)]))
-        compaction_failed = False
+        # A compaction that failed for a transient reason is retried on the
+        # next step of this turn — the context only keeps growing, so giving
+        # up on the first rate limit disables the safety net exactly when it
+        # is needed. Anything else, and repeated transient failures, stop it
+        # for the rest of the turn instead of paying for it every step.
+        compaction_off = False
+        compaction_failures = 0
 
         while True:
-            if not compaction_failed:
+            if not compaction_off:
                 try:
                     compacted = await self._maybe_compact()
                 except Exception as exc:  # noqa: BLE001 - the normal request may still fit
-                    compaction_failed = True
+                    compaction_failures += 1
+                    compaction_off = (not retry.is_transient(exc)
+                                      or compaction_failures >= _MAX_COMPACTION_FAILURES)
                     yield ContextCompactionFailed(str(exc))
                 else:
+                    compaction_failures = 0
                     if compacted:
                         yield ContextCompacted(compacted.tokens_before, compacted.tokens_after)
 
@@ -423,7 +562,10 @@ class Agent:
                 first_event_at: Optional[float] = None
                 try:
                     async with model_request_stream(
-                        model, request_messages, model_request_parameters=parameters
+                        model,
+                        request_messages,
+                        model_settings={"extra_headers": {"User-Agent": user_agent()}},
+                        model_request_parameters=parameters,
                     ) as stream:
                         async for event in stream:
                             if first_event_at is None:
@@ -523,7 +665,8 @@ class Agent:
                 yield ToolStart(call.tool_call_id, name, args)
                 result, denied = await tools.run_tool(name, args, self.cwd, self.mode,
                                                       self.confirm, self.toolset,
-                                                      safe_commands=self.config.safe_commands)
+                                                      safe_commands=self.config.safe_commands,
+                                                      ctx=self.tool_context)
 
                 slot.content = result
                 persist()