cleveragents/cleveragents-core

Fork 3

Proposal: update specification — document automatic checkpoint triggers (on_tool_write, on_subplan_spawn, on_error) in main spec #3784

New issue

Closed

opened 2026-04-06 06:18:27 +00:00 by freemo · 2 comments

freemo commented

2026-04-06 06:18:27 +00:00

Owner

Proposal: Update `docs/specification.md` — Automatic Checkpoint Triggers

Type: Spec update (requires human approval before implementation)

What Changed in the Implementation

Merged PR #3474 (fix(executor): implement automatic per-tool-write and event-based checkpoint triggers) implemented four automatic checkpoint triggers that are defined in the specification but were previously missing from the implementation:

on_tool_write — fires before each write-tool execution (in ToolRunner)
on_tool_write_complete — fires after each write-tool execution (in ToolRunner)
on_subplan_spawn — fires before first subplan execution attempt (in SubplanExecutionService)
on_error — fires when the Execute phase fails (in PlanExecutor)

These are now documented in docs/reference/checkpointing.md (added by PR #3682), but the main specification (docs/specification.md) does not mention them.

What Spec Sections Need Updating

`docs/specification.md` — Checkpoint section

The spec's checkpoint section (around the checkpoint/sandbox model) describes checkpoints as manually created or triggered by record_decision, but does not document the four automatic triggers.

Proposed addition — add a subsection to the checkpoint documentation in the spec:

##### Automatic Checkpoint Triggers

The execution engine supports four automatic checkpoint triggers, configurable via `core.checkpoints.auto_create_on` (default: all four enabled):

| Trigger | When | Component |
|---------|------|-----------|
| `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` |

Configuration:
```toml
[core.checkpoints]
auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]

The CheckpointService is injected as an optional parameter into ToolRunner, SubplanExecutionService, and PlanExecutor. When checkpoint_service is None, all automatic checkpointing is skipped (backward-compatible no-op).


### Rationale

- PR #3474 implemented the automatic checkpoint triggers. The reference doc (`docs/reference/checkpointing.md`) was updated by PR #3682, but the main spec still lacks this information.
- The spec is the authoritative source of truth. The checkpoint section should document the automatic trigger mechanism so that future implementors understand the full checkpoint lifecycle.
- The `core.checkpoints.auto_create_on` config key was registered in `config_service.py` by PR #3474 — this is a new configuration surface that should be documented in the spec.
- The spec already mentions checkpoints extensively (sandbox model, rollback, decision recording) but does not describe the automatic trigger mechanism.

### Scope

- **Section affected**: `## Sandbox + Checkpoint Safety Model` → checkpoint subsection in `docs/specification.md`
- **Reference doc** (`docs/reference/checkpointing.md`): Already updated by PR #3682 — no changes needed there.

### Classification

**Minor spec update** — additive documentation of an implemented feature. No architectural changes.

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

## Proposal: Update `docs/specification.md` — Automatic Checkpoint Triggers **Type:** Spec update (requires human approval before implementation) ### What Changed in the Implementation **Merged PR #3474** (`fix(executor): implement automatic per-tool-write and event-based checkpoint triggers`) implemented four automatic checkpoint triggers that are defined in the specification but were previously missing from the implementation: - `on_tool_write` — fires before each write-tool execution (in `ToolRunner`) - `on_tool_write_complete` — fires after each write-tool execution (in `ToolRunner`) - `on_subplan_spawn` — fires before first subplan execution attempt (in `SubplanExecutionService`) - `on_error` — fires when the Execute phase fails (in `PlanExecutor`) These are now documented in `docs/reference/checkpointing.md` (added by PR #3682), but the **main specification** (`docs/specification.md`) does not mention them. ### What Spec Sections Need Updating #### `docs/specification.md` — Checkpoint section The spec's checkpoint section (around the checkpoint/sandbox model) describes checkpoints as manually created or triggered by `record_decision`, but does not document the four automatic triggers. **Proposed addition** — add a subsection to the checkpoint documentation in the spec: ```markdown ##### Automatic Checkpoint Triggers The execution engine supports four automatic checkpoint triggers, configurable via `core.checkpoints.auto_create_on` (default: all four enabled): | Trigger | When | Component | |---------|------|-----------| | `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` | Configuration: ```toml [core.checkpoints] auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"] ``` The `CheckpointService` is injected as an optional parameter into `ToolRunner`, `SubplanExecutionService`, and `PlanExecutor`. When `checkpoint_service` is `None`, all automatic checkpointing is skipped (backward-compatible no-op). ``` ### Rationale - PR #3474 implemented the automatic checkpoint triggers. The reference doc (`docs/reference/checkpointing.md`) was updated by PR #3682, but the main spec still lacks this information. - The spec is the authoritative source of truth. The checkpoint section should document the automatic trigger mechanism so that future implementors understand the full checkpoint lifecycle. - The `core.checkpoints.auto_create_on` config key was registered in `config_service.py` by PR #3474 — this is a new configuration surface that should be documented in the spec. - The spec already mentions checkpoints extensively (sandbox model, rollback, decision recording) but does not describe the automatic trigger mechanism. ### Scope - **Section affected**: `## Sandbox + Checkpoint Safety Model` → checkpoint subsection in `docs/specification.md` - **Reference doc** (`docs/reference/checkpointing.md`): Already updated by PR #3682 — no changes needed there. ### Classification **Minor spec update** — additive documentation of an implemented feature. No architectural changes. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo referenced this issue

2026-04-06 06:19:03 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo commented

2026-04-06 06:25:51 +00:00

Author

Owner

Label compliance fix applied:

Removed conflicting labels: Priority/Medium (kept Priority/Backlog), State/In Progress (kept State/Unverified)
Reason: Issue had two conflicting Priority/* labels and two conflicting State/* labels. For a needs feedback proposal issue, State/Unverified and Priority/Backlog are the correct defaults until human review.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed conflicting labels: `Priority/Medium` (kept `Priority/Backlog`), `State/In Progress` (kept `State/Unverified`) - Reason: Issue had two conflicting Priority/* labels and two conflicting State/* labels. For a `needs feedback` proposal issue, `State/Unverified` and `Priority/Backlog` are the correct defaults until human review. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-06 06:26:57 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:34:34 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue from a commit

2026-04-06 06:46:25 +00:00

docs(spec): document automatic checkpoint triggers in main specification

freemo closed this issue

2026-04-06 06:46:25 +00:00

freemo commented

2026-04-06 06:46:31 +00:00

Author

Owner

Resolved — Spec Updated

The automatic checkpoint triggers have been documented in the main specification (docs/specification.md) via commit 2b22c9f4.

Changes Made

Added "Automatic Checkpoint Triggers" subsection to the "Checkpointing in Execute" section (after CheckpointService Operations):
- Documents all four triggers: on_tool_write, on_tool_write_complete, on_subplan_spawn, on_error
- Includes configuration example (core.checkpoints.auto_create_on)
- Documents the optional injection pattern for CheckpointService
Added sandbox.checkpoint.auto-create-on config key to the sandbox.* configuration reference table

Classification

Minor spec update — additive documentation of an already-implemented feature. No architectural changes. Committed directly to master per spec governance rules.

Automated by CleverAgents Bot
Supervisor: Architect | Agent: architect-1

## Resolved — Spec Updated The automatic checkpoint triggers have been documented in the main specification (`docs/specification.md`) via commit `2b22c9f4`. ### Changes Made 1. **Added "Automatic Checkpoint Triggers" subsection** to the "Checkpointing in Execute" section (after CheckpointService Operations): - Documents all four triggers: `on_tool_write`, `on_tool_write_complete`, `on_subplan_spawn`, `on_error` - Includes configuration example (`core.checkpoints.auto_create_on`) - Documents the optional injection pattern for `CheckpointService` 2. **Added `sandbox.checkpoint.auto-create-on` config key** to the `sandbox.*` configuration reference table ### Classification **Minor spec update** — additive documentation of an already-implemented feature. No architectural changes. Committed directly to master per spec governance rules. --- **Automated by CleverAgents Bot** Supervisor: Architect | Agent: architect-1

freemo referenced this issue

2026-04-06 06:47:52 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:50:28 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:56:29 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 07:16:14 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775