dsh-packycode-api 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.1.3
+
+- **Plan review when the CLI has no ExitPlanMode.** Print mode often does not offer that tool, so a plan-mode turn wrote `~/.dsh/packycode-claude-cli/plans/*.md` and came back as ordinary text. A plan file written during the run is now submitted through DSH's `exit_plan_mode` when the CLI returns. An older file in that directory is ignored.
+
+## 1.1.2
+
+- **Claude CLI follows DSH plan mode.** While the current session's plan mode is on (including a selection that applies on this step but is not logged yet), a Claude model turn and the `claude_code` tool run the local CLI with `--permission-mode plan`. That wins over the session permission preset and over an explicit `claudeCliMode` pin. The CLI may explore read-only; other permission prompts are denied, and after eight denials the run stops instead of hanging. `ExitPlanMode` is never allowed inside the CLI process. A submitted plan becomes the assistant's `exit_plan_mode` tool call, so DSH's existing review approves it and the next step implements. The delegation tool returns the plan text for the parent model to submit. Session titles stay read-only. A host without the plan-mode service behaves as before.
+
 ## 1.1.1
 
 - **Claude CLI search through MCP.** CLI-backed Claude turns and the `claude_code` delegation tool now get a temporary, authenticated, loopback HTTP MCP `web_search` tool calling the plugin's selected DeepSeek/GPT backend. Native CLI `WebSearch` is explicitly denied in every permission mode: it makes a separate Claude server-tool request that PackyCode can refuse even when ordinary turns work. The official CLI/system identity is preserved; no vendor headers or identities are forged. Backend selection applies to CLI searches even when DSH routing is set to Off/Do not take over; the DSH routing mode remains independent, and headless profiles need no `web` service. MCP callbacks capture their originating session ID before losing agent context and always call the direct PackyCode provider, never an auto-router fallback.

package/README.en.md

@@ -44,7 +44,7 @@ Open the desktop application's **Plugins** page, click **Add plugin**, and enter
 dsh-packycode-api
 ```
 
-Choose the **official** install source, then click **Install**. To pin a version, enter `dsh-packycode-api@1.1.1`.
+Choose the **official** install source, then click **Install**. To pin a version, enter `dsh-packycode-api@1.1.3`.
 
 Then **manually restart the desktop application**. Refreshing the page does not reload the plugin inside the Host process.
 
@@ -63,7 +63,7 @@ Choose a model from the `PackyCode` group. `deepseek-flash`, `gpt-6.1-sol`, and
 
 The **Plugins** page shows the installed state and version, and is also where you enable, disable, or uninstall.
 
-**For non-desktop profiles only:** `dsh plugin --profile <name> add dsh-packycode-api@1.1.1`. Do not use it for `desktop` — the CLI refuses it (`profile "desktop" is managed exclusively by the Electron application`).
+**For non-desktop profiles only:** `dsh plugin --profile <name> add dsh-packycode-api@1.1.3`. Do not use it for `desktop` — the CLI refuses it (`profile "desktop" is managed exclusively by the Electron application`).
 
 A local checkout can be linked with `dsh plugin --profile <name> add link:/path/to/dsh-packycode-api`.
 
@@ -153,14 +153,14 @@ A model in the list does not mean the current token group allows it. When changi
 - The `cc` group accepts only the official Claude CLI. A normal API client gets `403 This API endpoint is only accessible via the official Claude CLI`. This plugin runs the local `claude` binary for that group instead of switching the token to `cc-sale` or pretending to be the official client. If the token has no group the official CLI may use, the three Claude models still will not run.
 - Selecting a Claude model when the CLI is missing fails that turn with an install hint. It does not surface as a missing binary name alone.
 - The CLI receives this plugin's endpoint and current key (`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN`) and an isolated config directory, `~/.dsh/packycode-claude-cli`. Without that isolation, `env` in `~/.claude/settings.json` would override the plugin key.
-- CLI permission follows the session by default: `read-only` stays read-only, `workspace-write` may edit, and `danger-full-access` with approval disabled may use `full`. The CLI cannot ask the DSH user for approval, so a session that still asks never gets `full`. `claudeCliMode` can pin `read-only`, `edit`, or `full`. An empty `claudeCliPath` is looked up automatically; an empty `claudeCliCwd` uses the session workspace.
+- CLI permission follows the session by default: `read-only` stays read-only, `workspace-write` may edit, and `danger-full-access` with approval disabled may use `full`. The CLI cannot ask the DSH user for approval, so a session that still asks never gets `full`. `claudeCliMode` can pin `read-only`, `edit`, or `full`. DSH plan mode wins over that mapping and over the pin: the CLI runs with `--permission-mode plan`. Calling `ExitPlanMode`, or returning after writing the plan file when that tool is absent, submits the plan to DSH's review instead of editing in the same process. The previous mode returns after approval or `/plan off`. Session titles stay out of plan mode. An empty `claudeCliPath` is looked up automatically; an empty `claudeCliCwd` uses the session workspace.
 - Thinking and tool activity (`▸ Bash`, `▸ Read`, and `✗` on failure) appear in that turn's reasoning block. They are progress, not DSH tool calls. The CLI's own tools are outside the DSH sandbox.
 - The reasoning block opens with `▸ 启动 Claude Code CLI…` and then shows the CLI's version and model once it is up. When the gateway throttles or is busy (429, 503 `账号并发排队已满` / per-account wait queue full, and similar), the CLI retries up to 10 times on its own; each retry now shows as `↻ 网关返回 HTTP 503，CLI 自动重试 n/10` instead of looking hung. When the retries run out, the turn says PackyCode's Claude upstream is busy, not that the key is bad. A CLI that prints nothing for 2 minutes after starting is stopped and reported.
 - The conversation and its images reach the CLI over stdin (`--input-format stream-json`), not argv: a Windows command line is length-limited and cannot carry an image. Images in the conversation are sent to Claude as images, at the HTTP route's request size (at most 2048×2048, about 1 MiB each; at most 20 images and 20 MiB per turn, dropping the oldest first). An image left out is named with its read-only local copy, which the CLI can open with Read.
 - Every run carries `--append-system-prompt` (the delegation note). In `-p` mode the official CLI introduces itself as "You are Claude Code, Anthropic's official CLI for Claude …" when it has appended instructions and as "You are a Claude agent, built on Anthropic's Claude Agent SDK." when it has none; the latter was refused upstream as not coming from the official CLI (403 `only accepts requests from the official Claude Code CLI`). That is the official CLI's own behavior; the plugin does not rewrite its system prompt.
 - While the session model is a Claude model, titles are generated with `claude-haiku-5-5`, read-only, in a temporary directory, instead of a full Opus turn.
 - While the session model is `gpt-6-astra`, titles are generated with `gpt-6.1-sol` (same Codex group); the turns themselves stay on Astra. Other models title their own sessions.
-- The `claude_code` tool can delegate one task to the local CLI while the session model is `gpt-6.1-sol`, `gpt-6-astra`, or `deepseek-flash`. The requested `mode` cannot exceed what the session preset allows.
+- The `claude_code` tool can delegate one task to the local CLI while the session model is `gpt-6.1-sol`, `gpt-6-astra`, or `deepseek-flash`. The requested `mode` cannot exceed what the session preset allows. While the session is in plan mode the delegation plans too, and returns the plan text to the parent model.
 - An effort level the model does not support is rejected before the request is sent. Do not edit a model's effort map casually.
 
 </details>

package/README.md

@@ -48,7 +48,7 @@
 dsh-packycode-api
 ```
 
