@tea-agent/loop-agent 0.42.1 → 0.43.0-next.10

package/CHANGELOG.md

@@ -2,19 +2,79 @@
 
 ## [Unreleased]
 
+### 改进
+
+- 前端 Plan 普通分片按本批完整需求材料打包，固定提示词、用户消息和工具定义不再挤占 24 KB 分片目标，也不再触发发送前的机械二分，减少小需求逐 AC 会话；实际模型容量检查与超限恢复继续生效。
+
+- 前端 Plan 小任务合并规划不再受固定 48 KB 输入门槛限制，避免提示词、用户消息或工具定义变长导致额外分片；完整输入、其余任务规模条件及容量恢复机制保持不变。
+- 节点侧栏修复执行分次下拉菜单被执行记录工具栏遮挡的问题，直接展示所选失败尝试的简要原因，并移除重复的左右切换箭头。
+- Operator Chat 的 Pi Runtime 按职责拆出工具构造、运行态检视和 SDK 适配，并共用创建/恢复/分叉的会话准备流程；对外入口、错误类型和会话行为保持不变。
+
 ## [0.42.1] - 2026-09-09
 
 ### 新增
 
-- 新增了本发布周期内已经完成并通过验证的功能。
+- Operator Chat 浏览器面板（DSH 风格）：Console 右侧辅助栏新增「浏览器」tab——地址栏（自动补 https、仅 http/https、禁止 javascript/data/file 等危险协议与本机回环地址）、后退/前进/刷新导航栈、系统浏览器跳转；页面运行在无 same-origin、无 top-navigation 的沙箱 iframe 中（访问的页面拿不到 Console 的存储与 API），沙箱状态条支持单页面临时解锁（红色警示 + 一键恢复）；对拒绝被嵌入的站点（X-Frame-Options / frame-ancestors）给出明确解释面板与「在系统浏览器打开 / 仍要加载」出口，探测端点仅返回响应头、仅限 http(s) 非回环、8 秒硬超时。
+- Operator Chat 源代码管理（DSH 风格）：模型获得 `scm` 工具（status/diff/stage/unstage/discard/commit/log/branch/push/pull，固定参数 git 无 shell、限时限量输出）；Console 右侧辅助栏新增「源码」面板（DSH GitView 布局——分支下拉切换、已暂存/更改分组与全部暂存/取消暂存、单行提交框 Ctrl+Enter、内联分页历史带 refs 徽标与相对时间、点击文件看 diff、右键菜单放弃更改/复制路径）；模型与面板共用同一工作区级 ScmService。
+- Operator Chat 在具备 Aimax 凭据资格时，向对话进程注入 `$AIMAX_AUTH_TOKEN`（明文或 `sm4:v1:` 解密后的 ticket），供 skills 读取；文件缺失、无法解析或解密失败时不注入该变量。
+- Operator Chat 终端管理（DSH 风格）：模型获得 `terminal` 持久 PTY 工具（跨平台 shell 目录——Windows 提供 powershell/bash/cmd，macOS/Linux 提供 bash/zsh，pwsh 7 装了即用；cwd/环境变量/后台任务跨调用保留，完成标记协议 + 超时与截断保护，枚举与默认值按平台动态生成）；Console 右侧辅助栏新增「终端」面板（xterm.js 渲染，实时查看/接管模型的 shell，按平台动态展示可创建的 shell，支持发送输入、Ctrl+C、终止并关闭）；模型 shell 与用户面板共用同一会话注册表并开在工作区仓库根目录，命名区分来源。
+- Windows 原生 `cmd.exe` 终端体验补全：仅 Windows 平台提供 `cmd` shell，使用经典 `C:\path>` 提示符、cmd 黑底浅灰配色与方块光标，并补回 ConPTY 丢失的 `Microsoft Windows [版本 …]` 启动横幅；bash 与 PowerShell 保持各自原生输出，不注入 Windows 横幅。
+- Operator Chat 详情栏调整：「源码」tab 紧邻「文件」tab，便于在文件预览与源码管理之间快速切换。
 
 ### 改进
 
