@deepseek-ai/dsh-tool-schedule 0.2.1-rc.5 → 0.2.2-alpha.3

package/README.i18n.yaml

@@ -3,68 +3,86 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/schedule/tool-schedule/README.md
 /:
-  en: 5bcd39034f505033
-  zh: 9bfd85a1ad52bc67
+  en: d77b6ecc8e63e0f2
+  zh: 19ff500139aec118
 /deepseek-ai-dsh-tool-schedule:
   en: eb91320d8594cfca
   zh: 7a900a2029baafa5
 /deepseek-ai-dsh-tool-schedule/summary:
-  en: 3552ccd992a1540e
-  zh: 13241608f0b9fc8a
+  en: c7480ff7361e0c8f
+  zh: 4b6833658ca71cb8
 /deepseek-ai-dsh-tool-schedule/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
 /deepseek-ai-dsh-tool-schedule/use-this-package:
-  en: a692cac1bda0f1bc
-  zh: 3cc2e4bff8062e4e
+  en: d54bb40aa19d48e9
+  zh: 5ff029a30b4ee2c4
 /deepseek-ai-dsh-tool-schedule/use-this-package/when-to-choose-it:
-  en: a9203babc3d8db01
-  zh: 4b26bfe528f39972
+  en: 398e453a30e458b1
+  zh: 049514128eee6bda
+/deepseek-ai-dsh-tool-schedule/use-this-package/user-authorization:
+  en: bf63fe71777703fe
+  zh: 3935ef0931f9b50f
 /deepseek-ai-dsh-tool-schedule/use-this-package/the-four-tools:
-  en: f8aae686d0531c29
-  zh: 3cccd1ba81aae48d
+  en: 7b192d94290c0e38
+  zh: fdb6963131cb1cab
 /deepseek-ai-dsh-tool-schedule/use-this-package/minimal-configuration:
-  en: eef3a83c0ffb2931
-  zh: 9b527abfde4c3406
+  en: 4da5d0e7bff6f5b3
+  zh: 093699c732eacf72
 /deepseek-ai-dsh-tool-schedule/understand-the-implementation:
-  en: 065702b7a82b8fa1
-  zh: 642037baaa2c0f1d
+  en: b3bbc30caad60d2a
+  zh: a0c2fa3e8e085759
 /deepseek-ai-dsh-tool-schedule/understand-the-implementation/source-map:
-  en: 676c4e0595fcc8dd
-  zh: f02ed861f66e7747
+  en: 9d899dc328be7e20
+  zh: f0c353326e644395
 /deepseek-ai-dsh-tool-schedule/further-exploration:
-  en: 1484566b323c3cff
-  zh: 1b1b9fbf85daf3fa
+  en: d41b7d0d315a7086
+  zh: f69c26b34721ffde
 /deepseek-ai-dsh-tool-schedule/model-experience:
   en: 215e7ba838619b7b
   zh: a311da3843709f90
+/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt:
+  en: eb7c154ebdf40bd7
+  zh: 40f739f10eb4c89e
+/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt/what-the-model-sees:
+  en: bf567fba90b70e70
+  zh: 9b2e01bd756c9b20
+/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt/what-the-model-sees/task-authorization:
+  en: 286eac8fa217213b
+  zh: 805ac84224bc2140
+/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt/token-effect:
+  en: f943e9c303ec4c7b
+  zh: f44cb084c17b6d2b
+/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt/kv-cache-effect:
+  en: 8ecdb4f045cb35e5
+  zh: 46cd350ee096511d
 /deepseek-ai-dsh-tool-schedule/model-experience/tool-schemas:
   en: 3039bc5e7a796b21
   zh: 6b7a9eaf69c9ea53
 /deepseek-ai-dsh-tool-schedule/model-experience/tool-schemas/what-the-model-sees:
-  en: 0056efd9de0ecd8c
-  zh: 6887c2dd9ed8587f
+  en: c78c5a1ae65173ea
+  zh: 04533f81725efa04
 /deepseek-ai-dsh-tool-schedule/model-experience/tool-schemas/token-effect:
   en: 70fb9094859d0804
   zh: 30726b045484713c
 /deepseek-ai-dsh-tool-schedule/model-experience/tool-schemas/kv-cache-effect:
   en: 332231fb9f1b8146
   zh: eace0b2e789d1c0f
