UAT: ToolLifecycle domain model missing execute hook — spec requires four-stage lifecycle #2820

Closed
opened 2026-04-04 20:40:06 +00:00 by freemo · 8 comments
Owner

Metadata

  • Branch: fix/tool-lifecycle-domain-model-missing-execute-hook
  • Commit Message: fix(domain): add missing execute hook to ToolLifecycle model to satisfy spec four-stage lifecycle
  • Milestone: v3.7.0
  • Parent Epic: #393

Description

The ToolLifecycle domain model in src/cleveragents/domain/models/core/tool.py is missing the execute lifecycle hook, violating the specification's explicit requirement for a four-stage tool lifecycle.

What Was Tested

The ToolLifecycle domain model in src/cleveragents/domain/models/core/tool.py was analyzed against the specification's four-stage tool lifecycle requirement.

Expected Behavior (from spec)

The specification (docs/specification.md, line 135) explicitly states:

A Tool is the atomic unit of execution: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (read_only, writes, checkpointable), and a four-stage lifecycle (discover / activate / execute / deactivate).

The ToolLifecycle model should support all four lifecycle hooks: discover, activate, execute, and deactivate.

The ToolInstance protocol in src/cleveragents/tool/lifecycle.py correctly implements all four stages (discover, activate, execute, deactivate) as protocol methods.

Actual Behavior

The ToolLifecycle domain model (src/cleveragents/domain/models/core/tool.py, lines 275–291) only defines three lifecycle hooks:

class ToolLifecycle(BaseModel):
    discover: str | None = Field(default=None, description="Hook for tool discovery")
    activate: str | None = Field(default=None, description="Hook for tool activation")
    deactivate: str | None = Field(default=None, description="Hook for tool deactivation")

The execute hook is missing from the ToolLifecycle model. This means:

  1. Tool YAML configuration files cannot declare an execute lifecycle hook
  2. The Tool.from_config() factory method cannot parse an execute hook from YAML
  3. The Tool.as_cli_dict() method cannot render the execute hook for CLI display
  4. The domain model is inconsistent with the ToolInstance protocol which does implement execute

Code Location

  • File: src/cleveragents/domain/models/core/tool.py
  • Class: ToolLifecycle
  • Lines: 275–291

Steps to Reproduce

  1. Read src/cleveragents/domain/models/core/tool.py lines 275–291
  2. Compare with spec requirement for four-stage lifecycle (docs/specification.md, line 135)
  3. Note that execute hook is absent from ToolLifecycle model

Severity

Medium — The runtime ToolInstance protocol correctly implements execute, so runtime execution works. However, the domain model is incomplete and prevents tool YAML configs from declaring an execute lifecycle hook, which is a spec violation.

