The model-facing control surface for ctx.goals: get_goal, create_goal, and update_goal. The goal-tool Agent Note 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, 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?) supports edit, pause, resume, complete, and blocked. Replacements belong only to edit.

All calls are exclusive, so a model-ordered batch observes earlier mutations and their new revisions. ACP and other clients receive pure generic cards: read for get_goal, other for mutations.

A successful mutation that leaves the goal stopped contributes the existing terminal agent/turn-stop decision for that physical turn. A later same-turn resume clears the contribution. This avoids an extra model request after pause, block, or completion without changing ordinary loop continuation.

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.

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. Direct human authority may stop a goal immediately.

Config

- 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

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; 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. Successful results are compact JSON. Mutation results are followed by the goal domain's raw <goal_state> snapshot after the tool batch. activation in a result is a live observation and never becomes replay authority.

Token effect

Fixed schema cost plus one compact result per call. Mutations also retain the domain snapshot until compaction.

KV Cache effect

Schemas are prefix-stable while their definitions and visibility are unchanged. Calls, results, and resulting goal snapshots append after the reusable request prefix without invalidating earlier entries.

Known Limitations and Deferred Work

Semantic intent remains model judgment — execution can prove direct human provenance, not whether a 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 UI commands — these tools mutate state only; the same-session driver and human command surfaces are separate stack layers.
Prompt registration is independent of filtering — a scope may hide the tools while retaining their guidance unless the deployment scopes both registrations together.