@stackstackstack/dsh-plan-mode 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/plan/plan-mode/README.md
+README.md: bbc4723e014568e13b2204155a551e8d52b942ac
+README.zh.md: b1f4d75081dc6daaa4e902937552ebcc32d2ee91

package/README.md

@@ -0,0 +1,98 @@
+# @stackstackstack/dsh-plan-mode
+
+English | [中文](README.zh.md)
+
+Logged, per-agent plan collaboration state with deployment-owned guidance, direct `/plan [message]` entry and `/plan off` exit commands, and the reviewed `exit_plan_mode` exit. Plan mode is soft guidance; sandbox mode and approval policy enforce restrictions independently and do not read or write plan state.
+
+## Durable state
+
+`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace `SessionEventMap` member. `foldPlanMode(events)` returns the last logged value or `false`, so resume, fork, and compaction recover plan state directly from the session log. UIs observe committed flips through `session/event`.
+
+`ctx.planMode.set(agent, active)` appends the standalone `plan/mode` event immediately when the agent is idle, because no in-turn pre-step runs before the next prompt. While the agent is running, it holds a pending selection for the next accepted in-turn pre-step. It returns which happened (`committed`/`queued`), a `cancelled` reversal, or a `noop`. `get(agent)` returns `{ active, pending? }`, separating the logged state used to assemble the current step from a user's mid-turn selection. Initial and continuation pre-steps both apply pending selections; a same-step request-recovery retry reuses its frozen assembly and leaves the selection pending for the next pre-step. A changed user selection contributes one plugin-sourced `user/message` notice when the last logged request header described the other state (both commit paths).
+
+## Model and human interactions
+
+While active, `plan:policy` renders the configured `section`. The plugin always registers `exit_plan_mode`, keeping tool schemas stable across the transition; its execute path accepts only active plan mode and leaves it only after an exact user approval through `ctx.userQuestions`.
+
+The review question declares the `plan-review` presentation intent, naming `Approve` as the label that approves it, so a capable UI presents the plan as a decision instead of a generic question; the answer the tool reads is the same either way. A dismissed review — the user closing the request to speak instead — is reported to the model as such, telling it to stay in plan mode and wait for the message; every other review failure keeps the seam's own message.
+
+When `ctx.commands` is composed, the package registers `/plan [message]` and reserves the exact argument `off` for direct exit. Bare `/plan` selects plan mode; any other non-empty argument selects it first and is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance. `/plan off` selects inactive without sending model input; it also cancels a pending entry before plan mode reaches a request.
+
+The Web client consumes the plugin-owned `/plan` command; other entry points may drive the same service directly without defining a second mode vocabulary.
+
+## Session projection
+
+When the composition mounts `ctx.sessionProjections` ([`@stackstackstack/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. The unit folds two event kinds: a `command/run` record named `plan` with recorded `args` sets the wanted target (`off` → inactive, anything else → active), and `plan/mode` commits the logged state and clears it; every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an outstanding selection differs from the logged state — a pure replay quantity, so host restarts, other tabs, and cold reads all recover it from the log alone (the `/plan` handler calls `set()` before any failing path, so a failed handler cannot leave a recorded command without its plan selection). The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
+
+## Configuration
+
+```yaml
+- id: plan-mode
+  name: '@stackstackstack/dsh-plan-mode'
+  config:
+    section: |
+      You are in plan mode. Explore and design before presenting the complete
+      plan through exit_plan_mode.
+```
+
+`section` is required and non-empty. Unknown keys fail at load. The package does not accept arbitrary named modes, tool filters, sandbox settings, or approval policy.
+
+Design: [plan-specific collaboration state](../../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).
+
+## Model Experience
+
+### Plan policy system prompt
+
+#### What the model sees
+
+While plan mode is active, the model sees the deployment's exact `section` text at prompt order 50; inactive mode contributes no text.
+
+##### Configuration example
+
+```markdown
+You are in plan mode. Explore and design before presenting the complete plan through exit_plan_mode.
+```
+
+#### Token effect
+
+Inactive mode adds no tokens; active mode adds the configured section to every request.
+
+#### KV Cache effect
+
+The section is stable within plan mode, but entering or leaving changes the system prompt from order 50 onward.
+
+### Human command
+
+#### What the model sees
+
+`/plan`, `/plan off`, and their terminal results stay outside model history. A non-empty suffix other than the exact `off` argument becomes one trimmed user text block through `agent.steer()` after plan mode is selected. An active `/plan off` selection contributes the standard logged user-switch notice only when the last request header described plan mode; cancelling a pending entry contributes none because no request observed it.
+
+#### Token effect
+
+The optional message costs the same history tokens as submitting that text separately; bare `/plan` and `/plan off` add none. A narrated active exit adds the small retained switch notice.
+
+#### KV Cache effect
+
+The user block is append-only conversation growth. Entering or leaving plan mode changes the earlier policy section; a narrated exit notice is appended after the reusable request prefix.
+
+### Exit tool schema and review exchange
+
+#### What the model sees
+
+The [`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) remains available in both states; execution outside plan mode fails, while an approved in-mode review returns the canonical `{ approved: true }` value and renders the existing confirmation text. Rejection remains a failed call carrying review feedback, and a dismissed review a failed call naming the user's takeover.
+
+#### Token effect
+
+The stable schema is paid according to ToolRuntime mode, and each plan argument and review result remains in conversation history.
+
+#### KV Cache effect
+
+Mode transitions do not change the tool catalog; plan arguments and review results extend the conversation normally.
+
+## Known Limitations and Deferred Work
+
+- Plan mode guides rather than enforces; deployments that need enforced restrictions must configure sandbox and approval controls independently.
+- A selection made after the turn's final accepted pre-step is lost if the process exits before another accepted in-turn pre-step, so the UI must reapply it.
+- Forked agents inherit logged plan state, while newly spawned agents begin inactive; there is no creation-time plan option.
+- A live child owned by another agent cannot open the `exit_plan_mode` review. The failed call tells the child to include the unresolved decision in its final result; durable fork lineage alone does not prevent a session resumed as a runtime root from opening the review.
+- Only the Web UI has a specialized `plan-review` renderer; another interaction provider may present the same request through its generic option flow.

package/README.zh.md

@@ -0,0 +1,98 @@
+# @stackstackstack/dsh-plan-mode
+
+[English](README.md) | 中文
+
+按 agent（智能体）分别记录到日志的 plan 协作状态，提供由部署方配置的引导内容、用于直接进入的 `/plan [message]` 命令、用于直接退出的 `/plan off` 命令，以及经用户评审的 `exit_plan_mode` 退出方式。Plan mode 是软引导；沙箱模式和批准策略各自强制执行限制，且不读写 plan 状态。
+
+## 持久状态
+
+`plan/mode`（`{ active: boolean }`）是一个仅存在于日志中、每次以完整值替换的 `SessionEventMap` 成员。`foldPlanMode(events)` 返回最后记录的值，如果没有则返回 `false`，因此恢复、fork 和压缩（compaction）都能直接从会话日志恢复 plan 状态。UI 通过 `session/event` 观察已提交的切换。
+
+`ctx.planMode.set(agent, active)` 会在 agent 空闲时立即追加独立的 `plan/mode` 事件，因为下一个提示词之前不会运行轮内 pre-step。agent 运行时，该方法会保留待生效选择，直到下一个被接受的轮内 pre-step。返回值区分 `committed`、`queued`、表示反转的 `cancelled` 和 `noop`。`get(agent)` 返回 `{ active, pending? }`，将用于组装当前步骤的日志状态与用户的轮中选择分开。初始与续步 pre-step 都会应用待生效选择；同一步骤的请求恢复重试会复用已冻结的 assembly，并将该选择保留到下一个被接受的轮内 pre-step。当最后记录的请求头描述了另一状态时，用户选择的变更会贡献一条插件来源的 `user/message` 通知（两条提交路径皆然）。
+
+## 模型与人类交互
+
+激活时，`plan:policy` 会渲染已配置的 `section`。插件始终注册 `exit_plan_mode`，使工具 schema 在转换期间保持稳定；其 execute 路径只接受已激活的 plan mode，且只有通过 `ctx.userQuestions` 获得用户明确批准后才退出。
+
+评审问题声明 `plan-review` 呈现意图，并指名 `Approve` 为表示批准的标签，因此有能力的 UI 会把计划呈现为一次决定而非通用问题；两种情况下该工具读到的回答完全相同。放弃审阅——用户关闭请求，转而发言——会如实报告给模型，要求它留在 plan mode 中等待那条消息；其余每一种评审失败都保留 seam 自身的消息。
+
+组合 `ctx.commands` 时，该包会注册 `/plan [message]`，并将参数恰好为 `off` 的情况保留给直接退出。不带参数的 `/plan` 会启用 plan mode；任何其他非空参数都会先启用 plan mode，再通过 `agent.steer()` 提交，因此它会在 plan 引导下成为下一步骤的常规已记录用户消息。`/plan off` 会选择停用状态，不发送模型输入；它还可以在启用 plan mode 的待处理选择由轮内 pre-step 追加之前将其取消。
+
+Web 客户端使用该插件提供的 `/plan` 命令；其他入口可以直接驱动同一服务，无需定义第二套 mode 词汇。
+
+## 会话投影
+
+当组合挂载 `ctx.sessionProjections`（[`@stackstackstack/dsh-session-projection`](../../session/session-projection/README.md)）时，本包会在一个注入的子插件中注册 `plan` 投影单元。该单元折叠两类事件：名为 `plan` 且携带已记录 `args` 的 `command/run` 记录会设置目标状态（`off` → 未激活，其余 → 激活），`plan/mode` 会提交已记录状态并清除该目标；其他任何事件都返回同一个状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在尚未落实的选择与已记录状态不同时为 true。该值完全由日志回放得出，因此 host 重启、其他标签页和冷读都能仅凭日志恢复它。`/plan` 处理器会在任何可能失败的路径之前调用 `set()`，因此处理器失败时不会留下缺少对应 plan 选择的已记录命令。key 由 `src/types.ts` 通过声明合并加入 `SessionProjectionMap`：host 消费方经 `./types` 获取，client 聚合经 `./client` 获取。框架负责驱动该单元，载体通过历史尾页和 `session/projection` 推送帧提供其值。未挂载注册表的组合不受影响。
+
+## 配置
+
+```yaml
+- id: plan-mode
+  name: '@stackstackstack/dsh-plan-mode'
+  config:
+    section: |
+      You are in plan mode. Explore and design before presenting the complete
+      plan through exit_plan_mode.
+```
+
+`section` 必填且非空。出现未知键时，插件会加载失败。该包不接受任意命名的 mode、工具过滤器、沙箱设置或批准策略。
+
+设计：[plan 专用协作状态](../../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
+
+## 模型体验
+
+### Plan 策略系统提示词
+
+#### 模型所见内容
+
+Plan mode 激活时，模型会在提示词顺序 50 处看到部署方提供的原样 `section` 文本；未激活 mode 不贡献文本。
+
+##### 配置示例
+
+```markdown
+You are in plan mode. Explore and design before presenting the complete plan through exit_plan_mode.
+```
+
+#### Token 影响
+
+未激活 mode 不增加 token；mode 激活时，每个请求都会加入已配置的段落。
+
+#### KV Cache 影响
+
+该段在 plan mode 内稳定，但进入或退出会从顺序 50 开始改变系统提示词。
+
+### 人类命令
+
+#### 模型所见内容
+
+`/plan`、`/plan off` 及其终端结果留在模型历史之外。除恰好为 `off` 以外的非空后缀会在选择 plan mode 后，通过 `agent.steer()` 成为一个已去除首尾空白的用户文本块。plan mode 已激活时，选择 `/plan off` 只会在最后一个请求头描述了 plan mode 的情况下追加标准的已记录用户切换通知；取消待生效进入不会贡献通知，因为没有请求观测到它。
+
+#### Token 影响
+
+可选消息的历史 token 成本与单独提交该文本相同；不带参数的 `/plan` 和 `/plan off` 不增加 token。一次带有切换通知的已激活状态退出会追加一条简短且会保留的通知。
+
+#### KV Cache 影响
+
+用户块是仅追加的对话增长。进入或退出 plan mode 会改变更早的策略段；退出转换的记录通知会追加在可复用请求前缀之后。
+
+### 退出工具 schema 与评审交互
+
+#### 模型所见内容
+
+[`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) 在两种状态下均可用；在 plan mode 外执行会失败，而 plan mode 内经批准的评审会返回规范的 `{ approved: true }` 值，并渲染既有的确认文本。拒绝仍是携带评审反馈的失败调用，放弃审阅则是一次指明用户接手的失败调用。
+
+#### Token 影响
+
+稳定 schema 的成本取决于 ToolRuntime mode，每次传入的 plan 参数和评审结果都会保留在对话历史中。
+
+#### KV Cache 影响
+
+mode 转换不改变工具目录；plan 参数与评审结果按常规方式扩展对话。
+
+## 已知限制与暂缓事项
+
+- Plan mode 只进行引导，而不强制执行；需要强制限制的部署必须分别配置沙箱与批准控制。
+- 如果进程在另一个被接受的轮内 pre-step 之前退出，某轮最后一个被接受的 pre-step 之后作出的选择会丢失，因此 UI 必须重新应用它。
+- Fork 的 agent 会继承已记录的 plan 状态，新 spawn 的 agent 则从未激活状态开始；不存在创建时 plan 选项。
+- 由另一个 agent 所有的存活子级无法打开 `exit_plan_mode` 审阅。该调用失败时会提示子级在最终结果中包含尚未解决的决策；仅有持久化 fork 谱系并不会阻止恢复为运行时根的会话打开该审阅。
+- 只有 Web UI 具备专用的 `plan-review` 渲染器；其他交互提供方可以通过通用选项流程呈现同一请求。

