paimon 0.2.4__tar.gz → 0.2.6__tar.gz

{paimon-0.2.4/paimon.egg-info → paimon-0.2.6}/PKG-INFO

@@ -1,13 +1,15 @@
 Metadata-Version: 2.4
 Name: paimon
-Version: 0.2.4
+Version: 0.2.6
 Summary: A minimal code agent built on pydantic-ai + textual
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic-ai-slim[anthropic,openai]>=2.31.0
 Requires-Dist: textual>=8.2.7
 Requires-Dist: textual-serve>=1.1.3
+Requires-Dist: pyyaml>=6
 Dynamic: license-file
 
 # Paimon
@@ -38,10 +40,14 @@ uvx paimon
 
 The first launch asks for a provider, model, API base and key. Then just type what you want done. Write `@path/to/file` in a prompt to hand a file to the agent.
 
-While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits.
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits. A line starting with `!` runs in a shell instead of being sent, and Paimon sees what it printed. `!!` keeps it to yourself.
 
 `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. It can also leave a command running in a tab of its own, a dev server or a watcher, instead of holding up a turn.
 
+## Skills
+
+Paimon loads [Agent Skills](https://agentskills.io) from `~/.config/paimon/skills`, `~/.agents/skills` and every `.agents/skills` from the working directory up to the repository root. Only each skill's name and description go into the system prompt; the model reads the `SKILL.md` when a task matches, and `/skill:name args` sends it explicitly (the `/` command palette lists them). More locations go in `config.json` as `"skills": ["~/.claude/skills"]` or on the command line with `--skill PATH`; `--no-skills` skips the default locations. When two skills share a name, explicit paths beat the project's, which beat the global ones.
+
 ## Using Paimon as a subagent
 
 Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. A profile keeps that model's account separate:
@@ -111,6 +117,102 @@ Each profile keeps its model settings in `~/.config/paimon/<name>/config.json`,
 
 Read and edit modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) without asking; `--strict` turns that off. **This is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
 
+## Architecture
+
+`Agent.run` is a UI-agnostic stream of events; the TUI, `--web` and headless mode are three renderers over that one stream. `Supervisor` sits between an agent and the subagents or background commands it starts, and is the permission boundary for both.
+
+```mermaid
+flowchart TD
+    subgraph entry["Entry points"]
+        CLI["cli.py"]
+        Commands["commands.py<br/>status / login / sessions"]
+        Headless["headless.py<br/>-p, one-shot"]
+        App["app.py<br/>Textual TUI / --web"]
+    end
+
+    subgraph tui["TUI widgets"]
+        Pane["pane.py<br/>SessionPane"]
+        CommandPane["commandpane.py<br/>background command pane"]
+        Tabs["tabs.py<br/>pane strip"]
+        Login["login.py<br/>provider / model / key"]
+        UIWidgets["ui.py<br/>prompt input, confirmations"]
+        Diff["diff.py<br/>side-by-side diff rendering"]
+    end
+
+    subgraph core["Agent loop"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools.py<br/>tool REGISTRY"]
+        SessionMod["session.py<br/>JSONL persistence"]
+        Compaction["compaction.py"]
+        ModelWindows["model_windows.py<br/>context window sizes"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path expansion"]
+        Aside["aside.py<br/>off-turn question, unrecorded"]
+    end
+
+    subgraph concurrency["Jobs & subagents"]
+        Supervisor["supervisor.py<br/>job pool, permissions"]
+        Jobs["jobs.py<br/>AgentJob / CommandJob"]
+        AgentTypes["agents.py<br/>subagent types"]
+    end
+
+    subgraph support["Config & skills"]
+        Config["config.py<br/>profiles, credentials"]
+        Skills["skills.py<br/>Agent Skills discovery"]
+    end
+
+    CLI --> Commands
+    CLI --> Headless
+    CLI --> App
+    CLI --> Config
+
+    Headless --> AgentLoop
+    Headless --> Mentions
+
+    App --> Pane
+    App --> CommandPane
+    App --> Tabs
+    App --> Login
+    App --> Supervisor
+    App --> Config
+
+    Pane --> AgentLoop
+    Pane --> Aside
+    Pane --> Diff
+    Pane --> UIWidgets
+    Pane --> LLM
+    CommandPane --> Pane
+    UIWidgets --> Diff
+
+    AgentLoop --> LLM
+    AgentLoop --> PromptMod
+    AgentLoop --> ToolsMod
+    AgentLoop --> SessionMod
+    AgentLoop --> Compaction
+    AgentLoop --> Retry
+    AgentLoop --> Mentions
+    AgentLoop -. "spawn_agent / run_background" .-> Supervisor
+
+    Aside --> Retry
+    Aside --> SessionMod
+
+    PromptMod --> Skills
+    Compaction --> ModelWindows
+
+    Supervisor --> Jobs
+    Supervisor --> AgentTypes
+    Supervisor --> ToolsMod
+    Supervisor -. "launch callback" .-> App
+    Jobs --> AgentLoop
+
+    AgentTypes --> ToolsMod
+    AgentTypes --> Config
+    Skills --> Config
+    Config --> LLM
+```
+
 ## Telemetry
 
 Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.

{paimon-0.2.4 → paimon-0.2.6}/README.md

@@ -26,10 +26,14 @@ uvx paimon
 
 The first launch asks for a provider, model, API base and key. Then just type what you want done. Write `@path/to/file` in a prompt to hand a file to the agent.
 
-While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits.
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits. A line starting with `!` runs in a shell instead of being sent, and Paimon sees what it printed. `!!` keeps it to yourself.
 
 `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. It can also leave a command running in a tab of its own, a dev server or a watcher, instead of holding up a turn.
 
+## Skills
+
+Paimon loads [Agent Skills](https://agentskills.io) from `~/.config/paimon/skills`, `~/.agents/skills` and every `.agents/skills` from the working directory up to the repository root. Only each skill's name and description go into the system prompt; the model reads the `SKILL.md` when a task matches, and `/skill:name args` sends it explicitly (the `/` command palette lists them). More locations go in `config.json` as `"skills": ["~/.claude/skills"]` or on the command line with `--skill PATH`; `--no-skills` skips the default locations. When two skills share a name, explicit paths beat the project's, which beat the global ones.
+
 ## Using Paimon as a subagent
 
 Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. A profile keeps that model's account separate:
@@ -99,6 +103,102 @@ Each profile keeps its model settings in `~/.config/paimon/<name>/config.json`,
 
 Read and edit modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) without asking; `--strict` turns that off. **This is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
 
+## Architecture
+
+`Agent.run` is a UI-agnostic stream of events; the TUI, `--web` and headless mode are three renderers over that one stream. `Supervisor` sits between an agent and the subagents or background commands it starts, and is the permission boundary for both.
+
+```mermaid
+flowchart TD
+    subgraph entry["Entry points"]
+        CLI["cli.py"]
+        Commands["commands.py<br/>status / login / sessions"]
+        Headless["headless.py<br/>-p, one-shot"]
+        App["app.py<br/>Textual TUI / --web"]
+    end
+
+    subgraph tui["TUI widgets"]
+        Pane["pane.py<br/>SessionPane"]
+        CommandPane["commandpane.py<br/>background command pane"]
+        Tabs["tabs.py<br/>pane strip"]
+        Login["login.py<br/>provider / model / key"]
+        UIWidgets["ui.py<br/>prompt input, confirmations"]
+        Diff["diff.py<br/>side-by-side diff rendering"]
+    end
+
+    subgraph core["Agent loop"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools.py<br/>tool REGISTRY"]
+        SessionMod["session.py<br/>JSONL persistence"]
+        Compaction["compaction.py"]
+        ModelWindows["model_windows.py<br/>context window sizes"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path expansion"]
+        Aside["aside.py<br/>off-turn question, unrecorded"]
+    end
+
+    subgraph concurrency["Jobs & subagents"]
+        Supervisor["supervisor.py<br/>job pool, permissions"]
+        Jobs["jobs.py<br/>AgentJob / CommandJob"]
+        AgentTypes["agents.py<br/>subagent types"]
+    end
+
+    subgraph support["Config & skills"]
+        Config["config.py<br/>profiles, credentials"]
+        Skills["skills.py<br/>Agent Skills discovery"]
+    end
+
+    CLI --> Commands
+    CLI --> Headless
+    CLI --> App
+    CLI --> Config
+
+    Headless --> AgentLoop
+    Headless --> Mentions
+
+    App --> Pane
+    App --> CommandPane
+    App --> Tabs
+    App --> Login
+    App --> Supervisor
+    App --> Config
+
+    Pane --> AgentLoop
+    Pane --> Aside
+    Pane --> Diff
+    Pane --> UIWidgets
+    Pane --> LLM
+    CommandPane --> Pane
+    UIWidgets --> Diff
+
+    AgentLoop --> LLM
+    AgentLoop --> PromptMod
+    AgentLoop --> ToolsMod
+    AgentLoop --> SessionMod
+    AgentLoop --> Compaction
+    AgentLoop --> Retry
+    AgentLoop --> Mentions
+    AgentLoop -. "spawn_agent / run_background" .-> Supervisor
+
+    Aside --> Retry
+    Aside --> SessionMod
+
+    PromptMod --> Skills
+    Compaction --> ModelWindows
+
+    Supervisor --> Jobs
+    Supervisor --> AgentTypes
+    Supervisor --> ToolsMod
+    Supervisor -. "launch callback" .-> App
+    Jobs --> AgentLoop
+
+    AgentTypes --> ToolsMod
+    AgentTypes --> Config
+    Skills --> Config
+    Config --> LLM
+```
+
 ## Telemetry
 
 Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.

{paimon-0.2.4 → paimon-0.2.6}/README.zh-CN.md

@@ -26,10 +26,14 @@ uvx paimon
 
 首次启动会询问 provider、模型、API base 和 key。之后输入要完成的任务即可。在提示中写 `@path/to/file` 可以把文件提供给 agent。
 
-运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 写文件或执行命令前先询问，**edit** 放行工作目录内的编辑，**yolo** 从不询问，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。
+运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 写文件或执行命令前先询问，**edit** 放行工作目录内的编辑，**yolo** 从不询问，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。以 `!` 开头的一行不发给模型，而是直接在 shell 里执行，输出 Paimon 也能看到。`!!` 则不告诉它。
 
 `Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane。Paimon 自己也能开 pane：让它同时做两件互不相干的事，它会在新 tab 里起第二个 agent。它也能把一条命令留在单独的 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
 
+## Skills
+
+Paimon 会从 `~/.config/paimon/skills`、`~/.agents/skills` 以及工作目录到仓库根之间每一层的 `.agents/skills` 加载 [Agent Skills](https://agentskills.io)。system prompt 里只放每个 skill 的名字和描述，任务匹配时模型自己去读 `SKILL.md`，也可以用 `/skill:name 参数` 显式发送（`/` 命令面板里列出了它们）。其他位置可以写进 `config.json` 的 `"skills": ["~/.claude/skills"]`，或者用命令行参数 `--skill PATH`；`--no-skills` 跳过默认位置。同名时显式指定的优先于项目的，项目的优先于全局的。
+
 ## 当作 subagent 使用
 
 前沿模型擅长制定计划和验收结果，中间的执行步骤往往比较机械。让 Paimon 使用成本较低的模型执行，由 Claude Code 或 Codex 制定计划并检查结果。用一个 profile 单独保存该模型的账号：
@@ -99,6 +103,102 @@ paimon --profile work               # 单独配置的另一个账号
 
 read 和 edit 模式会不经询问执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉。**这是防止 agent 失误的护栏，不是安全边界。** 需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
 
+## 架构
+
+`Agent.run` 产出一串与 UI 无关的事件流，TUI、`--web` 和无头模式都是这条事件流的渲染器。`Supervisor` 位于 agent 和它启动的子 agent、后台命令之间，是两者共同的权限边界。
+
+```mermaid
+flowchart TD
+    subgraph entry["入口"]
+        CLI["cli.py"]
+        Commands["commands.py<br/>status / login / sessions"]
+        Headless["headless.py<br/>-p，单次运行"]
+        App["app.py<br/>Textual TUI / --web"]
+    end
+
+    subgraph tui["TUI 组件"]
+        Pane["pane.py<br/>SessionPane"]
+        CommandPane["commandpane.py<br/>后台命令 pane"]
+        Tabs["tabs.py<br/>pane 标签栏"]
+        Login["login.py<br/>provider / 模型 / key"]
+        UIWidgets["ui.py<br/>输入框、确认面板"]
+        Diff["diff.py<br/>并排 diff 渲染"]
+    end
+
+    subgraph core["Agent 主循环"]
+        AgentLoop["agent.py<br/>Agent.run()"]
+        LLM["llm.py<br/>build_model()"]
+        PromptMod["prompt.py<br/>system prompt"]
+        ToolsMod["tools.py<br/>工具注册表"]
+        SessionMod["session.py<br/>JSONL 持久化"]
+        Compaction["compaction.py"]
+        ModelWindows["model_windows.py<br/>各模型上下文窗口大小"]
+        Retry["retry.py"]
+        Mentions["mentions.py<br/>@path 展开"]
+        Aside["aside.py<br/>回合外提问，不落盘"]
+    end
+
+    subgraph concurrency["任务与子 agent"]
+        Supervisor["supervisor.py<br/>任务池、权限"]
+        Jobs["jobs.py<br/>AgentJob / CommandJob"]
+        AgentTypes["agents.py<br/>子 agent 类型"]
+    end
+
+    subgraph support["配置与 skills"]
+        Config["config.py<br/>profile、凭证"]
+        Skills["skills.py<br/>Agent Skills 发现"]
+    end
+
+    CLI --> Commands
+    CLI --> Headless
+    CLI --> App
+    CLI --> Config
+
+    Headless --> AgentLoop
+    Headless --> Mentions
+
+    App --> Pane
+    App --> CommandPane
+    App --> Tabs
+    App --> Login
+    App --> Supervisor
+    App --> Config
+
+    Pane --> AgentLoop
+    Pane --> Aside
+    Pane --> Diff
+    Pane --> UIWidgets
+    Pane --> LLM
+    CommandPane --> Pane
+    UIWidgets --> Diff
+
+    AgentLoop --> LLM
+    AgentLoop --> PromptMod
+    AgentLoop --> ToolsMod
+    AgentLoop --> SessionMod
+    AgentLoop --> Compaction
+    AgentLoop --> Retry
+    AgentLoop --> Mentions
+    AgentLoop -. "spawn_agent / run_background" .-> Supervisor
+
+    Aside --> Retry
+    Aside --> SessionMod
+
+    PromptMod --> Skills
+    Compaction --> ModelWindows
+
+    Supervisor --> Jobs
+    Supervisor --> AgentTypes
+    Supervisor --> ToolsMod
+    Supervisor -. "启动回调" .-> App
+    Jobs --> AgentLoop
+
+    AgentTypes --> ToolsMod
+    AgentTypes --> Config
+    Skills --> Config
+    Config --> LLM
+```
+
 ## 遥测
 
 每次启动会向 Google Analytics 发送一条匿名事件：随机生成的安装 id、启动方式、版本号、操作系统名称，以及配置的 provider 和模型名。会话、提示词、文件和密钥一概不上报。设置 `PAIMON_NO_TELEMETRY=1` 或 `DO_NOT_TRACK=1` 可以关闭。

{paimon-0.2.4 → paimon-0.2.6}/paimon/agent.py

@@ -10,7 +10,7 @@ import json
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import AsyncIterator, Callable, Optional
+from typing import AsyncIterator, Callable, Optional, Sequence
 
 from pydantic_ai.direct import model_request_stream
 from pydantic_ai.messages import (
@@ -30,18 +30,22 @@ from pydantic_ai.messages import (
 )
 from pydantic_ai.models import Model, ModelRequestParameters
 
-from . import aside, compaction, retry, tools
+from . import agents, aside, compaction, retry, tools
 from .config import Config
 from .llm import NoModelError, build_model, user_agent
 from .mentions import expand_mentions
 from .prompt import build_system_prompt
+from .skills import Skill, SkillDiagnostic, discover_skills, expand_skill_command
 from .session import (
     Session,
     SessionIncompleteError,
     agents_message,
     agents_text,
     is_agents_message,
+    is_shell_message,
     is_summary_message,
+    shell_message,
+    shell_text,
 )
 
 # Transient compaction failures tolerated in one turn before it is left off.
@@ -166,13 +170,26 @@ class AgentsNotice:
     text: str
 
 
+@dataclass
+class ShellRun:
+    """A command the user ran themselves with the "!" prefix.
+
+    Like AgentsNotice this is not replay-only: the run is persisted as a
+    synthetic user message, so it is both yielded when it happens and rebuilt
+    when the session is resumed.
+    """
+
+    command: str
+    output: 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 | ToolBudgetExhausted | TurnEnd
     | ContextCompacted | ContextCompactionFailed | ModelRetry | UserInput
-    | CompactionNotice | AgentsNotice
+    | CompactionNotice | AgentsNotice | ShellRun
 )
 
 
@@ -207,6 +224,9 @@ def replay_events(messages: list[ModelMessage]) -> list[AgentEvent]:
         if is_agents_message(message):
             events.append(AgentsNotice(agents_text(message)))
             continue
+        if is_shell_message(message):
+            events.append(ShellRun(*shell_text(message)))
+            continue
         if isinstance(message, ModelRequest):
             for part in message.parts:
                 if isinstance(part, UserPromptPart) and isinstance(part.content, str) and part.content:
@@ -287,10 +307,13 @@ def _strip_foreign_thinking(history: list[ModelMessage], model: Model) -> list[M
 # Re-exported so UI code can keep importing it from here.
 ConfirmFn = tools.ConfirmFn
 
-# Takes the messages a user queued while a turn was already running, clearing
-# the queue as it goes. The loop calls it before every model request, so what
-# it returns reaches the model at the next step rather than the next turn.
-PendingFn = Callable[[], list[str]]
+# Takes what the user queued while a turn was already running, clearing the
+# queue as it goes. The loop calls it before every model request, so what it
+# returns reaches the model at the next step rather than the next turn. A
+# plain string is a typed prompt and goes through the usual expansion; a
+# ready-made request is one paimon assembled (a "!" shell run) and is appended
+# verbatim, since @path in a command's output is output, not a mention.
+PendingFn = Callable[[], list[str | ModelRequest]]
 
 
 class Agent:
@@ -312,8 +335,20 @@ class Agent:
                  confirm: Optional[ConfirmFn] = None, mode: str = "yolo",
                  config: Optional[Config] = None,
                  toolset: Optional[dict[str, tools.Tool]] = None,
-                 model_override: Optional[str] = None):
+                 model_override: Optional[str] = None,
+                 skills: Sequence[Skill] = (),
+                 skill_diagnostics: Sequence[SkillDiagnostic] = (),
+                 agent_types: Sequence[agents.AgentType] = (),
+                 agent_type_diagnostics: Sequence[SkillDiagnostic] = ()):
         self.cwd = Path(cwd or Path.cwd())
+        # The skills listed in the system prompt and expandable by /skill:name,
+        # with whatever discovery had to complain about (for the UI to show).
+        self.skills = list(skills)
+        self.skill_diagnostics = list(skill_diagnostics)
+        # The agent types spawn_agent may name, discovered like skills; the
+        # launcher reads them off whoever called spawn_agent.
+        self.agent_types = list(agent_types)
+        self.agent_type_diagnostics = list(agent_type_diagnostics)
         self.confirm = confirm
         self.mode = mode
         self.config = config or Config.load()
@@ -339,6 +374,12 @@ class Agent:
         self.history: list[ModelMessage] = session.messages()
         # This agent's tool set; None means everything in tools.REGISTRY.
         self.toolset = dict(tools.REGISTRY if toolset is None else toolset)
+        # The registry's spawn_agent knows no types; this agent's copy lists
+        # the ones it discovered, so the schema below advertises them. A
+        # toolset without spawn_agent (subagents, headless) skips it whole.
+        if "spawn_agent" in self.toolset and self.agent_types:
+            self.toolset["spawn_agent"] = agents.spawn_tool_with_types(
+                self.toolset["spawn_agent"], self.agent_types)
         self.tool_schemas = tools.schemas(self.toolset)
         self._tool_definitions = tools.definitions(self.toolset)
         self._cached_model: Optional[tuple[tuple, Model]] = None
@@ -356,19 +397,23 @@ class Agent:
              append_system_prompt: Optional[str] = None,
              toolset: Optional[dict[str, tools.Tool]] = None,
              model_override: Optional[str] = None,
-             parent: Optional[str] = None) -> "Agent":
+             parent_session_id: Optional[str] = None,
+             agent_type: 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 role is immutable.
-        The dynamic parts of the prompt (date, environment, AGENTS.md) are
-        rebuilt on resume — a session picked up months later must not keep
-        telling the model the old date or stale project rules — and when they
-        changed, the rebuilt snapshot is appended to the log, so it always
-        records the prompt each turn actually ran with.
-        ``parent`` marks the new session as a subagent's, which keeps it out of
-        the session listings its parent shows up in.
+        The dynamic parts of the prompt (date, environment, AGENTS.md, the
+        skill list) are rebuilt on resume — a session picked up months later
+        must not keep telling the model the old date or stale project rules —
+        and when they changed, the rebuilt snapshot is appended to the log, so
+        it always records the prompt each turn actually ran with.
+        ``parent_session_id`` marks the new session as a subagent's, which
+        keeps it out of the session listings its parent shows up in;
+        ``agent_type`` records what type it was spawned as, so resuming the
+        session can restore the type's narrowing. Both apply to new sessions
+        only and are ignored on resume, where the header already says.
 
         Raises ``SessionBusyError`` when the session is already open (here or
         in another process) and ``SessionIncompleteError`` when a resumed log
@@ -378,9 +423,14 @@ class Agent:
         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")
+        config = config or Config.load()
+        skills, skill_diagnostics = discover_skills(
+            cwd, extra_paths=config.skills, include_defaults=config.include_default_skills)
+        agent_types, agent_type_diagnostics = agents.discover_agent_types(
+            cwd, extra_paths=config.agents, include_defaults=config.include_default_agents)
         is_new = session is None
         if session is None:
-            session = Session.create(cwd, parent)
+            session = Session.create(cwd, parent_session_id, agent_type)
         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
@@ -388,7 +438,7 @@ class Agent:
         try:
             if is_new:
                 appended = append_system_prompt.strip() if append_system_prompt else None
-                system_prompt = build_system_prompt(cwd)
+                system_prompt = build_system_prompt(cwd, skills)
                 if appended:
                     system_prompt += f"\n\n{appended}"
                 session.append_system_prompt(system_prompt, appended=appended)
@@ -397,13 +447,16 @@ class Agent:
                 stored, appended = session.system_prompt_parts()
                 if stored is None:
                     raise SessionIncompleteError("Session does not contain a persisted system prompt")
-                system_prompt = build_system_prompt(cwd)
+                system_prompt = build_system_prompt(cwd, skills)
                 if appended:
                     system_prompt += f"\n\n{appended}"
                 if system_prompt != stored:
                     session.append_system_prompt(system_prompt, appended=appended)
             return cls(session, system_prompt, cwd=cwd, confirm=confirm, mode=mode,
-                       config=config, toolset=toolset, model_override=model_override)
+                       config=config, toolset=toolset, model_override=model_override,
+                       skills=skills, skill_diagnostics=skill_diagnostics,
+                       agent_types=agent_types,
+                       agent_type_diagnostics=agent_type_diagnostics)
         except BaseException:
             session.unlock()
             raise
@@ -554,6 +607,27 @@ class Agent:
                                         max_tokens=max_tokens):
             yield delta
 
+    # ---- Commands the user runs themselves ---------------------------------
+
+    async def run_shell(self, command: str) -> str:
+        """Run a shell command on the user's behalf and return what it printed.
+
+        The TUI's "!" prefix. No permission gate: the gate exists so the model
+        cannot run something the user did not ask for, and here the user *is*
+        the one asking. Nothing is recorded — the caller decides whether the
+        run reaches the model now or at the running turn's next step.
+        """
+        return await tools.user_shell(command, self.cwd, self.tool_context)
+
+    def record_shell(self, command: str, output: str) -> None:
+        """Persist a "!" run so the model sees what the user just did.
+
+        Only between turns. While one is running the message belongs in the
+        pending queue instead, which the loop drains between steps — appended
+        here it would land between a tool call and its result.
+        """
+        self._append_message(shell_message(command, output))
+
     # ---- Tools the agent loop runs itself ----------------------------------
     # These mutate agent-held state or end the turn, so they cannot go through
     # the stateless tools.run_tool. Each handler fills ``slot`` with the tool
@@ -659,10 +733,25 @@ class Agent:
         "stop_job": _run_supervised,
     }
 
-    async def run(self, user_input: str, *, expand: bool = True,
+    def expand_input(self, text: str) -> str:
+        """What a typed message becomes: a /skill:name command expands to the
+        skill's content, then @path mentions are inlined."""
+        def mentions(part: str) -> str:
+            return expand_mentions(part, self.cwd)
+
+        expanded = expand_skill_command(text, self.skills, expand_args=mentions)
+        # Unchanged (the same object back) means it was not a skill command.
+        return mentions(text) if expanded is text else expanded
+
+    async def run(self, user_input: Optional[str], *, expand: bool = True,
                   max_tool_calls: Optional[int] = None) -> AsyncIterator[AgentEvent]:
         """Run one user turn to completion, yielding events along the way.
 
+        ``user_input`` may be None: a wake-up turn, run so the model reacts to
+        agents that finished — the status line injected below is its only new
+        input. When there is nothing to report either, the turn never happened:
+        no events, nothing persisted, no model request.
+
         ``expand=False`` skips @path expansion, for callers that assembled the
         prompt themselves and must not have unrelated text rewritten (piped
         stdin, where a line like ``@foo.py`` is data rather than a mention).
@@ -674,16 +763,19 @@ class Agent:
         an explicit refusal persisted as its result, ToolBudgetExhausted is
         yielded and the turn ends.
         """
-        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 user_input is None and not summary:
+            return
         if summary:
             self._append_message(agents_message(summary))
             yield AgentsNotice(summary)
-        self._append_message(ModelRequest(parts=[UserPromptPart(content=prompt)]))
+        if user_input is not None:
+            prompt = self.expand_input(user_input) if expand else user_input
+            self._append_message(ModelRequest(parts=[UserPromptPart(content=prompt)]))
 
         # Every turn leaves exactly one terminal ``turn_end`` record in the
         # session: success, error (with the exception), max_tool_calls or
@@ -742,8 +834,16 @@ class Agent:
             # results already recorded. Before compaction, so they count
             # towards the context check and survive a history replacement.
             for queued in (self.pending() if self.pending is not None else []):
+                # A ready-made request is one the caller already showed the
+                # user (a "!" run, whose output was on screen the moment the
+                # command exited), so it is appended without an event of its
+                # own — and without expansion, since @path in a command's
+                # output is output rather than a mention.
+                if isinstance(queued, ModelRequest):
+                    self._append_message(queued)
+                    continue
                 self._append_message(ModelRequest(
-                    parts=[UserPromptPart(content=expand_mentions(queued, self.cwd))]))
+                    parts=[UserPromptPart(content=self.expand_input(queued))]))
                 yield UserInput(queued)
 
             if not compaction_off: