cleveragents/cleveragents-core

Fork 3

Proposal: update specification — checkpoint trigger names and config key path inconsistency #5009

New issue

Open

opened 2026-04-09 00:46:17 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 00:46:17 +00:00

Owner

Specification Update Proposal

Triggered by: Analysis of merged PRs #3474 (automatic checkpoint triggers) and #4890 (UAT: checkpoint config key mismatch), comparing src/cleveragents/application/services/config_service.py, src/cleveragents/tool/runner.py, and src/cleveragents/application/services/subplan_execution_service.py against docs/specification.md.

What Changed in the Implementation

PR #3474 implemented the four automatic checkpoint triggers for the Execute phase. The implementation uses different trigger names than the spec, and the spec itself has an internal inconsistency in the config key path.

Discrepancy 1: Checkpoint Trigger Names

Current spec text (line 19451–19456):

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`

What the implementation actually uses (src/cleveragents/tool/runner.py, src/cleveragents/application/services/config_service.py):

# config_service.py line 484
"before_tool_execute,after_tool_execute,on_subplan_spawn,on_error"

# tool/runner.py lines 55-56
"before_tool_execute",
"after_tool_execute",

The implementation uses:

before_tool_execute (spec says on_tool_write)
after_tool_execute (spec says on_tool_write_complete)
on_subplan_spawn ✓ (matches)
on_error ✓ (matches)

Rationale for the implementation's naming: The names before_tool_execute and after_tool_execute are more precise and consistent with the general "tool execution" lifecycle rather than implying only write tools trigger them. The implementation correctly gates these on write tools (_tool_writes flag), but the trigger names themselves describe the execution phase rather than the write operation.

Proposed spec update: Update the trigger names in the spec to match the implementation:

on_tool_write → before_tool_execute
on_tool_write_complete → after_tool_execute

Affected spec locations:

Line 19451–19456: Trigger table
Line 19462: TOML example
Line 30722: Config reference table (see Discrepancy 2)

Discrepancy 2: Config Key Path — Internal Spec Inconsistency

The spec has two conflicting config key paths for the same setting:

Spec line 19449 (Automatic Checkpoint Triggers section):

configurable via `core.checkpoints.auto_create_on`

Spec line 30722 (Configuration Reference table):

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

What the implementation uses (config_service.py line 480–493):

_register(
    "core",
    "checkpoints.auto_create_on",
    ...
    env_var="CLEVERAGENTS_CHECKPOINT_AUTO_CREATE_ON",
)

The implementation uses core.checkpoints.auto_create_on (matching line 19449). The configuration reference table at line 30722 uses sandbox.checkpoint.auto-create-on — a different section and naming convention.

Proposed spec update: Update the configuration reference table (line 30722) to use the correct key path core.checkpoints.auto-create-on (matching the implementation and the inline spec at line 19449), and update the default values to use the implementation's trigger names.

Scope

Spec sections affected:

## Plan Lifecycle → ### Execute Phase → #### Automatic Checkpoint Triggers (lines ~19449–19465): Update trigger names and TOML example
## Configuration Reference → ### sandbox.checkpoint.* table (line ~30722): Move entry to core.checkpoints.* section and update trigger names

Summary of Proposed Changes

Location	Current	Proposed
Line 19453	`on_tool_write`	`before_tool_execute`
Line 19454	`on_tool_write_complete`	`after_tool_execute`
Line 19462	`auto_create_on = ["on_tool_write", "on_tool_write_complete", ...]`	`auto_create_on = ["before_tool_execute", "after_tool_execute", ...]`
Line 30722	`sandbox.checkpoint.auto-create-on`	Move to `core.checkpoints.*` section as `core.checkpoints.auto-create-on`
Line 30722 default	`["on_tool_write", "on_tool_write_complete", ...]`	`["before_tool_execute", "after_tool_execute", ...]`

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

## Specification Update Proposal **Triggered by:** Analysis of merged PRs #3474 (automatic checkpoint triggers) and #4890 (UAT: checkpoint config key mismatch), comparing `src/cleveragents/application/services/config_service.py`, `src/cleveragents/tool/runner.py`, and `src/cleveragents/application/services/subplan_execution_service.py` against `docs/specification.md`. --- ## What Changed in the Implementation PR #3474 implemented the four automatic checkpoint triggers for the Execute phase. The implementation uses different trigger names than the spec, and the spec itself has an internal inconsistency in the config key path. --- ## Discrepancy 1: Checkpoint Trigger Names **Current spec text (line 19451–19456):** | 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` | **What the implementation actually uses** (`src/cleveragents/tool/runner.py`, `src/cleveragents/application/services/config_service.py`): ```python # config_service.py line 484 "before_tool_execute,after_tool_execute,on_subplan_spawn,on_error" # tool/runner.py lines 55-56 "before_tool_execute", "after_tool_execute", ``` The implementation uses: - `before_tool_execute` (spec says `on_tool_write`) - `after_tool_execute` (spec says `on_tool_write_complete`) - `on_subplan_spawn` ✓ (matches) - `on_error` ✓ (matches) **Rationale for the implementation's naming:** The names `before_tool_execute` and `after_tool_execute` are more precise and consistent with the general "tool execution" lifecycle rather than implying only write tools trigger them. The implementation correctly gates these on write tools (`_tool_writes` flag), but the trigger names themselves describe the execution phase rather than the write operation. **Proposed spec update:** Update the trigger names in the spec to match the implementation: - `on_tool_write` → `before_tool_execute` - `on_tool_write_complete` → `after_tool_execute` Affected spec locations: - Line 19451–19456: Trigger table - Line 19462: TOML example - Line 30722: Config reference table (see Discrepancy 2) --- ## Discrepancy 2: Config Key Path — Internal Spec Inconsistency The spec has two conflicting config key paths for the same setting: **Spec line 19449 (Automatic Checkpoint Triggers section):** ``` configurable via `core.checkpoints.auto_create_on` ``` **Spec line 30722 (Configuration Reference table):** ``` | `sandbox.checkpoint.auto-create-on` | list | `["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]` | `CLEVERAGENTS_CHECKPOINT_AUTO_CREATE_ON` | ... ``` **What the implementation uses** (`config_service.py` line 480–493): ```python _register( "core", "checkpoints.auto_create_on", ... env_var="CLEVERAGENTS_CHECKPOINT_AUTO_CREATE_ON", ) ``` The implementation uses `core.checkpoints.auto_create_on` (matching line 19449). The configuration reference table at line 30722 uses `sandbox.checkpoint.auto-create-on` — a different section and naming convention. **Proposed spec update:** Update the configuration reference table (line 30722) to use the correct key path `core.checkpoints.auto-create-on` (matching the implementation and the inline spec at line 19449), and update the default values to use the implementation's trigger names. --- ## Scope Spec sections affected: - `## Plan Lifecycle` → `### Execute Phase` → `#### Automatic Checkpoint Triggers` (lines ~19449–19465): Update trigger names and TOML example - `## Configuration Reference` → `### sandbox.checkpoint.*` table (line ~30722): Move entry to `core.checkpoints.*` section and update trigger names --- ## Summary of Proposed Changes | Location | Current | Proposed | |----------|---------|---------| | Line 19453 | `on_tool_write` | `before_tool_execute` | | Line 19454 | `on_tool_write_complete` | `after_tool_execute` | | Line 19462 | `auto_create_on = ["on_tool_write", "on_tool_write_complete", ...]` | `auto_create_on = ["before_tool_execute", "after_tool_execute", ...]` | | Line 30722 | `sandbox.checkpoint.auto-create-on` | Move to `core.checkpoints.*` section as `core.checkpoints.auto-create-on` | | Line 30722 default | `["on_tool_write", "on_tool_write_complete", ...]` | `["before_tool_execute", "after_tool_execute", ...]` | --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

