fix(docs): checkpoint trigger names in docs/reference/checkpointing.md do not match implementation #3694

New issue

Open

opened 2026-04-05 22:12:51 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 22:12:51 +00:00

Owner

Bug: Checkpoint Trigger Name Mismatch

Severity: High — the reference documentation documents trigger names that do not exist in the implementation, making the configuration API undiscoverable and incorrect.

Discrepancy

docs/reference/checkpointing.md (lines 68-71, updated in PR #3682) says:

| `on_tool_write`          | Before each write-tool execution       | `ToolRunner` |
| `on_tool_write_complete` | After each write-tool execution        | `ToolRunner` |
| `on_subplan_spawn`       | Before first subplan execution attempt | `SubplanExecutionService` |
| `on_error`               | When the Execute phase fails           | `PlanExecutor` |

src/cleveragents/tool/runner.py (lines 53-60) actually defines:

DEFAULT_AUTO_TRIGGERS: frozenset[str] = frozenset({
    "before_tool_execute",
    "after_tool_execute",
    "on_subplan_spawn",
    "on_error",
})

And the implementation at lines 478 and 520 uses:

if _tool_writes and self._is_trigger_active("before_tool_execute"):
    ...
if _tool_writes and self._is_trigger_active("after_tool_execute"):
    ...

The trigger names on_tool_write and on_tool_write_complete do not exist in the implementation. The correct names are before_tool_execute and after_tool_execute.

Impact

Users who configure core.checkpoints.auto_create_on = ["on_tool_write"] will get no checkpoints (the trigger name won't match any active trigger).
The configuration example in checkpointing.md line 77 is incorrect.

Fix Required

Update docs/reference/checkpointing.md to use the correct trigger names:

Trigger	When	Component
`before_tool_execute`	Before each write-tool execution	`ToolRunner`
`after_tool_execute`	After each write-tool execution	`ToolRunner`
`on_subplan_spawn`	Before first subplan execution attempt	`SubplanExecutionService`
`on_error`	When the Execute phase fails	`PlanExecutor`

And update the configuration example:

[core.checkpoints]
auto_create_on = ["before_tool_execute", "after_tool_execute", "on_subplan_spawn", "on_error"]

References

Implementation: src/cleveragents/tool/runner.py lines 53-60, 478, 520
Incorrect docs: docs/reference/checkpointing.md lines 68-77
Introduced by: PR #3682 (docs PR used wrong trigger names)

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Bug: Checkpoint Trigger Name Mismatch **Severity:** High — the reference documentation documents trigger names that do not exist in the implementation, making the configuration API undiscoverable and incorrect. ## Discrepancy **`docs/reference/checkpointing.md` (lines 68-71, updated in PR #3682) says:** ``` | `on_tool_write` | Before each write-tool execution | `ToolRunner` | | `on_tool_write_complete` | After each write-tool execution | `ToolRunner` | | `on_subplan_spawn` | Before first subplan execution attempt | `SubplanExecutionService` | | `on_error` | When the Execute phase fails | `PlanExecutor` | ``` **`src/cleveragents/tool/runner.py` (lines 53-60) actually defines:** ```python DEFAULT_AUTO_TRIGGERS: frozenset[str] = frozenset({ "before_tool_execute", "after_tool_execute", "on_subplan_spawn", "on_error", }) ``` And the implementation at lines 478 and 520 uses: ```python if _tool_writes and self._is_trigger_active("before_tool_execute"): ... if _tool_writes and self._is_trigger_active("after_tool_execute"): ... ``` The trigger names `on_tool_write` and `on_tool_write_complete` **do not exist** in the implementation. The correct names are `before_tool_execute` and `after_tool_execute`. ## Impact - Users who configure `core.checkpoints.auto_create_on = ["on_tool_write"]` will get no checkpoints (the trigger name won't match any active trigger). - The configuration example in `checkpointing.md` line 77 is incorrect. ## Fix Required Update `docs/reference/checkpointing.md` to use the correct trigger names: | Trigger | When | Component | |---------|------|-----------| | `before_tool_execute` | Before each write-tool execution | `ToolRunner` | | `after_tool_execute` | After each write-tool execution | `ToolRunner` | | `on_subplan_spawn` | Before first subplan execution attempt | `SubplanExecutionService` | | `on_error` | When the Execute phase fails | `PlanExecutor` | And update the configuration example: ```toml [core.checkpoints] auto_create_on = ["before_tool_execute", "after_tool_execute", "on_subplan_spawn", "on_error"] ``` ## References - Implementation: `src/cleveragents/tool/runner.py` lines 53-60, 478, 520 - Incorrect docs: `docs/reference/checkpointing.md` lines 68-77 - Introduced by: PR #3682 (docs PR used wrong trigger names) --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo referenced this issue

2026-04-05 22:13:11 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:20:38 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:22:14 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654