Subtasks

  • Write a @tdd_expected_fail-tagged Behave scenario in features/ capturing the missing execute field on ToolLifecycle (issue-capture test per bug-fix workflow)
  • Add execute: str | None = Field(default=None, description="Hook for tool execution") to ToolLifecycle in src/cleveragents/domain/models/core/tool.py
  • Verify Tool.from_config() correctly parses the execute hook from YAML tool configuration files
  • Verify Tool.as_cli_dict() correctly renders the execute hook for CLI display
  • Add static type annotations and verify with nox -e typecheck (Pyright — no # type: ignore permitted)
  • Write Behave unit test scenarios covering: ToolLifecycle with all four hooks set, ToolLifecycle with execute=None (default), and round-trip YAML serialisation/deserialisation preserving execute
  • Verify nox -e coverage_report reports ≥ 97% coverage

Definition of Done

  • ToolLifecycle.execute field is present and matches the spec's four-stage lifecycle contract
  • Tool.from_config() correctly parses execute from YAML
  • Tool.as_cli_dict() correctly renders execute in CLI output
  • All Behave unit test scenarios pass (nox -e unit_tests)
  • Pyright type checking passes with no suppressions (nox -e typecheck)
  • Linting passes (nox -e lint)
  • All nox stages pass
  • Coverage >= 97%
  • PR is merged and this issue is closed

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/tool-lifecycle-domain-model-missing-execute-hook` - **Commit Message**: `fix(domain): add missing execute hook to ToolLifecycle model to satisfy spec four-stage lifecycle` - **Milestone**: v3.7.0 - **Parent Epic**: #393 ## Description The `ToolLifecycle` domain model in `src/cleveragents/domain/models/core/tool.py` is missing the `execute` lifecycle hook, violating the specification's explicit requirement for a four-stage tool lifecycle. ### What Was Tested The `ToolLifecycle` domain model in `src/cleveragents/domain/models/core/tool.py` was analyzed against the specification's four-stage tool lifecycle requirement. ### Expected Behavior (from spec) The specification (`docs/specification.md`, line 135) explicitly states: > A Tool is the atomic unit of execution: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a **four-stage lifecycle** (`discover` / `activate` / `execute` / `deactivate`). The `ToolLifecycle` model should support all four lifecycle hooks: `discover`, `activate`, **`execute`**, and `deactivate`. The `ToolInstance` protocol in `src/cleveragents/tool/lifecycle.py` correctly implements all four stages (`discover`, `activate`, `execute`, `deactivate`) as protocol methods. ### Actual Behavior The `ToolLifecycle` domain model (`src/cleveragents/domain/models/core/tool.py`, lines 275–291) only defines **three** lifecycle hooks: ```python class ToolLifecycle(BaseModel): discover: str | None = Field(default=None, description="Hook for tool discovery") activate: str | None = Field(default=None, description="Hook for tool activation") deactivate: str | None = Field(default=None, description="Hook for tool deactivation") ``` The `execute` hook is **missing** from the `ToolLifecycle` model. This means: 1. Tool YAML configuration files cannot declare an `execute` lifecycle hook 2. The `Tool.from_config()` factory method cannot parse an `execute` hook from YAML 3. The `Tool.as_cli_dict()` method cannot render the `execute` hook for CLI display 4. The domain model is inconsistent with the `ToolInstance` protocol which does implement `execute` ### Code Location - **File**: `src/cleveragents/domain/models/core/tool.py` - **Class**: `ToolLifecycle` - **Lines**: 275–291 ### Steps to Reproduce 1. Read `src/cleveragents/domain/models/core/tool.py` lines 275–291 2. Compare with spec requirement for four-stage lifecycle (`docs/specification.md`, line 135) 3. Note that `execute` hook is absent from `ToolLifecycle` model ### Severity **Medium** — The runtime `ToolInstance` protocol correctly implements `execute`, so runtime execution works. However, the domain model is incomplete and prevents tool YAML configs from declaring an `execute` lifecycle hook, which is a spec violation. ## Subtasks - [ ] Write a `@tdd_expected_fail`-tagged Behave scenario in `features/` capturing the missing `execute` field on `ToolLifecycle` (issue-capture test per bug-fix workflow) - [ ] Add `execute: str | None = Field(default=None, description="Hook for tool execution")` to `ToolLifecycle` in `src/cleveragents/domain/models/core/tool.py` - [ ] Verify `Tool.from_config()` correctly parses the `execute` hook from YAML tool configuration files - [ ] Verify `Tool.as_cli_dict()` correctly renders the `execute` hook for CLI display - [ ] Add static type annotations and verify with `nox -e typecheck` (Pyright — no `# type: ignore` permitted) - [ ] Write Behave unit test scenarios covering: `ToolLifecycle` with all four hooks set, `ToolLifecycle` with `execute=None` (default), and round-trip YAML serialisation/deserialisation preserving `execute` - [ ] Verify `nox -e coverage_report` reports ≥ 97% coverage ## Definition of Done - [ ] `ToolLifecycle.execute` field is present and matches the spec's four-stage lifecycle contract - [ ] `Tool.from_config()` correctly parses `execute` from YAML - [ ] `Tool.as_cli_dict()` correctly renders `execute` in CLI output - [ ] All Behave unit test scenarios pass (`nox -e unit_tests`) - [ ] Pyright type checking passes with no suppressions (`nox -e typecheck`) - [ ] Linting passes (`nox -e lint`) - [ ] All nox stages pass - [ ] Coverage >= 97% - [ ] PR is merged and this issue is closed --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.7.0 milestone 2026-04-04 20:40:11 +00:00
Author
Owner

Starting implementation on branch fix/tool-lifecycle-domain-model-missing-execute-hook.

Plan: Add missing execute hook to ToolLifecycle domain model in src/cleveragents/domain/models/core/tool.py, verify from_config() and as_cli_dict() handle it correctly, write Behave tests, and ensure ≥97% coverage.

Difficulty assessment: Low → starting at sonnet tier.


Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/tool-lifecycle-domain-model-missing-execute-hook`. **Plan:** Add missing `execute` hook to `ToolLifecycle` domain model in `src/cleveragents/domain/models/core/tool.py`, verify `from_config()` and `as_cli_dict()` handle it correctly, write Behave tests, and ensure ≥97% coverage. Difficulty assessment: Low → starting at sonnet tier. --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Author
Owner

All subtasks complete. Quality gates passed. Creating PR.

Implementation summary:

  • Added execute: str | None = Field(default=None, description="Hook for tool execution") to ToolLifecycle in src/cleveragents/domain/models/core/tool.py — completing the four-stage lifecycle (discover / activate / execute / deactivate) as required by the spec.
  • Updated Tool.as_cli_dict() to render the lifecycle block (including execute) when set.
  • Created features/tool_lifecycle_execute_hook.feature with 8 scenarios covering: issue-capture TDD test, all four hooks, execute defaults to None, execute set independently, from_config parsing, as_cli_dict rendering.
  • Created features/steps/tool_lifecycle_execute_hook_steps.py with all step definitions.

Quality gates:

  • Pyright: 0 errors, 0 warnings
  • Ruff lint: All checks passed
  • Behave: 131 scenarios passed, 0 failed (new feature + consolidated_tool)

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

All subtasks complete. Quality gates passed. Creating PR. **Implementation summary:** - Added `execute: str | None = Field(default=None, description="Hook for tool execution")` to `ToolLifecycle` in `src/cleveragents/domain/models/core/tool.py` — completing the four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`) as required by the spec. - Updated `Tool.as_cli_dict()` to render the `lifecycle` block (including `execute`) when set. - Created `features/tool_lifecycle_execute_hook.feature` with 8 scenarios covering: issue-capture TDD test, all four hooks, execute defaults to None, execute set independently, `from_config` parsing, `as_cli_dict` rendering. - Created `features/steps/tool_lifecycle_execute_hook_steps.py` with all step definitions. **Quality gates:** - ✅ Pyright: 0 errors, 0 warnings - ✅ Ruff lint: All checks passed - ✅ Behave: 131 scenarios passed, 0 failed (new feature + consolidated_tool) --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Author
Owner