-/deepseek-ai-dsh-tool-schedule/model-experience/reminder-results:
-  en: ffeb087f9476fddf
-  zh: 94569d39555d5192
-/deepseek-ai-dsh-tool-schedule/model-experience/reminder-results/what-the-model-sees:
-  en: 68ce690c2d5c2312
-  zh: d3a9fca950518702
-/deepseek-ai-dsh-tool-schedule/model-experience/reminder-results/token-effect:
-  en: a08931b2c5048399
-  zh: 758ea2131adb23e4
-/deepseek-ai-dsh-tool-schedule/model-experience/reminder-results/kv-cache-effect:
+/deepseek-ai-dsh-tool-schedule/model-experience/task-results:
+  en: c47b2272c94ac202
+  zh: 6a5bcfde187b3007
+/deepseek-ai-dsh-tool-schedule/model-experience/task-results/what-the-model-sees:
+  en: 18459cc1f3009e83
+  zh: 00a9e870dae49f58
+/deepseek-ai-dsh-tool-schedule/model-experience/task-results/token-effect:
+  en: 681160f74fec9bec
+  zh: c4cec94e94c56aa8
+/deepseek-ai-dsh-tool-schedule/model-experience/task-results/kv-cache-effect:
   en: 2fbf2175168e8244
   zh: 9c4c1964ae59e661
 /deepseek-ai-dsh-tool-schedule/known-limitations-and-deferred-work:
-  en: 7623c6ce4dc40597
-  zh: ad91348cb37d0ec6
+  en: a160cb125b7c20a1
+  zh: 708113b410d87d46
 /deepseek-ai-dsh-tool-schedule/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: b2ee0fbaa165910d

package/README.md

@@ -1,5 +1,5 @@
 ---
-description: "Preset-scoped reminder management tools (schedule_create, schedule_list, schedule_update, schedule_delete) over the Host ctx.schedule service, for deployments choosing which agents may keep durable reminders."
+description: "Preset-scoped scheduled task tools (schedule_create, schedule_list, schedule_view, schedule_edit) over the Host ctx.schedule service, for deployments choosing which agents may manage scheduled tasks."
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use `dsh-tool-schedule` to let an agent create, list, edit, and delete durable Host reminders through `schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete`. The package registers the four tools in the preset or Agent scope that mounts it, so the composition decides which agents receive them; `minimal` keeps none. Each call acts on the calling Agent's Session and only manages stored reminders — the Host `@deepseek-ai/dsh-schedule` service owns storage, scheduling, and delivery. Failures return one structured error code instead of storage details.
+Use `dsh-tool-schedule` to let an agent create, list, view, update, and delete Host scheduled tasks through `schedule_create`, `schedule_list`, `schedule_view`, and `schedule_edit`. A scheduled task delivers its instruction to a target Session at each occurrence of its recurrence rule. The package registers the four tools in the preset or Agent scope that mounts it; `minimal` keeps none. Tasks belong to the Host: the tools read and change any task by id, and only the delivery target names a Session. The Host `@deepseek-ai/dsh-schedule` service owns storage, scheduling, and delivery. Failures return one structured error code.
 
 ## Table of Contents
 
@@ -25,18 +25,24 @@ Use `dsh-tool-schedule` to let an agent create, list, edit, and delete durable H
 <a id="use-this-package"></a>
 ## Use this package
 
-Add the row below to a preset's plugin list when that preset's agents should manage durable reminders. The shipped Web `standard`, `cordis`, and `ptc` presets mount it; `minimal` does not.
+Add the row below to a preset's plugin list when that preset's agents should manage scheduled tasks. The shipped Web `standard`, `cordis`, and `ptc` presets mount it; `minimal` does not.
 
 ### When to choose it
 
-Choose it for any preset whose agents need to schedule future work in their own Session, and load `@deepseek-ai/dsh-schedule` in the same process: this package is only the model-facing consumer of that service. A preset that should stay capability-poor — `minimal` is the shipped example — omits the row, and its agents see no reminder tool at all.
+Choose it for any preset whose agents need to schedule future work, and load `@deepseek-ai/dsh-schedule` in the same process: this package is only the model-facing consumer of that service. A preset that should stay capability-poor — `minimal` is the shipped example — omits the row, and its agents see no Schedule tool at all.
+
+### User authorization
+
+One shared `tool:schedule` system-prompt section requires explicit user authorization to create or modify tasks. Prior explicit authorization for the running scheduled task remains valid, such as pausing that task after a monitored PR merges.
 
 ### The four tools
 
