编码智能体 CLI：工具、会话树、压缩、扩展与运行模式Coding agent CLI with read, bash, edit, write tools and session management
← → 翻页 · F 全屏 · O 目录 · T 明暗 · L 语言← → navigate · F fullscreen · O overview · T theme · L language
resolveAppMode() 同时看参数和 stdin/stdout 是否为 TTY：-p、或 stdin / stdout 任一不是 TTY 时走 print，--mode json / --mode rpc 显式指定。resolveAppMode() looks at both args and whether stdin/stdout are TTYs: -p, or a non-TTY stdin or stdout, means print; --mode json / --mode rpc are explicit.
_handleAgentEvent），所以扩展总能先看到并改写。Events reach extensions before UI listeners (_handleAgentEvent), so extensions always see and rewrite first._handlePostAgentRun() 决定是否再跑一次：可重试错误 → 退避重试；超出上下文或超过阈值 → 压缩；还有排队消息 → continue()。After a run, _handlePostAgentRun() decides whether to go again: retryable error → back off and retry; context overflow or over threshold → compact; queued messages → continue().session_before_switch / session_before_fork 返回 { cancel: true } 时，整个替换中止，方法返回 { cancelled: true }。If session_before_switch / session_before_fork returns { cancel: true }, the replacement stops and the method returns { cancelled: true }.
read 从头截断（truncateHead），bash 从尾截断（truncateTail）——命令最后的输出通常最重要。read truncates from the head (truncateHead), bash from the tail (truncateTail) — the end of a command's output usually matters most.
~/.pi/agent/sessions/ 下，文件名带时间戳与 UUIDv7。Files live under ~/.pi/agent/sessions/, one directory per cwd, named with a timestamp and a UUIDv7.wx 标志，避免并发覆盖。Writes are lazy: nothing hits disk before the first user or assistant message, and the first write uses the wx flag to avoid clobbering.ctx：ExtensionContext 有 18 个成员（cwd、模型、会话、ui …），命令处理器拿到的 ExtensionCommandContext 还能新建 / 分叉 / 切换会话。Every handler's second argument is ctx: ExtensionContext has 18 members (cwd, model, session, ui …); command handlers get ExtensionCommandContext, which can also create / fork / switch sessions.ctx.ui 有 28 个成员：对话框、通知、状态栏、widget、自定义组件；在 RPC 模式下它们变成 extension_ui_request。ctx.ui has 28 members: dialogs, notifications, status, widgets, custom components; in RPC mode they become extension_ui_requests.prompt 不等运行结束：预检通过就回响应（带 disposition），之后的一切以事件到达。prompt does not wait for the run: it responds once preflight passes (with a disposition), and everything after arrives as events.extension_ui_request，宿主用同一个 id 回 extension_ui_response；通知类请求不需要回答。Extension UI that needs an answer (select / confirm / input / editor) emits an extension_ui_request; the host replies with an extension_ui_response carrying the same id. Notification-style requests need no answer.deepMergeSettings(global, project)：项目值覆盖全局值，嵌套对象逐键合并。deepMergeSettings(global, project): project values win, nested objects merge key by key.
增加模型可调用的工具，与内置工具并列。Add tools the model can call, alongside the built-ins.
41 种事件，18 种可返回结果来改写或拦截。41 events; 18 can return a result to rewrite or intercept.
斜杠命令与快捷键。Slash commands and keyboard shortcuts.
接入新的模型 provider 或虚拟模型路由。Add model providers or virtual-model routing.
在 TUI 中放入自定义组件。Put custom components into the TUI.