-- 完善了日常使用体验和运行稳定性。
+- 修复前端设计评审与实施评审遗漏 `complete_review_scope` 工具权限，导致模型无法完成分段确认、最终评审反复被拒绝的问题；补充真实 Pi SDK 工具激活与分段收口回归验证。
+
+- 对话正文与 Human Gate、任务活动和产物卡片统一绑定会话所属工作区；修正旧式任务／运行链接，只有操作编号时查询真实记录再定位，工作区冲突或记录缺失时明确提示，避免误入其他工作区或总览。
+
+- 节点侧栏在首次原始运行中隐藏「来源与影响」，派生运行保留该入口；打开运行中节点默认定位到「执行记录」，手动选择和明确的链接位置在刷新时保持。
+
+- 修复前端契约可选字段未填写时，评审分片索引引用不存在字段、导致设计评审启动前失败的问题。分片生成跳过 undefined；读取端明确拒绝缺失字段、无效引用、重复或非法范围及未索引内容，保留合法空数组和 JSON 空值。
+
+- Operator Chat 侧栏「添加工作区」图标改为与 DSH 一致的文件夹加号，不再用纯加号。
+- Operator Chat 侧栏改为单一「新会话」；空白会话在输入框上方用芯片选择工作区和模式（工作流 / Pi），有历史后芯片收起。不再用落地页双卡或「新 Pi」按钮；换模式会复用或新建对应空白会话，不会改已有会话的模式。
+- 修复模型续跑取消后带部分文字仍被标记成功的问题；前端 Plan 的取消、认证、限流及策略失败优先于容量恢复，精确格式错误保留原修复路径。完整性检查按需求建立单次索引，减少大计划重复扫描，同时拆分纯检查与恢复策略模块。
+- 长会话中的输入框不再因历史消息和工具记录增多而逐键重绘整段会话，输入与自动增高在低性能电脑上更流畅。
+- 优化 Operator Chat 长会话的流式渲染：完成回合、消息行、工具卡和用户输入锚点建立稳定的 memo 边界，流式文本更新不再重复渲染整段历史或重装锚点测量监听；缓存会在历史消息或工具实际更新时正确失效；无新增折叠回合时不再提交空状态及重复写入本地存储，工具参数与结果格式化按真实输入变化缓存。
+- 对话页「过程折叠」对齐 DSH 细节：模型回复完成时直接进入折叠态，不再先展开再跳动；折叠摘要、过程内容和最终回答采用与 DSH 一致的间距，折叠内容仍保留在页面中，浏览器 Ctrl+F 可直接命中并自动展开；折叠行展开时不再多出底部空隙；箭头改为 16px、颜色更淡的固定图标（靠旋转而非换图标），并补齐系统「减少动态效果」偏好；汇总文案新增「N 个 subagent」，内置 Explore 子代理不再计入普通工具调用。
+- 恢复前端 Plan 实时事实分页读取、逐需求 UX 遗漏检查与已完成范围复用；超限时补齐剩余验证目标，并接通 DAG 到 SDK 的原会话续跑。局部状态修改保留其他需求的关联，沿用耐久账本、显式替换和冻结分片边界。
+
+- DAG 的 Pi SDK 节点遇到 `stopReason=length` 时，先在原会话内最多续跑 3 次，保留已完成写入和事实，成功恢复不消耗额外节点重试次数；共享原超时与上下文预算，已成功提交终态时不重复续跑，耗尽后才进入原有缩片或重试路径。
+- 修复前端 Design Review 成功后可能清空原 Plan 账本的问题，撤回未接通合同校验和物化的修订工具；同时移除误加在实施后 Review 的修订指令。Review 节点内局部修订尚未实现，设计缺陷仍走原有拒绝与恢复流程。
+- 前端 Plan 输出超限后按已提交事实续跑：带部分结果或网关诊断也会保留进度，自动缩小剩余需求；单个过大需求进一步按缺失事实逐项恢复，并在恢复耗尽时输出剩余范围。
+- 大需求前端 Plan 增加可分页的实时事实读取，保留长标识和跨批验收绑定；UX 按有限需求范围执行，重试复用完整批次和全局命名表，逐需求检查遗漏。冻结交付文件超过单 writer 容量时在 Contract 后提前识别拆分需求；自动子任务执行链路尚未接通，此项不代表自动拆分已可用。
+
+- 前端 DAG 修正否定约束导致的小任务误升级；Plan 在分片前统一 compact 判定并保留完整执行组。支持冻结 coverage 并发上限（1–4，默认 4），限流后减少后续并发且不增加重试。自动恢复子进程与 DAG 共用长跑超时，避免继承通用 120 秒上限而中途终止。
+- 前端 DAG 保留完整需求并按作用域/执行组分批，工具提交改为先校验和耐久保存再回执；支持按组共享覆盖、逐端点/逐 finding 提交和缺项恢复。小任务走短流程，容量耗尽直接缩小剩余工作；模型窗口不再硬编码为 100K/16K。独立 AC、来源保真与 writer/verify 门禁保持有效。
+- 观测台阅读与口径修补：失败节点的产出页把「错误输出」提到正文之前，未登记文件关系时不再展示空文件卡；检查器 Tab 条放不下时两端渐隐提示并保证选中 Tab 可见，每页顶部说明卡可收起。异常 Task 的分类与建议跟进显示中文业务术语（未知 token 原样透传并可悬停看原始值），资源池「合计」改为口径明确的「已建 Task」并附悬停说明，数据更新文案改为「数据更新于 … · 仅提示」。DAG 详情面包屑使用可读运行标题（缺失回退运行 ID、窄屏截断），「记录保存位置」移入「诊断信息」折叠区，页面刷新按钮与标题同行靠右。
+- 观测台保留检查器 Tab 导航，日志分类收进下拉框，辅助操作改为带提示的图标；所有执行记录区域（检查器执行记录/产出、运行页最新输出）统一配备对话式「回到底部」悬浮按钮：内容可滚动且视口离开底部即出现，贴底或内容不足一屏时隐藏，点击回到底部；活跃运行同时恢复跟随并提示未读条数，终态运行同样可用。执行分次仅在相关页面固定显示，上翻暂停跟随，并记住分次阅读位置。补充日志搜索、错误过滤、图定位和完整脱敏文本下载。
+- 实际上下文改为中文材料目录优先、技术信息折叠；修复历史轮次混读当前上下文和旧请求覆盖新尝试的问题。保留仅看错误与原始协议事件，原始协议使用直接可达的图标开关，移除单项更多菜单和日志 HTML 导出；交接包明确固定来源并支持刷新。
+- 检查器隐藏无内容或明确不适用的入口：单次执行不显示尝试对比，Shell/静态节点不显示实际上下文，静态节点不显示执行记录；切换节点与新增尝试时自动更新，保留用户当前的比较选择。
+- 资源池筛选覆盖任务标题和全部任务区域，返回列表及历史分页保留阅读状态；重跑草稿和影响预览可恢复，结果不确定时原样重试已确认的请求，避免重复创建运行。
+- 执行记录默认跟随最新内容；上翻自动暂停并出现对话式「回到底部」按钮，点击回到底部；历史记录保留阅读位置，终态运行同样可用。
+- DAG 节点检查器仅对最新且仍运行的执行默认跟随；右下角显示阅读状态、新记录提示和“回到最新”，上翻即暂停。
 
 ### 修复
 