-- `schedule_create(prompt, title, <one selector>)` — Create one reminder. Supply a non-empty prompt, a title of at most 120 characters, and exactly one of `after_seconds`, `at`, `every_seconds`, `daily`, `weekly`, or `cron`. Returns the canonical reminder view.
-- `schedule_list()` — List every active reminder of the calling Session with its id, title, UTC target, state, and delivery mode.
-- `schedule_update(id, <title|prompt|one selector>)` — Replace the name, instruction, or timing in place, or a combination of them. An unknown or ended reminder returns `updated: false` with the reason code; `after_seconds` is create-only.
-- `schedule_delete(id)` — Remove one retained reminder, active or ended. Unknown or already-deleted ids return `deleted: false`.
+- `schedule_create(title, prompt, rrule, target)` — Create one task; all four inputs are required. `title` has at most 120 characters and names the action and object in the user's language; keep timing, status, and ids in their fields. `prompt` is the instruction delivered at each occurrence, and `rrule` is one `DTSTART` line and one `RRULE` line in the [RFC 5545 subset of Schedule](../../../docs/subsystems/schedule.md#rrule-input). Returns the task with its generated id.
+- `schedule_list(active?, limit?, offset?)` — List one page of every Host task, including tasks that other Sessions created. Active tasks come first by next occurrence, and paused and ended tasks follow, newest first. `active: true` keeps only active tasks and `active: false` only paused and ended tasks; `limit` is 1 through 500 and defaults to 100.
+- `schedule_view(id)` — Read one task by id. An unknown id returns `{ id, code: 'schedule_not_found' }`.
+- `schedule_edit(id, action, ...)` — An `update` changes at least one of `title`, `prompt`, `rrule`, `target`, and `active`; `active: false` pauses the task and `active: true` resumes it. Resume needs a future occurrence; supply a new `rrule` if the old rule is exhausted. With `expectedUpdatedAt`, an update or delete of a task that changed after that read returns `schedule_conflict` and changes nothing. A `delete` accepts no patch field and removes the task with its saved deliveries.
+
+`target` selects the Session that receives each delivery: `this_session` delivers to the calling Session, `new_once` creates one Session at the first delivery and reuses it, and `new` creates a Session for every delivery. Omit it on edit to preserve the destination and settings. Supplying it replaces the destination; `new_once` reserves a different Session, and either creating target captures the editor's working directory and composed preset.
 
 ### Minimal configuration
 