PR #3052 created on branch fix/tool-lifecycle-domain-model-missing-execute-hook. PR review and merge handled by continuous review stream.

PR URL: #3052


Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

PR #3052 created on branch `fix/tool-lifecycle-domain-model-missing-execute-hook`. PR review and merge handled by continuous review stream. **PR URL:** https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/3052 --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Author
Owner

PR #3052 has been reviewed, approved, and scheduled to merge when all CI checks pass.

Review summary: The PR correctly adds the missing execute hook to the ToolLifecycle domain model, completing the four-stage lifecycle (discover / activate / execute / deactivate) as required by the specification. Code is clean, well-tested (8 new BDD scenarios), and follows existing patterns. Single atomic commit with proper Conventional Changelog format.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3052 has been reviewed, approved, and scheduled to merge when all CI checks pass. **Review summary**: The PR correctly adds the missing `execute` hook to the `ToolLifecycle` domain model, completing the four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`) as required by the specification. Code is clean, well-tested (8 new BDD scenarios), and follows existing patterns. Single atomic commit with proper Conventional Changelog format. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer
Author
Owner

PR #3052 reviewed, approved, and merged.

The ToolLifecycle domain model now includes the execute hook, completing the four-stage lifecycle (discover / activate / execute / deactivate) as required by the specification. All CI checks passed.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3052 reviewed, approved, and merged. The `ToolLifecycle` domain model now includes the `execute` hook, completing the four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`) as required by the specification. All CI checks passed. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer
Author
Owner

Issue transitioned to State/Completed and closed. Stale dependency link (PR #3052 → this issue) was removed to allow closure.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

Issue transitioned to `State/Completed` and closed. Stale dependency link (PR #3052 → this issue) was removed to allow closure. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer
Author
Owner

PR #3052 independently reviewed, approved, and merged. All CI checks passed (lint, typecheck, security, quality, unit_tests, integration_tests, e2e_tests, coverage). Issue already in State/Completed and closed — no further action needed.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3052 independently reviewed, approved, and merged. All CI checks passed (lint, typecheck, security, quality, unit_tests, integration_tests, e2e_tests, coverage). Issue already in `State/Completed` and closed — no further action needed. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer
Author
Owner

PR #3052 reviewed, approved, and merged. The ToolLifecycle domain model now includes the execute hook, completing the four-stage lifecycle (discover / activate / execute / deactivate) as required by the specification.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3052 reviewed, approved, and merged. The `ToolLifecycle` domain model now includes the `execute` hook, completing the four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`) as required by the specification. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#393 Epic: Skill & Tool Lifecycle
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#2820
No description provided.