HAL9000 added the

labels

2026-04-09 00:46:28 +00:00

HAL9000 referenced this issue

2026-04-09 00:47:14 +00:00

[AUTO-SPEC] Specification Update Report (Cycle 1) #5010

HAL9000 referenced this issue

2026-04-09 00:54:13 +00:00

[AUTO-WATCHDOG] Alert: Implementation Orchestrator Cannot Dispatch Workers — Tool Access Limitation #5070

HAL9000 referenced this issue

2026-04-09 01:52:32 +00:00

[AUTO-SPEC] Specification Update Report (Cycle 5) #5145

HAL9000 referenced this issue

2026-04-09 02:55:53 +00:00

[AUTO-ARCH] Architecture Review (Cycle 1) #5158

HAL9000 referenced this issue

2026-04-09 02:56:12 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 4) #5160

HAL9000 referenced this issue from a commit

2026-04-09 02:56:56 +00:00

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

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

2026-04-09 02:57:04 +00:00

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

HAL9000 commented

2026-04-09 02:57:30 +00:00

Author

Owner

Architecture Action Taken

This spec update proposal has been implemented. PR #5163 has been created with the following changes:

Checkpoint trigger names updated in the Automatic Checkpoint Triggers table and TOML example:
- on_tool_write → before_tool_execute
- on_tool_write_complete → after_tool_execute
Config key path corrected in the Configuration Reference table:
- sandbox.checkpoint.auto-create-on → core.checkpoints.auto-create-on
- Default values updated to use corrected trigger names

PR #5163 is awaiting human approval (needs feedback label applied). The spec will be updated once merged.

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architect | Instance: architect-1

## Architecture Action Taken This spec update proposal has been implemented. PR #5163 has been created with the following changes: 1. **Checkpoint trigger names** updated in the Automatic Checkpoint Triggers table and TOML example: - `on_tool_write` → `before_tool_execute` - `on_tool_write_complete` → `after_tool_execute` 2. **Config key path** corrected in the Configuration Reference table: - `sandbox.checkpoint.auto-create-on` → `core.checkpoints.auto-create-on` - Default values updated to use corrected trigger names PR #5163 is awaiting human approval (`needs feedback` label applied). The spec will be updated once merged. --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architect | Instance: architect-1

HAL9000 referenced this issue

2026-04-09 02:57:42 +00:00

[AUTO-ARCH] Architecture Review (Cycle 1) #5158

HAL9000 referenced this issue

2026-04-09 03:01:41 +00:00

[AUTO-SPEC] Specification Update Report (Cycle 6) #5184

HAL9000 referenced this issue

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

[AUTO-UAT-POOL] UAT Testing Report (Cycle 5) #5200

HAL9000 referenced this issue

2026-04-09 04:36:52 +00:00

[AUTO-SPEC] Specification Update Report (Cycle 6) #5184