-- 修复了影响使用体验或运行稳定性的问题。
+- 悬停或打开会话「更多」菜单时，Pi / 工作流徽章与相对时间一并让出，避免被三个点按钮盖住。
+- 修复点「新 Pi」后一发消息侧栏就变成「工作流」：全局会话列表和点进会话时漏了 `sessionMode`，缺省被当成工作流。
+- 修复手动压缩上下文后，长会话会清空并重复绘制大量历史内容的问题；压缩结果现在会直接在当前消息流中更新，不再触发整段会话重载。
+- 修复对话页存在运行活动时，收起状态的右侧辅助栏展开按钮覆盖「运行活动 N」及数字徽标的问题；中大尺寸布局现在保留 8px 操作间距，窄屏布局不变。
+- 修复 Operator Chat 消息流的六处实际使用问题：
+  - **回复被吞**：断线/重连（含每 25 秒的 SSE 事件窗口轮转）后，保留事件里已经生成的正文会在事件流恢复时重新应用到对应回合，不再被静默丢弃；仅当该回合已有更新内容时才跳过，避免重复气泡。
+  - **用户输入消失或重复**：新消息发送后会在每一帧模型输出中持续显示，不再等回复结束才重新出现；服务端确认后，提交回滚（排队抢占、被拒绝、连接失败）不再删掉已确认的消息；确认帧到达时会原地合并临时消息与会话快照，不再重复显示同一条输入。
+  - **回复重复**：上下文溢出自动压缩并重新生成后，被打断的旧回复会被取代，不再与重新生成的回复同时显示。
+  - **只有思考没有正文**：模型回复以工具调用或思考结尾时，正文会作为回答显示，不再被折叠进「过程」区。
+  - **空气泡误删**：只包含思考或工具内容、正文为空的回合不再被清理掉。
+  - **停止语义**：被停止中断的工具调用显示「已停止」，不再显示为「出错」并强制展开、计入「N 次出错」。
+
+- 任务成功与收尾只认可匹配当前契约版本和哈希的运行；更新需求后重新审查 gate，旧成功记录不再阻止新运行。需求独立审核接受 `revision: null` 表示无修订，保留拒绝结论和身份校验；相同角色、相同内容的 PRD 重复导入复用不可变引用，不再重复增加副本或无故推进契约版本。
+
+- 前端 Plan 重试复用首次冻结的分片归属，避免重试提示词变长导致进度绑定不匹配或重复处理已完成需求；布局缺失、损坏或漂移时保留证据并阻断派发。风险路由仅忽略完整的范围排除声明，条件句和嵌套否定中的真实权限风险在生成期与运行期均保持升级。
+- 执行记录搜索直接高亮命中文字，标识当前跳转记录；未搜索或无匹配时禁用上下箭头，清空搜索恢复原文。
+
+- 恢复运行在导入节点缺少明确读取范围时阻断工作区漂移，避免复用受变更影响的旧结果；读取范围明确且不受影响时仍可按路径复用。
+- 前端验证将子目录执行的 Vitest 报告统一为仓库相对路径，并对齐实际目录别名，避免已通过测试被误判为未执行；被筛除或失败的目标仍阻断。
 
 ## [0.42.0] - 2026-09-07
 

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.42.1",
-  "gitSha": "c5b2a591968093ab6ec1b62d7be6fc6c02b4ade7",
-  "builtAt": "2026-09-09T13:13:47.201Z"
+  "version": "0.43.0-next.10",
+  "gitSha": "a57ccda19e1372045d03071a01e7e6df1be2e942",
+  "builtAt": "2026-09-10T04:37:15.842Z"
 }