@@ -44,7 +50,7 @@ Choose it for any preset whose agents need to schedule future work in their own
 - name: '@deepseek-ai/dsh-tool-schedule'
 ```
 
-The package declares no `Config` fields. It injects `ctx.tools` and registers the four tools once the scope resolves the Host `ctx.schedule` service, so a composition that keeps that service off mounts no reminder tool. Each call acts on the Session of the Agent that dispatched it.
+The package declares no `Config` fields. It injects `ctx.tools` and `ctx.systemPrompt` and registers the four tools and their shared guidance once the scope resolves the Host `ctx.schedule` service, so a composition that keeps that service off mounts no Schedule tool. Each call acts for the Agent that dispatched it.
 
 -----
 
@@ -54,13 +60,13 @@ The package declares no `Config` fields. It injects `ctx.tools` and registers th
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-The plugin registers four `defineTool` definitions through the context that loads it, so a preset mount decides visibility and Cordis effect ownership disposes them with the mount. Execution reads `exec.agent` for the Session binding and the injected `ctx.schedule` service for storage; the delegation-depth guard runs before selector and identity checks, all before the service call, and any failure the service raises that is not a `ScheduleInputError` collapses to `internal_error` so storage details never reach the model. Model content is the canonical JSON of the returned value, and the Host service owns persistence, scheduling, Session restoration, and delivery.
+The plugin registers four `defineTool` definitions and one `tool:schedule` system-prompt section in the scope that resolves `ctx.schedule`, so a preset mount decides visibility and Cordis effect ownership disposes them with the mount. The section is empty when neither `schedule_create` nor `schedule_edit` is visible through `ctx.tools.get()` in the requesting scope, including delegated scopes whose preset filters those tools. This lookup works for both Native and PTC presentation. Execution reads `exec.agent` for the acting Session. The delegation-depth guard runs first and the argument checks of `schedule_edit` run next, both before the service call. A `ScheduleInputError` keeps its code when the output schema of the tool declares that code, and every other failure becomes `internal_error`, so storage details never reach the model. Model content is the canonical JSON of the returned value, and the Host service owns persistence, scheduling, Session restoration, and delivery.
 
 ### Source map
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: the four registrations, selector validation, and the render/present helpers |
+| [`src/index.ts`](src/index.ts) | Plugin entry: the four tools, their shared guidance, output schemas, target resolution, and render/present helpers |
 
 </details>
 
@@ -73,18 +79,38 @@ The plugin registers four `defineTool` definitions through the context that load
 - [Schedule group map](../README.md) — the sibling packages in this group.
 - [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-schedule) — the exact four schemas the model receives.
 - [Schedule subsystem](../../../docs/subsystems/schedule.md) — the `ctx.schedule` Cordis surface and stored types.
-- [Schedule user guide](../../../docs/user/guide/schedule.md) — the user-facing reminder workflow.
+- [Schedule user guide](../../../docs/user/guide/schedule.md) — the user-facing scheduled task workflow.
 
 -----
 
 <a id="model-experience"></a>
 ## Model Experience
 
+### Shared system prompt
+
+#### What the model sees
+
+One `tool:schedule` section when `schedule_create` or `schedule_edit` is visible in the calling Agent's scope. Tool descriptions retain their operation-specific guidance without repeating this policy. A `complete: true` system-prompt override replaces ordinary sections, including this one.
+
+##### Task authorization
+
+```markdown
+Only create or modify scheduled tasks at the user's explicit request; prior explicit user authorization for the running scheduled task remains valid.
+```
+
+#### Token effect
+
+One fixed sentence per assembled prompt in Native and PTC mode. Scopes that hide both mutation tools pay no cost for this section.
+
+#### KV Cache effect
+
+Prefix-stable while the section text and mutation-tool visibility are unchanged. Mounting, disposal, or filtering may invalidate reuse from this section.
+
 ### Tool schemas
 
 #### What the model sees
 
-The generated [`schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-schedule) whenever this package is visible in the calling Agent's scope. Title guidance does not rewrite stored titles or add validation beyond the existing non-empty and length checks.
+The generated [`schedule_create`, `schedule_list`, `schedule_view`, and `schedule_edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-schedule) whenever this package is visible in the calling Agent's scope. The catalog shows the default configuration; the `target` description of `schedule_create` adds the configured spacing of `new` deliveries when it exceeds one minute.
 
 #### Token effect
 
@@ -94,15 +120,15 @@ A fixed schema cost on every request from an Agent whose preset mounts the packa
 
 Prefix-stable while tool definitions and visibility are unchanged. Mounting, disposal, or a scope change may invalidate reuse from the first changed schema token.
 
-### Reminder results
+### Task results
 
 #### What the model sees
 
-One lossless JSON text block per call: a reminder view for `schedule_create`, an array of views for `schedule_list`, `{ id, deleted }` for `schedule_delete`, and a reminder view or `{ id, updated: false, code }` for `schedule_update`. A rejected call returns `{ code, message }` carrying one published error code.
+One canonical JSON text block per call. `schedule_create` returns the task; `schedule_list` returns `{ items, shown, total, limit, offset }`; `schedule_view` returns the task or `{ id, code: 'schedule_not_found' }`; and `schedule_edit` returns the updated task, `{ id, deleted: true }`, `{ id, code: 'schedule_not_found' }`, or `{ id, code: 'schedule_conflict' }`. Task results discriminate all seven timing kinds with `kind` and retain their authoritative timing fields. They include `id`, `title`, `prompt`, `scheduledAt`, `scheduledAtLocal`, `target`, `status`, optional `updatedAt` for revision comparison, and optional `lastDelivery` with `scheduledAt`, `deliveredAt`, and `targetSessionId`. The model input continues to expose RRULE; a rejected call returns `{ code, message }` with a declared output code.
 
 #### Token effect
 
-Results remain in the calling Session's history until compaction and repeat the stored reminder fields; a long reminder list costs its full rendered length on every later request.
+Results remain in the calling Session's history until compaction and repeat the task summary; a `schedule_list` page costs its full rendered length, at most `limit` tasks, on every later request.
 
 #### KV Cache effect
 
@@ -114,10 +140,11 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **No tools without the Host service** — a composition that mounts this package without `ctx.schedule` leaves the plugin pending, so none of the four tools register.
 - **Every call needs a calling Agent** — a call dispatched without one returns `internal_error` rather than guessing a Session.
-- **Deletion does not retract a queued message** — a reminder the Host already delivered stays in the Session inbox after `schedule_delete`.
-- **Reminder timing belongs to the Host** — the tools expose no target-time correction, clock source, or delivery retry; those limits are the service's.
-- **Every tool refuses a delegated caller** — each of `schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete` reads the calling Agent's delegation depth before dispatch and returns `{ code: 'subagent_session', message: 'A delegated subagent cannot use reminders.' }` when that depth is above zero. The guard lives in this package and reads `delegationDepthOf` from `@deepseek-ai/dsh-subagent`, the same accounting the delegation cap enforces, so it holds under any preset that mounts the tools.
-- **A Session a delegated child owns cannot arm a reminder** — `ScheduleService.create` throws `ScheduleInputError` with code `subagent_session`, and `ScheduleService.update` returns the non-mutating `subagent_session` result, when the Session's Agent has a delegation depth above zero. The delegation depth is the accounting the delegation cap itself reads, and the persisted session header carries it across a cold resume. The rule sits in the service, not in these tools, so other in-process consumers reach it too: the Automation surface included. `schedule_list` and `schedule_delete` still serve that Session, so a reminder stored before this rule stays removable.
+- **Every tool reaches every Host task** — `schedule_list` returns tasks that other Sessions created, and `schedule_view` and `schedule_edit` read, change, and delete any task by id. The authorization sentence guides model behavior; the Host does not validate user intent or add ownership checks per Session. A preset whose agents must not manage Host tasks omits the row.
+- **Deletion does not retract a queued message** — a message that the Host already delivered stays in the target Session inbox after a `schedule_edit` delete.
+- **Task timing belongs to the Host** — the tools expose no clock source, delivery retry, or execution result; those limits are the service's.
+- **Every tool refuses a delegated caller** — each of the four tools reads the calling Agent's delegation depth before it calls the service and returns `{ code: 'subagent_session', message: 'A delegated subagent cannot use scheduled tasks.' }` when that depth is above zero. The guard lives in this package and reads `delegationDepthOf` from `@deepseek-ai/dsh-subagent`, the same accounting the delegation cap enforces, so it holds under any preset that mounts the tools.
+- **A delegated child still sees the four tools** — a child joins its parent's preset, so its requests carry the four schemas and their token cost; the refusal above, not schema omission, keeps the child from managing tasks.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "预设作用域的提醒管理工具（schedule_create、schedule_list、schedule_update、schedule_delete），基于宿主 ctx.schedule 服务，供选择哪些 agent 可以维护持久提醒的部署使用。"
+description: "预设作用域的定时任务工具（schedule_create、schedule_list、schedule_view、schedule_edit），基于宿主 ctx.schedule 服务，供选择哪些 agent 可以管理定时任务的部署使用。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-使用 `dsh-tool-schedule`，可通过 `schedule_create`、`schedule_list`、`schedule_update` 与 `schedule_delete` 让 agent（智能体）创建、列出、编辑和删除宿主持久提醒。本包把四个工具注册进挂载它的 preset 或 Agent 作用域，因此由组合决定哪些 agent 获得这些工具；`minimal` 不获得。每次调用都作用于调用方 Agent 的 Session，并且只管理已存储的提醒——存储、调度与投递由宿主 `@deepseek-ai/dsh-schedule` 服务负责。失败时返回一个结构化错误码，而不是存储细节。
+使用 `dsh-tool-schedule`，可通过 `schedule_create`、`schedule_list`、`schedule_view` 与 `schedule_edit` 让 agent（智能体）创建、列出、查看、更新和删除宿主定时任务。定时任务在其重复规则的每个发生时点把指令投递到一个目标 Session。本包把四个工具注册进挂载它的 preset 或 Agent 作用域；`minimal` 不获得。任务属于宿主：这些工具按 id 读取和改变任意任务，只有投递目标指定 Session。存储、调度与投递由宿主 `@deepseek-ai/dsh-schedule` 服务负责。失败时返回一个结构化错误码。
 
 ## 目录
 
@@ -25,18 +25,24 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-当某个 preset 的 agent 需要管理持久提醒时，把下面这一行加入该 preset 的插件列表。随产品发布的 Web `standard`、`cordis` 与 `ptc` preset 会挂载它；`minimal` 不会。
+当某个 preset 的 agent 需要管理定时任务时，把下面这一行加入该 preset 的插件列表。随产品发布的 Web `standard`、`cordis` 与 `ptc` preset 会挂载它；`minimal` 不会。
 
 ### 何时选用
 
-当 preset 的 agent 需要在自己的 Session 中安排未来工作时选用它，并在同一进程内加载 `@deepseek-ai/dsh-schedule`：本包只是该服务面向模型的消费方。需要保持能力精简的 preset——随产品发布的例子是 `minimal`——会省略该行，其 agent 完全看不到提醒工具。
+当 preset 的 agent 需要安排未来工作时选用它，并在同一进程内加载 `@deepseek-ai/dsh-schedule`：本包只是该服务面向模型的消费方。需要保持能力精简的 preset——随产品发布的例子是 `minimal`——会省略该行，其 agent 完全看不到 Schedule 工具。
+
+### 用户授权
+
+共享的 `tool:schedule` system prompt 段落要求创建或修改任务时获得用户明确授权。用户此前为当前运行的定时任务明确授予的授权继续有效，例如在监控的 PR 合并后暂停该任务。
 
 ### 四个工具
 
-- `schedule_create(prompt, title, <一个选择器>)` —— 创建一条提醒。需提供非空提示文本、不超过 120 个字符的标题，以及 `after_seconds`、`at`、`every_seconds`、`daily`、`weekly`、`cron` 中的恰好一个。返回规范提醒视图。
-- `schedule_list()` —— 列出调用方 Session 的全部活动提醒及其 id、标题、UTC 目标、状态与投递模式。
-- `schedule_update(id, <title|prompt|一个选择器>)` —— 原地替换名称、指令或时间，或它们的组合。未知或已结束的提醒返回 `updated: false` 及原因码；`after_seconds` 仅限创建时使用。
-- `schedule_delete(id)` —— 删除一条保留的提醒，无论活动还是已结束。未知或已删除的 id 返回 `deleted: false`。
+- `schedule_create(title, prompt, rrule, target)` —— 创建一个任务，四项输入均为必填。`title` 不超过 120 个字符，使用用户的语言命名动作与对象；时间、状态和 id 保留在各自字段中。`prompt` 是每个发生时点投递的指令，`rrule` 是 [Schedule 所支持的 RFC 5545 子集](../../../docs/subsystems/schedule.zh.md#rrule-input)中的一行 `DTSTART` 与一行 `RRULE`。返回任务及其生成的 id。
+- `schedule_list(active?, limit?, offset?)` —— 列出宿主全部任务中的一页，包括其他 Session 创建的任务。活动任务按下一个发生时点排在前面，暂停与已结束的任务随后，按最新时间在前。`active: true` 只保留活动任务，`active: false` 只保留暂停与已结束的任务；`limit` 取 1 到 500，默认 100。
+- `schedule_view(id)` —— 按 id 读取一个任务。未知 id 返回 `{ id, code: 'schedule_not_found' }`。
+- `schedule_edit(id, action, ...)` —— `update` 至少改变 `title`、`prompt`、`rrule`、`target` 与 `active` 中的一项；`active: false` 暂停任务，`active: true` 恢复任务。恢复需要未来发生时点；旧规则耗尽时须提供新的 `rrule`。带有 `expectedUpdatedAt` 时，如果任务在那次读取之后发生过改变，更新或删除返回 `schedule_conflict` 且不做任何改变。`delete` 不接受任何补丁字段，并移除任务及其已保存的投递。
+
+`target` 选择接收每次投递的 Session：`this_session` 投递到调用方 Session，`new_once` 在首次投递时创建一个 Session 并在之后复用它，`new` 为每次投递创建一个 Session。编辑时省略该字段可保留目的地与设置。提供该字段会替换目的地；`new_once` 预留另一个 Session，两种新建目标都会保存编辑者的工作目录与组合后的 preset。
 
 ### 最小配置
 
@@ -44,7 +50,7 @@ kind: "package-reference"
 - name: '@deepseek-ai/dsh-tool-schedule'
 ```
 
-本包不声明任何 `Config` 字段。它注入 `ctx.tools`，并在作用域解析到宿主 `ctx.schedule` 服务后注册这四个工具，因此保持该服务关闭的组合不会挂载任何提醒工具。每次调用都作用于派发该调用的 Agent 的 Session。
+本包不声明任何 `Config` 字段。它注入 `ctx.tools` 和 `ctx.systemPrompt`，并在作用域解析到宿主 `ctx.schedule` 服务后注册这四个工具及其共享指导，因此保持该服务关闭的组合不会挂载任何 Schedule 工具。每次调用都代表派发该调用的 Agent 执行。
 
 -----
 
@@ -54,13 +60,13 @@ kind: "package-reference"
 <details>
 <summary>实现内部细节——点击展开</summary>
 
-插件通过加载它的上下文注册四个 `defineTool` 定义，因此由 preset 挂载决定可见性，并由 Cordis effect 的所有权随挂载一并释放。执行时读取 `exec.agent` 作为 Session 绑定，并读取注入的 `ctx.schedule` 服务进行存储；委派深度守卫先于选择器与身份校验运行，二者均在服务调用之前完成，服务抛出的任何非 `ScheduleInputError` 失败都收敛为 `internal_error`，因此存储细节不会到达模型。模型内容为返回值的规范 JSON，而持久化、调度、Session 恢复与投递都由宿主服务负责。
+插件在解析到 `ctx.schedule` 的作用域内注册四个 `defineTool` 定义与一个 `tool:schedule` system prompt 段落，因此由 preset 挂载决定可见性，并由 Cordis effect 的所有权随挂载一并释放。当请求作用域中的 `ctx.tools.get()` 既看不到 `schedule_create` 也看不到 `schedule_edit` 时，该段落为空；preset 过滤了这些工具的委派作用域也包括在内。此查询同时适用于 Native 与 PTC 呈现方式。执行时读取 `exec.agent` 作为执行操作的 Session。委派深度守卫先运行，`schedule_edit` 的参数校验随后运行，二者都在服务调用之前完成。当工具的输出 schema 声明了某个 `ScheduleInputError` 的错误码时，该错误保留其错误码；其他任何失败都变为 `internal_error`，因此存储细节不会到达模型。模型内容为返回值的规范 JSON，而持久化、调度、Session 恢复与投递都由宿主服务负责。
 
 ### 源码映射
 
 | 文件 | 作用 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：四个注册、选择器校验，以及 render/present 辅助函数 |
+| [`src/index.ts`](src/index.ts) | 插件入口：四个工具、共享指导、输出 schema、目标解析，以及 render/present 辅助函数 |
 
 </details>
 
@@ -73,18 +79,38 @@ kind: "package-reference"
 - [Schedule 分组映射](../README.zh.md) —— 本组内的同级包。
 - [生成的工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-schedule) —— 模型接收的确切四个 schema。
 - [Schedule 子系统](../../../docs/subsystems/schedule.zh.md) —— `ctx.schedule` 的 Cordis 接线区域与存储类型。
-- [Schedule 用户指南](../../../docs/user/guide/schedule.zh.md) —— 面向用户的提醒工作流。
+- [Schedule 用户指南](../../../docs/user/guide/schedule.zh.md) —— 面向用户的定时任务工作流。
 
 -----
 
 <a id="model-experience"></a>
 ## 模型体验
 
+### 共享 system prompt
+
+#### What the model sees
+
+当 `schedule_create` 或 `schedule_edit` 在调用方 Agent 的作用域内可见时，模型收到一个 `tool:schedule` 段落。工具说明保留各自的操作指导，不再重复这条规则。`complete: true` 的 system prompt 覆盖会替换普通段落，本段落也包括在内。
+
+##### 任务授权
+
+```markdown
+Only create or modify scheduled tasks at the user's explicit request; prior explicit user authorization for the running scheduled task remains valid.
+```
+
+#### Token effect
+
+Native 和 PTC 模式下，每次组装 prompt 只加入一句固定文本。同时隐藏两个修改工具的作用域不承担本段落的开销。
+
+#### KV Cache effect
+
+段落文本与修改工具可见性不变时，前缀保持稳定。挂载、释放或过滤都可能使从该段落开始的复用失效。
+
 ### 工具 schema
 
 #### What the model sees
 
-只要本包在调用方 Agent 的作用域内可见，模型就会收到生成的 [`schedule_create`、`schedule_list`、`schedule_update` 与 `schedule_delete` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-schedule)。标题指引不会改写已存标题，也不会在现有的非空和长度检查之外增加校验。
+只要本包在调用方 Agent 的作用域内可见，模型就会收到生成的 [`schedule_create`、`schedule_list`、`schedule_view` 与 `schedule_edit` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-schedule)。目录展示默认配置；当 `new` 投递的配置间隔超过一分钟时，`schedule_create` 的 `target` 描述会加上该间隔。
 
 #### Token effect
 
@@ -94,15 +120,15 @@ kind: "package-reference"
 
 只要工具定义与可见性不变，前缀保持稳定。挂载、释放或作用域变化都可能使从首个变化 schema token 起的复用失效。
 
-### 提醒结果
+### 任务结果
 
 #### What the model sees
 
-每次调用返回一个无损 JSON 文本块：`schedule_create` 返回提醒视图，`schedule_list` 返回视图数组，`schedule_delete` 返回 `{ id, deleted }`，`schedule_update` 返回提醒视图或 `{ id, updated: false, code }`。被拒绝的调用返回带有某个已发布错误码的 `{ code, message }`。
+每次调用返回一个规范 JSON 文本块。`schedule_create` 返回任务；`schedule_list` 返回 `{ items, shown, total, limit, offset }`；`schedule_view` 返回任务或 `{ id, code: 'schedule_not_found' }`；`schedule_edit` 返回更新的任务、`{ id, deleted: true }`、`{ id, code: 'schedule_not_found' }` 或 `{ id, code: 'schedule_conflict' }`。任务结果用 `kind` 区分七种时间类型，并保留权威时间字段。结果包含 `id`、`title`、`prompt`、`scheduledAt`、`scheduledAtLocal`、`target`、`status`，可选的 `updatedAt` 用于版本比较；可选的 `lastDelivery` 包含 `scheduledAt`、`deliveredAt` 与 `targetSessionId`。模型输入继续暴露 RRULE；拒绝调用返回带已声明输出错误码的 `{ code, message }`。
 
 #### Token effect
 
-结果会留在调用方 Session 的历史中直到压缩，并重复存储的提醒字段；较长的提醒列表在之后每次请求中都付出其全部渲染长度。
+结果会留在调用方 Session 的历史中直到压缩，并重复任务摘要；一页 `schedule_list` 结果最多包含 `limit` 个任务，在之后每次请求中都付出其全部渲染长度。
 
 #### KV Cache effect
 
@@ -114,10 +140,11 @@ kind: "package-reference"
 
 - **没有宿主服务就没有工具** —— 在缺少 `ctx.schedule` 的组合中挂载本包会让插件保持挂起，四个工具都不会注册。
 - **每次调用都需要调用方 Agent** —— 未携带 Agent 的派发返回 `internal_error`，而不会猜测某个 Session。
-- **删除不会撤回已排队的消息** —— 宿主已经投递的提醒在 `schedule_delete` 之后仍留在 Session 收件箱中。
-- **提醒时间由宿主负责** —— 这些工具不提供目标时间校正、时钟来源或投递重试；这些限制属于该服务。
-- **每个工具都拒绝被委派的调用方** —— `schedule_create`、`schedule_list`、`schedule_update` 与 `schedule_delete` 都会在派发前读取调用方 Agent 的委派深度，当该深度大于零时返回 `{ code: 'subagent_session', message: 'A delegated subagent cannot use reminders.' }`。该守卫位于本包内，读取来自 `@deepseek-ai/dsh-subagent` 的 `delegationDepthOf`，即委派封顶本身执行的同一份记账，因此在任何挂载这些工具的 preset 下都成立。
-- **被委派子 agent 拥有的 Session 不能设置提醒** —— 当 Session 的 Agent 委派深度大于零时，`ScheduleService.create` 会抛出 `ScheduleInputError`（code 为 `subagent_session`），`ScheduleService.update` 则返回非变更的 `subagent_session` 结果。委派深度正是委派封顶本身读取的同一份记账，持久化 session header 让它在冷恢复后仍然成立。这条规则在服务层而非这些工具里，因此其它进程内消费方（包括自动化任务页面）也会命中。`schedule_list` 与 `schedule_delete` 仍可服务该 Session，所以在这条规则之前存储的提醒仍可删除。
+- **每个工具都能触及宿主的全部任务** —— `schedule_list` 返回其他 Session 创建的任务，`schedule_view` 与 `schedule_edit` 按 id 读取、改变和删除任意任务。授权说明约束模型行为；宿主不校验用户意图，也不增加按 Session 的归属检查。不应管理宿主任务的 agent 所用 preset 应省略这一行。
+- **删除不会撤回已排队的消息** —— 宿主已经投递的消息在 `schedule_edit` 删除之后仍留在目标 Session 收件箱中。
+- **任务时间由宿主负责** —— 这些工具不提供时钟来源、投递重试或执行结果；这些限制属于该服务。
+- **每个工具都拒绝被委派的调用方** —— 四个工具都会在调用服务之前读取调用方 Agent 的委派深度，当该深度大于零时返回 `{ code: 'subagent_session', message: 'A delegated subagent cannot use scheduled tasks.' }`。该守卫位于本包内，读取来自 `@deepseek-ai/dsh-subagent` 的 `delegationDepthOf`，即委派封顶本身执行的同一份记账，因此在任何挂载这些工具的 preset 下都成立。
+- **被委派的子 agent 仍能看到这四个工具** —— 子 agent 加入父方的 preset，因此其请求携带这四个 schema 及其 token 成本；阻止它管理任务的是上述拒绝，而不是省略 schema。
 
 <a id="dev-note"></a>
 ### 开发备注