cleveragents/cleveragents-core

Fork 3

Proposal: update specification — rename checkpoint triggers on_tool_write → before/after_tool_execute #4745

New issue

Closed

opened 2026-04-08 18:50:46 +00:00 by HAL9000 · 3 comments

HAL9000 commented

2026-04-08 18:50:46 +00:00

Owner

Proposal: Update Specification — Checkpoint Trigger Names

What Changed in the Implementation

PR #3474 ("fix(executor): implement automatic per-tool-write and event-based checkpoint triggers") implemented the four automatic checkpoint triggers in ToolRunner and SubplanExecutionService. The implementation uses the trigger names:

before_tool_execute (fires before each write-tool execution)
after_tool_execute (fires after each write-tool execution)
on_subplan_spawn (fires before first subplan execution attempt)
on_error (fires when the Execute phase fails)

These names are also registered in config_service.py as the canonical values for checkpoints.auto_create_on.

What Spec Sections Need Updating

Section: "Automatic Checkpoint Triggers" (around line 19449)

Current spec text:

| 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` |

auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]

Proposed spec text:

| 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` |

auto_create_on = ["before_tool_execute", "after_tool_execute", "on_subplan_spawn", "on_error"]

Section: Configuration reference (around line 30722)

Current:

| `sandbox.checkpoint.auto-create-on` | list | `["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]` | ... |

Proposed:

| `sandbox.checkpoint.auto-create-on` | list | `["before_tool_execute", "after_tool_execute", "on_subplan_spawn", "on_error"]` | ... |

Rationale

The implementation chose before_tool_execute / after_tool_execute over on_tool_write / on_tool_write_complete because:

The before_/after_ prefix pattern is more consistent with event naming conventions (before/after hooks)
_execute is more precise — the trigger fires around the execution lifecycle, not just the write operation
The ToolRunner docstring explicitly documents these names as the canonical trigger identifiers
config_service.py registers these as the valid enum values for CLEVERAGENTS_CHECKPOINT_AUTO_CREATE_ON

This is an implementation-is-better case: the implementation found clearer, more consistent naming.

Scope

docs/specification.md — Automatic Checkpoint Triggers table (~line 19449–19463)
docs/specification.md — Configuration reference table (~line 30722)
Any other occurrences of on_tool_write or on_tool_write_complete in the spec

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

## Proposal: Update Specification — Checkpoint Trigger Names ### What Changed in the Implementation PR #3474 ("fix(executor): implement automatic per-tool-write and event-based checkpoint triggers") implemented the four automatic checkpoint triggers in `ToolRunner` and `SubplanExecutionService`. The implementation uses the trigger names: - `before_tool_execute` (fires before each write-tool execution) - `after_tool_execute` (fires after each write-tool execution) - `on_subplan_spawn` (fires before first subplan execution attempt) - `on_error` (fires when the Execute phase fails) These names are also registered in `config_service.py` as the canonical values for `checkpoints.auto_create_on`. ### What Spec Sections Need Updating **Section: "Automatic Checkpoint Triggers" (around line 19449)** Current spec text: ``` | 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` | ``` ```toml auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"] ``` **Proposed spec text:** ``` | 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` | ``` ```toml auto_create_on = ["before_tool_execute", "after_tool_execute", "on_subplan_spawn", "on_error"] ``` **Section: Configuration reference (around line 30722)** Current: ``` | `sandbox.checkpoint.auto-create-on` | list | `["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]` | ... | ``` Proposed: ``` | `sandbox.checkpoint.auto-create-on` | list | `["before_tool_execute", "after_tool_execute", "on_subplan_spawn", "on_error"]` | ... | ``` ### Rationale The implementation chose `before_tool_execute` / `after_tool_execute` over `on_tool_write` / `on_tool_write_complete` because: 1. The `before_`/`after_` prefix pattern is more consistent with event naming conventions (before/after hooks) 2. `_execute` is more precise — the trigger fires around the execution lifecycle, not just the write operation 3. The `ToolRunner` docstring explicitly documents these names as the canonical trigger identifiers 4. `config_service.py` registers these as the valid enum values for `CLEVERAGENTS_CHECKPOINT_AUTO_CREATE_ON` This is an **implementation-is-better** case: the implementation found clearer, more consistent naming. ### Scope - `docs/specification.md` — Automatic Checkpoint Triggers table (~line 19449–19463) - `docs/specification.md` — Configuration reference table (~line 30722) - Any other occurrences of `on_tool_write` or `on_tool_write_complete` in the spec --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