-在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.1.1`。
+在**安装源**中选择**官方源**，然后点击**安装**。需要固定版本时填入 `dsh-packycode-api@1.1.3`。
 
 完成后**手动重启桌面应用**。仅刷新页面不会重新加载 Host 里的插件。
 
@@ -67,7 +67,7 @@ dsh-packycode-api
 
 桌面应用的**插件**页可以看到已安装状态与版本，也可以在那里启用、停用或卸载。
 
-**仅用于非 desktop profile：** `dsh plugin --profile <name> add dsh-packycode-api@1.1.1`。不要对 `desktop` 使用它 —— CLI 会直接拒绝（`profile "desktop" is managed exclusively by the Electron application`）。
+**仅用于非 desktop profile：** `dsh plugin --profile <name> add dsh-packycode-api@1.1.3`。不要对 `desktop` 使用它 —— CLI 会直接拒绝（`profile "desktop" is managed exclusively by the Electron application`）。
 
 本地开发可以用绝对路径：`dsh plugin --profile <name> add link:/path/to/dsh-packycode-api`。
 
@@ -157,14 +157,14 @@ Claude Code CLI → 本机临时 MCP web_search → 插件选定的 DeepSeek/GPT
 - `cc`（Claude Code 专用）只接受官方 Claude CLI。用普通 API 客户端调 Claude 会 403：`This API endpoint is only accessible via the official Claude CLI`。本插件因此调用本机 `claude`，而不是改去 `cc-sale`，也不是伪造客户端身份。令牌如果没有开放给官方 CLI 的分组，这三个模型仍然不可用。
 - 选了 Claude 模型但本机没有 CLI 时，这一回合会直接说明未安装，并指向设置页的安装按钮。
 - CLI 使用插件配置的地址和当前 Key（`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN`），以及独立配置目录 `~/.dsh/packycode-claude-cli`。不隔离的话，`~/.claude/settings.json` 里的 `env` 会盖掉插件 Key。
-- CLI 权限默认跟随当前会话：`read-only` → 只读，`workspace-write` → 可编辑，`danger-full-access` 且不再审批 → `full`。CLI 不能向 DSH 弹审批，所以只要会话还要审批，就不会给它 `full`。也可把设置项 `claudeCliMode` 固定成 `read-only` / `edit` / `full`。`claudeCliPath` 留空则自动查找；`claudeCliCwd` 留空则用当前会话工作区。
+- CLI 权限默认跟随当前会话：`read-only` → 只读，`workspace-write` → 可编辑，`danger-full-access` 且不再审批 → `full`。CLI 不能向 DSH 弹审批，所以只要会话还要审批，就不会给它 `full`。也可把设置项 `claudeCliMode` 固定成 `read-only` / `edit` / `full`。DSH 计划模式优先于该映射和这个固定档：CLI 以 `--permission-mode plan` 只读探索。它调用 `ExitPlanMode`，或在没有该工具时把计划写进计划文件后返回，都会交给 DSH 审阅；批准或 `/plan off` 之后才恢复原来的档位。会话标题不进入计划模式。`claudeCliPath` 留空则自动查找；`claudeCliCwd` 留空则用当前会话工作区。
 - 思考过程和工具调用（`▸ Bash`、`▸ Read`，失败时带 `✗`）会出现在这一回合的思考区。它们是进度，不是 DSH 的工具调用。CLI 自己的工具不受 DSH 沙箱约束。
 - 思考区第一行是「▸ 启动 Claude Code CLI…」，CLI 起来后显示版本和模型。网关限流或繁忙（429、503 `账号并发排队已满` 等）时，CLI 会自己重试最多 10 次，每次重试都会显示成 `↻ 网关返回 HTTP 503，CLI 自动重试 n/10`，不再像卡住。重试用完仍失败时，会说明是 PackyCode 的 Claude 上游繁忙，不是 Key 的问题。CLI 启动后 2 分钟内没有任何输出会被停止并报告原因。
 - 对话记录和图片通过 stdin 交给 CLI（`--input-format stream-json`），不走命令行参数：Windows 命令行长度有上限，而且命令行带不了图片。对话里的图片会以图片形式发给 Claude（与 HTTP 路由相同的压缩规格：每张不超过 2048×2048、约 1 MiB；一回合最多 20 张、合计 20 MiB，超出时先舍弃最早的）。没随消息发出的图片会写明本机只读副本的路径，CLI 需要时可以用 Read 读取。
 - 每次运行都带 `--append-system-prompt`（委派说明）。在 `-p` 模式下，官方 CLI 有追加说明时会以 "You are Claude Code, Anthropic's official CLI for Claude …" 自我介绍，没有时是 "You are a Claude agent, built on Anthropic's Claude Agent SDK."；后者曾被上游当成非官方 CLI 拒绝（403 `only accepts requests from the official Claude Code CLI`）。这是官方 CLI 自己的行为，插件没有改写它的系统提示词。
 - 会话跑在 Claude 模型上时，生成标题改用 `claude-haiku-5-5`，只读、临时目录，避免为起标题跑一整轮 Opus。
 - 会话跑在 `gpt-6-astra` 上时，标题改由 `gpt-6.1-sol` 生成（同一个 Codex 分组）；对话本身仍然用 Astra。其它模型的标题由会话模型自己生成。
-- 另有 `claude_code` 工具：当前模型是 `gpt-6.1-sol`、`gpt-6-astra` 或 `deepseek-flash` 时，可以把一个任务委派给本机 Claude Code。请求的 `mode` 不会超过会话权限允许的上限。
+- 另有 `claude_code` 工具：当前模型是 `gpt-6.1-sol`、`gpt-6-astra` 或 `deepseek-flash` 时，可以把一个任务委派给本机 Claude Code。请求的 `mode` 不会超过会话权限允许的上限；会话处于计划模式时，这个委派也只规划，并把计划正文交回父模型。
 - 声明了模型不支持的推理档位会被 harness 在发请求前拒绝，不要随手改档位映射。
 
 </details>

package/lib/index.js

@@ -1,10 +1,10 @@
 import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
-import { isAbsolute, join, posix, win32 } from "node:path";
+import { isAbsolute, join, posix, sep, win32 } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { HarnessError, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -1427,10 +1427,10 @@ const plainDescription = (part) => part.kind === "image" ? `[图片 ${attachment
 * @param cwd - the working directory the CLI will run in, when known.
 * @returns the instructions text.
 */
-function delegationInstructions(options, cwd) {
+function delegationInstructions(options, cwd, { plan = false } = {}) {
 	const system = typeof options?.system === "string" && options.system.trim() !== "" ? options.system.trim() : "";
 	return [
-		"本回合由 DeepSeek Harness 委派给 Claude Code 执行。用户消息是 DeepSeek Harness 会话的近期对话记录，最后一条是当前请求；其中的图片已作为图片随消息附上，「只读副本」路径也可以用 Read 工具读取。请用你自己的工具完成任务，直接输出最终结果；不要反问、不要复述流程。",
+		plan ? "本回合 DeepSeek Harness 处于计划模式。只做只读探索，把完整实施计划写成以一级标题开头的 Markdown，写入 CLI 指定的计划文件。若有 ExitPlanMode 就调用它；没有也在写完后停下来。不要修改项目、不要开始实施。DeepSeek Harness 会用这份计划打开审阅。用户消息是 DeepSeek Harness 会话的近期对话记录，最后一条是当前请求；其中的图片已作为图片随消息附上，「只读副本」路径也可以用 Read 工具读取。" : "本回合由 DeepSeek Harness 委派给 Claude Code 执行。用户消息是 DeepSeek Harness 会话的近期对话记录，最后一条是当前请求；其中的图片已作为图片随消息附上，「只读副本」路径也可以用 Read 工具读取。请用你自己的工具完成任务，直接输出最终结果；不要反问、不要复述流程。",
 		cwd === void 0 ? void 0 : `工作目录：${cwd}`,
 		system === "" ? void 0 : `补充说明（来自 DeepSeek Harness，其中提到的工具你未必拥有）：${system.slice(0, 2e3)}`
 	].filter((part) => part !== void 0).join("\n");
@@ -1642,6 +1642,34 @@ function createBlockWriter() {
 			if (open?.kind === "reasoning") open.sealed = false;
 			yield* write("reasoning", `${separator}${line}`);
 		},
+		/** One complete tool call after whatever text or reasoning is open. */
+		*toolCall(id, name, args) {
+			yield* close();
+			index += 1;
+			const block = {
+				type: "tool-call",
+				id,
+				name,
+				arguments: args
+			};
+			yield {
+				type: "block-start",
+				index,
+				blockType: "tool-call"
+			};
+			yield {
+				type: "tool-call-delta",
+				index,
+				id,
+				name,
+				argumentsDelta: args
+			};
+			yield {
+				type: "block-end",
+				index,
+				block
+			};
+		},
 		close
 	};
 }
@@ -1706,15 +1734,16 @@ async function cliCall(options, { titleModel, cwdOf, modeOf, attachmentsOf, imag
 		cwd: tmpdir()
 	};
 	const cwd = cwdOf();
+	const mode = modeOf();
 	return {
 		content: await buildDelegatedContent(options, {
 			attachments: attachmentsOf(),
 			limits: imageLimits,
 			signal: options?.signal
 		}),
-		appendSystemPrompt: delegationInstructions(options, cwd),
+		appendSystemPrompt: delegationInstructions(options, cwd, { plan: mode === "plan" }),
 		model: options.model,
-		mode: modeOf(),
+		mode,
 		cwd
 	};
 }
@@ -1816,6 +1845,8 @@ function createClaudeCliAdapter({ inner, runner, modelIds = CLI_BACKED_MODEL_IDS
 		let retries = 0;
 		/** The key this run uses, as the runner described it (never the token). */
 		let runKey;
+		/** Set when the CLI submitted a plan; the turn then ends as DSH's review tool. */
+		let submittedPlan;
 		try {
 			let finished;
 			let lastRequest;
@@ -1858,11 +1889,26 @@ function createClaudeCliAdapter({ inner, runner, modelIds = CLI_BACKED_MODEL_IDS
 				case "request-usage":
 					lastRequest = event.usage;
 					break;
+				case "plan":
+					if (typeof event.plan === "string" && event.plan !== "") submittedPlan = event.plan;
+					break;
 				case "result":
 					finished = event.result;
 					break;
 				default: break;
 			}
+			if (submittedPlan !== void 0) {
+				yield* blocks.toolCall(`plan-${randomUUID()}`, "exit_plan_mode", JSON.stringify({ plan: submittedPlan }));
+				yield {
+					type: "usage",
+					usage: turnUsage(lastRequest, finished)
+				};
+				yield {
+					type: "finish",
+					reason: { kind: "tool-calls" }
+				};
+				return;
+			}
 			yield* blocks.close();
 			yield {
 				type: "usage",
@@ -2098,7 +2144,12 @@ const CLAUDE_CLI_MODES = Object.freeze({
 		"Write",
 		"NotebookEdit"
 	]) }),
-	full: Object.freeze({ skipPermissions: true })
+	full: Object.freeze({ skipPermissions: true }),
+	/**
+	* DSH plan mode. Not a permission rank: file edits stay blocked, and
+	* `ExitPlanMode` is handed back to DSH instead of letting the CLI implement.
+	*/
+	plan: Object.freeze({ permissionMode: "plan" })
 });
 const DEFAULT_CLAUDE_MODE = "edit";
 /** Isolated CLI home; the plugin owns the endpoint and key it runs with. */
@@ -2279,11 +2330,128 @@ function buildClaudeArgs({ mode = DEFAULT_CLAUDE_MODE, model, stream = false, ap
 	if (searchBridge !== void 0 && (!/^mcp__packycode_search_[a-f0-9]+__web_search$/u.test(searchBridge.toolName ?? "") || typeof searchBridge.configPath !== "string")) throw new Error("PackyCode CLI search bridge configuration is invalid");
 	args.push("--append-system-prompt", searchBridge === void 0 ? instructions : `${instructions}\n\n${searchBridge.instructions}`);
 	if (spec.skipPermissions === true) args.push("--dangerously-skip-permissions");
-	else args.push("--allowedTools", ...spec.allowedTools, ...searchBridge === void 0 ? [] : [searchBridge.toolName]);
+	else if (typeof spec.permissionMode === "string") {
+		args.push("--permission-mode", spec.permissionMode);
+		if (searchBridge !== void 0) args.push("--allowedTools", searchBridge.toolName);
+	} else args.push("--allowedTools", ...spec.allowedTools, ...searchBridge === void 0 ? [] : [searchBridge.toolName]);
 	if (disableNativeSearch || searchBridge !== void 0) args.push("--disallowedTools", "WebSearch");
 	if (searchBridge !== void 0) args.push("--mcp-config", searchBridge.configPath);
 	return args;
 }
+/** How many permission prompts one plan-mode run will refuse before stopping. */
+const MAX_PLAN_DENIALS = 8;
+/** A plan file larger than this is not read into the turn. */
+const PLAN_FILE_MAX_BYTES = 2e5;
+const PLAN_FILE_CLOCK_SKEW_MS = 2e3;
+const PLAN_EXIT_DENY = "Write the plan to the plan file first, starting with a # heading, then call ExitPlanMode again.";
+const PLAN_ACTION_DENY = "Plan mode is active. Do not edit files or run commands that change the system. Continue read-only exploration, write the plan file, and call ExitPlanMode.";
+const PLAN_DIALOG_ERROR = "Plan mode cannot ask the user from the CLI. Decide and continue, or call ExitPlanMode.";
+const PLAN_DENY_LIMIT_MESSAGE = "claude_code plan mode stopped after too many denied permission prompts";
+/**
+* Markdown DSH's `exit_plan_mode` will accept. A body without a heading gets
+* one, because the review tool requires the plan to start with `#`.
+* @param value - candidate plan text.
+* @returns the plan, or undefined when there is nothing to submit.
+*/
+function planMarkdown(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	if (trimmed === "") return void 0;
+	const bounded = trimmed.length > PLAN_FILE_MAX_BYTES ? trimmed.slice(0, PLAN_FILE_MAX_BYTES) : trimmed;
+	return /^#\s+\S/u.test(bounded) ? bounded : `# Plan\n\n${bounded}`;
+}
+/** Whether `file` is the root itself or a path inside it, after resolving links. */
+function pathInside(root, file, realpath) {
+	let rootReal;
+	let fileReal;
+	try {
+		rootReal = realpath(root);
+		fileReal = realpath(file);
+	} catch {
+		return false;
+	}
+	const prefix = rootReal.endsWith(sep) ? rootReal : `${rootReal}${sep}`;
+	return fileReal === rootReal || fileReal.startsWith(prefix);
+}
+/**
+* The plan a CLI `ExitPlanMode` request is submitting.
+*
+* The tool's own schema does not carry the plan; the CLI injects `plan` and
+* `planFilePath` from the file it told the model to write. Text on the request
+* wins. A path is read only when it resolves inside this run's config home or
+* `~/.claude/plans`, is a markdown file written for this run, and is bounded.
+* Anything else is ignored — a model-supplied path is not a licence to read
+* the disk.
+* @param input - the control request's `input`.
+* @param options - config home, when the run started, and file-system seams.
+* @returns plan markdown, or undefined when the request has none yet.
+*/
+function readSubmittedPlan(input, { configDir, startedAt = Date.now(), home = homedir(), readFile = (file) => readFileSync(file, "utf8"), stat = statSync, realpath = realpathSync } = {}) {
+	const inline = planMarkdown(input?.plan);
+	if (inline !== void 0) return inline;
+	const requested = typeof input?.planFilePath === "string" ? input.planFilePath : "";
+	if (requested === "") return void 0;
+	if (![configDir, join(home, ".claude", "plans")].filter((root) => typeof root === "string" && root !== "").some((root) => pathInside(root, requested, realpath))) return void 0;
+	let file;
+	try {
+		file = realpath(requested);
+		const info = stat(file);
+		if (!info.isFile() || info.size > PLAN_FILE_MAX_BYTES || info.mtimeMs < startedAt - PLAN_FILE_CLOCK_SKEW_MS) return void 0;
+	} catch {
+		return;
+	}
+	if (!file.toLowerCase().endsWith(".md")) return void 0;
+	try {
+		return planMarkdown(readFile(file));
+	} catch {
+		return;
+	}
+}
+/**
+* The plan file a print-mode CLI wrote and then returned without calling
+* `ExitPlanMode`. `-p` often has no interactive plan tool, so the file is
+* what DSH reviews. Only a markdown file under this run's config `plans`
+* directory or `~/.claude/plans`, newer than the run, is eligible. The newest
+* one wins.
+* @param options - config home, when the run started, and file-system seams.
+* @returns plan markdown, or undefined when this run wrote none.
+*/
+function findPlanWrittenDuringRun({ configDir, startedAt = Date.now(), home = homedir(), readdir = readdirSync, readFile = (file) => readFileSync(file, "utf8"), stat = statSync, realpath = realpathSync } = {}) {
+	const roots = [typeof configDir === "string" && configDir !== "" ? join(configDir, "plans") : "", join(home, ".claude", "plans")].filter((root) => root !== "");
+	let newest;
+	let newestMtime = -Infinity;
+	for (const root of roots) {
+		let names;
+		try {
+			names = readdir(root);
+		} catch {
+			continue;
+		}
+		for (const name of names) {
+			if (typeof name !== "string" || !name.toLowerCase().endsWith(".md")) continue;
+			const candidate = join(root, name);
+			let info;
+			try {
+				info = stat(candidate);
+			} catch {
+				continue;
+			}
+			if (!info.isFile() || info.mtimeMs < startedAt - PLAN_FILE_CLOCK_SKEW_MS || info.mtimeMs < newestMtime) continue;
+			const text = readSubmittedPlan({ planFilePath: candidate }, {
+				configDir,
+				startedAt,
+				home,
+				readFile,
+				stat,
+				realpath
+			});
+			if (text === void 0) continue;
+			newest = text;
+			newestMtime = info.mtimeMs;
+		}
+	}
+	return newest;
+}
 /**
 * Build what the CLI reads from stdin for one run.
 *
@@ -2557,13 +2725,16 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 		if (disposed || signal?.aborted) throw new Error("claude_code was aborted");
 		const cancellation = new AbortController();
 		const runSignal = signal === void 0 ? cancellation.signal : AbortSignal.any([signal, cancellation.signal]);
+		const startedAt = Date.now();
 		const state = {
 			stdout: "",
 			stderr: "",
 			timedOut: false,
 			silent: false,
 			sawOutput: false,
-			settled: false
+			settled: false,
+			denies: 0,
+			startedAt
 		};
 		let child;
 		let bridge;
@@ -2704,12 +2875,126 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 			}
 			child.stdout?.setEncoding?.("utf8");
 			child.stderr?.setEncoding?.("utf8");
+			let controlBuffer = "";
+			let stdinEnded = false;
+			const endStdin = () => {
+				if (stdinEnded) return;
+				stdinEnded = true;
+				try {
+					child.stdin?.end?.();
+				} catch {}
+			};
+			const writeStdin = (frame) => {
+				try {
+					child.stdin?.write?.(frame);
+				} catch {}
+			};
+			const controlResponse = (requestId, response) => {
+				writeStdin(`${JSON.stringify({
+					type: "control_response",
+					response: {
+						subtype: "success",
+						request_id: requestId,
+						response
+					}
+				})}\n`);
+			};
+			const stopForDenials = () => {
+				state.denyExhausted = true;
+				endStdin();
+				kill();
+			};
+			const refuseControl = (requestId, kind) => {
+				state.denies += 1;
+				if (state.denies > MAX_PLAN_DENIALS) {
+					stopForDenials();
+					return;
+				}
+				if (kind === "dialog") {
+					writeStdin(`${JSON.stringify({
+						type: "control_response",
+						response: {
+							subtype: "error",
+							request_id: requestId,
+							error: PLAN_DIALOG_ERROR
+						}
+					})}\n`);
+					return;
+				}
+				controlResponse(requestId, {
+					behavior: "deny",
+					message: PLAN_ACTION_DENY
+				});
+			};
+			/**
+			* Plan mode keeps stdin open so a permission prompt can be answered.
+			* `ExitPlanMode` with a plan stops the child; it is never allowed,
+			* because allowing it would make the CLI start editing in this process.
+			*/
+			const handlePlanLine = (line) => {
+				const trimmed = line.trim();
+				if (!trimmed.startsWith("{")) return;
+				let message;
+				try {
+					message = JSON.parse(trimmed);
+				} catch {
+					return;
+				}
+				if (message?.type === "result") {
+					endStdin();
+					return;
+				}
+				if (message?.type !== "control_request") return;
+				const requestId = message.request_id;
+				const request = message.request;
+				if (typeof requestId !== "string" || request === null || typeof request !== "object") {
+					state.denies += 1;
+					if (state.denies > MAX_PLAN_DENIALS) stopForDenials();
+					return;
+				}
+				if (request.subtype !== "can_use_tool") {
+					refuseControl(requestId, "dialog");
+					return;
+				}
+				if (request.tool_name === "ExitPlanMode") {
+					const plan = readSubmittedPlan(request.input, {
+						configDir,
+						startedAt
+					});
+					if (plan !== void 0) {
+						state.plan = scrub(plan);
+						endStdin();
+						kill();
+						return;
+					}
+					state.denies += 1;
+					if (state.denies > MAX_PLAN_DENIALS) {
+						stopForDenials();
+						return;
+					}
+					controlResponse(requestId, {
+						behavior: "deny",
+						message: PLAN_EXIT_DENY
+					});
+					return;
+				}
+				refuseControl(requestId, "tool");
+			};
 			child.stdout?.on("data", (chunk) => {
 				state.sawOutput = true;
 				clearStartup();
 				const text = String(chunk);
 				state.stdout = scrub((state.stdout + text).slice(-4194304));
 				onStdout?.(text);
+				if (mode !== "plan") return;
+				controlBuffer += text;
+				let index = controlBuffer.indexOf("\n");
+				while (index !== -1) {
+					const line = controlBuffer.slice(0, index);
+					controlBuffer = controlBuffer.slice(index + 1);
+					handlePlanLine(line);
+					index = controlBuffer.indexOf("\n");
+				}
 			});
 			child.stderr?.on("data", (chunk) => {
 				state.stderr = scrub((state.stderr + String(chunk)).slice(-4194304));
@@ -2728,6 +3013,12 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 						const detail = state.stderr.trim().split("\n").slice(-4).join(" ").slice(0, 400);
 						return reject(/* @__PURE__ */ new Error(`Claude Code CLI printed nothing within ${Math.round(startupTimeoutMs / 1e3)}s of starting and was stopped${detail === "" ? "" : `: ${detail}`}`));
 					}
+					if (signal?.aborted) return reject(/* @__PURE__ */ new Error("claude_code was aborted"));
+					if (state.denyExhausted === true) return reject(/* @__PURE__ */ new Error(PLAN_DENY_LIMIT_MESSAGE));
+					if (typeof state.plan === "string") return resolve({
+						code,
+						killSignal
+					});
 					if (runSignal.aborted) return reject(/* @__PURE__ */ new Error("claude_code was aborted"));
 					resolve({
 						code,
@@ -2743,7 +3034,8 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 			});
 			closed.catch(() => void 0);
 			child.stdin?.on?.("error", () => void 0);
-			child.stdin?.end?.(input);
+			if (mode === "plan") writeStdin(input);
+			else child.stdin?.end?.(input);
 			if (runSignal.aborted) kill();
 			return {
 				child,
@@ -2769,7 +3061,30 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 		* @param options - prompt, mode, model, working directory, and cancellation.
 		* @returns the CLI's answer plus its own accounting.
 		*/
-		async run({ prompt, mode = DEFAULT_CLAUDE_MODE, model, appendSystemPrompt, cwd, signal, enableSearch } = {}) {
+		async run({ prompt, content, mode = DEFAULT_CLAUDE_MODE, model, appendSystemPrompt, cwd, signal, enableSearch } = {}) {
+			if (mode === "plan") {
+				let finished;
+				for await (const event of this.stream({
+					prompt,
+					content,
+					mode,
+					model,
+					appendSystemPrompt,
+					cwd,
+					signal,
+					enableSearch
+				})) if (event.type === "result") finished = event.result;
+				if (finished === void 0) throw new Error("claude_code plan mode ended without a result");
+				return {
+					result: finished.result,
+					model: finished.model,
+					mode: "plan",
+					costUsd: finished.costUsd,
+					durationMs: finished.durationMs,
+					inputTokens: finished.inputTokens,
+					outputTokens: finished.outputTokens
+				};
+			}
 			const startedAt = Date.now();
 			const { state, closed } = await start({
 				prompt,
@@ -2902,6 +3217,42 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 					const event = readClaudeStreamEvents(JSON.parse(scrub(buffer.trim()))).find((item) => item.type === "result");
 					if (event !== void 0) sawResult = event.result;
 				} catch {}
+				if (mode === "plan" && typeof state.plan !== "string" && exitStatus?.code === 0) {
+					const written = findPlanWrittenDuringRun({
+						configDir,
+						startedAt: state.startedAt
+					});
+					if (written !== void 0) state.plan = scrub(written);
+				}
+				if (typeof state.plan === "string") {
+					if (deltaKind !== void 0) {
+						const tail = deltaRedactor.flush({ boundary: true });
+						if (tail !== "") yield {
+							type: deltaKind,
+							text: tail
+						};
+					}
+					const usage = sawResult?.usage ?? {};
+					yield {
+						type: "plan",
+						plan: state.plan
+					};
+					yield {
+						type: "result",
+						result: {
+							result: state.plan,
+							model: typeof sawResult?.model === "string" && sawResult.model !== "" ? sawResult.model : model ?? "",
+							mode: "plan",
+							costUsd: typeof sawResult?.total_cost_usd === "number" ? sawResult.total_cost_usd : 0,
+							durationMs: typeof sawResult?.duration_ms === "number" ? sawResult.duration_ms : Date.now() - startedAt,
+							inputTokens: typeof usage.input_tokens === "number" ? usage.input_tokens : 0,
+							outputTokens: typeof usage.output_tokens === "number" ? usage.output_tokens : 0,
+							cacheReadTokens: typeof usage.cache_read_input_tokens === "number" ? usage.cache_read_input_tokens : 0,
+							cacheWriteTokens: typeof usage.cache_creation_input_tokens === "number" ? usage.cache_creation_input_tokens : 0
+						}
+					};
+					return;
+				}
 				if (sawResult === void 0) throw new Error(failureMessage(void 0, void 0, state.stderr));
 				if (sawResult.is_error === true || exitStatus?.code !== 0) throw new Error(failureMessage(sawResult, exitStatus?.code ?? exitStatus?.killSignal, state.stderr));
 				const usage = sawResult.usage ?? {};
@@ -3733,6 +4084,36 @@ function claudeModeFor(sandbox, approval) {
 	}
 }
 /**
+* Whether this session should run the CLI in plan mode.
+*
+* The model request runs inside `agent/pre-step`, before the plan-mode service
+* appends `plan/mode`. `pending` is that not-yet-logged selection and wins over
+* the logged `active` bit, matching the `plan:policy` section. Without the
+* service, the logged projection is the only signal. A missing session, a
+* missing service, or a throw means plan mode is off — never a failed turn.
+* @param ctx - the plugin context; services are read without an inject requirement.
+* @param session - the session whose plan state is read.
+* @returns true when the CLI must plan instead of acting.
+*/
+function planModeForSession(ctx, session) {
+	if (session === void 0 || session === null) return false;
+	try {
+		const agent = ctx.get?.("agents")?.currentInitiator?.();
+		if (agent?.session === session) {
+			const state = ctx.get?.("planMode")?.get?.(agent);
+			if (state !== void 0 && state !== null) return planSelected(state);
+		}
+		return ctx.get?.("sessionProjections")?.stateOf?.(session, "plan")?.active === true;
+	} catch {
+		return false;
+	}
+}
+/** `pending` is the selection the in-flight request was assembled with. */
+function planSelected(state) {
+	if (typeof state?.pending === "boolean") return state.pending;
+	return state?.active === true;
+}
+/**
 * Read a session's CLI mode from the host's permission services.
 * @param ctx - the plugin context; services are read without an inject requirement.
 * @param session - the session whose permission state is read.
@@ -3768,16 +4149,25 @@ function capClaudeMode(requested, ceiling) {
 *
 * @module dsh-packycode-api/claude-tool
 */
+/** Modes a caller of `claude_code` may ask for. Plan mode is not one of them. */
+const CLAUDE_TOOL_MODES = Object.freeze([
+	"read-only",
+	"edit",
+	"full"
+]);
 /** What a `claude_code` tool run is told about where its task came from. */
 const CLAUDE_TOOL_INSTRUCTIONS = "This task was delegated to Claude Code by another agent in DeepSeek Harness through its claude_code tool. The task text is self-contained; complete it with your own tools and reply with the final result only.";
+/** What the same run is told while the parent session is in DSH plan mode. */
+const CLAUDE_TOOL_PLAN_INSTRUCTIONS = "This task was delegated to Claude Code while DeepSeek Harness is in plan mode. Explore read-only, write a complete markdown plan that starts with a # heading to the CLI plan file, then call ExitPlanMode. Do not edit the project or start implementing. Reply with the plan text only.";
 /**
-* @param options - the CLI runner, and the most a run may do for a session.
+* @param options - the CLI runner, the most a run may do for a session, and
+*   whether that session is in DSH plan mode.
 * @returns the tool definition to register.
 */
-function createClaudeCodeTool({ runner, modeCeiling }) {
+function createClaudeCodeTool({ runner, modeCeiling, planActive }) {
 	return defineTool({
 		name: "claude_code",
-		description: "Delegate a task to the local Claude Code CLI (the official `claude` binary), which runs it with its own tools and returns its final answer. Use it when the user asks for Claude or when a task suits Claude Code. The child runs with this plugin's PackyCode endpoint and API key, in an isolated config home. `mode` bounds what it may do on its own: \"read-only\" (Read/Grep/Glob), \"edit\" (also Edit/Write), \"full\" (bypasses the CLI's permission checks, including shell commands); it defaults to, and is capped at, what this session's permission preset allows. It starts a fresh CLI session per call, takes tens of seconds, and bills through this plugin's stored PackyCode keys. Web searches use the selected DeepSeek/GPT backend through a read-only MCP tool rather than native WebSearch. Its internal tool calls are not part of this session's transcript — only the returned answer is.",
+		description: "Delegate a task to the local Claude Code CLI (the official `claude` binary), which runs it with its own tools and returns its final answer. Use it when the user asks for Claude or when a task suits Claude Code. The child runs with this plugin's PackyCode endpoint and API key, in an isolated config home. `mode` bounds what it may do on its own: \"read-only\" (Read/Grep/Glob), \"edit\" (also Edit/Write), \"full\" (bypasses the CLI's permission checks, including shell commands); it defaults to, and is capped at, what this session's permission preset allows. While this session is in DSH plan mode the CLI plans instead, whatever `mode` says, and the returned result is the plan for you to submit with exit_plan_mode — do not treat it as permission to edit. It starts a fresh CLI session per call, takes tens of seconds, and bills through this plugin's stored PackyCode keys. Web searches use the selected DeepSeek/GPT backend through a read-only MCP tool rather than native WebSearch. Its internal tool calls are not part of this session's transcript — only the returned answer is.",
 		parameters: {
 			prompt: {
 				type: "string",
@@ -3786,7 +4176,7 @@ function createClaudeCodeTool({ runner, modeCeiling }) {
 			},
 			mode: {
 				type: "string",
-				enum: Object.keys(CLAUDE_CLI_MODES),
+				enum: [...CLAUDE_TOOL_MODES],
 				description: "What the CLI may do on its own. Defaults to the most this session's permission preset allows; a wider mode is capped to it. Ask for \"full\" only when the task genuinely needs shell commands."
 			},
 			model: {
@@ -3834,11 +4224,13 @@ function createClaudeCodeTool({ runner, modeCeiling }) {
 			const sessionCwd = exec?.agent?.session?.header?.cwd;
 			const requested = typeof args.cwd === "string" ? args.cwd.trim() : "";
 			const cwd = requested === "" ? sessionCwd : isAbsolute(requested) ? requested : sessionCwd === void 0 ? requested : join(sessionCwd, requested);
+			const session = exec?.agent?.session;
+			const planning = planActive?.(session) === true;
 			return await runner.run({
 				prompt: args.prompt,
-				mode: capClaudeMode(args.mode, modeCeiling(exec?.agent?.session)) ?? "edit",
+				mode: planning ? "plan" : capClaudeMode(args.mode, modeCeiling(session)) ?? "edit",
 				model: args.model,
-				appendSystemPrompt: CLAUDE_TOOL_INSTRUCTIONS,
+				appendSystemPrompt: planning ? CLAUDE_TOOL_PLAN_INSTRUCTIONS : CLAUDE_TOOL_INSTRUCTIONS,
 				cwd,
 				signal: exec?.signal
 			});
@@ -6036,7 +6428,10 @@ function apply(ctx, config) {
 			resolveAttachments: attachments
 		}),
 		runner: claudeRunner,
-		resolveMode: () => cliModeCeiling(currentSession()) ?? "edit",
+		resolveMode: () => {
+			const session = currentSession();
+			return planModeForSession(ctx, session) ? "plan" : cliModeCeiling(session) ?? "edit";
+		},
 		resolveCwd: resolveCliCwd,
 		resolveAttachments: attachments,
 		explainKey: (runKey) => keys.describe(runKey)
@@ -6135,9 +6530,10 @@ function apply(ctx, config) {
 	ctx.inject(["tools"], (toolsCtx) => {
 		ctx.effect(() => toolsCtx.tools.register(createClaudeCodeTool({
 			runner: claudeRunner,
-			modeCeiling: cliModeCeiling
+			modeCeiling: cliModeCeiling,
+			planActive: (session) => planModeForSession(ctx, session)
 		})), "packycode-api: claude_code tool");
 	});
 }
 //#endregion
-export { AUTO_CLAUDE_MODE, CHANNEL, CLAUDE_CLI_MODES, CLAUDE_INSTALL_COMMAND, CLAUDE_MISSING_MESSAGE, CLAUDE_NPM_PACKAGE, CLAUDE_TOOL_INSTRUCTIONS, CLI_BACKED_MODEL_IDS, CLI_IMAGE_LIMITS, Config, DEFAULT_API_HOST, DEFAULT_APPEND_SYSTEM_PROMPT, DEFAULT_SEARCH_BACKEND, DEFAULT_STATUS_HOST, DISPLAY_NAME, LEGACY_STATUS_HOSTS, PACKYCODE_AUTO_SEARCH_PROVIDER_ID, PACKYCODE_MODELS, PACKYCODE_MODEL_IDS, PACKYCODE_SEARCH_PROVIDER_ID, PLUGIN_ID, PROVIDER, PackyCodeKeyRing, SEARCH_BACKENDS, SEARCH_BACKEND_MODELS, SEARCH_MODES, SETTINGS_NAMESPACE, TITLE_MODEL_ID, TITLE_MODEL_ROUTES, accountHostOrder, apply, assertApiKey, buildClaudeArgs, buildClaudeEnvironment, buildClaudeInput, buildDelegatedContent, buildSearchRequest, capClaudeMode, catalogCoverage, classifyClientPolicy, classifyGatewayFailure, claudeBinaryCandidates, claudeModeFor, claudeModeForSession, cliSearchInstructions, createBalanceReader, createClaudeCliAdapter, createClaudeCliManager, createClaudeCodeTool, createClaudeRunner, createClaudeSearchBridge, createGroupReader, createKeyChooser, createPackyCodeAutoSearchProvider, createPackyCodeProfile, createPackyCodeProvider, createPackyCodeRpc, createPackyCodeSearchProvider, createProfileSearchComposition, createRouteAdapter, createSearchComposition, createSearchController, delegationInstructions, describeRunKey, explainCliClientPolicyFailure, explainCliGroupFailure, explainClientPolicyFailure, explainNpmFailure, findClaudeBinary, guardKeyRotation, inject, keyNote, locateClaudeBinary, locateNpm, name, normalizeFailureMessage, normalizeHost, npmCandidates, parseBillingSubscription, parseBillingUsage, parseClaudeResult, parseClaudeVersion, parseMessagesSearchResponse, parsePricing, parseResponsesSearchResponse, parseSelectedGroups, parseTokenUsage, pickKeyForModel, readClaudeStreamEvents, readSearchChoice, renderAuxiliaryPrompt, renderDelegatedPrompt, resolveSpawnCommand, statusHostOrder, summarizeToolUse };
+export { AUTO_CLAUDE_MODE, CHANNEL, CLAUDE_CLI_MODES, CLAUDE_INSTALL_COMMAND, CLAUDE_MISSING_MESSAGE, CLAUDE_NPM_PACKAGE, CLAUDE_TOOL_INSTRUCTIONS, CLI_BACKED_MODEL_IDS, CLI_IMAGE_LIMITS, Config, DEFAULT_API_HOST, DEFAULT_APPEND_SYSTEM_PROMPT, DEFAULT_SEARCH_BACKEND, DEFAULT_STATUS_HOST, DISPLAY_NAME, LEGACY_STATUS_HOSTS, PACKYCODE_AUTO_SEARCH_PROVIDER_ID, PACKYCODE_MODELS, PACKYCODE_MODEL_IDS, PACKYCODE_SEARCH_PROVIDER_ID, PLUGIN_ID, PROVIDER, PackyCodeKeyRing, SEARCH_BACKENDS, SEARCH_BACKEND_MODELS, SEARCH_MODES, SETTINGS_NAMESPACE, TITLE_MODEL_ID, TITLE_MODEL_ROUTES, accountHostOrder, apply, assertApiKey, buildClaudeArgs, buildClaudeEnvironment, buildClaudeInput, buildDelegatedContent, buildSearchRequest, capClaudeMode, catalogCoverage, classifyClientPolicy, classifyGatewayFailure, claudeBinaryCandidates, claudeModeFor, claudeModeForSession, cliSearchInstructions, createBalanceReader, createClaudeCliAdapter, createClaudeCliManager, createClaudeCodeTool, createClaudeRunner, createClaudeSearchBridge, createGroupReader, createKeyChooser, createPackyCodeAutoSearchProvider, createPackyCodeProfile, createPackyCodeProvider, createPackyCodeRpc, createPackyCodeSearchProvider, createProfileSearchComposition, createRouteAdapter, createSearchComposition, createSearchController, delegationInstructions, describeRunKey, explainCliClientPolicyFailure, explainCliGroupFailure, explainClientPolicyFailure, explainNpmFailure, findClaudeBinary, guardKeyRotation, inject, keyNote, locateClaudeBinary, locateNpm, name, normalizeFailureMessage, normalizeHost, npmCandidates, parseBillingSubscription, parseBillingUsage, parseClaudeResult, parseClaudeVersion, parseMessagesSearchResponse, parsePricing, parseResponsesSearchResponse, parseSelectedGroups, parseTokenUsage, pickKeyForModel, planModeForSession, readClaudeStreamEvents, readSearchChoice, renderAuxiliaryPrompt, renderDelegatedPrompt, resolveSpawnCommand, statusHostOrder, summarizeToolUse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-packycode-api",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "packageManager": "pnpm@10.32.1",
   "description": "Use a PackyCode (PackyAPI) API key in DeepSeek Harness through a built-in multi-protocol model route with key rotation and balance display",
   "type": "module",