用途：pi 将 Pi 编码智能体 API 封装为 iii 函数，用于在任意主机目录上执行无头编码任务，包括文件编辑、shell 与搜索。一次 pi::run 调用执行一轮 Pi 回合，运行与终端 Pi 相同的进程内智能体循环和相同工具（read、bash、edit、write），返回最终结果、token 用量与成本。Pi 发出的每个事件原样镜像到 pi::events 流，翻译后的 AgentEvent 视图进入 agent::events，供 iii 控制台与 acp worker 渲染。
主要能力：pi::run 执行一轮并等待，接受 prompt（或 messages 数组，最后一条用户消息作为提示），以及 model、cwd、thinking_level、tools、iii_context，返回 {session_id, pi_session_id, result, stop_reason, usage, total_cost_usd}。pi::start 立即返回 {session_id, started}，进度通过流获取。pi::steer 向运行中的任务注入指令，在当前工具调用完成后生效；pi::follow_up 排队一条消息，在智能体本应停止后处理；pi::stop 中断会话的实时运行；pi::status 返回会话即时视图（live 标志、状态、轮次、用量、成本）；pi::sessions::list 列出该 worker 运行过的所有会话；run::start_and_wait 是 pi::run 的别名，供控制台与 acp worker 驱动。
使用方式：通过同一 session_id 可跨调用继续对话，worker 会恢复底层 Pi 会话文件并保留完整上下文。长任务可用 pi::start 不阻塞调用，随后跟踪 pi::events（group_id = session_id）获取原始进度，或 agent::events 获取渲染视图，并用 pi::stop 中断。回合默认携带 iii 运行时上下文，智能体可通过 iii CLI 发现并调用任何已注册函数（engine::functions::list、iii trigger <fn> --help），可用 iii_context: false 按回合禁用。thinking_level（off 到 xhigh）设置推理强度，tools 将活动工具集限制为允许列表。
限制：Pi 在进程内运行循环（无 CLI 子进程），因此需要 worker 环境中有模型凭据（如 ANTHROPIC_API_KEY）或已有 Pi 登录，否则回合在首次模型请求时失败。工具执行发生在 Pi 自身工具集内，而非引擎权限模型；pi::run / pi::start 未经人工批准不可被智能体调用（见 iii-permissions.yaml）。每个会话同一时间只能有一轮：发送另一轮前先检查 pi::status（live: true），并行运行同一会话会在底层会话文件上产生竞争。agent::events 携带整消息帧（message_complete、function_execution_start/end、turn_end、agent_end），原始 Pi 事件形态（含 message_update 的 token 增量）位于 pi::events。