@deepseek-ai/dsh-tool-goal 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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/goal/tool-goal/README.md
+README.md: b93da1ced1cfbea0b4cdc2a7e253b9a515e75b21
+README.zh.md: 2c813c6406b170f93ee0b90939904d3570425ec3

package/README.md

@@ -0,0 +1,80 @@
+# @deepseek-ai/dsh-tool-goal
+
+English | [中文](README.zh.md)
+
+The model-facing control surface for [`ctx.goals`](../goal/README.md): `get_goal`, `create_goal`, and `update_goal`. The [goal-tool Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md) owns the authority split and Codex-shaped UX.
+
+## Tools
+
+- `get_goal()` returns the current goal or `null`, including the compare-and-set id/revision, durable phase, admitted/capped goal rounds, any blocker reason, and current process-local activation.
+- `create_goal(objective, max_goal_rounds?)` creates one goal from a direct top-level human turn. The model may infer long-running goal intent without an exact command phrase; non-human turns and subagents are rejected at execution.
+- `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`. Replacements belong only to `edit`; `blocked_reason` is required only for `blocked` and is persisted with the stable code `model-reported`. Strict-schema empty-string and zero fillers count as omitted, while meaningful values remain limited to their action.
+
+All calls are exclusive, so a model-ordered batch observes earlier mutations and their new revisions. UI clients receive pure generic cards: read for `get_goal`, other for mutations. Mutation cards select the first meaningful action value and otherwise show the goal id, so accepted fillers never produce blank input.
+
+All three canonical values match the compact JSON already rendered to Native callers: `{ goal: null }` or `{ goal: { id, revision, objective, phase, roundsStarted, maxGoalRounds, blockedReason? }, activation }`. Programmatic consumers therefore receive the same domain structure without parsing the rendered JSON.
+
+An autonomous goal round that successfully reports `complete` or `blocked` marks that tool execution with `concludeTurn()` so the physical turn stops after the step. Direct-human mutations never contribute this stop: the assistant may acknowledge the change and concurrent human steering remains available to the loop.
+
+## Authority
+
+Execution requires the exact live `exec.agent`, its inherited `AgentRegistry` initiator, running status, and an open turn. Create, edit, pause, and resume additionally require an accepted `{ kind: 'user' }` message or steering event in a runtime-root agent's current turn. Durable fork lineage does not demote a resumed root; live subagent ownership does.
+
+`{ kind: 'user' }` is a host attestation. `Agent.followup()` and `steer()` assign it when their caller omits a source, so plugins, schedulers, and other non-human producers must pass their own source rather than inheriting human authority.
+
+Complete and blocked also accept the exact current goal round: a goal-sourced `user/message` whose id, revision, and round equal the folded current goal. A goal-round blocked call is mechanically rejected until `blockedAfterConsecutiveRounds`; the model judges whether the same condition actually persisted and must describe it in `blocked_reason`. Direct human authority may stop a goal immediately.
+
+## Config
+
+```yaml
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+  config:
+    blockedAfterConsecutiveRounds: 3
+```
+
+The value must be a positive safe integer. It supplies both the hard lower bound on model self-blocking and the number named in model guidance.
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+A fixed goal policy says when semantic human intent warrants creation, requires exact read-before-update refs, explains rearming after resume/fork, and limits completion/blocking claims. The configured threshold is interpolated into that guidance.
+
+##### Goal policy
+
+```markdown
+Use goal tools for one long-running completion objective in the current session. create_goal may infer goal intent from a direct human request in any language; do not create a goal for routine single-turn work. Call get_goal before update_goal and copy its exact goal_id and revision. After session resume or fork, an active goal is disarmed: when a human asks to continue or resume in any wording or language, use update_goal action resume to rearm it. Mark complete only when the objective is actually achieved. Mark blocked only after the same blocking condition persists for at least 3 consecutive goal rounds, and report that concrete condition in blocked_reason; difficulty, uncertainty, or useful remaining work is not blocked.
+```
+
+#### Token effect
+
+Small fixed input cost on every request where this plugin's prompt registration is in scope.
+
+#### KV Cache effect
+
+Prefix-stable while the plugin scope, configured threshold, and guidance text are unchanged. Activation, disposal, or configuration changes may invalidate reuse from this prompt section.
+
+### Tool schemas and results
+
+#### What the model sees
+
+The generated [`get_goal`, `create_goal`, and `update_goal` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-goal). Successful results are compact JSON. A mutation appends the goal domain's durable `goal/change` event without queuing model context. `activation` in a result is a live observation and never becomes replay authority.
+
+#### Token effect
+
+Fixed schema cost plus one compact result per call. The durable mutation adds no separate model-visible context.
+
+#### KV Cache effect
+
+Schemas are prefix-stable while their definitions and visibility are unchanged. Calls and results append after the reusable request prefix without invalidating earlier entries.
+
+## Known Limitations and Deferred Work
+
+- **Semantic intent remains model judgment** — execution can prove that the current turn contains a direct human message, not whether the request is substantial enough to merit a goal.
+- **Same-condition blocking remains model judgment** — the runtime enforces distinct admitted-round count, not semantic equivalence of obstacles; an independent evaluator is deferred.
+- **No scheduling or direct human rendering** — these tools mutate state only; the same-session driver and [`dsh-command-goal`](../command-goal/README.md) are independent consumers of the same domain.
+- **Goal-round authority requires a driver** — the autonomous `complete`/`blocked` path is dormant unless a continuation driver admits goal-sourced user turns; mounting this tool package alone does not create them.
+- **Prompt registration is independent of filtering** — a scope may hide the tools while retaining their guidance unless the deployment scopes both registrations together.

package/README.zh.md

@@ -0,0 +1,80 @@
+# @deepseek-ai/dsh-tool-goal
+
+[English](README.md) | 中文
+
+[`ctx.goals`](../goal/README.md) 的面向模型控制接口：`get_goal`、`create_goal` 和 `update_goal`。[goal 工具 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md) 负责权限拆分与 Codex 风格用户体验。
+
+## 工具
+
+- `get_goal()` 返回当前 goal 或 `null`，包括比较并设置 id／revision、持久 phase、Goal Round 的已准入数／上限、任何 blocker reason，以及当前进程本地续行启用状态。
+- `create_goal(objective, max_goal_rounds?)` 根据顶层人类直接发起的轮次创建一个 goal。模型可以推断长期运行的 goal 意图，而无需精确命令短语；非人类轮次和 subagent 会在执行时被拒绝。
+- `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`。替换值只属于 `edit`；`blocked_reason` 只有在 action 为 `blocked` 时才必填，并以稳定代码 `model-reported` 持久化。严格 schema 下的空字符串和零填充值视为省略，而有意义的值仍限定到各自 action。
+
+所有调用都互斥，因此模型排序的批次能观察到更早变更及其新 revision。UI 客户端会收到纯通用卡片：`get_goal` 使用 read，变更使用 other。变更卡片选择第一个有意义的 action 值，否则显示 goal id，因此已接受的填充值绝不会产生空输入。
+
+3 个规范值都与已经渲染给 Native 调用方的紧凑 JSON 一致：`{ goal: null }` 或 `{ goal: { id, revision, objective, phase, roundsStarted, maxGoalRounds, blockedReason? }, activation }`。因此，编程消费方无需解析渲染后的 JSON，即可收到相同领域结构。
+
+自主 Goal Round 成功报告 `complete` 或 `blocked` 时，会用 `concludeTurn()` 标记该次工具执行，使物理轮次在该步骤后停止。人类直接变更绝不会导致这种停止：assistant 可以确认变更，循环仍可接收并发的人类 steering（中途引导）。
+
+## 权限
+
+执行要求完全相同的活跃 `exec.agent`、其继承的 `AgentRegistry` initiator、running 状态与开放轮次。create、edit、pause 和 resume 还要求运行时根 agent（智能体）的当前轮次中存在已接受的 `{ kind: 'user' }` 消息或 steering 事件。持久 fork 谱系不会降低已恢复根 agent 的等级；活跃 subagent 所有权会降低。
+
+`{ kind: 'user' }` 是宿主证明。`Agent.followup()` 与 `steer()` 会在调用方省略 source 时分配该值，因此插件、调度器与其他非人类生产方必须传入自己的 source，不能继承用户权限。
+
+complete 与 blocked 还接受完全一致的当前 Goal Round：来源为 goal 的 `user/message`，其 id、revision 和 Round 编号与折叠后的当前 goal 相等。在达到 `blockedAfterConsecutiveRounds` 前，Goal Round 的 blocked 调用会被机械拒绝；模型判断同一条件是否确实持续，并必须在 `blocked_reason` 中说明。人类直接授权可以立即停止 goal。
+
+## 配置
+
+```yaml
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+  config:
+    blockedAfterConsecutiveRounds: 3
+```
+
+该值必须是正的安全整数。它既提供模型自行报告阻塞的硬下限，也决定模型指引中指明的数值。
+
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到的内容
+
+固定 goal 策略说明何种用户语义意图值得创建 goal，要求更新前先精确读取 ref，解释会话 resume／fork 后如何重新启用续行，并限制完成／阻塞声明。配置的阈值会插入该指引。
+
+##### Goal 策略
+
+```markdown
+Use goal tools for one long-running completion objective in the current session. create_goal may infer goal intent from a direct human request in any language; do not create a goal for routine single-turn work. Call get_goal before update_goal and copy its exact goal_id and revision. After session resume or fork, an active goal is disarmed: when a human asks to continue or resume in any wording or language, use update_goal action resume to rearm it. Mark complete only when the objective is actually achieved. Mark blocked only after the same blocking condition persists for at least 3 consecutive goal rounds, and report that concrete condition in blocked_reason; difficulty, uncertainty, or useful remaining work is not blocked.
+```
+
+#### Token 影响
+
+此插件的提示词注册位于请求范围内时，每次请求都会产生少量固定输入成本。
+
+#### KV Cache 影响
+
+插件范围、配置阈值和指引文本不变时，前缀保持稳定。启用、dispose（资源释放）或配置变更可能使此提示词章节的复用失效。
+
+### 工具 schema 与结果
+
+#### 模型看到的内容
+
+生成的 [`get_goal`、`create_goal` 和 `update_goal` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-goal)。成功结果是紧凑 JSON。变更会追加 goal 领域的持久 `goal/change` 事件，而不会把模型上下文排队。结果中的 `activation` 是实时观察值，绝不会成为回放权限依据。
+
+#### Token 影响
+
+固定 schema 成本，加上每次调用的一条紧凑结果。持久变更不会增加单独的模型可见上下文。
+
+#### KV Cache 影响
+
+schema 的定义与可见性不变时，前缀保持稳定。调用和结果会追加到可复用请求前缀之后，不会使更早条目失效。
+
+## 已知限制与暂缓事项
+
+- **语义意图仍由模型判断**：执行只能证明当前轮次包含一条人类直接发送的消息，无法证明请求是否足够重大而值得创建 goal。
+- **阻塞条件是否相同仍由模型判断**：运行时强制统计互不重复的已准入 Goal Round，而不判断障碍在语义上是否等价；独立评估器的实现暂缓。
+- **不负责调度或直接面向人类呈现**：这些工具只变更状态；同会话驱动器与 [`dsh-command-goal`](../command-goal/README.md) 是同一领域的独立消费方。
+- **Goal Round 权限需要驱动器**：除非续行驱动器准入 goal 来源的用户轮次，否则自主 `complete`／`blocked` 路径不会启用；只挂载这个包不会创建这些轮次。
+- **提示词注册与过滤相互独立**：某个范围可能隐藏工具，却保留指引，除非部署将两项注册限定在同一范围。