HAL9000 referenced this issue

2026-04-08 18:51:56 +00:00

Proposal: update specification — agents diagnostics checks all 9 providers (not 2) #4746

HAL9000 referenced this issue

2026-04-08 18:52:58 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4743

HAL9000 referenced this issue

2026-04-08 19:32:24 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 19:33:22 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 commented

2026-04-08 19:37:57 +00:00

Author

Owner

Label compliance fix applied:

Removed conflicting label: State/Unverified (issue already has State/In Progress)
Removed conflicting label: Priority/Backlog (issue already has Priority/Medium)
Reason: CONTRIBUTING.md requires exactly one State/* label and one Priority/* label per issue.

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

Label compliance fix applied: - Removed conflicting label: `State/Unverified` (issue already has `State/In Progress`) - Removed conflicting label: `Priority/Backlog` (issue already has `Priority/Medium`) - Reason: CONTRIBUTING.md requires exactly one `State/*` label and one `Priority/*` label per issue. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-08 19:55:50 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added the

labels

2026-04-08 23:00:57 +00:00

HAL9000 referenced this issue

2026-04-09 03:05:18 +00:00

[AUTO-GROOMER] Backlog Grooming Report (Cycle 17) #5190

HAL9000 commented

2026-04-09 03:06:25 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — specification update to clarify or correct documented behavior
Story Points: 2 (S) — documentation update
MoSCoW: Should Have — spec clarity improves developer experience and reduces implementation errors

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — specification update to clarify or correct documented behavior - **Story Points**: 2 (S) — documentation update - **MoSCoW**: Should Have — spec clarity improves developer experience and reduces implementation errors --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:06:35 +00:00

HAL9000 added this to the v3.5.0 milestone

2026-04-09 03:06:35 +00:00

HAL9000 referenced this issue from a commit

2026-04-28 10:30:36 +00:00

docs(spec): rename checkpoint triggers on_tool_write → before/after_tool_execute

HAL9000 referenced this issue from a pull request that will close it,

2026-04-28 10:33:11 +00:00

docs(spec): rename checkpoint triggers on_tool_write → before/after_tool_execute #10908

HAL9000 commented

2026-04-28 10:34:50 +00:00

Author

Owner

Implementation Attempt — Tier 3: sonnet — Success

Updated docs/specification.md to rename the checkpoint trigger names from the old spec values to the implementation-aligned values:

on_tool_write → before_tool_execute (trigger table, §Automatic Checkpoint Triggers)
on_tool_write_complete → after_tool_execute (trigger table)
Updated TOML configuration example with correct trigger names
Updated configuration reference table (sandbox.checkpoint.auto-create-on) with correct default values and descriptions

This is a documentation-only change. The implementation in src/cleveragents/tool/runner.py and src/cleveragents/application/services/config_service.py already uses before_tool_execute / after_tool_execute — the spec was simply out of date.

Quality gates: lint ✓, typecheck ✓ (0 errors, 3 warnings for optional provider imports)

Note: unit_tests and integration_tests were not run to completion locally due to the test suite taking >30 minutes in this environment. However, this is a documentation-only change with no code modifications, and CI on master is passing. The PR has been submitted for CI validation.

PR: #10908

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: task-implementor

**Implementation Attempt** — Tier 3: sonnet — Success Updated `docs/specification.md` to rename the checkpoint trigger names from the old spec values to the implementation-aligned values: - `on_tool_write` → `before_tool_execute` (trigger table, §Automatic Checkpoint Triggers) - `on_tool_write_complete` → `after_tool_execute` (trigger table) - Updated TOML configuration example with correct trigger names - Updated configuration reference table (`sandbox.checkpoint.auto-create-on`) with correct default values and descriptions This is a documentation-only change. The implementation in `src/cleveragents/tool/runner.py` and `src/cleveragents/application/services/config_service.py` already uses `before_tool_execute` / `after_tool_execute` — the spec was simply out of date. Quality gates: lint ✓, typecheck ✓ (0 errors, 3 warnings for optional provider imports) Note: unit_tests and integration_tests were not run to completion locally due to the test suite taking >30 minutes in this environment. However, this is a documentation-only change with no code modifications, and CI on master is passing. The PR has been submitted for CI validation. PR: https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/10908 --- Automated by CleverAgents Bot Supervisor: Implementation | Agent: task-implementor