wave-agent-sdk 1.1.5 → 1.3.0

package/dist/builtin/plugins.js

@@ -41,9 +41,9 @@ const guidance = [
   "- 边界模糊时也先写 spec 草稿请用户确认，不要直接改代码。",
   "- 规格编写技能（specify）由 AI 自动触发：对话中涉及新需求或需求变更时主动创建或更新规格文件，不需要用户手动调用（不出现在斜杠命令列表中）。",
   \`- 新增或修改 spec 后运行校验：\${specCount}（自动检测 docs/specs/，否则 specs/，否则退出）。\`,
-  "- 阶段衔接一律用 AskUserQuestion 单选让用户点击决策，不要求自然语言：spec 确认（确认通过/需要修改）、是否制作原型、是否制定技术方案（plan）均通过单选推进。",
-  "- 可选原型阶段（在规格之后、plan 之前）：仅实现前端界面，数据全部使用 mock；可选 plan 阶段：进入 plan 模式制定技术方案，批准后再编码。二者均可跳过——最短流程=规格+编码，最长=规格+原型+plan+编码。仅当需求涉及前端界面时才询问是否制作原型，无前端界面的需求（后端服务、CLI、算法库等）直接跳过原型询问。",
-  "- 用 task 工具追踪进度：规格、原型、plan、编码各阶段开始前用 TaskCreate 创建任务并标记进行中（TaskUpdate），完成/批准/确认后标记完成，让用户在任务列表中看到当前所处阶段。",
+  "- 规格确认与阶段衔接一次完成：通过 AskUserQuestion 单选让用户点击决策（选项只传「直接实现 / 制定技术方案」，并在问题文案中说明如需调整规格可选「其他」输入修改意见；「其他」由 AskUserQuestion 自动附加，勿手动添加；选「其他」=规格需调整，按反馈修改后再次询问）。",
+  "- 可选技术方案阶段：制定技术方案并批准后再编码；也可跳过——最短流程=规格+编码，最长=规格+技术方案+编码。",
+  "- 用 task 工具追踪进度：规格、技术方案、编码各阶段开始前用 TaskCreate 创建任务并标记进行中（TaskUpdate），完成/批准/确认后标记完成，让用户在任务列表中看到当前所处阶段。",
 ].join("\\n");
 
 // JSON form → parsed as hookSpecificOutput.additionalContext by the hook manager.
@@ -131,7 +131,7 @@ if (warnings.length) {
 `,
     "plugins/sdd/skills/specify/SKILL.md": `---
 name: specify
-description: 根据自然语言描述创建或更新功能规格说明，并通过单选衔接可选原型、技术方案（plan）与编码阶段。
+description: 根据自然语言描述创建或更新功能规格说明，并通过单选衔接可选技术方案与编码阶段。
 user-invocable: false
 ---
 
@@ -147,7 +147,7 @@ $ARGUMENTS
 
 根据对话中的功能描述，执行以下步骤：
 
-0. **创建进度任务**：用 TaskCreate 创建「编写功能规格」任务，并用 TaskUpdate 标记进行中。后续每个阶段（原型、plan、编码）同样在开始前创建任务、结束后更新状态，让用户在任务列表中看到当前进度。
+0. **创建进度任务**：用 TaskCreate 创建「编写功能规格」任务，并用 TaskUpdate 标记进行中。后续每个阶段（技术方案、编码）同样在开始前创建任务、结束后更新状态，让用户在任务列表中看到当前进度。
 
 1. **确定规格文件路径**：
    - **确定规格根目录**：优先复用项目中已有的规格目录——若 \`docs/specs/\` 存在则用之，否则若 \`specs/\` 存在则用之，否则默认 \`specs/\`（并在完成报告中说明所选目录，便于用户纠正）。
@@ -172,23 +172,14 @@ $ARGUMENTS
 
 5. **校验并确认规格**：
    - 运行会话引导中给出的 spec-count 校验命令（自动检测 docs/specs/，否则 specs/，否则跳过）
-   - 输出规格文件路径，并通过 AskUserQuestion 单选请求确认（选项：确认通过 / 需要修改）
-   - 选「需要修改」→ 按用户反馈更新规格后重新校验，并再次单选确认；选「确认通过」→ 将「编写功能规格」任务标记完成
+   - 输出规格文件路径，并通过 AskUserQuestion 单选请求决策（选项只传：直接实现 / 制定技术方案；AskUserQuestion 会自动附加「其他」选项，勿手动添加「其他」；在问题文案中说明如需调整规格可选「其他」并输入修改意见）
+   - 用户选「其他」并输入意见 → 视为规格需要调整：按用户反馈更新规格后重新校验，并再次单选
+   - 选「直接实现」→ 将「编写功能规格」任务标记完成，进入编码阶段
+   - 选「制定技术方案」→ 将「编写功能规格」任务标记完成；用 TaskCreate 创建「制定技术方案」任务并标记进行中；调用 EnterPlanMode 进入技术方案模式，制定技术方案（技术选型、架构设计、实现步骤）并写入计划文件；用 ExitPlanMode 请求批准——被拒绝则按反馈更新方案后重新请求，批准后标记任务完成
 
-6. **询问是否制作原型（可选阶段，位于规格之后、plan 之前）**：
-   - 仅当需求涉及前端界面时弹出询问；需求不涉及前端界面（如后端服务、CLI 工具、算法库）时，跳过本阶段直接进入下一步，不弹出原型选择
-   - 通过 AskUserQuestion 单选询问（选项：制作原型 / 跳过）
-   - 选「制作原型」→ 用 TaskCreate 创建「制作原型」任务并标记进行中；仅实现前端界面，数据全部使用 mock（不接后端、不接真实数据）；完成后展示可交互原型供用户查看，并将任务标记完成
-   - 选「跳过」→ 直接进入下一步
-
-7. **询问是否制定技术方案（可选 plan 阶段）**：
-   - 通过 AskUserQuestion 单选询问（选项：进入 plan 模式 / 跳过）
-   - 选「进入 plan 模式」→ 用 TaskCreate 创建「制定技术方案」任务并标记进行中；调用 EnterPlanMode 进入 plan 模式，制定技术方案（技术选型、架构设计、实现步骤）并写入计划文件；用 ExitPlanMode 请求批准——被拒绝则按反馈更新方案后重新请求，批准后标记任务完成
-   - 选「跳过」→ 直接进入下一步
-
-8. **编码阶段**：
+6. **编码阶段**：
    - 用 TaskCreate 创建「实现功能」任务并标记进行中
-   - 按已确认的规格实现；若制作了原型则遵循其交互设计，若批准了技术方案则遵循其架构
+   - 按已确认的规格实现；若批准了技术方案则遵循其架构
    - 实现完成后将任务标记完成
 
 ## 指南

package/dist/builtin/skills/settings.js

@@ -702,7 +702,7 @@ You can extend the Safe Zone by adding \`additionalDirectories\` to your \`permi
 
 ## Permission Modes
 
-The \`permissionMode\` setting determines how Wave handles requests to use restricted tools (e.g., \`Bash\`, \`Edit\`, \`Write\`, \`AskUserQuestion\`).
+The \`defaultMode\` setting (under \`permissions\`, aligning with Claude Code's settings key) determines how Wave handles requests to use restricted tools (e.g., \`Bash\`, \`Edit\`, \`Write\`, \`AskUserQuestion\`).
 
 | Mode | Description |
 | :--- | :--- |
@@ -717,7 +717,7 @@ The \`permissionMode\` setting determines how Wave handles requests to use restr
 \`\`\`json
 {
   "permissions": {
-    "permissionMode": "default",
+    "defaultMode": "default",
     "additionalDirectories": ["/home/user/my-exports"],
     "allow": ["ls -R", "git status"],
     "deny": ["rm -rf"]
@@ -735,7 +735,7 @@ You can pre-approve or explicitly forbid specific operations using \`allow\` and
 When a tool is called, Wave checks:
 1. If the operation matches a \`deny\` rule, it is rejected.
 2. If the operation matches an \`allow\` rule, it is permitted.
-3. If no rules match, the behavior depends on the \`permissionMode\`.
+3. If no rules match, the behavior depends on the \`defaultMode\`.
 
 ### Rule Syntax
 
@@ -924,18 +924,7 @@ Wave clones the marketplace repo, reads the manifest, and copies the plugin to i
 
 ### Updating Plugins
 
-Marketplaces with \`autoUpdate: true\` are checked for updates on startup:
-
-\`\`\`json
-{
-  "marketplaces": {
-    "my-plugins": {
-      "source": { "source": "github", "repo": "user/my-plugins" },
-      "autoUpdate": true
-    }
-  }
-}
-\`\`\`
+Every registered marketplace is refreshed when you open a plugin marketplace surface — the settings page's plugin marketplace view, or the CLI plugin manager (\`/plugin\`). Each checkout is pulled (or cloned if missing). Refreshing a marketplace does **not** upgrade installed plugins, and there is no per-marketplace switch for it. Plugin upgrades only happen through an explicit action: updating a single plugin, or updating a whole marketplace (\`wave plugin marketplace update [name]\`, or the batch entry in either UI) to upgrade all of its plugins in batch.
 
 ### Marketplace Scopes
 
@@ -998,7 +987,7 @@ For detailed permission configuration and available permission modes, see [PERMI
   "permissions": {
     "allow": ["Bash", "Read"],
     "deny": ["Write"],
-    "permissionMode": "default",
+    "defaultMode": "default",
     "additionalDirectories": ["/tmp/wave-exports"]
   }
 }
@@ -1104,10 +1093,6 @@ The \`SKILL.md\` file uses YAML frontmatter for configuration and Markdown for i
 ---
 name: my-skill
 description: A brief description of what the skill does.
-context: fork
-allowed-tools:
-  - Bash
-  - Read
 ---
 
 # My Skill Instructions
@@ -1117,6 +1102,8 @@ When this skill is invoked, follow these steps:
 2. Use the \`Bash\` tool to run \`npm test\`.
 \`\`\`
 
+By default, new skills only include \`name\` and \`description\`. Only add \`context: fork\` or \`allowed-tools\` when the user explicitly asks for them.
+
 ### YAML Frontmatter Fields
 
 - \`name\`: (Required) Unique identifier (lowercase, numbers, hyphens).

package/dist/builtin/skills/wave-daemon.d.ts

@@ -0,0 +1 @@
+export declare const waveDaemonSkill: Record<string, string>;

package/dist/builtin/skills/wave-daemon.js

@@ -0,0 +1,194 @@
+import { BASH_TOOL_NAME, READ_TOOL_NAME } from "../../constants/tools.js";
+export const waveDaemonSkill = {
+    "skills/wave-daemon/SKILL.md": `---
+name: wave-daemon
+description: Delegate a development or research task to a background wave daemon session — session creation in an isolated worktree, dispatching messages, aborting and re-scoping, monitoring progress, approving permissions, answering AskUserQuestion, and tearing sessions down with destroy.
+allowed-tools: ${BASH_TOOL_NAME}(wave daemon *), ${BASH_TOOL_NAME}(git *), ${READ_TOOL_NAME}
+---
+
+# Wave daemon delegation
+
+Delegate development work (code changes, bug fixes, features) and research work (reading code and producing conclusions — which often turns into code changes) to a **wave daemon session** instead of doing the long task inline. A daemon session runs in the background with no UI window, keeps generating while no client is attached, and survives client disconnects.
+
+The authoritative command reference is the Wave documentation, CLI → *Daemon client commands* (\`docs/cli.md\` in the Wave repo). This skill is the playbook: what to run, in what order, and the traps to avoid.
+
+## 0. Mental model
+
+- \`wave --daemon <socket>\` starts the daemon (server side). \`wave daemon <subcommand>\` is the client that talks to it. The two never interfere.
+- Every client subcommand connects to the fixed socket \`~/.wave/daemon.sock\` (\`$HOME/.wave/daemon.sock\`); there is no \`--socket\` override, so you are always talking to this machine's daemon for the current user.
+- The daemon is **resident**: once started it does not exit when idle. It goes away only when stopped (\`wave daemon stop\`), killed, restarted after a CLI upgrade, or the machine restarts. It is not supervised by pm2/systemd, so it does not come back by itself.
+- Every subcommand except \`stop\` starts a daemon on demand when the socket is absent, then retries. "No daemon is running" is therefore never a problem to work around — just run the command.
+- Sessions are persisted as transcripts under \`~/.wave/projects/<project>/<sessionId>.jsonl\`, so a session can be re-hosted from disk after the daemon restarts.
+- All subcommands are non-interactive: results on stdout, diagnostics on stderr.
+
+## 1. Daemon lifecycle
+
+\`\`\`bash
+wave daemon stop      # graceful: every hosted session is destroyed (each saves its transcript), the socket is removed, the process exits; idempotent ("Daemon is not running" when none is up)
+wave daemon restart   # stop the old daemon (if any), then start a fresh one from the current CLI
+\`\`\`
+
+**After upgrading the CLI, restart the daemon** — it runs the code it was started with and will not pick up a new build on its own. This is the main reason \`restart\` exists.
+
+One-off edge: \`stop\` / \`restart\` cannot stop a daemon that predates the \`shutdown\` RPC (i.e. one still running an older build). The wait times out — \`daemon did not exit within 10000ms\` — because the old process ignores the request and the socket stays up. Kill that process yourself, then run any client subcommand (e.g. \`wave daemon list\`) to start a daemon from the current CLI; \`restart\` works normally from then on.
+
+## 2. Creating a session
+
+\`\`\`bash
+wave daemon create --worktree [name] --workdir <dir> --permission-mode bypassPermissions
+\`\`\`
+
+- Prints the new sessionId on the first line (scripts read it from there), plus a second line with the worktree path and branch when \`--worktree\` was used.
+- \`--worktree\` creates the session in a fresh git worktree, so it never touches your main checkout. The name is optional — one is generated when omitted.
+- \`--permission-mode\` defaults to \`bypassPermissions\` for daemon-created sessions, so a session created this way raises no approval prompts at all. Passing the flag explicitly is redundant but fine and self-documenting. Valid modes: \`default\`, \`bypassPermissions\`, \`acceptEdits\`, \`plan\`, \`dontAsk\`.
+- \`--workdir\` defaults to the current directory.
+
+## 3. Dispatching work and following up
+
+\`\`\`bash
+wave daemon send <sessionId> <message>                # async dispatch (the default)
+wave daemon send <sessionId> <message> --wait 600     # wait up to 600s and print the reply
+\`\`\`
+
+- The default is fire-and-forget: the command exits 0 (printing \`Sent message to session: <sessionId>\`) as soon as the message is **delivered**. On an idle session it lands in history and the turn starts; on a busy session it is queued and takes effect when the current turn finishes.
+- \`--wait <seconds>\` blocks until the reply to *that* message arrives and prints only the assistant's final reply text. On timeout it exits non-zero; if the session is stuck on a pending approval it says so and points at \`respond\`.
+- A \`send --wait\` failure of \`Message aborted before producing a reply\` means the turn was interrupted mid-generation — the message was delivered, it just never produced text.
+
+**An interrupted send is not a lost message.** If the shell or tool running \`wave daemon send\` is interrupted or times out, the message may already have been delivered and be executing in the daemon. Verify with \`wave daemon status <sessionId>\` before resending — a duplicate send duplicates the work.
+
+To block on the work instead of checking it, follow the send with \`wave daemon wait <sessionId> --from-busy\` — the flag covers the moment right after an async send where the session still reports idle (§5).
+
+## 4. Changing your mind: abort first
+
+A \`send\` to a *generating* session is queued, not applied immediately — the current turn runs to completion first. To correct a task or change its scope mid-flight:
+
+\`\`\`bash
+wave daemon abort <sessionId>     # interrupt in-flight generation (subagents, bash commands and queued messages included)
+wave daemon send <sessionId> <corrected task>
+\`\`\`
+
+\`abort\` is idempotent and a no-op on an idle session, so it is safe to run without checking first. It does not clear completed history, and it does **not** touch the session's permission mode — the session stays live in the daemon's memory.
+
+## 5. Monitoring
+
+\`\`\`bash
+wave daemon list                   # sessions currently live in the daemon's in-memory registry
+wave daemon status <sessionId>     # one session: status, pending approvals, and the last message
+wave daemon wait <sessionId>       # block until it settles, then print that same snapshot
+wave daemon status <id> --lines 0  # status line only — no message text (single-shot snapshot)
+wave daemon status <id> --lines 5  # widen the context window when the last message is not enough
+\`\`\`
+
+\`status\` reports one of three states — \`idle\`, \`generating\`, or \`waiting for approval\` (listed with the pending request ids). It is plain text; there is no \`--json\`.
+
+\`--lines N\` prints the last N messages. **The default is 1** — the last message alone — because message text is never truncated, so a single long report is already tens of thousands of characters; the default has to stay bounded. N counts messages, not output lines.
+
+- \`--lines 0\` prints no message text at all — just the header and the \`Status:\` line. Use it when a snapshot only needs the status (cheaper than pulling a report you will not read).
+- text is whitespace-collapsed, and tool-only messages print nothing (they still count toward N);
+- it is the last N **messages**, so behind a long tail of intermediate narration ("still investigating…") the final report can fall outside the window.
+
+So the final report is what the default \`status <id>\` already gives you; raise \`--lines\` only when the last message is not the report you want.
+
+**To wait for the report, use \`wave daemon wait <sessionId>\`** — do not build a polling loop. It attaches, blocks until your session settles, then prints exactly what \`status <id> --lines N\` prints, so \`msg=$(wave daemon wait <id>)\` captures the report itself. Your session's own \`loadingChange\` push is only the **wake-up**: the idle verdict is read from the daemon registry when it wakes, and the daemon broadcasts every session's notifications to every connection, so a concurrent session's push is ignored (it can neither end the wait nor count as the busy phase). Its exit code is the contract:
+
+| exit | meaning |
+| ---- | ------- |
+| \`0\` | the session went idle — the snapshot on stdout is the final report |
+| \`3\` | the session is hanging on a permission approval — the snapshot lists the pending request ids; answer them with \`respond\` (§6) and \`wait\` again |
+| \`1\` | error — daemon unreachable, unknown sessionId, the session was destroyed while you waited, or \`--timeout\` elapsed |
+
+- A session that is already idle when you call it returns \`0\` immediately (it never hangs).
+- **\`--from-busy\` for the send-then-wait race.** An async \`send\` returns as soon as the message is *delivered*, so for a moment the session still reports idle and a plain \`wait\` would return before the turn even started. \`--from-busy\` makes the wait first observe a busy phase **of that session** (its own push, or the registry reporting it as generating), then idle — a concurrent session being busy does not count.
+- \`--timeout <seconds>\` bounds the wait (default: wait forever); on expiry it exits \`1\`.
+- \`--lines N\` (default 1) and \`--lines 0\` behave exactly as in \`status\`; progress lines go to stderr, stdout carries only the snapshot.
+- **Waiting on a session someone else destroys.** If another client runs \`wave daemon destroy <id>\` while you are blocked in \`wait\` (the daemon itself staying up), the wait does not hang: it notices the session left the registry and exits \`1\` with \`Session <id> no longer exists (destroyed while waiting)\` — a gone session is never reported as finished. The daemon drops the session from its registry *before* running the teardown, so this holds for the whole destroy window (the abort that clears the loading flag cannot be mistaken for a finished turn).
+- **A re-keyed or in-place-reconfigured session is not a destroyed one.** A live session can change its id (a cleared chat mints a new one): the daemon announces it and the wait follows the *same* session on the new id instead of exiting \`1\` (\`send --wait\` follows it too, so the reply is not missed). A config reload rebuilds the session's agent in place: while that runs the session stays listed, is reported busy (never "listed + idle"), reads keep answering, and writes are refused with a retryable error — so the wait keeps waiting; only a **failed** rebuild drops the session, and then \`1\` with the same "no longer exists" error is correct.
+
+**Unattended monitoring needs no wrapper script.** Those three exits cover every way a session can end: \`0\` = finished (stdout is the report), \`3\` = blocked on an approval (go \`respond\`, then \`wait\` again), \`1\` = error, including the session being destroyed out from under you. So \`msg=$(wave daemon wait <id>)\` plus a branch on the exit code replaces the hand-rolled poller completely — there is no fourth case left to poll for.
+
+If the CLI on that host predates \`wave daemon wait\`, fall back to a **background poll** — run it in the background rather than blocking on \`send --wait\`:
+
+\`\`\`bash
+while true; do
+  out=$(wave daemon status "$SESSION_ID" --lines 0)
+  echo "$out"
+  case "$out" in
+    *"Status: idle"*|*"waiting for approval"*) break ;;
+  esac
+  sleep 30
+done
+\`\`\`
+
+That loop is a pattern to re-create per session with whatever background-execution mechanism your host offers (on Windows, PowerShell's \`Start-Sleep\` in place of \`sleep\`), and one poller per session so they do not interfere. Prefer \`wait\`: one process, no poll latency, and an exit code that tells idle (0) apart from waiting-for-approval (3) and from error (1, a destroyed session included). \`waiting for approval\` is an action signal (go answer it, §6); \`idle\` means the turn settled and is worth a look.
+
+Do not hand-parse the transcript jsonl (\`~/.wave/projects/<project>/<sessionId>.jsonl\`) to recover a report — \`status <id>\` / \`wait <id>\` are the supported paths. If you ever do read the raw file: each line is one message (\`{"timestamp":…,"role":…,"blocks":[…]}\`) and text lives in \`blocks[].content\` on the \`{"type":"text"}\` block. There is no \`blocks[].text\` field, so a lookup by \`text\` silently returns nothing and looks like "the session never reported".
+
+An \`idle\` reading can also be a transient pause between turns (waiting on a verification run, a CI job, or a pending approval). Re-check \`status\` before concluding the task is finished, and if the session goes back to \`generating\`, block on it again (or \`wait --from-busy\` if the busy phase has not started yet).
+
+## 6. Permission approvals
+
+\`\`\`bash
+wave daemon respond <sessionId> <requestId> --allow
+wave daemon respond <sessionId> <requestId> --deny --reason "why"
+wave daemon respond <sessionId> <requestId> --allow --rule "Bash(ls)"              # persist this allow rule for the session
+wave daemon respond <sessionId> <requestId> --allow --mode bypassPermissions      # switch the session's permission mode
+\`\`\`
+
+- Exactly one of \`--allow\` / \`--deny\` is required. \`respond\` validates the requestId first (\`Request not found or already handled\`) and refuses to touch another session's request.
+- \`--mode\` also applies a mode switch, so after that one answer the session stops asking. Requests already queued still need their own \`respond\`.
+- An \`acceptEdits\` session asks for approval on every shell command; approving them one at a time cannot keep up with generation. Switch the mode with \`--mode bypassPermissions\` instead of responding in a loop.
+
+**The root cause of an approval flood is a restarted daemon process.** The permission mode is not recorded in the session transcript, so when a new daemon process re-hosts a session from disk (after \`stop\` / a kill, a CLI-upgrade restart, or a machine reboot), the mode is re-derived from the current configuration — \`permissions.defaultMode\` from settings, else \`default\`. A session created with \`bypassPermissions\` therefore comes back as \`default\` and starts asking for approvals.
+
+- \`abort\` does **not** cause this: the session stays in the daemon's memory with its mode intact. If approvals suddenly flood after a long interruption, look for a daemon restart, not for \`abort\`.
+- Recovery is one command: \`respond <requestId> --allow --mode bypassPermissions\`.
+- The symptom can be masked: if the repository's settings set \`permissions.defaultMode: bypassPermissions\`, the re-derived mode is bypass anyway and you will never see the fallback.
+
+## 7. AskUserQuestion requests
+
+\`status\` renders a pending \`AskUserQuestion\` in full: every question as \`Q<i> [header] <question>\`, with its options numbered from 0. Those option numbers are what \`--answer\` accepts.
+
+\`\`\`bash
+wave daemon respond <sessionId> <requestId> --allow --answer "0"       # option 0 of the only question
+wave daemon respond <sessionId> <requestId> --allow --answer "1,0"     # one option number per question, in order
+\`\`\`
+
+The older form still works: a JSON object keyed by the full question text, with the chosen option label as the value — exactly what the GUI dialog submits:
+
+\`\`\`bash
+wave daemon respond <sessionId> <requestId> --allow --answer '{"<full question text>":"<option label>"}'
+\`\`\`
+
+Whether to answer at all depends on whether the user is around:
+
+- If the user can see the session (they have the desktop app open), do not answer for them — relay the question and let them choose.
+- If the user has explicitly handed the work over and is away ("I'm offline, it's on you"), answer with the recommended option (the first one, or an option the question marks as recommended), then report what you answered so they can override it.
+
+Answering resolves the request and the session resumes generating on its own — no extra nudge is needed, though \`status\` may briefly still read \`generating\`.
+
+## 8. Finishing: destroy, and the worktree
+
+\`\`\`bash
+wave daemon destroy <sessionId> --remove-worktree
+\`\`\`
+
+- \`destroy\` is idempotent, and does not require the session to be live in the registry.
+- \`--remove-worktree\` is **two steps**: it resolves the session's worktree from its working directory and removes it (path + branch, through the worktree-removal protocol, which also fires the WorktreeRemove hook) and then destroys the session. It refuses to remove the main working tree, so a session that was not created in a linked worktree just fails that step.
+- Because it is two steps, an interrupted \`destroy --remove-worktree\` can be **half-done**: the worktree directory, its branch and uncommitted changes are already gone while the session is still alive. After such an interruption verify all three: \`wave daemon list\` / \`status\` (is the session still there?), \`git worktree list\` and the repo's worktree directory (folder + branch), and \`~/.wave/projects/\` (transcript). A session that was killed but whose transcript survives is still recoverable from the jsonl.
+- Destroy is destructive and irreversible: confirm with the user before running it.
+
+Whose session is it? Only tear down sessions you created with \`wave daemon create\`. Never destroy a session created by the desktop app — the user may still be using it — or one you do not recognize. If you cannot tell who created it, ask.
+
+## 9. Checklist
+
+- Create with \`--worktree\` and \`--permission-mode bypassPermissions\` (the mode default is already bypass, so no approvals appear).
+- \`send\` is async by default; after any interruption, check \`status\` before resending.
+- \`abort\` before re-scoping a running session.
+- Read the final report by blocking: \`wave daemon wait <id>\` (exit 0 = idle, 3 = stuck on an approval, 1 = error — session unknown or destroyed mid-wait; defaults to the last message, raise \`--lines\` if that one is not it). Use \`status <id>\` when you want a snapshot without blocking.
+- To watch a session unattended, loop on \`wait\` and branch on its exit code — no shell polling script to maintain (§5).
+- An approval flood means the daemon process restarted and the mode fell back — recover with \`--mode bypassPermissions\`.
+- After a CLI upgrade, \`wave daemon restart\` (kill the old process first if \`restart\` times out).
+- \`destroy --remove-worktree\` last, after user confirmation, only for sessions you created.
+- Sessions the desktop app manages churn quickly on their own; a shifting \`wave daemon list\` is normal, not a fault.
+`,
+};

package/dist/constants/images.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Outbound image dimension budget: the per-side pixel ceiling we deliberately
+ * keep every image under, aligned with Claude Code's `IMAGE_MAX_WIDTH` /
+ * `IMAGE_MAX_HEIGHT`.
+ *
+ * Two gates enforce it and they must agree on the number:
+ *
+ * - the webview paste path (`packages/webview/src/utils/imageValidation.ts`)
+ *   downsamples an oversized paste in the browser, before it becomes a message;
+ * - the SDK's outbound rewrite pass (`utils/imageRewrite.ts`, via sharp) is the
+ *   catch-all for every other source (Read tool, file paths, hosts that cannot
+ *   re-encode).
+ *
+ * The value lives here rather than in `utils/imageBudget.ts` because the
+ * webview is a browser bundle: by contract it may only take *values* from
+ * `wave-agent-sdk/constants`, and `utils/*` is not a public subpath. Copying
+ * `2000` into the webview would let the two gates drift apart silently — the
+ * paste would shrink to one number while the SDK judged by another.
+ *
+ * Not to be confused with the gateway's *hard* bound: `MAX_IMAGE_DIMENSION_PX`
+ * in `utils/imageDimensions.ts` (8192px per side) is where the upstream starts
+ * rejecting the whole request with `HTTP 400 ... unsupported image`. That one is
+ * an immovable external limit; this one is our own conservative budget and can
+ * be raised freely when we want more image fidelity.
+ */
+export declare const OUTBOUND_IMAGE_MAX_DIMENSION_PX = 2000;

package/dist/constants/images.js

@@ -0,0 +1,26 @@
+/**
+ * Outbound image dimension budget: the per-side pixel ceiling we deliberately
+ * keep every image under, aligned with Claude Code's `IMAGE_MAX_WIDTH` /
+ * `IMAGE_MAX_HEIGHT`.
+ *
+ * Two gates enforce it and they must agree on the number:
+ *
+ * - the webview paste path (`packages/webview/src/utils/imageValidation.ts`)
+ *   downsamples an oversized paste in the browser, before it becomes a message;
+ * - the SDK's outbound rewrite pass (`utils/imageRewrite.ts`, via sharp) is the
+ *   catch-all for every other source (Read tool, file paths, hosts that cannot
+ *   re-encode).
+ *
+ * The value lives here rather than in `utils/imageBudget.ts` because the
+ * webview is a browser bundle: by contract it may only take *values* from
+ * `wave-agent-sdk/constants`, and `utils/*` is not a public subpath. Copying
+ * `2000` into the webview would let the two gates drift apart silently — the
+ * paste would shrink to one number while the SDK judged by another.
+ *
+ * Not to be confused with the gateway's *hard* bound: `MAX_IMAGE_DIMENSION_PX`
+ * in `utils/imageDimensions.ts` (8192px per side) is where the upstream starts
+ * rejecting the whole request with `HTTP 400 ... unsupported image`. That one is
+ * an immovable external limit; this one is our own conservative budget and can
+ * be raised freely when we want more image fidelity.
+ */
+export const OUTBOUND_IMAGE_MAX_DIMENSION_PX = 2000;

package/dist/constants/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Constants entry (`wave-agent-sdk/constants`).
+ *
+ * Hosts that drive the agent over JSON-RPC import shared values from here rather
+ * than from the SDK barrel: the barrel pulls in the whole agent runtime,
+ * including dependencies that do work while their module body evaluates and can
+ * therefore take a host down at load time. Every module re-exported below must
+ * stay dependency-free so this entry remains cheap to bundle.
+ */
+export * from "./images.js";
+export * from "./memory.js";
+export * from "./messages.js";
+export * from "./plugins.js";
+export * from "./subagents.js";
+export * from "./toolLimits.js";
+export * from "./tools.js";

package/dist/constants/index.js

@@ -0,0 +1,16 @@
+/**
+ * Constants entry (`wave-agent-sdk/constants`).
+ *
+ * Hosts that drive the agent over JSON-RPC import shared values from here rather
+ * than from the SDK barrel: the barrel pulls in the whole agent runtime,
+ * including dependencies that do work while their module body evaluates and can
+ * therefore take a host down at load time. Every module re-exported below must
+ * stay dependency-free so this entry remains cheap to bundle.
+ */
+export * from "./images.js";
+export * from "./memory.js";
+export * from "./messages.js";
+export * from "./plugins.js";
+export * from "./subagents.js";
+export * from "./toolLimits.js";
+export * from "./tools.js";

package/dist/constants/memory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Auto-memory taxonomy and entrypoint limits.
+ *
+ * The entrypoint (`MEMORY.md`) is an index that is always loaded into the
+ * conversation context, so it needs a hard size bound. A line cap alone does
+ * not provide one: a 200-line index of very long lines was observed at close
+ * to 200 KB. Both caps apply and the tighter one wins.
+ *
+ * Aligned with Claude Code's `memdir/memdir.ts` (MAX_ENTRYPOINT_LINES /
+ * MAX_ENTRYPOINT_BYTES); the second bound is counted in characters, not bytes
+ * — Claude Code's constant carries the BYTES name but its value is derived
+ * from "~125 chars/line at 200 lines" and is compared against `String.length`.
+ */
+export declare const MEMORY_ENTRYPOINT_NAME = "MEMORY.md";
+export declare const MAX_MEMORY_ENTRYPOINT_LINES = 200;
+export declare const MAX_MEMORY_ENTRYPOINT_CHARS = 25000;
+/** Recommended per-line length for `MEMORY.md` index entries. */
+export declare const MEMORY_INDEX_LINE_GUIDANCE_CHARS = 150;
+export declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+/**
+ * Parse a raw frontmatter value into a MemoryType. Invalid or missing values
+ * return undefined — files written before the taxonomy existed keep working
+ * and unknown types degrade gracefully.
+ */
+export declare function parseMemoryType(raw: unknown): MemoryType | undefined;

