larkin 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.5.5
+
+Pi uses a small Larkin-owned tmux Bash extension when tmux is available on macOS/Linux. Commands preserve their working directory, including non-Git paths with spaces; a foreground wait can return while the same command continues. The returned task ID supports inspection and cancellation, and background completion resumes the Agent. Native Windows and environments without tmux retain Pi's native Bash.
+
+Removed the injected subagent plugin, its ledger/watchdog and supervised-command infrastructure, the 60-second Bash hard-kill rule, and mandatory delegation guidance. Pi-owned turns now occupy Runtime busy state without a second host prompt. Historical subagent files are left untouched. Background commands survive Pi shutdown in tmux; notification recovery across Pi restarts is not provided. No third-party tmux plugin is installed or redistributed.
+
 ## 0.5.4
 
 Inbox Audit is now optional and off by default. The Dashboard and CLI support global and per-Agent switches and inspection gaps. Saving a gap updates scheduling without replacing Runtime sessions; editing a gap alone does not enable auditing. Only originally wake-eligible human group/topic work is audited.

package/README.md

@@ -91,7 +91,13 @@ Feishu (https://open.feishu.cn) and Lark (https://open.larksuite.com) are differ
 
 During setup, choose one of the three externally installed runtimes: Pi (`pi`), Codex (`codex`), or Claude Code (`claude`). Larkin does not ship a runtime and does not store provider credentials. Install the runtime yourself and complete its own login (`pi` login flow, `codex login`, or `claude login`) before setup. Interactive setup lists each runtime as installed or not installed and refuses a missing binary; non-interactive setup requires `--runtime` and exits non-zero with the same missing-install message.
 
-`larkin setup --model <id>` optionally stores a catalog model for that runtime. After setup, use `larkin model` and `larkin runtime` to inspect or switch. For Pi, Larkin talks to your installed `pi --mode rpc`, verifies the RPC handshake and compaction capability contract, and injects its supported extensions through `pi -e` (background subagents and the 60-second foreground bash timeout guard).
+`larkin setup --model <id>` optionally stores a catalog model for that runtime. After setup, use `larkin model` and `larkin runtime` to inspect or switch. For Pi, Larkin talks to your installed `pi --mode rpc` and verifies the RPC handshake and compaction capability contract.
+
+### Optional Pi tmux-backed bash
+
+On macOS and Linux with `tmux` 3.2 or newer installed, Larkin provides a small tmux-backed Bash tool. Commands run in their requested directory, including non-Git directories and paths with spaces. By default the tool waits up to 30 seconds, then returns a `taskId` while the same command continues; `background: true` returns immediately. The `tmux` tool lists, inspects and stops tasks owned by that Pi instance. Completed background commands notify the Agent. There is no Larkin-imposed 60-second kill or ten-minute command limit.
+
+Without a supported tmux version, or on native Windows, Pi keeps native bash. After Pi shuts down, background commands remain in tmux, but automatic completion notifications are not restored; use `tmux list-sessions` to find the session containing the task ID and attach manually. Larkin does not require a third-party tmux plugin.
 
 ### Optional Inbox Audit
 

package/artifacts/release/THIRD_PARTY_NOTICES.txt

@@ -4,7 +4,7 @@ Generated at release time from Larkin's installed runtime dependency closure.
 Development-only dependencies are intentionally excluded. Packages without a bundled license file
 use an explicitly audited, version- and hash-pinned license source and remain identified by locked package name and version.
 
-Runtime package versions: 101
+Runtime package versions: 97
 
 | Package | Version | Relationship | Declared license | License texts (SHA-256) | Lock integrity |
 | --- | ---: | --- | --- | --- | --- |
@@ -43,8 +43,6 @@ Runtime package versions: 101
 | @radix-ui/react-use-controllable-state | 1.2.6 | runtime transitive | MIT | LICENSE (0e80a2d229d2fd4fc7e8636142ec5d0ff0bc031f14c15b682e2ac01dfd5b5138) | sha512-uEQJGT97ZA/TgP/Hydw47lHu+/vQj6z/0jA+WeTbK1o9Rx45GImjpD0tc3W5ad3D6XTSR6e1yEO0FvGq6WQfVQ== |
 | @radix-ui/react-use-effect-event | 0.0.5 | runtime transitive | MIT | LICENSE (0e80a2d229d2fd4fc7e8636142ec5d0ff0bc031f14c15b682e2ac01dfd5b5138) | sha512-7cshFL8HGS/7HEiHH+9kL9HBwp2sa9yX18Knwek6KYWmXwM7pegMgta2AXMQKI+rq3JnfSj9x8wYqFMTdG1Jgg== |
 | @radix-ui/react-use-layout-effect | 1.1.4 | runtime transitive | MIT | LICENSE (0e80a2d229d2fd4fc7e8636142ec5d0ff0bc031f14c15b682e2ac01dfd5b5138) | sha512-K20DkRkUwDnxEYMBPcg3Y6voLkEy5p5QQmszZgLngKKiC7dzBR/aEuK3w1qlx2JWDUNH6FluahYdgR3BP+QbYw== |
-| @sinclair/typebox | 0.34.52 | runtime transitive | MIT | license (411f1c560755e27b3dec9622c13b8b7a3ec1c83f4ffb8c56a8847528aa96911a) | sha512-XiMQh7qqVlxZzcVD+kkGMNGMzcTrDMLWI7S4x7z1MkCkbDPrekpZXEUK0eZqZFMuHQg2a2DZOcDIh9o5v3Gonw== |
-| @tintinweb/pi-subagents | 0.14.3 | runtime direct | MIT | LICENSE (e7d9d11c28cce34f09dc7d2b0a3a6609ccba5fbc8e926e6d1bfdf060930e9f05) | sha512-iDqeadh6114AZvw8HYe1PEq8M0MZ9czJKTAIsklCPUbV9vUMS+g/LAV0vW3O9PiBXKNJh8hkrY8L6iIr8XNEqA== |
 | agent-base | 6.0.2 | runtime transitive | MIT | AUDITED-agent-base@9.0.0-LICENSE (71368fd0f5b4129191e9afcd1e1ef2dc89a9090d3e4d80bbab92dafd032b3bef) | sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ== |
 | agent-base | 9.0.0 | runtime transitive | MIT | LICENSE (71368fd0f5b4129191e9afcd1e1ef2dc89a9090d3e4d80bbab92dafd032b3bef) | sha512-TQf59BsZnytt8GdJKLPfUZ54g/iaUL2OWDSFCCvMOhsHduDQxO8xC4PNeyIkVcA5KwL2phPSv0douC0fgWzmnA== |
 | aria-hidden | 1.2.6 | runtime transitive | MIT | LICENSE (30f0cfddf483d1128e3610205020f2041a6c5e837aa999e0aa82e5576187d4a9) | sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA== |
@@ -53,7 +51,6 @@ Runtime package versions: 101
 | call-bind-apply-helpers | 1.0.2 | runtime transitive | MIT | LICENSE (5e325595b4ea8cfec3802f545b1def5d7b73e4a5b8e9ba63e32a320f67732292) | sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ== |
 | call-bound | 1.0.4 | runtime transitive | MIT | LICENSE (5e325595b4ea8cfec3802f545b1def5d7b73e4a5b8e9ba63e32a320f67732292) | sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg== |
 | combined-stream | 1.0.8 | runtime transitive | MIT | License (47eb8ca82c798246774946d1be0f9aa08f025fa8325ced0947aeeb4c05fe5547) | sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg== |
-| croner | 10.0.1 | runtime transitive | MIT | LICENSE (ad9aa40aaab4bee08121a0180096cc6a72abf29e19e606328b66c0178f41d267) | sha512-ixNtAJndqh173VQ4KodSdJEI6nuioBWI0V1ITNKhZZsO0pEMoDxz539T4FTTbSZ/xIOSuDnzxLVRqBVSvPNE2g== |
 | debug | 4.4.3 | runtime transitive | MIT | LICENSE (23eb8602cd5902bcfca56b23aa08e8672a809f5a12eaf8bb56abfa9d44e1a4fd) | sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA== |
 | delayed-stream | 1.0.0 | runtime transitive | MIT | License (47eb8ca82c798246774946d1be0f9aa08f025fa8325ced0947aeeb4c05fe5547) | sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ== |
 | detect-node-es | 1.1.0 | runtime transitive | MIT | LICENSE (54b32293ea560d22cd9b62af9b2cda1a030d910a48c6601d227c5ff2338d95f8) | sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ== |
@@ -84,7 +81,6 @@ Runtime package versions: 101
 | mime-db | 1.52.0 | runtime transitive | MIT | LICENSE (cc1dfd4dafa27271e8212cd3b274eeb3f262e40a6fdab36ddc3f9696f706f58b) | sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg== |
 | mime-types | 2.1.35 | runtime transitive | MIT | LICENSE (71f83c4c0621102a56d9853812777b85751bce7e9726f686f5b056c1f8a4b0e6) | sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw== |
 | ms | 2.1.3 | runtime transitive | MIT | license.md (1662fae9b5314d11cf51284e2dcd1f006a354f7343f08712a730fcff9a359801) | sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== |
-| nanoid | 5.1.16 | runtime transitive | MIT | LICENSE (4383cb2c3608397ce7a4159502614ed66890f8999c2a9c056dd3b1024d6721f0) | sha512-kVrnsrJqMR8+oLJnGEmSWw9BivK5mt7H3FZatVRjrc5wGqFYuBxX1yG7+A7Gi5AefkX6t/oCkizcQgpu0cY1dQ== |
 | object-inspect | 1.13.4 | runtime transitive | MIT | LICENSE (bd40cc437e28a3ad7bef2ad34e6b72e757b182e67bda1acadbab4ef0476f8232) | sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew== |
 | proper-lockfile | 4.1.2 | runtime direct | MIT | LICENSE (aaa78451b6fecd1b9c4594c796c133c0e90cad100372ff8bc6de615e9ef9adf1) | sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA== |
 | protobufjs | 7.6.5 | runtime transitive | BSD-3-Clause | LICENSE (49d6a1c9a623784c61c6cb70f773f3457faceb1914a13c8560a9823b7631950c) | sha512-/FPD0nUc9jH6rfFjji9IBqOz4pcSE3CsT1m7Ep6Mdb0LxSUMj8hgl6GomOvZzpNpAqqGaXA0P3VSrZLFzIhQrw== |
@@ -414,55 +410,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
---- SHA-256 411f1c560755e27b3dec9622c13b8b7a3ec1c83f4ffb8c56a8847528aa96911a ---
-TypeBox
-
-Json Schema Type Builder with Static Type Resolution for TypeScript
-
-The MIT License (MIT)
-
-Copyright (c) 2017-2026 Haydn Paterson
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
---- SHA-256 4383cb2c3608397ce7a4159502614ed66890f8999c2a9c056dd3b1024d6721f0 ---
-The MIT License (MIT)
-
-Copyright 2017 Andrey Sitnik <andrey@sitnik.es>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
 --- SHA-256 47eb8ca82c798246774946d1be0f9aa08f025fa8325ced0947aeeb4c05fe5547 ---
 Copyright (c) 2011 Debuggable Limited <felix@debuggable.com>
 
@@ -968,29 +915,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
---- SHA-256 ad9aa40aaab4bee08121a0180096cc6a72abf29e19e606328b66c0178f41d267 ---
-The MIT License (MIT)
-
-Copyright (c) 2015-2021 Hexagon <github.com/Hexagon>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
 --- SHA-256 b495047bd93a9b06913511076f504daba17d5bbeb3e0650f3bb53a4220329c57 ---
 ISC License
 
@@ -1711,29 +1635,6 @@ Copyright (c) 2012 Felix Geisendörfer (felix@debuggable.com) and contributors
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  THE SOFTWARE.
 
---- SHA-256 e7d9d11c28cce34f09dc7d2b0a3a6609ccba5fbc8e926e6d1bfdf060930e9f05 ---
-MIT License
-
-Copyright (c) 2026 tintinweb
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
 --- SHA-256 e7dc37bf662d7f786efcb46c545615e70c1daf458a38385521c63cf6607cdfe1 ---
 BSD 3-Clause License
 

package/dist/agent/context-prompt.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContextPromptBuilder = exports.AGENT_MENTION_GUIDANCE = exports.LARKIN_STANDING_PROMPT_VERSION = void 0;
+exports.ContextPromptBuilder = exports.AGENT_MENTION_GUIDANCE = exports.PI_TMUX_BASH_GUIDANCE = exports.LARKIN_STANDING_PROMPT_VERSION = void 0;
 const node_crypto_1 = require("node:crypto");
 const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
 /**
@@ -16,7 +16,18 @@ const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v28";
+exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v30";
+/**
+ * Pi 长命令引导的唯一来源。仅在当前工具列表出现 tmux-backed bash 时适用；
+ * 不声明 tmux 一定可用，也不复述扩展的工具细节。
+ * 工具拒绝当前 workspace 时只要求如实报告，不因此禁止其它已授权工具。
+ */
+exports.PI_TMUX_BASH_GUIDANCE = [
+    "If the current tools include a tmux-backed bash, long-running work may continue after a wait timeout. That timeout is not process failure.",
+    "Use the identifiers those tools return to inspect or stop the same process. When a command finishes, handle the completion notification in this originating conversation.",
+    "The user-installed extension owns tool names, arguments, and other details. Do not assume tmux or extra inspect/stop tools exist unless they appear in the current tool list.",
+    "If an available tool refuses the current workspace, report that limitation. Other authorized tools in the current list remain available. Do not assume the refusing tool works in every workspace.",
+];
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -123,21 +134,9 @@ class ContextPromptBuilder {
             "Larkin Runtime Host is the only production runtime path. Do not start a second runtime or a legacy daemon.",
             ...(input.runtime === "pi" ? [
                 "",
-                "## Background subagents (pi)",
-                "Long-running, independent work MUST use the Agent tool with run_in_background: true. It is the ONLY supported background mechanism. nohup, `&`, disown, and shell background jobs are forbidden for delegated work.",
-                "Foreground bash is hard-capped at 60 seconds. Never pass a bash timeout above 60. Never use nested bash to outlive 60s. If work must outlive 60s, Agent({ prompt, description, run_in_background: true }) and inside that background agent use supervised_start (executable+args, shell:false) once, then loop supervised_wait (timeout <= 60). Wait timeout returns still running and does NOT kill the process; Steer can arrive after each wait. Total lifetime is 600s. Abort/cancel/shutdown reaps the process tree. Do not use nohup / '&' / disown.",
-                "Correct pattern:",
-                "1. Call Agent with arguments like {\"prompt\": \"<task>\", \"description\": \"<short label>\", \"run_in_background\": true}.",
-                "2. The tool returns an agent id immediately. Report it to the user and end the turn.",
-                "3. Do NOT poll or sleep; a completion notification arrives automatically.",
-                "4. On the notification, check the Inbox, then publish exactly one final summary.",
-                "If you explicitly use get_subagent_result with wait: true, make at most one bounded wait call per turn. If it returns timedOut: true, do not loop or call wait again in the same turn; yield and let the completion notification wake you.",
-                "Forbidden pattern (never acceptable): `nohup sh -c '...' > /tmp/x.out 2>&1 &`, `sleep N; cat ...`, disown, or any shell background substitute. These bypass subagent isolation.",
-                "Keep corrections, approvals, short commands, and Feishu writes in the foreground; do not delegate them.",
-                "Parallel independent tasks: when the user clearly asks for two or more independent tasks with no dependencies between them, delegate EACH task to its own background subagent in a single message with multiple Agent tool calls (one per task, all with run_in_background: true), report every job id, and end the turn. Do not run them one-by-one in the foreground and do not merge them into one subagent.",
-                "Sequential dependent tasks: when tasks depend on each other, sending the user an order message is a REQUIRED first step: before executing any follow-up work, send a message stating the execution order (for example: first I will do A, then B; I will report back after each step). Then execute in order and report as promised; never stay silent while chaining long work.",
-                "Reporting location: always report job ids and final summaries in the same conversation and thread where the user's message arrived (reply-in-thread when the request arrived in a thread). Never start a new conversation or DM for subagent status reports.",
-                ""
+                "## Long-running commands (pi)",
+                ...exports.PI_TMUX_BASH_GUIDANCE,
+                "",
             ] : []),
             "",
             "## Available Larkin agent commands",

package/dist/agent/context-prompt.mjs

@@ -13,7 +13,18 @@ import { agentCliPromptCapabilities } from "./agent-cli-capabilities.mjs";
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v28";
+export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v30";
+/**
+ * Pi 长命令引导的唯一来源。仅在当前工具列表出现 tmux-backed bash 时适用；
+ * 不声明 tmux 一定可用，也不复述扩展的工具细节。
+ * 工具拒绝当前 workspace 时只要求如实报告，不因此禁止其它已授权工具。
+ */
+export const PI_TMUX_BASH_GUIDANCE = [
+    "If the current tools include a tmux-backed bash, long-running work may continue after a wait timeout. That timeout is not process failure.",
+    "Use the identifiers those tools return to inspect or stop the same process. When a command finishes, handle the completion notification in this originating conversation.",
+    "The user-installed extension owns tool names, arguments, and other details. Do not assume tmux or extra inspect/stop tools exist unless they appear in the current tool list.",
+    "If an available tool refuses the current workspace, report that limitation. Other authorized tools in the current list remain available. Do not assume the refusing tool works in every workspace.",
+];
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -120,21 +131,9 @@ export class ContextPromptBuilder {
             "Larkin Runtime Host is the only production runtime path. Do not start a second runtime or a legacy daemon.",
             ...(input.runtime === "pi" ? [
                 "",
-                "## Background subagents (pi)",
-                "Long-running, independent work MUST use the Agent tool with run_in_background: true. It is the ONLY supported background mechanism. nohup, `&`, disown, and shell background jobs are forbidden for delegated work.",
-                "Foreground bash is hard-capped at 60 seconds. Never pass a bash timeout above 60. Never use nested bash to outlive 60s. If work must outlive 60s, Agent({ prompt, description, run_in_background: true }) and inside that background agent use supervised_start (executable+args, shell:false) once, then loop supervised_wait (timeout <= 60). Wait timeout returns still running and does NOT kill the process; Steer can arrive after each wait. Total lifetime is 600s. Abort/cancel/shutdown reaps the process tree. Do not use nohup / '&' / disown.",
-                "Correct pattern:",
-                "1. Call Agent with arguments like {\"prompt\": \"<task>\", \"description\": \"<short label>\", \"run_in_background\": true}.",
-                "2. The tool returns an agent id immediately. Report it to the user and end the turn.",
-                "3. Do NOT poll or sleep; a completion notification arrives automatically.",
-                "4. On the notification, check the Inbox, then publish exactly one final summary.",
-                "If you explicitly use get_subagent_result with wait: true, make at most one bounded wait call per turn. If it returns timedOut: true, do not loop or call wait again in the same turn; yield and let the completion notification wake you.",
-                "Forbidden pattern (never acceptable): `nohup sh -c '...' > /tmp/x.out 2>&1 &`, `sleep N; cat ...`, disown, or any shell background substitute. These bypass subagent isolation.",
-                "Keep corrections, approvals, short commands, and Feishu writes in the foreground; do not delegate them.",
-                "Parallel independent tasks: when the user clearly asks for two or more independent tasks with no dependencies between them, delegate EACH task to its own background subagent in a single message with multiple Agent tool calls (one per task, all with run_in_background: true), report every job id, and end the turn. Do not run them one-by-one in the foreground and do not merge them into one subagent.",
-                "Sequential dependent tasks: when tasks depend on each other, sending the user an order message is a REQUIRED first step: before executing any follow-up work, send a message stating the execution order (for example: first I will do A, then B; I will report back after each step). Then execute in order and report as promised; never stay silent while chaining long work.",
-                "Reporting location: always report job ids and final summaries in the same conversation and thread where the user's message arrived (reply-in-thread when the request arrived in a thread). Never start a new conversation or DM for subagent status reports.",
-                ""
+                "## Long-running commands (pi)",
+                ...PI_TMUX_BASH_GUIDANCE,
+                "",
             ] : []),
             "",
             "## Available Larkin agent commands",

package/dist/runtime/pi-state-dir.cjs

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectivePiStateDir = effectivePiStateDir;
+exports.ensureOwnedTree = ensureOwnedTree;
+exports.ensurePrivateDirectory = ensurePrivateDirectory;
+exports.mkdirPrivateExclusive = mkdirPrivateExclusive;
+exports.writePrivateExclusive = writePrivateExclusive;
+exports.writePrivateAtomic = writePrivateAtomic;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** Same implicit root the Pi adapter uses when `stateDir` is omitted. */
+function effectivePiStateDir(input) {
+    return input.stateDir ?? node_path_1.default.join(input.workspaceDir, ".larkin");
+}
+/**
+ * 从 root 起逐层建 0700 子树。root 可以位于 /var、/tmp 等合法祖先 link 之后；
+ * 任一层 owned 组件自身是 symlink 则拒绝，不顺着 link 往外写。
+ */
+function ensureOwnedTree(root, parts = [], create = true) {
+    const resolved = node_path_1.default.resolve(root);
+    if (node_fs_1.default.existsSync(resolved)) {
+        const stat = node_fs_1.default.lstatSync(resolved);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Error(`unsafe private directory: ${resolved}`);
+    }
+    else if (create) {
+        node_fs_1.default.mkdirSync(resolved, { recursive: true, mode: 0o700 });
+        if (node_fs_1.default.lstatSync(resolved).isSymbolicLink() || !node_fs_1.default.lstatSync(resolved).isDirectory()) {
+            throw new Error(`unsafe private directory: ${resolved}`);
+        }
+    }
+    else {
+        throw new Error(`unsafe private directory: ${resolved}`);
+    }
+    let dir = resolved;
+    for (const part of parts) {
+        if (!part || part === "." || part === ".." || /[\\/]/.test(part))
+            throw new Error(`unsafe owned path component: ${part}`);
+        dir = node_path_1.default.join(dir, part);
+        try {
+            const existing = node_fs_1.default.lstatSync(dir);
+            if (existing.isSymbolicLink() || !existing.isDirectory())
+                throw new Error(`unsafe private directory: ${dir}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (!create)
+                throw new Error(`unsafe private directory: ${dir}`);
+            node_fs_1.default.mkdirSync(dir, { mode: 0o700 });
+            if (node_fs_1.default.lstatSync(dir).isSymbolicLink() || !node_fs_1.default.lstatSync(dir).isDirectory())
+                throw new Error(`unsafe private directory: ${dir}`);
+        }
+        if (process.platform !== "win32")
+            node_fs_1.default.chmodSync(dir, 0o700);
+    }
+    return dir;
+}
+function ensurePrivateDirectory(directory) {
+    ensureOwnedTree(directory);
+}
+/** 独占新建 0700 目录；已存在或变成 symlink 都拒绝。 */
+function mkdirPrivateExclusive(directory) {
+    node_fs_1.default.mkdirSync(directory, { mode: 0o700 });
+    const created = node_fs_1.default.lstatSync(directory);
+    if (created.isSymbolicLink() || !created.isDirectory())
+        throw new Error(`unsafe private directory: ${directory}`);
+    if (process.platform !== "win32")
+        node_fs_1.default.chmodSync(directory, 0o700);
+}
+/** 独占新建 0600 文件；已存在（含 symlink）时失败，不跟随写出。 */
+function writePrivateExclusive(file, content) {
+    node_fs_1.default.writeFileSync(file, content, { mode: 0o600, flag: "wx" });
+    if (process.platform !== "win32")
+        node_fs_1.default.chmodSync(file, 0o600);
+}
+/** 原子写 0600 文件；目标或父目录已是 symlink 时拒绝，避免落到目录外。 */
+function writePrivateAtomic(file, content) {
+    try {
+        if (node_fs_1.default.lstatSync(node_path_1.default.dirname(file)).isSymbolicLink())
+            throw new Error(`unsafe private directory: ${node_path_1.default.dirname(file)}`);
+        if (node_fs_1.default.lstatSync(file).isSymbolicLink())
+            throw new Error(`${node_path_1.default.basename(file)} must not be a symlink`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const temporary = node_path_1.default.join(node_path_1.default.dirname(file), `.${node_path_1.default.basename(file)}.${process.pid}.${node_crypto_1.default.randomUUID()}.tmp`);
+    try {
+        node_fs_1.default.writeFileSync(temporary, content, { mode: 0o600, flag: "wx" });
+        node_fs_1.default.renameSync(temporary, file);
+        node_fs_1.default.chmodSync(file, 0o600);
+    }
+    finally {
+        try {
+            node_fs_1.default.unlinkSync(temporary);
+        }
+        catch { /* renamed or absent */ }
+    }
+}

package/dist/runtime/pi-state-dir.mjs

@@ -0,0 +1,94 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/** Same implicit root the Pi adapter uses when `stateDir` is omitted. */
+export function effectivePiStateDir(input) {
+    return input.stateDir ?? path.join(input.workspaceDir, ".larkin");
+}
+/**
+ * 从 root 起逐层建 0700 子树。root 可以位于 /var、/tmp 等合法祖先 link 之后；
+ * 任一层 owned 组件自身是 symlink 则拒绝，不顺着 link 往外写。
+ */
+export function ensureOwnedTree(root, parts = [], create = true) {
+    const resolved = path.resolve(root);
+    if (fs.existsSync(resolved)) {
+        const stat = fs.lstatSync(resolved);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Error(`unsafe private directory: ${resolved}`);
+    }
+    else if (create) {
+        fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
+        if (fs.lstatSync(resolved).isSymbolicLink() || !fs.lstatSync(resolved).isDirectory()) {
+            throw new Error(`unsafe private directory: ${resolved}`);
+        }
+    }
+    else {
+        throw new Error(`unsafe private directory: ${resolved}`);
+    }
+    let dir = resolved;
+    for (const part of parts) {
+        if (!part || part === "." || part === ".." || /[\\/]/.test(part))
+            throw new Error(`unsafe owned path component: ${part}`);
+        dir = path.join(dir, part);
+        try {
+            const existing = fs.lstatSync(dir);
+            if (existing.isSymbolicLink() || !existing.isDirectory())
+                throw new Error(`unsafe private directory: ${dir}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (!create)
+                throw new Error(`unsafe private directory: ${dir}`);
+            fs.mkdirSync(dir, { mode: 0o700 });
+            if (fs.lstatSync(dir).isSymbolicLink() || !fs.lstatSync(dir).isDirectory())
+                throw new Error(`unsafe private directory: ${dir}`);
+        }
+        if (process.platform !== "win32")
+            fs.chmodSync(dir, 0o700);
+    }
+    return dir;
+}
+export function ensurePrivateDirectory(directory) {
+    ensureOwnedTree(directory);
+}
+/** 独占新建 0700 目录；已存在或变成 symlink 都拒绝。 */
+export function mkdirPrivateExclusive(directory) {
+    fs.mkdirSync(directory, { mode: 0o700 });
+    const created = fs.lstatSync(directory);
+    if (created.isSymbolicLink() || !created.isDirectory())
+        throw new Error(`unsafe private directory: ${directory}`);
+    if (process.platform !== "win32")
+        fs.chmodSync(directory, 0o700);
+}
+/** 独占新建 0600 文件；已存在（含 symlink）时失败，不跟随写出。 */
+export function writePrivateExclusive(file, content) {
+    fs.writeFileSync(file, content, { mode: 0o600, flag: "wx" });
+    if (process.platform !== "win32")
+        fs.chmodSync(file, 0o600);
+}
+/** 原子写 0600 文件；目标或父目录已是 symlink 时拒绝，避免落到目录外。 */
+export function writePrivateAtomic(file, content) {
+    try {
+        if (fs.lstatSync(path.dirname(file)).isSymbolicLink())
+            throw new Error(`unsafe private directory: ${path.dirname(file)}`);
+        if (fs.lstatSync(file).isSymbolicLink())
+            throw new Error(`${path.basename(file)} must not be a symlink`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temporary, content, { mode: 0o600, flag: "wx" });
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* renamed or absent */ }
+    }
+}

package/dist/runtime/pi-tmux-extension.mjs

@@ -0,0 +1,137 @@
+import crypto from "node:crypto";
+import { Type } from "typebox";
+import { createLarkinTmux, DEFAULT_BASH_WAIT_SECONDS, ForeignTmuxTaskError, formatTmuxTaskText, LARKIN_TMUX_COMPLETION_TYPE, tmuxAvailable, } from "./pi-tmux.mjs";
+function resultOf(snapshot) {
+    return {
+        content: [{ type: "text", text: formatTmuxTaskText(snapshot) }],
+        details: {
+            taskId: snapshot.taskId,
+            status: snapshot.status,
+            exitCode: snapshot.exitCode,
+            output: snapshot.output,
+        },
+    };
+}
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        details: { taskId: "", status: "failed", exitCode: null, output: message },
+    };
+}
+export function registerLarkinTmuxExtension(pi) {
+    if (!tmuxAvailable())
+        return false;
+    const stateDir = process.env.LARKIN_STATE_DIR || `${process.cwd()}/.larkin`;
+    const agentId = process.env.LARKIN_AGENT_ID || "agent";
+    const instanceId = process.env.LARKIN_TMUX_INSTANCE_ID
+        || process.env.LARKIN_RUNTIME_OBSERVATION_GENERATION
+        || crypto.randomUUID();
+    const tmux = createLarkinTmux({ stateDir, agentId, instanceId, env: process.env });
+    const watchers = new Map();
+    const notified = new Set();
+    const stopWatchers = () => {
+        for (const timer of watchers.values())
+            clearInterval(timer);
+        watchers.clear();
+    };
+    const notifyOnce = (snapshot) => {
+        if (snapshot.status === "running" || notified.has(snapshot.taskId))
+            return;
+        notified.add(snapshot.taskId);
+        pi.sendMessage({
+            customType: LARKIN_TMUX_COMPLETION_TYPE,
+            content: formatTmuxTaskText(snapshot),
+            display: true,
+            details: {
+                taskId: snapshot.taskId,
+                exitCode: snapshot.exitCode,
+                output: snapshot.output,
+            },
+        }, { triggerTurn: true, deliverAs: "followUp" });
+    };
+    const watch = (taskId) => {
+        if (watchers.has(taskId) || notified.has(taskId))
+            return;
+        const timer = setInterval(() => {
+            try {
+                const snapshot = tmux.peek(taskId);
+                if (snapshot.status === "running")
+                    return;
+                clearInterval(timer);
+                watchers.delete(taskId);
+                notifyOnce(snapshot);
+            }
+            catch {
+                clearInterval(timer);
+                watchers.delete(taskId);
+            }
+        }, 250);
+        watchers.set(taskId, timer);
+    };
+    pi.on("session_shutdown", () => {
+        stopWatchers();
+    });
+    pi.registerTool({
+        name: "bash",
+        label: "bash",
+        description: "Run a command in a detached tmux window. timeout is a wait window only and never hard-kills. background:true returns immediately.",
+        parameters: Type.Object({
+            command: Type.String(),
+            timeout: Type.Optional(Type.Number()),
+            background: Type.Optional(Type.Boolean()),
+        }),
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const snapshot = tmux.start(params.command, ctx.cwd);
+            if (params.background === true) {
+                watch(snapshot.taskId);
+                return resultOf(tmux.peek(snapshot.taskId));
+            }
+            const timeout = typeof params.timeout === "number" && params.timeout >= 0 ? params.timeout : DEFAULT_BASH_WAIT_SECONDS;
+            const waited = await tmux.wait(snapshot.taskId, timeout, signal);
+            if (waited.status === "running")
+                watch(waited.taskId);
+            return resultOf(waited);
+        },
+    });
+    pi.registerTool({
+        name: "tmux",
+        label: "tmux",
+        description: "List, peek, or kill Larkin-owned tmux tasks for this Agent. Foreign task IDs are rejected.",
+        parameters: Type.Object({
+            action: Type.Union([Type.Literal("list"), Type.Literal("peek"), Type.Literal("kill")]),
+            taskId: Type.Optional(Type.String()),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                if (params.action === "list") {
+                    const tasks = tmux.list();
+                    return {
+                        content: [{ type: "text", text: tasks.map(formatTmuxTaskText).join("\n---\n") || "no owned tmux tasks" }],
+                        details: { taskId: "", status: "completed", exitCode: 0, output: "" },
+                    };
+                }
+                if (!params.taskId)
+                    return errorResult("taskId is required for peek and kill");
+                if (params.action === "peek")
+                    return resultOf(tmux.peek(params.taskId));
+                const killed = tmux.kill(params.taskId);
+                notified.add(params.taskId);
+                const timer = watchers.get(params.taskId);
+                if (timer) {
+                    clearInterval(timer);
+                    watchers.delete(params.taskId);
+                }
+                return resultOf(killed);
+            }
+            catch (error) {
+                if (error instanceof ForeignTmuxTaskError)
+                    return errorResult(error.message);
+                throw error;
+            }
+        },
+    });
+    return true;
+}
+export default function larkinTmuxExtension(pi) {
+    registerLarkinTmuxExtension(pi);
+}