package/dist/executors/dag-pi-executor.js

@@ -4512,16 +4512,18 @@ function buildFrontendPlanWorkload(input) {
     const workCost = (ids) => 1 + ids.reduce((total, id) => total + Math.max(1, (input.requirementCosts?.get(id) ?? 2) - 1), 0);
     const policy = input.sessionOptions.frontendExecutionPolicy;
     const targetBytes = policy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES;
-    const userMessageBytes = Buffer.byteLength(input.sessionOptions.userMessage ?? "");
     const buildWorkBatches = (ids) => {
         const work = workGroups.flatMap((g, index) => {
             const members = g.requirementIds.filter(id => ids.includes(id));
             return members.length ? [{ id: `${index}:${g.id}`, requirementIds: members,
                     requirements: members.map(id => fullUnits.get(id) ?? { id }), estimatedCalls: workCost(members) }] : [];
         });
-        const scaffoldBytes = Buffer.byteLength(input.basePrompt.replace(/<frontend_plan_input>[\s\S]*?<\/frontend_plan_input>/, JSON.stringify({ ...compiledInput, requirements: [] }))) + userMessageBytes + Buffer.byteLength(JSON.stringify(input.coverageTools));
+        // Pack complete work units, not the repeated request scaffold. Deducting
+        // fixed context/tools can leave a one-byte budget and force one AC per
+        // session without reducing that overhead. The SDK checks the actual
+        // request against model capacity; capacity recovery splits unfinished work.
         return packFrontendInputUnits(work, {
-            targetBytes: Math.max(1, targetBytes - scaffoldBytes),
+            targetBytes,
             maxUnits: policy?.maxScopeUnits ?? 4,
             maxCost: FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS, cost: g => g.estimatedCalls,
         }).map(batch => batch.flatMap(g => g.requirementIds));
@@ -4533,7 +4535,6 @@ function buildFrontendPlanWorkload(input) {
         frozenInput, workGroups, buildWorkBatches,
         compactEligible: input.requirementCosts !== undefined &&
             workGroups.length <= FRONTEND_PLAN_SMALL_MAX_REQUIREMENTS &&
-            Buffer.byteLength(input.basePrompt) + userMessageBytes + Buffer.byteLength(JSON.stringify(input.allTools)) <= targetBytes * 2 &&
             workGroups.reduce((total, group) => total + workCost(group.requirementIds), 0) <= FRONTEND_PLAN_SMALL_MAX_ESTIMATED_CALLS &&
             countFrontendPlanTargetSurfaces(input.basePrompt) === 1,
     };
@@ -4785,8 +4786,6 @@ export async function runFrontendPlanSegmentedSessions(input) {
     const { workGroups, buildWorkBatches, compactEligible } = buildFrontendPlanWorkload({
         basePrompt: input.basePrompt, requirementIds: allRequirementIds,
         requirementCosts: input.requirementCosts, sessionOptions: input.sessionOptions,
-        coverageTools: input.segmentCustomTools(coverageSegment.toolNames),
-        allTools: input.segmentCustomTools(null),
     });
     // Small, single-surface requests do not benefit from six isolated Pi
     // sessions. Keep the typed ledger as the authority, but let one local
@@ -4971,17 +4970,6 @@ export async function runFrontendPlanSegmentedSessions(input) {
             "state-flow": "record_state_flow", "data-flow": "record_data_flow", "mock-api": "record_mock_api",
         };
         const customTools = input.segmentCustomTools(atomicFocus ? new Set([atomicTools[atomicFocus.kind]]) : session.toolNames);
-        const scopeForPacking = session.coverageSlice ?? session.requirementSlice;
-        const envelopeBytes = Buffer.byteLength(prompt) + Buffer.byteLength(input.sessionOptions.userMessage ?? "") + Buffer.byteLength(JSON.stringify(customTools));
-        if (envelopeBytes > (input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES) && scopeForPacking && session.id !== "compact-local") {
-            const groups = workGroups.map(g => g.requirementIds.filter(id => scopeForPacking.includes(id))).filter(g => g.length);
-            if (groups.length > 1) {
-                const half = Math.ceil(groups.length / 2);
-                queue.splice(index, 1, ...[groups.slice(0, half).flat(), groups.slice(half).flat()].map(slice => ({ ...session, ...(session.coverageOnly ? { coverageSlice: slice } : { requirementSlice: slice }) })));
-                invocationCount -= 1;
-                continue;
-            }
-        }
         const result = await observeFrontendSession({
             ...input.observation, phase: `plan/${session.id}`, scopeIds: session.requirementSlice ?? session.coverageSlice ?? allRequirementIds,
             prompt, userMessage: input.sessionOptions.userMessage, customTools, committedCount: input.committedFactCount, durableCommittedCount: () => lastDurableCount,
@@ -6088,12 +6076,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 flushLedger: () => options.ledgerTools.flush(),
             });
             if (planRequirementIds.length > 1) {
-                const coverageTools = FRONTEND_PLAN_SEGMENTS.find(segment => segment.id === "coverage").toolNames;
                 const workload = buildFrontendPlanWorkload({
                     basePrompt: input.prompt, requirementIds: planRequirementIds,
                     requirementCosts: planRequirementCosts, sessionOptions: piSessionOptions,
-                    allTools: planLedgerTools.customTools,
-                    coverageTools: planLedgerTools.customTools.filter(tool => isRecordObject(tool) && coverageTools.has(String(tool.name))),
                 });
                 let coverageBatches;
                 try {

package/dist/worker/console/chat/pi-runtime/custom-tools/ask-user-question.js

@@ -0,0 +1,44 @@
+/**
+ * Session-bound ask_user_question custom tool.
+ * ConsolePiRuntime supplies the sessionId and UserQuestionRegistry.
+ */
+const ASK_USER_QUESTION_DESCRIPTION = "Ask the user concise questions when a confirmation, choice, or missing detail is required before proceeding. " +
+    "The tool pauses until the user answers. Use it instead of writing questions as ordinary assistant text. " +
+    "Send one or more questions with stable ids; recommended options should be first and end with (Recommended).";
+export async function buildAskUserQuestionTool(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    return defineTool({
+        name: "ask_user_question",
+        label: "Ask user",
+        description: ASK_USER_QUESTION_DESCRIPTION,
+        promptSnippet: ASK_USER_QUESTION_DESCRIPTION,
+        parameters: Type.Object({
+            questions: Type.Array(Type.Object({
+                id: Type.String({ description: "Stable question id echoed in the answer." }),
+                question: Type.String({ description: "Specific user-facing question." }),
+                header: Type.Optional(Type.String({ description: "Optional short heading." })),
+                detail: Type.Optional(Type.String({ description: "Optional Markdown context shown below the question." })),
+                options: Type.Optional(Type.Array(Type.Object({
+                    label: Type.String({ description: "Short user-facing option label." }),
+                    description: Type.Optional(Type.String({ description: "One sentence explaining impact or tradeoff." })),
+                }, { additionalProperties: false }))),
+                multi_select: Type.Optional(Type.Boolean({ description: "Allow more than one option." })),
+            }, { additionalProperties: false }), { minItems: 1, maxItems: 20 }),
+        }, { additionalProperties: false }),
+        async execute(toolCallId, params, signal) {
+            const answer = await options.registry.ask({
+                sessionId: options.sessionId,
+                toolCallId,
+                questions: params.questions,
+                signal,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(answer) }],
+                details: answer,
+            };
+        },
+    });
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/explore-tools.js

@@ -0,0 +1,202 @@
+/**
+ * Session-less safe explore custom tools (safe-read / safe-grep / git-status /
+ * git-diff). Execution uses explore-tools.ts path guards and secret scrubbing.
+ * ConsolePiRuntime owns the sessionless cache.
+ */
+/**
+ * Build the safe explore custom tools (roadmap M0-A / G16): safe-read,
+ * safe-grep, gitStatus, gitDiff. These replace the bare SDK bash/read/grep so
+ * the model can probe the repo WITHOUT write escapes (echo redirect, tee,
+ * sed -i, node -e) and WITHOUT reading sensitive files (env files, key/pem,
+ * auth.json, sessions dir) — and every returned byte is secret-scrubbed
+ * before reaching the model context.
+ *
+ * gitStatus/gitDiff use a FIXED argv (typed, no shell) so they cannot be
+ * turned into an arbitrary-shell vector.
+ */
+export async function buildExploreCustomTools(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { execFileSync } = await import("node:child_process");
+    const repoRoot = options.repoRoot;
+    const { safeReadFile, safeGrep, scrubSecrets } = await import("../../explore-tools.js");
+    function safeGit(args) {
+        try {
+            const stdout = execFileSync("git", args, {
+                cwd: repoRoot,
+                encoding: "utf8",
+                // Fixed argv, no shell, bounded output.
+                maxBuffer: 512 * 1024,
+                timeout: 10_000,
+                windowsHide: true,
+            });
+            return { ok: true, stdout };
+        }
+        catch (e) {
+            return {
+                ok: false,
+                code: "GIT_FAILED",
+                message: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }
+    const safeReadTool = defineTool({
+        name: "safe-read",
+        label: "safe-read",
+        description: "Read a repo-relative file with sensitive-file denylist (.env*/*.key/*.pem/.git/**/auth.json/sessions/**) and secret scrubbing. Absolute paths and .. are rejected.",
+        promptSnippet: "safe-read: read a repo file (safe; secrets scrubbed)",
+        parameters: Type.Object({
+            path: Type.String({ description: "repo-relative file path" }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const raw = String(params.path ?? "");
+            try {
+                const result = await safeReadFile(repoRoot, raw);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result) }],
+                    details: result,
+                };
+            }
+            catch (e) {
+                const err = e;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: err.message ?? String(e),
+                                code: err.code ?? "READ_FAILED",
+                            }),
+                        },
+                    ],
+                    details: {
+                        error: err.message ?? String(e),
+                        code: err.code ?? "READ_FAILED",
+                    },
+                };
+            }
+        },
+    });
+    const safeGrepTool = defineTool({
+        name: "safe-grep",
+        label: "safe-grep",
+        description: "Line search across the repo working tree with sensitive-file denylist and secret scrubbing. pattern is a JS regex source; optional glob filters paths.",
+        promptSnippet: "safe-grep: search repo files (safe; secrets scrubbed)",
+        parameters: Type.Object({
+            pattern: Type.String({ description: "regex source (no shell)" }),
+            caseInsensitive: Type.Optional(Type.Boolean()),
+            glob: Type.Optional(Type.String({ description: "optional glob filter e.g. *.ts" })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const result = await safeGrep(repoRoot, String(params.pattern ?? ""), {
+                    caseInsensitive: Boolean(params.caseInsensitive),
+                    glob: params.glob ? String(params.glob) : undefined,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result) }],
+                    details: result,
+                };
+            }
+            catch (e) {
+                const err = e;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: err.message ?? String(e),
+                                code: err.code ?? "GREP_FAILED",
+                            }),
+                        },
+                    ],
+                    details: {
+                        error: err.message ?? String(e),
+                        code: err.code ?? "GREP_FAILED",
+                    },
+                };
+            }
+        },
+    });
+    const gitStatusTool = defineTool({
+        name: "git-status",
+        label: "git-status",
+        description: "Typed `git status --porcelain` (fixed argv, no shell). Returns scrubbed working-tree status.",
+        promptSnippet: "git-status: working tree status (read-only)",
+        parameters: Type.Object({}, { additionalProperties: false }),
+        async execute() {
+            const r = safeGit(["status", "--porcelain"]);
+            if (!r.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: r.message, code: r.code }),
+                        },
+                    ],
+                    details: { error: r.message, code: r.code },
+                };
+            }
+            const { scrubbed, redactions } = scrubSecrets(r.stdout);
+            const payload = { status: scrubbed, redactions };
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                details: payload,
+            };
+        },
+    });
+    const gitDiffTool = defineTool({
+        name: "git-diff",
+        label: "git-diff",
+        description: "Typed `git diff` (fixed argv: --stat or a single -- path; no shell). Returns scrubbed diff. path must be repo-relative and not sensitive.",
+        promptSnippet: "git-diff: diff (read-only, scrubbed)",
+        parameters: Type.Object({
+            path: Type.Optional(Type.String({
+                description: "optional repo-relative path to diff (default: whole tree --stat)",
+            })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            let rawPath = params.path ? String(params.path) : undefined;
+            // If a path is supplied, validate it via the read-path guard so git diff
+            // cannot be aimed at sensitive files (.env* / auth.json / sessions).
+            if (rawPath) {
+                const { guardReadPath } = await import("../../explore-tools.js");
+                const g = await guardReadPath(repoRoot, rawPath);
+                if (!g.ok) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ error: g.message, code: g.code }),
+                            },
+                        ],
+                        details: { error: g.message, code: g.code },
+                    };
+                }
+                rawPath = g.repoRelative;
+            }
+            const args = rawPath ? ["diff", "--", rawPath] : ["diff", "--stat"];
+            const r = safeGit(args);
+            if (!r.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: r.message, code: r.code }),
+                        },
+                    ],
+                    details: { error: r.message, code: r.code },
+                };
+            }
+            const { scrubbed, redactions } = scrubSecrets(r.stdout);
+            const payload = { diff: scrubbed, redactions };
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                details: payload,
+            };
+        },
+    });
+    return [safeReadTool, safeGrepTool, gitStatusTool, gitDiffTool];
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/goal-tools.js