package/dist/constants/memory.js

@@ -0,0 +1,34 @@
+/**
+ * Auto-memory taxonomy and entrypoint limits.
+ *
+ * The entrypoint (`MEMORY.md`) is an index that is always loaded into the
+ * conversation context, so it needs a hard size bound. A line cap alone does
+ * not provide one: a 200-line index of very long lines was observed at close
+ * to 200 KB. Both caps apply and the tighter one wins.
+ *
+ * Aligned with Claude Code's `memdir/memdir.ts` (MAX_ENTRYPOINT_LINES /
+ * MAX_ENTRYPOINT_BYTES); the second bound is counted in characters, not bytes
+ * — Claude Code's constant carries the BYTES name but its value is derived
+ * from "~125 chars/line at 200 lines" and is compared against `String.length`.
+ */
+export const MEMORY_ENTRYPOINT_NAME = "MEMORY.md";
+export const MAX_MEMORY_ENTRYPOINT_LINES = 200;
+export const MAX_MEMORY_ENTRYPOINT_CHARS = 25000;
+/** Recommended per-line length for `MEMORY.md` index entries. */
+export const MEMORY_INDEX_LINE_GUIDANCE_CHARS = 150;
+export const MEMORY_TYPES = [
+    "user",
+    "feedback",
+    "project",
+    "reference",
+];
+/**
+ * Parse a raw frontmatter value into a MemoryType. Invalid or missing values
+ * return undefined — files written before the taxonomy existed keep working
+ * and unknown types degrade gracefully.
+ */
+export function parseMemoryType(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    return MEMORY_TYPES.find((t) => t === raw);
+}