package/lib/index.js

@@ -0,0 +1,372 @@
+import z from "@deepseek-ai/schemastery";
+import { GoalId } from "@deepseek-ai/dsh-goal";
+import { HarnessError, boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/authority.js
+/** Execution-time authority checks for the model-facing goal tools. */
+/** Throw one structured tool-policy failure. */
+function reject(message, code = "GOAL_TOOL_AUTHORITY_REQUIRED") {
+	throw new HarnessError(message, code);
+}
+/** Locate the open turn enclosing a model tool call. */
+function openTurn(agent) {
+	const events = agent.session.events;
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const boundary = events[index];
+		if (boundary?.type === "turn/end") reject("goal tools require an open model turn", "GOAL_TOOL_DRIVER_REQUIRED");
+		if (boundary?.type === "turn/start") return {
+			start: boundary,
+			events: events.slice(index + 1)
+		};
+	}
+	return reject("goal tools require an open model turn", "GOAL_TOOL_DRIVER_REQUIRED");
+}
+/**
+* Resolve and authenticate the calling agent and its driver boundary.
+* @param ctx - Context carrying the live agent registry.
+* @param exec - Tool execution metadata supplied by the registry.
+* @returns The authenticated agent and its current turn window.
+*/
+function goalToolExecution(ctx, exec) {
+	const agent = exec.agent;
+	if (agent === void 0) return reject("goal tools require a calling agent", "GOAL_TOOL_AGENT_REQUIRED");
+	if (ctx.agents.get(agent.id) !== agent || agent.status !== "running" || ctx.agents.currentInitiator() !== agent) return reject("goal tools require the exact live calling agent inside its active driver", "GOAL_TOOL_DRIVER_REQUIRED");
+	return {
+		agent,
+		...openTurn(agent)
+	};
+}
+/**
+* Whether host-attested human input appears in the current root-agent turn.
+* An omitted `Agent.followup()` / `steer()` source resolves to `user`, so non-human
+* producers must supply their own source rather than inheriting this authority.
+*/
+function hasDirectHumanInput(ctx, execution) {
+	if (!ctx.agents.roots().includes(execution.agent)) return false;
+	return execution.events.some((event) => event.type === "user/message" && event.data.source.kind === "user");
+}
+/** Whether this turn is the current goal's exact admitted round. */
+function isMatchingGoalRound(execution, goal) {
+	return execution.events.some((event) => event.type === "user/message" && event.data.source.kind === "goal" && event.data.source.goalId === goal.id && event.data.source.revision === goal.revision && event.data.source.round === goal.roundsStarted);
+}
+/**
+* Require authority originating in a human message accepted by a runtime root.
+* @param ctx - Context carrying the live agent graph.
+* @param execution - Authenticated current tool execution.
+*/
+function requireDirectHuman(ctx, execution) {
+	if (hasDirectHumanInput(ctx, execution)) return;
+	reject("this goal operation requires a direct human turn on a top-level agent");
+}
+/**
+* Resolve completion authority from either direct human input or the exact goal round.
+* @param ctx - Context carrying live agents and goal state.
+* @param execution - Authenticated current tool execution.
+* @returns The direct-human or exact-goal-round authority grant.
+*/
+function completionAuthority(ctx, execution) {
+	if (hasDirectHumanInput(ctx, execution)) return { kind: "direct-human" };
+	const goal = ctx.goals.get(execution.agent);
+	if (goal !== void 0 && isMatchingGoalRound(execution, goal)) return {
+		kind: "goal-round",
+		goal
+	};
+	return reject("complete and blocked require a direct human turn or the current goal round");
+}
+//#endregion
+//#region lib/types/wrapup.js
+/**
+* Render the closing-message instruction injected after an autonomous goal
+* round reports `complete` or `blocked`, replacing the former hard turn stop
+* so the model still addresses the user once before the turn ends.
+* @param objective - the terminal goal's objective, echoed for grounding.
+* @param blockedReason - the validated report for `blocked`; omitted for `complete`.
+* @returns a fresh one-block context for `ToolRunContext.deferContext()`.
+*/
+function renderWrapupContext(objective, blockedReason) {
+	const heading = `Objective: ${JSON.stringify(objective)}\n`;
+	return [{
+		type: "text",
+		text: blockedReason === void 0 ? "<goal_complete>\n" + heading + "The goal is marked complete and this autonomous run is ending. Write the closing message to the user now: state the outcome, summarize what was done and how it was verified, and point to the concrete results (files, commits, or other artifacts). Report only what earlier rounds and tool results in this session actually establish; when a detail is not in the session, say so instead of inventing it. Note anything the user should review or do next. Address the user directly. Do not call any more tools in this run; further work waits for the user's next instruction.\n</goal_complete>" : "<goal_blocked>\n" + heading + `Blocked: ${JSON.stringify(blockedReason)}\nThe goal is marked blocked and this autonomous run is ending. Write the closing message to the user now: state what has been completed so far, describe the concrete blocking condition and what you tried, and say exactly what you need from the user to continue. Report only what earlier rounds and tool results in this session actually establish; when a detail is not in the session, say so instead of inventing it. Address the user directly. Do not call any more tools in this run; further work waits for the user's next instruction.
+</goal_blocked>`
+	}];
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Model-facing `get_goal`, `create_goal`, and `update_goal` tools over the
+* persisted same-session goal domain.
+* @module @deepseek-ai/dsh-tool-goal
+*/
+const name = "tool-goal";
+const inject = [
+	"agents",
+	"goals",
+	"tools",
+	"systemPrompt"
+];
+/** Schemastery config for the goal-tool policy. */
+const Config = z.object({ blockedAfterConsecutiveRounds: z.number().step(1).min(1).default(3) });
+const UPDATE_ACTIONS = [
+	"edit",
+	"pause",
+	"resume",
+	"complete",
+	"blocked"
+];
+const CREATE_DESCRIPTION = "Create one persisted same-session completion goal when the current direct human request is a long-running objective that should continue across autonomous goal rounds. You may infer that intent without requiring the user to say \"create a goal\". Do not use this for trivial single-turn work. Execution rejects non-human and subagent authority.";
+const GET_DESCRIPTION = "Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal.";
+const GOAL_VALUE_SCHEMA = { oneOf: [{
+	type: "object",
+	additionalProperties: false,
+	properties: { goal: {
+		type: "null",
+		required: true
+	} }
+}, {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		goal: {
+			type: "object",
+			additionalProperties: false,
+			required: true,
+			properties: {
+				id: {
+					type: "string",
+					required: true
+				},
+				revision: {
+					type: "integer",
+					required: true
+				},
+				objective: {
+					type: "string",
+					required: true
+				},
+				phase: {
+					type: "string",
+					required: true,
+					enum: [
+						"active",
+						"paused",
+						"blocked",
+						"complete"
+					]
+				},
+				roundsStarted: {
+					type: "integer",
+					required: true
+				},
+				maxGoalRounds: {
+					type: "integer",
+					required: true
+				},
+				blockedReason: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						code: {
+							type: "string",
+							required: true
+						},
+						message: {
+							type: "string",
+							required: true
+						}
+					}
+				}
+			}
+		},
+		activation: {
+			type: "string",
+			required: true,
+			enum: ["armed", "disarmed"]
+		}
+	}
+}] };
+/** Render policy guidance with its deployment-selected blocked threshold. */
+function guidance(blockedAfter) {
+	return `Use goal tools for one long-running completion objective in the current session. create_goal may infer goal intent from a direct human request in any language; do not create a goal for routine single-turn work. Call get_goal before update_goal and copy its exact goal_id and revision. After session resume or fork, an active goal is disarmed: when a human asks to continue or resume in any wording or language, use update_goal action resume to rearm it. Mark complete only when the objective is actually achieved. Mark blocked only after the same blocking condition persists for at least ${blockedAfter} consecutive goal rounds, and report that concrete condition in blocked_reason; difficulty, uncertainty, or useful remaining work is not blocked.`;
+}
+/** Validate config even when apply is called directly outside Loader normalization. */
+function resolveConfig(config) {
+	const blockedAfter = config.blockedAfterConsecutiveRounds ?? 3;
+	if (!Number.isSafeInteger(blockedAfter) || blockedAfter < 1) throw new TypeError("blockedAfterConsecutiveRounds must be a positive safe integer");
+	return { blockedAfterConsecutiveRounds: blockedAfter };
+}
+/** Whether optional text is meaningful rather than a strict-schema empty filler. */
+function hasText(value) {
+	return value !== void 0 && value !== "";
+}
+/** Whether an optional round cap is meaningful rather than a strict-schema zero filler. */
+function hasRoundCap(value) {
+	return value !== void 0 && value !== 0;
+}
+/** Build the exact compare-and-set ref from model arguments. */
+function goalRef(goalId, revision) {
+	if (goalId.length === 0 || goalId !== goalId.trim() || !Number.isSafeInteger(revision) || revision < 1) throw new HarnessError("goal_id must be non-empty and revision must be a positive safe integer", "GOAL_TOOL_INVALID_UPDATE");
+	return {
+		id: GoalId(goalId),
+		revision
+	};
+}
+/** Stable compact model result; activation is an observation, not replay state. */
+function goalValue(goal) {
+	if (goal === void 0) return { goal: null };
+	return {
+		goal: {
+			id: goal.id,
+			revision: goal.revision,
+			objective: goal.objective,
+			phase: goal.phase,
+			roundsStarted: goal.roundsStarted,
+			maxGoalRounds: goal.maxGoalRounds,
+			...goal.blockedReason === void 0 ? {} : { blockedReason: {
+				code: goal.blockedReason.code,
+				message: goal.blockedReason.message
+			} }
+		},
+		activation: goal.activation
+	};
+}
+/** Reusable canonical output declaration for all three goal controls. */
+const GOAL_OUTPUT = {
+	schema: GOAL_VALUE_SCHEMA,
+	render: (_args, value) => [{
+		type: "text",
+		text: JSON.stringify(value)
+	}]
+};
+/** Generic, args-only pending presentation shared by the goal tools. */
+function present(title, kind, rawInput) {
+	return {
+		card: "generic",
+		title,
+		kind,
+		...rawInput === void 0 ? {} : { rawInput }
+	};
+}
+/** Register the three Codex-shaped goal tools and their shared policy section. */
+function apply(ctx, config) {
+	const resolved = resolveConfig(config);
+	ctx.systemPrompt.section({
+		name: "tool:goal",
+		order: 114,
+		text: guidance(resolved.blockedAfterConsecutiveRounds)
+	});
+	ctx.tools.register(defineTool({
+		name: "get_goal",
+		description: GET_DESCRIPTION,
+		parameters: {},
+		output: GOAL_OUTPUT,
+		execute(_args, exec) {
+			const execution = goalToolExecution(ctx, exec);
+			return Promise.resolve(goalValue(ctx.goals.get(execution.agent)));
+		},
+		presentCall: () => present("Read current goal", "read")
+	}));
+	ctx.tools.register(defineTool({
+		name: "create_goal",
+		description: CREATE_DESCRIPTION,
+		parameters: {
+			objective: {
+				type: "string",
+				required: true,
+				description: "The concrete completion objective inferred from the direct human request."
+			},
+			max_goal_rounds: {
+				type: "number",
+				description: "Optional positive safe-integer limit on automatic continuation rounds."
+			}
+		},
+		output: GOAL_OUTPUT,
+		execute(args, exec) {
+			const execution = goalToolExecution(ctx, exec);
+			requireDirectHuman(ctx, execution);
+			const goal = ctx.goals.create(execution.agent, {
+				objective: args.objective,
+				...args.max_goal_rounds === void 0 ? {} : { maxGoalRounds: args.max_goal_rounds }
+			});
+			return Promise.resolve(goalValue(goal));
+		},
+		presentCall: (args) => present("Create goal", "other", args.objective)
+	}));
+	ctx.tools.register(defineTool({
+		name: "update_goal",
+		description: "Update the exact current goal revision. edit, pause, and resume require a direct top-level human request. During an automatic continuation of the current goal, complete and blocked are also allowed. blocked is rejected before the configured minimum round count; the model remains responsible for judging that the same condition persisted across those rounds and must explain it in blocked_reason.",
+		parameters: {
+			goal_id: {
+				type: "string",
+				required: true,
+				description: "Exact id returned by get_goal."
+			},
+			revision: {
+				type: "number",
+				required: true,
+				description: "Exact positive revision returned by get_goal."
+			},
+			action: {
+				type: "string",
+				required: true,
+				enum: UPDATE_ACTIONS,
+				description: "edit | pause | resume | complete | blocked"
+			},
+			objective: {
+				type: "string",
+				description: "Replacement objective; valid only with action edit."
+			},
+			max_goal_rounds: {
+				type: "number",
+				description: "Replacement cap; valid only with action edit."
+			},
+			blocked_reason: {
+				type: "string",
+				description: "Concrete blocking condition; required only with action blocked."
+			}
+		},
+		output: GOAL_OUTPUT,
+		execute(args, exec) {
+			const execution = goalToolExecution(ctx, exec);
+			const ref = goalRef(args.goal_id, args.revision);
+			const replacements = {
+				...hasText(args.objective) ? { objective: args.objective } : {},
+				...hasRoundCap(args.max_goal_rounds) ? { maxGoalRounds: args.max_goal_rounds } : {}
+			};
+			if (args.action === "edit") {
+				requireDirectHuman(ctx, execution);
+				if (hasText(args.blocked_reason)) throw new HarnessError("blocked_reason is valid only with action blocked", "GOAL_TOOL_INVALID_UPDATE");
+				const goal = ctx.goals.edit(execution.agent, ref, replacements);
+				return Promise.resolve(goalValue(goal));
+			}
+			if (args.action === "pause" || args.action === "resume") {
+				requireDirectHuman(ctx, execution);
+				if (hasText(args.objective) || hasRoundCap(args.max_goal_rounds) || hasText(args.blocked_reason)) throw new HarnessError("objective and max_goal_rounds are valid only with action edit; blocked_reason is valid only with action blocked", "GOAL_TOOL_INVALID_UPDATE");
+				const goal = args.action === "pause" ? ctx.goals.pause(execution.agent, ref) : ctx.goals.resume(execution.agent, ref);
+				return Promise.resolve(goalValue(goal));
+			}
+			const authority = completionAuthority(ctx, execution);
+			if (hasText(args.objective) || hasRoundCap(args.max_goal_rounds)) throw new HarnessError("objective and max_goal_rounds are valid only with action edit", "GOAL_TOOL_INVALID_UPDATE");
+			if (args.action === "complete" && hasText(args.blocked_reason)) throw new HarnessError("blocked_reason is valid only with action blocked", "GOAL_TOOL_INVALID_UPDATE");
+			if (args.action === "blocked" && (args.blocked_reason === void 0 || args.blocked_reason.trim().length === 0)) throw new HarnessError("blocked_reason is required with action blocked", "GOAL_TOOL_INVALID_UPDATE");
+			if (args.action === "blocked" && authority.kind === "goal-round" && authority.goal.roundsStarted < resolved.blockedAfterConsecutiveRounds) throw new HarnessError(`blocked requires at least ${resolved.blockedAfterConsecutiveRounds} consecutive goal rounds; current round is ${authority.goal.roundsStarted}`, "GOAL_TOOL_BLOCK_THRESHOLD");
+			const goal = args.action === "complete" ? ctx.goals.complete(execution.agent, ref) : ctx.goals.block(execution.agent, ref, {
+				code: "model-reported",
+				message: args.blocked_reason
+			});
+			if (authority.kind === "goal-round") exec.deferContext(createUserMessage({
+				content: args.action === "complete" ? renderWrapupContext(goal.objective) : renderWrapupContext(goal.objective, args.blocked_reason),
+				source: {
+					kind: "plugin",
+					plugin: "tool-goal",
+					form: "notice",
+					summary: boundContextSummary(`${args.action}: ${goal.objective}`)
+				}
+			}));
+			return Promise.resolve(goalValue(goal));
+		},
+		presentCall: (args) => present(`${args.action === "blocked" ? "Mark" : args.action.charAt(0).toUpperCase() + args.action.slice(1)} goal`, "other", hasText(args.blocked_reason) ? args.blocked_reason : hasText(args.objective) ? args.objective : hasRoundCap(args.max_goal_rounds) ? args.max_goal_rounds : args.goal_id)
+	}));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tool-goal`.
+* @module @deepseek-ai/dsh-tool-goal/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-goal";
+/** Cordis companion plugin name. */
+const name = "tool-goal-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter owns no independent state or event protocol;
+* accepted mutations are checked by the goal domain and authority behavior is package-tested.
+*/
+const install = () => {};
+/**
+* Register this package's 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/authority.d.ts

@@ -0,0 +1,44 @@
+/** Execution-time authority checks for the model-facing goal tools. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { GoalView } from '@deepseek-ai/dsh-goal';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+type TurnStartEvent = Extract<SessionEvent, {
+    type: 'turn/start';
+}>;
+/** Current open turn plus the events accepted after its start boundary. */
+export interface GoalToolExecution {
+    readonly agent: Agent;
+    readonly start: TurnStartEvent;
+    readonly events: readonly SessionEvent[];
+}
+/** Hard authority granted to one state-changing call. */
+export type GoalToolAuthority = {
+    readonly kind: 'direct-human';
+} | {
+    readonly kind: 'goal-round';
+    readonly goal: GoalView;
+};
+/**
+ * Resolve and authenticate the calling agent and its driver boundary.
+ * @param ctx - Context carrying the live agent registry.
+ * @param exec - Tool execution metadata supplied by the registry.
+ * @returns The authenticated agent and its current turn window.
+ */
+export declare function goalToolExecution(ctx: Context, exec: ToolRunContext): GoalToolExecution;
+/**
+ * Require authority originating in a human message accepted by a runtime root.
+ * @param ctx - Context carrying the live agent graph.
+ * @param execution - Authenticated current tool execution.
+ */
+export declare function requireDirectHuman(ctx: Context, execution: GoalToolExecution): void;
+/**
+ * Resolve completion authority from either direct human input or the exact goal round.
+ * @param ctx - Context carrying live agents and goal state.
+ * @param execution - Authenticated current tool execution.
+ * @returns The direct-human or exact-goal-round authority grant.
+ */
+export declare function completionAuthority(ctx: Context, execution: GoalToolExecution): GoalToolAuthority;
+export {};
+//# sourceMappingURL=authority.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Model-facing `get_goal`, `create_goal`, and `update_goal` tools over the
+ * persisted same-session goal domain.
+ * @module @deepseek-ai/dsh-tool-goal
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "tool-goal";
+export declare const inject: string[];
+/** Model policy and hard lower bounds for goal-state updates. */
+export interface Config {
+    /** Minimum admitted goal rounds before the model may self-report `blocked`. */
+    blockedAfterConsecutiveRounds?: number;
+}
+/** Schemastery config for the goal-tool policy. */
+export declare const Config: z<Config>;
+/** Register the three Codex-shaped goal tools and their shared policy section. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-goal`.
+ * @module @deepseek-ai/dsh-tool-goal/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-goal-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/wrapup.d.ts

@@ -0,0 +1,12 @@
+/** Model-visible wrap-up instruction for a terminal autonomous goal update. */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+/**
+ * Render the closing-message instruction injected after an autonomous goal
+ * round reports `complete` or `blocked`, replacing the former hard turn stop
+ * so the model still addresses the user once before the turn ends.
+ * @param objective - the terminal goal's objective, echoed for grounding.
+ * @param blockedReason - the validated report for `blocked`; omitted for `complete`.
+ * @returns a fresh one-block context for `ToolRunContext.deferContext()`.
+ */
+export declare function renderWrapupContext(objective: string, blockedReason?: string): ContentBlock[];
+//# sourceMappingURL=wrapup.d.ts.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@deepseek-ai/dsh-tool-goal",
+  "description": "Model-facing same-session goal tools with execution-time authority checks",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/goal/tool-goal"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-goal": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-goal": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}