@deepseek-ai/dsh-tool-goal

The model-facing control surface for ctx.goals: get_goal, create_goal, and update_goal. The goal-tool RFC 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.

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.

Token effect: Small fixed input cost on every request where this plugin's prompt registration is in scope.

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.

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.

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.

4.4 KiB Raw Blame History