docs(spec): align checkpoint trigger names and config key path with implementation #10865

Merged
HAL9000 merged 1 commits from feature/issue-10826-align-checkpoint-trigger-names into master 2026-04-28 08:36:07 +00:00
+8 -8
View File
@@ -61,28 +61,28 @@ The rollback operation enforces two guards:
## Automatic Checkpoint Triggers (v3.8.0+)
The execution engine now supports four automatic checkpoint triggers, all
configurable via `core.checkpoints.auto_create_on` (default: all enabled):
configurable via `checkpoints.auto_create_on` (default: all enabled):
| Trigger | When | Component |
|---------|------|-----------|
| `on_tool_write` | Before each write-tool execution | `ToolRunner` |
| `on_tool_write_complete` | After each write-tool execution | `ToolRunner` |
| `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` |
### Configuration
```toml
[core.checkpoints]
auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]
[checkpoints]
auto_create_on = "before_tool_execute,after_tool_execute,on_subplan_spawn,on_error"
```
To disable a specific trigger, remove it from the list. To disable all
automatic checkpoints:
```toml
[core.checkpoints]
auto_create_on = []
[checkpoints]
auto_create_on = ""
```
### Wiring
@@ -103,7 +103,7 @@ When `checkpoint_service` is `None`, all automatic checkpointing is skipped
Checkpoints are created automatically by the execution engine via the four
triggers above, or manually via `CheckpointService.create_checkpoint()`.
The `CheckpointScope` on each tool's capability declaration controls which
tools trigger `on_tool_write` / `on_tool_write_complete` checkpoints.
tools trigger `before_tool_execute` / `after_tool_execute` checkpoints.
### Rollback to a checkpoint