package/lib/index.js

@@ -0,0 +1,391 @@
+import { Service } from "@deepseek-ai/cordis";
+import { z } from "zod";
+import { createUserMessage } from "@stackstackstack/dsh-llm";
+import { defineTool } from "@stackstackstack/dsh-tools";
+import { UserQuestionError } from "@stackstackstack/dsh-user-questions";
+//#region lib/types/index.js
+/**
+* Plan mode is logged per-agent collaboration state: while active, a
+* deployment-owned guidance section is included in each model request, and
+* `exit_plan_mode` presents the completed plan for user review, while the
+* `/plan off` command lets a user leave directly. Sandbox mode and approval
+* policy enforce restrictions independently and do not read or write plan
+* state.
+*
+* The state in force is folded from the session log (`plan/mode`, last one
+* wins), so resume and fork restore it without a live mirror. User selections
+* remain pending until the next accepted in-turn pre-step. The service includes
+* the selected state in the proposed step assembly, then appends `plan/mode`
+* from `agent/pre-step` only when the step is accepted. Same-step request
+* retries reuse their assembly.
+*
+* The exit tool remains registered while plan mode is inactive, so entering
+* or leaving plan mode changes only the prompt section, not the request tool
+* catalog.
+*
+* Agent Note:
+* - .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
+*
+* @module @stackstackstack/dsh-plan-mode
+*/
+/**
+* The model-facing exit tool's name. It stays registered while plan mode is
+* inactive so the request tool catalog is stable across transitions.
+*/
+const EXIT_PLAN_MODE = "exit_plan_mode";
+/** The review question's id, echoed in the answer this tool reads. */
+const REVIEW_ID = "plan-review";
+/** The review question's approve option label. */
+const APPROVE_LABEL = "Approve";
+/** The review question's keep-planning option label. */
+const KEEP_PLANNING_LABEL = "Keep planning";
+const EXIT_DESCRIPTION = "Use only in plan mode. Present your plan for the user's review and, on approval, leave plan mode. Send the COMPLETE plan as markdown, starting with a # heading that names it. The user may approve (carry out the plan from your next step) or keep planning — their feedback comes back in the tool result; revise and present again.";
+/** The plan's first markdown heading (any level), or `undefined` when it has none. */
+function firstHeading(plan) {
+	for (const line of plan.split("\n")) {
+		const match = /^#{1,6}\s+(.+?)\s*$/.exec(line);
+		if (match) return match[1];
+	}
+}
+/**
+* Validate deployment-owned plan guidance. Missing, blank, non-string, or
+* unknown fields fail at plugin load rather than being ignored.
+*
+* @param config Raw plugin config.
+* @returns A detached validated config.
+*/
+function resolveConfig(config) {
+	const section = config.section;
+	if (typeof section !== "string") throw new Error("PlanModeConfig needs a string `section`");
+	if (section.trim() === "") throw new Error("PlanModeConfig needs a non-empty `section`");
+	const unknown = Object.keys(config).filter((key) => key !== "section");
+	if (unknown.length > 0) throw new Error(`PlanModeConfig has unknown key(s) ${unknown.join(", ")} — config is { section }`);
+	return { section };
+}
+/**
+* Whether plan mode is active after the first `end` events. The last
+* `plan/mode` wins; a prefix with none is inactive.
+*
+* @param events The session log or any prefix of it.
+* @param end Fold `events[0, end)`; defaults to the whole log.
+* @returns Whether plan mode is active.
+*/
+function foldPlanMode(events, end = events.length) {
+	let active = false;
+	let index = 0;
+	for (const event of events) {
+		if (index >= end) break;
+		index++;
+		if (event.type === "plan/mode") active = event.data.active;
+	}
+	return active;
+}
+/** Wire payload schema of the `plan` projection. */
+const planProjectionSchema = z.object({
+	active: z.boolean(),
+	pending: z.boolean()
+});
+/** Whether the log holds an opened turn without its closing `turn/end`. */
+function hasOpenTurn(events) {
+	let open = false;
+	for (const event of events) if (event.type === "turn/start") open = true;
+	else if (event.type === "turn/end") open = false;
+	return open;
+}
+/** Plan state at the last logged request header, or `undefined` before the first header. */
+function planModeAtLastHeader(events) {
+	let lastHeader = -1;
+	let index = 0;
+	for (const event of events) {
+		if (event.type === "request/header") lastHeader = index;
+		index++;
+	}
+	if (lastHeader < 0) return void 0;
+	return foldPlanMode(events, lastHeader + 1);
+}
+/**
+* `ctx.planMode`: owns logged plan state, applies and narrates selected state at step start,
+* the `plan:policy` section, the `/plan` command, and the stable exit tool.
+* UIs observe committed flips through `session/event`; there is no live mirror.
+*/
+var PlanModeController = class extends Service {
+	static inject = ["tools", "systemPrompt"];
+	/** Validated deployment-owned guidance. */
+	section;
+	/**
+	* Latest selection per session awaiting the next accepted in-turn pre-step.
+	* `narrate` is true for user selections and false for the exit tool, whose
+	* result already narrates the transition.
+	*/
+	pendingIntents = /* @__PURE__ */ new WeakMap();
+	constructor(ctx, config = { section: "" }) {
+		super(ctx, "planMode");
+		this.section = resolveConfig(config).section;
+		let disposed = false;
+		ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
+			const decision = await next();
+			const pending = this.pendingIntents.get(agent.session);
+			if (decision.kind === "reject" || signal.aborted || pending === void 0) return decision;
+			const narration = this.narration(agent.session, pending.active);
+			try {
+				this.onBoundary(agent.session);
+			} catch (error) {
+				ctx.logger.warn("dsh-plan-mode: failed to append selected plan mode at step start: %o", error);
+				return decision;
+			}
+			return !pending.narrate || narration === void 0 ? decision : {
+				...decision,
+				messages: [...decision.messages, narration]
+			};
+		});
+		ctx.effect(() => () => {
+			disposed = true;
+		}, "dsh-plan-mode: close service lifetime");
+		ctx.systemPrompt.section({
+			name: "plan:policy",
+			order: 50,
+			text: (context) => {
+				if (context.agent === void 0) return "";
+				return this.pendingIntents.get(context.agent.session)?.active ?? foldPlanMode(context.agent.session.events) ? this.section : "";
+			}
+		});
+		ctx.inject(["sessionProjections"], (projectionCtx) => {
+			projectionCtx.sessionProjections.register({
+				key: "plan",
+				schema: planProjectionSchema,
+				init: () => ({
+					active: false,
+					wanted: null
+				}),
+				apply: (state, event) => {
+					if (event.type === "command/run" && event.data.name === "plan") {
+						if (event.data.args === void 0) return state;
+						const wanted = event.data.args.trim() !== "off";
+						return wanted === state.wanted ? state : {
+							active: state.active,
+							wanted
+						};
+					}
+					if (event.type === "plan/mode") return {
+						active: event.data.active,
+						wanted: null
+					};
+					return state;
+				},
+				view: (state) => ({
+					active: state.active,
+					pending: state.wanted !== null && state.wanted !== state.active
+				}),
+				stateVersion: 1
+			});
+		});
+		ctx.inject(["commands"], (commandCtx) => {
+			commandCtx.commands.register({
+				name: "plan",
+				description: "Enter or leave plan mode",
+				input: { hint: "[off|message]" },
+				handler: ({ agent, rawInput }) => {
+					const message = rawInput.trim();
+					if (message === "off") switch (this.set(agent, false)) {
+						case "committed": return {
+							kind: "success",
+							text: "Plan mode off."
+						};
+						case "queued": return {
+							kind: "success",
+							text: "Leaving plan mode (applies from the next step)."
+						};
+						case "cancelled": return {
+							kind: "success",
+							text: "Plan mode entry cancelled."
+						};
+						case "noop": return foldPlanMode(agent.session.events) ? {
+							kind: "success",
+							text: "Leaving plan mode (applies from the next step)."
+						} : {
+							kind: "success",
+							text: "Plan mode is already inactive."
+						};
+					}
+					const outcome = this.set(agent, true);
+					if (message !== "") agent.steer(createUserMessage({
+						content: [{
+							type: "text",
+							text: message
+						}],
+						source: { kind: "user" }
+					}));
+					return {
+						kind: "success",
+						text: outcome === "committed" ? "Plan mode on. Use /plan off to leave." : "Entering plan mode (applies from the next step). Use /plan off to leave."
+					};
+				}
+			});
+		});
+		ctx.tools.register(defineTool({
+			name: EXIT_PLAN_MODE,
+			description: EXIT_DESCRIPTION,
+			parameters: { plan: {
+				type: "string",
+				required: true,
+				description: "The complete plan, as markdown, starting with a # heading that names it."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { approved: {
+						type: "boolean",
+						const: true,
+						required: true
+					} }
+				},
+				render: () => [{
+					type: "text",
+					text: "Plan approved — plan mode exited; carry out the plan starting with your next step."
+				}]
+			},
+			execute: async (args, exec) => {
+				const agent = exec.agent;
+				if (agent === void 0) throw new Error(`${EXIT_PLAN_MODE} requires a calling agent (no session to switch)`);
+				if (!foldPlanMode(agent.session.events)) throw new Error(`${EXIT_PLAN_MODE} is only available in plan mode`);
+				if (!/^#\s+\S/.test(args.plan.trim())) throw new Error(`${EXIT_PLAN_MODE} requires a non-empty markdown plan starting with a # heading`);
+				const interaction = ctx.get("userQuestions");
+				if (interaction === void 0) throw new Error("no user-questions channel is available to review the plan; ask the user to switch the session mode instead");
+				const answer = await interaction.ask({
+					questions: [{
+						id: REVIEW_ID,
+						header: "Plan review",
+						question: "Approve this plan and leave plan mode?",
+						detail: args.plan,
+						options: [{
+							label: APPROVE_LABEL,
+							description: "Leave plan mode; the plan is carried out from the next step."
+						}, {
+							label: KEEP_PLANNING_LABEL,
+							description: "Stay in plan mode; feedback goes back to the model."
+						}],
+						intent: {
+							kind: "plan-review",
+							approve: APPROVE_LABEL
+						}
+					}],
+					agent,
+					signal: exec.signal
+				}).catch((cause) => {
+					if (cause instanceof UserQuestionError && cause.code === "ASK_CANCELLED") throw new Error("The user dismissed the plan review to speak instead; stay in plan mode, stop here, and wait for their message.");
+					throw cause;
+				});
+				if (disposed) throw new Error("the plan-mode service was reloaded while the plan was under review; present the plan again");
+				const reviewItems = answer.answers.filter((entry) => entry.id === REVIEW_ID);
+				const item = reviewItems.length === 1 ? reviewItems[0] : void 0;
+				if (item?.selected.length !== 1 || item.selected[0] !== APPROVE_LABEL || item.custom !== void 0) {
+					const feedback = item?.custom ?? "";
+					throw new Error(feedback === "" ? "The user chose to keep planning; revise the plan and present it again." : `The user chose to keep planning; their feedback: ${feedback}`);
+				}
+				this.pendingIntents.set(agent.session, {
+					active: false,
+					narrate: false
+				});
+				return { approved: true };
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: firstHeading(args.plan) ?? "Plan",
+				kind: "other",
+				content: [{
+					type: "text",
+					text: args.plan
+				}]
+			}),
+			presentResult: (_args, result) => ({
+				card: "generic",
+				title: "Plan review",
+				content: result.content
+			})
+		}));
+	}
+	/**
+	* Read the logged plan state and any selected state awaiting the next
+	* accepted in-turn pre-step.
+	*
+	* @param agent The agent to read.
+	* @returns Current logged state plus a pending selection, when present.
+	*/
+	get(agent) {
+		const active = foldPlanMode(agent.session.events);
+		const pending = this.pendingIntents.get(agent.session);
+		return pending === void 0 ? { active } : {
+			active,
+			pending: pending.active
+		};
+	}
+	/**
+	* Select whether plan mode should be active. Between turns the method
+	* appends the change immediately because no in-turn pre-step will run until
+	* another prompt starts a turn. The open-turn fold is the idle signal:
+	* agent status stays `running` through post-turn checkpointing, when no
+	* further in-turn pre-step runs. During an open turn the selection remains
+	* pending until the next accepted in-turn pre-step. Repeated selection of
+	* the current or already-pending state is a no-op.
+	*
+	* @param agent The agent to switch.
+	* @param active Whether plan mode should be active.
+	* @returns what happened: `committed` (logged now), `queued` (awaiting the
+	* next accepted in-turn pre-step), `cancelled` (an opposite pending selection
+	* was cleared; the logged state already matches), or `noop` (already in that
+	* state).
+	*/
+	set(agent, active) {
+		const session = agent.session;
+		if (active === (this.pendingIntents.get(session)?.active ?? foldPlanMode(session.events))) return "noop";
+		if (hasOpenTurn(session.events)) {
+			this.pendingIntents.set(session, {
+				active,
+				narrate: true
+			});
+			return foldPlanMode(session.events) === active ? "cancelled" : "queued";
+		}
+		if (active === foldPlanMode(session.events)) {
+			this.pendingIntents.delete(session);
+			return "cancelled";
+		}
+		session.append("plan/mode", { active });
+		this.pendingIntents.delete(session);
+		const narration = this.narration(session, active);
+		if (narration !== void 0) agent.inject(narration);
+		return "committed";
+	}
+	/** Append one pending selection before the next request assembly. */
+	onBoundary(session) {
+		const pending = this.pendingIntents.get(session);
+		if (pending === void 0) return;
+		const target = pending.active;
+		if (target === foldPlanMode(session.events)) {
+			this.pendingIntents.delete(session);
+			return;
+		}
+		session.append("plan/mode", { active: target });
+		this.pendingIntents.delete(session);
+	}
+	/** Build a user-switch notice when the last logged header described the other mode. */
+	narration(session, target) {
+		const told = planModeAtLastHeader(session.events);
+		if (told === void 0 || told === target) return;
+		const text = target ? "The user switched this session to plan mode." : "The user switched this session back to the default mode.";
+		return createUserMessage({
+			content: [{
+				type: "text",
+				text
+			}],
+			source: {
+				kind: "plugin",
+				plugin: "plan-mode",
+				form: "notice",
+				summary: text
+			}
+		});
+	}
+};
+//#endregion
+export { EXIT_PLAN_MODE, PlanModeController, PlanModeController as default, foldPlanMode, resolveConfig };