@@ -0,0 +1,78 @@
+/**
+ * Session-bound Goal tools (workflow-mode only).
+ * create_goal still requires a consumed model-create grant from the registry.
+ */
+const GET_GOAL_DESCRIPTION = "Read the current session's durable cross-turn Goal, including revision, status, round limit, and whether this Console process is authorized to continue it.";
+const CREATE_GOAL_DESCRIPTION = "Create a durable cross-turn Goal only when the user explicitly asks to start or create a Goal. Never silently upgrade an ordinary request. A session may have only one unfinished Goal.";
+const UPDATE_GOAL_DESCRIPTION = "Finish or block the current durable Goal using its exact goalId and revision. Set complete only when the objective is genuinely achieved and no required work remains. Set blocked only when safe progress cannot continue; include the blocker.";
+export async function buildGoalTools(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const textResult = (value) => ({
+        content: [{ type: "text", text: JSON.stringify(value) }],
+        details: value,
+    });
+    return [
+        defineTool({
+            name: "get_goal",
+            label: "Get goal",
+            description: GET_GOAL_DESCRIPTION,
+            promptSnippet: GET_GOAL_DESCRIPTION,
+            parameters: Type.Object({}, { additionalProperties: false }),
+            async execute() {
+                return textResult({ goal: options.registry.get(options.sessionId) });
+            },
+        }),
+        defineTool({
+            name: "create_goal",
+            label: "Create goal",
+            description: CREATE_GOAL_DESCRIPTION,
+            promptSnippet: CREATE_GOAL_DESCRIPTION,
+            parameters: Type.Object({
+                objective: Type.String({
+                    description: "Concrete final objective and completion standard explicitly requested by the user.",
+                }),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                if (!options.registry.consumeModelCreateGrant(options.sessionId)) {
+                    return textResult({
+                        ok: false,
+                        code: "GOAL_EXPLICIT_REQUEST_REQUIRED",
+                        message: "create_goal requires an explicit user request to create or start a Goal",
+                    });
+                }
+                return textResult(options.registry.create({
+                    sessionId: options.sessionId,
+                    objective: params.objective,
+                }));
+            },
+        }),
+        defineTool({
+            name: "update_goal",
+            label: "Update goal",
+            description: UPDATE_GOAL_DESCRIPTION,
+            promptSnippet: UPDATE_GOAL_DESCRIPTION,
+            parameters: Type.Object({
+                goalId: Type.String(),
+                revision: Type.Number({ minimum: 1 }),
+                status: Type.Union([
+                    Type.Literal("complete"),
+                    Type.Literal("blocked"),
+                ]),
+                blocker: Type.Optional(Type.String()),
+            }, { additionalProperties: false }),
+            async execute(_toolCallId, params) {
+                return textResult(options.registry.update({
+                    sessionId: options.sessionId,
+                    goalId: params.goalId,
+                    expectedRevision: params.revision,
+                    phase: params.status,
+                    blocker: params.blocker,
+                    arm: false,
+                }));
+            },
+        }),
+    ];
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/operator-tools.js

@@ -0,0 +1,86 @@
+/**
+ * Session-less operator-action custom tools (workflow-mode business tools).
+ * Definitions and execute() live here; ConsolePiRuntime owns caching and
+ * composition with session-bound tools.
+ */
+import { authorizeChatSessionTool, DEFAULT_CONSOLE_CHAT_SESSION_MODE, } from "../../session-mode.js";
+import { buildModelCallableToolSchemas } from "../../tool-adapter.js";
+/**
+ * Build Pi custom ToolDefinition objects for every whitelisted operator action.
+ * Each tool's execute() routes into the operator action dispatcher (Gate 3).
+ * Requires the `typebox` + `defineTool` packages (both bundled with the SDK).
+ */
+export async function buildCustomOperatorTools(options) {
+    // typebox is a transitive dep of @earendil-works/pi-coding-agent; Node's
+    // resolver hoists to the SDK's nested copy. defineTool is re-exported by SDK.
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const schemas = buildModelCallableToolSchemas();
+    const ctx = options.actionContext;
+    return schemas.map((schema) => {
+        // TypeBox schema is built dynamically; cast through unknown to the builder
+        // since Static<TParams> is structural and cannot be statically inferred here.
+        const parameters = Type.Object(schema.inputParams.reduce((acc, param) => {
+            // Carry the registry's param description into the tool schema so
+            // the model sees parameter semantics, not just names/types.
+            const desc = param.description?.trim()
+                ? { description: param.description }
+                : {};
+            let t;
+            switch (param.type) {
+                case "string":
+                    t = Type.String(desc);
+                    break;
+                case "boolean":
+                    t = Type.Boolean(desc);
+                    break;
+                case "number":
+                    t = Type.Number(desc);
+                    break;
+                case "array":
+                    t = Type.Array(Type.String({}), Object.keys(desc).length ? desc : {});
+                    break;
+                default:
+                    t = Type.Object({}, { additionalProperties: true });
+            }
+            acc[param.name] = param.required ? t : Type.Optional(t);
+            return acc;
+        }, {}), { additionalProperties: false });
+        return defineTool({
+            name: schema.toolId,
+            label: schema.toolId,
+            description: `${schema.description} (kind=${schema.kind}; cli: ${schema.cli})`,
+            promptSnippet: schema.description,
+            parameters: parameters,
+            async execute(toolCallId, params) {
+                const decision = authorizeChatSessionTool(schema.toolId, options.sessionMode ?? DEFAULT_CONSOLE_CHAT_SESSION_MODE);
+                if (!decision.ok) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error: decision.message,
+                                    code: decision.code,
+                                }),
+                            },
+                        ],
+                        details: { error: decision.message, code: decision.code },
+                    };
+                }
+                // Defer require to avoid circular import at module load.
+                const { dispatchChatToolCall } = await import("../../session-store.js");
+                const result = await dispatchChatToolCall(ctx, decision.toolId, params, toolCallId, options.sessionMode);
+                const payload = result.ok
+                    ? result.result
+                    : { error: result.message, code: result.errorCode };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload) }],
+                    details: payload,
+                };
+            },
+        });
+    });
+}