package/dist/constants/messages.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 插件变更提示的逐字文案（docs/specs/ecosystem/plugin.md「插件变更提示」）。
+ * 宿主端共用以免文案漂移（JetBrains 侧是逐字一致的 Kotlin 常量副本）；两条都是
+ * 中性提示，不占成功 / 失败语义色。
+ *
+ * 放在 `constants/` 而非 pluginManager：宿主只需要这两行文案，插件重载本身跑在
+ * CLI 子进程里（宿主不加载 `PluginManager`）。从 SDK 桶入口取文案会把整个 agent
+ * 运行时——连同会在模块求值期抛错的依赖——一起打进宿主 bundle。
+ */
+export declare const PLUGIN_CHANGE_PENDING_MESSAGE = "\u63D2\u4EF6\u5DF2\u53D8\u66F4\u3002\u8FD0\u884C /reload-plugins \u4F7F\u5176\u751F\u6548\u3002";
+export declare const PLUGIN_RELOADED_MESSAGE = "\u63D2\u4EF6\u5DF2\u91CD\u8F7D\u3002";

package/dist/constants/messages.js

@@ -0,0 +1,11 @@
+/**
+ * 插件变更提示的逐字文案（docs/specs/ecosystem/plugin.md「插件变更提示」）。
+ * 宿主端共用以免文案漂移（JetBrains 侧是逐字一致的 Kotlin 常量副本）；两条都是
+ * 中性提示，不占成功 / 失败语义色。
+ *
+ * 放在 `constants/` 而非 pluginManager：宿主只需要这两行文案，插件重载本身跑在
+ * CLI 子进程里（宿主不加载 `PluginManager`）。从 SDK 桶入口取文案会把整个 agent
+ * 运行时——连同会在模块求值期抛错的依赖——一起打进宿主 bundle。
+ */
+export const PLUGIN_CHANGE_PENDING_MESSAGE = "插件已变更。运行 /reload-plugins 使其生效。";
+export const PLUGIN_RELOADED_MESSAGE = "插件已重载。";

package/dist/constants/plugins.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Plugin system constants.
+ */
+/**
+ * Version assumed when a plugin manifest omits `version` (spec plugin A-022).
+ * Install and load must agree on it: a manifest that installs must also load.
+ */
+export declare const DEFAULT_PLUGIN_VERSION = "1.0.0";

package/dist/constants/plugins.js

@@ -0,0 +1,8 @@
+/**
+ * Plugin system constants.
+ */
+/**
+ * Version assumed when a plugin manifest omits `version` (spec plugin A-022).
+ * Install and load must agree on it: a manifest that installs must also load.
+ */
+export const DEFAULT_PLUGIN_VERSION = "1.0.0";

package/dist/constants/tools.d.ts

@@ -23,3 +23,4 @@ export declare const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
 export declare const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
 export declare const WORKFLOW_TOOL_NAME = "Workflow";
 export declare const ARTIFACT_TOOL_NAME = "Artifact";
+export declare const EXEC_TOOL_NAME = "Exec";

package/dist/constants/tools.js

@@ -23,3 +23,4 @@ export const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
 export const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
 export const WORKFLOW_TOOL_NAME = "Workflow";
 export const ARTIFACT_TOOL_NAME = "Artifact";
+export const EXEC_TOOL_NAME = "Exec";