package/lib/invariant.js

@@ -0,0 +1,41 @@
+//#region lib/types/invariant.js
+/** Package-owned durable plan-mode invariants. @module @stackstackstack/dsh-plan-mode/invariant */
+const PACKAGE_NAME = "@stackstackstack/dsh-plan-mode";
+/** Cordis companion plugin name. */
+const name = "plan-mode-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Validate one `plan/mode` event before it reaches the durable log.
+* `plan/mode` is a standalone whole-value event: an idle selection commits
+* between turns and a mid-turn selection commits at the step boundary, so
+* no turn-enclosure relation exists — only the payload shape is checkable.
+*/
+function validateEvent(event, fail) {
+	if (event.type !== "plan/mode") return;
+	const active = event.data.active;
+	if (typeof active !== "boolean") fail(`plan/mode carries invalid active state ${JSON.stringify(active)}; expected a boolean`);
+}
+/** Install validation for loaded and newly appended plan-mode state. */
+const install = Object.assign((ctx, fail) => {
+	const seed = (session) => {
+		for (const event of session.events) validateEvent(event, fail);
+	};
+	for (const session of ctx.sessions.list()) seed(session);
+	ctx.on("session/created", (session) => {
+		seed(session);
+	}, { global: true });
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [, event] = args;
+		validateEvent(event, fail);
+	}, { global: true });
+}, { inject: ["sessions"] });
+/**
+* Register the plan-mode invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the plan domain: a pure re-export of the package's
+ * types outlet. Client code imports ONLY the client namespace (repo
+ * discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ *
+ * @module @stackstackstack/dsh-plan-mode/client
+ */
+export type * from './types.ts';
+//# sourceMappingURL=client.d.ts.map