package/dist/worker/console/chat/pi-runtime/custom-tools/todo-write.js

@@ -0,0 +1,38 @@
+/**
+ * Session-bound todo_write custom tool.
+ * Description is mode-aware; ConsolePiRuntime owns when to register it.
+ */
+import { PI_TODO_WRITE_DESCRIPTION, } from "../../session-mode.js";
+const TODO_WRITE_DESCRIPTION = "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (no partial updates, no per-item edits). Before starting multi-step work, add one todo per concrete step. Keep at least one todo `in_progress` while work remains. Mark a todo `completed` immediately when it is done (do not batch completions) and resend the full list as progress or DAG state advances. Skip the list for simple Q&A, read-only lookups, and single-step tasks. Use it for multi-step implementation and whenever you prepare, run, or supervise a DAG — call `todo_write` before entering the DAG tool chain. Phrase DAG todos as user-facing phases users can understand, not copies of internal DAG nodes. Statuses: `pending` / `in_progress` / `completed`.";
+export async function buildTodoWriteTool(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const description = options.sessionMode === "pi"
+        ? PI_TODO_WRITE_DESCRIPTION
+        : TODO_WRITE_DESCRIPTION;
+    return defineTool({
+        name: "todo_write",
+        label: "Update todo list",
+        description,
+        promptSnippet: description,
+        parameters: Type.Object({
+            todos: Type.Array(Type.Object({
+                content: Type.String({ description: "Short imperative task description." }),
+                status: Type.Union([
+                    Type.Literal("pending"),
+                    Type.Literal("in_progress"),
+                    Type.Literal("completed"),
+                ]),
+            }, { additionalProperties: false })),
+        }, { additionalProperties: false }),
+        async execute(toolCallId, params) {
+            const result = options.registry.write(options.sessionId, toolCallId, params.todos);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                details: result,
+            };
+        },
+    });
+}