cleveragents/cleveragents-core

Fork 3

UAT: ToolRuntimeError hierarchy does not inherit from CleverAgentsError — tool lifecycle exceptions bypass structured error handling pipeline #3762

New issue

Open

opened 2026-04-05 22:32:11 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 22:32:11 +00:00

Owner

Metadata

Branch: fix/tool-runtime-error-inherits-cleveragents-error
Commit Message: fix(tool): make ToolRuntimeError inherit from CleverAgentsError per spec exception hierarchy
Milestone: (backlog — no milestone assigned)
Parent Epic: #397

Background and Context

Per docs/specification.md and the project's error handling philosophy (ADR-005), all application-specific exceptions MUST inherit from CleverAgentsError to ensure consistent error handling, structured logging, and propagation through the top-level error pipeline.

The current implementation in src/cleveragents/tool/lifecycle.py defines ToolRuntimeError and all its subclasses as direct descendants of Python's built-in Exception, completely bypassing the project-wide exception hierarchy.

Current Behavior

# src/cleveragents/tool/lifecycle.py
class ToolRuntimeError(Exception):  # BUG: should be CleverAgentsError
    """Base error for tool runtime failures."""

class ToolAccessDeniedError(ToolRuntimeError): ...
class ToolCheckpointRequiredError(ToolRuntimeError): ...
class ToolNotActivatedError(ToolRuntimeError): ...
class ToolActivationError(ToolRuntimeError): ...
class ToolExecutionError(ToolRuntimeError): ...
class ToolSafetyViolationError(ToolRuntimeError): ...
class ToolSandboxRequiredError(ToolRuntimeError): ...
class ToolHumanApprovalRequiredError(ToolRuntimeError): ...
class ToolCostLimitExceededError(ToolRuntimeError): ...
class ToolRetryLimitExceededError(ToolRuntimeError): ...
class ToolDeactivationError(ToolRuntimeError): ...

The following assertion fails:

from cleveragents.tool.lifecycle import ToolRuntimeError
from cleveragents.core.exceptions import CleverAgentsError
assert issubclass(ToolRuntimeError, CleverAgentsError)  # AssertionError

Expected Behavior

ToolRuntimeError should inherit from CleverAgentsError (from cleveragents.core.exceptions):

from cleveragents.core.exceptions import CleverAgentsError

class ToolRuntimeError(CleverAgentsError):
    """Base error for tool runtime failures."""

All subclasses would automatically inherit from CleverAgentsError through ToolRuntimeError.

Impact

Tool lifecycle exceptions cannot be caught by top-level CleverAgentsError handlers
Structured error logging pipeline is bypassed for all tool execution failures
Inconsistent with the project-wide exception hierarchy pattern
The tool lifecycle is a core execution path — this affects every tool invocation
Similar bugs already filed for PluginError (#3685) and SandboxError

Code Location

src/cleveragents/tool/lifecycle.py — lines defining ToolRuntimeError and all subclasses (approximately lines 60-120)

Steps to Reproduce

Import ToolRuntimeError from cleveragents.tool.lifecycle
Import CleverAgentsError from cleveragents.core.exceptions
Assert issubclass(ToolRuntimeError, CleverAgentsError) — this fails

Subtasks

Write TDD issue-capture Behave scenario tagged @tdd_expected_fail asserting issubclass(ToolRuntimeError, CleverAgentsError) (fails before fix)
Add import of CleverAgentsError from cleveragents.core.exceptions in src/cleveragents/tool/lifecycle.py
Change class ToolRuntimeError(Exception) to class ToolRuntimeError(CleverAgentsError)
Verify all 11 ToolRuntimeError subclasses transitively satisfy issubclass(X, CleverAgentsError)
Verify top-level except CleverAgentsError handlers now correctly catch tool lifecycle exceptions (add/update Behave scenario)
Remove @tdd_expected_fail tag once fix is in place and all scenarios pass
Run nox -e typecheck — Pyright must pass with no suppressions
Run nox -e unit_tests — all Behave scenarios pass
Run nox -e coverage_report — coverage ≥ 97%
Run nox (all default sessions) — all gates pass

Definition of Done

ToolRuntimeError inherits from CleverAgentsError
All ToolRuntimeError subclasses transitively inherit from CleverAgentsError
issubclass(ToolRuntimeError, CleverAgentsError) passes
Existing tool lifecycle tests continue to pass
nox -e typecheck passes
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

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

## Metadata - **Branch**: `fix/tool-runtime-error-inherits-cleveragents-error` - **Commit Message**: `fix(tool): make ToolRuntimeError inherit from CleverAgentsError per spec exception hierarchy` - **Milestone**: *(backlog — no milestone assigned)* - **Parent Epic**: #397 ## Background and Context Per `docs/specification.md` and the project's error handling philosophy (ADR-005), **all application-specific exceptions MUST inherit from `CleverAgentsError`** to ensure consistent error handling, structured logging, and propagation through the top-level error pipeline. The current implementation in `src/cleveragents/tool/lifecycle.py` defines `ToolRuntimeError` and all its subclasses as direct descendants of Python's built-in `Exception`, completely bypassing the project-wide exception hierarchy. ## Current Behavior ```python # src/cleveragents/tool/lifecycle.py class ToolRuntimeError(Exception): # BUG: should be CleverAgentsError """Base error for tool runtime failures.""" class ToolAccessDeniedError(ToolRuntimeError): ... class ToolCheckpointRequiredError(ToolRuntimeError): ... class ToolNotActivatedError(ToolRuntimeError): ... class ToolActivationError(ToolRuntimeError): ... class ToolExecutionError(ToolRuntimeError): ... class ToolSafetyViolationError(ToolRuntimeError): ... class ToolSandboxRequiredError(ToolRuntimeError): ... class ToolHumanApprovalRequiredError(ToolRuntimeError): ... class ToolCostLimitExceededError(ToolRuntimeError): ... class ToolRetryLimitExceededError(ToolRuntimeError): ... class ToolDeactivationError(ToolRuntimeError): ... ``` The following assertion fails: ```python from cleveragents.tool.lifecycle import ToolRuntimeError from cleveragents.core.exceptions import CleverAgentsError assert issubclass(ToolRuntimeError, CleverAgentsError) # AssertionError ``` ## Expected Behavior `ToolRuntimeError` should inherit from `CleverAgentsError` (from `cleveragents.core.exceptions`): ```python from cleveragents.core.exceptions import CleverAgentsError class ToolRuntimeError(CleverAgentsError): """Base error for tool runtime failures.""" ``` All subclasses would automatically inherit from `CleverAgentsError` through `ToolRuntimeError`. ## Impact - Tool lifecycle exceptions cannot be caught by top-level `CleverAgentsError` handlers - Structured error logging pipeline is bypassed for all tool execution failures - Inconsistent with the project-wide exception hierarchy pattern - The tool lifecycle is a core execution path — this affects every tool invocation - Similar bugs already filed for `PluginError` (#3685) and `SandboxError` ## Code Location `src/cleveragents/tool/lifecycle.py` — lines defining `ToolRuntimeError` and all subclasses (approximately lines 60-120) ## Steps to Reproduce 1. Import `ToolRuntimeError` from `cleveragents.tool.lifecycle` 2. Import `CleverAgentsError` from `cleveragents.core.exceptions` 3. Assert `issubclass(ToolRuntimeError, CleverAgentsError)` — this fails ## Subtasks - [ ] Write TDD issue-capture Behave scenario tagged `@tdd_expected_fail` asserting `issubclass(ToolRuntimeError, CleverAgentsError)` (fails before fix) - [ ] Add import of `CleverAgentsError` from `cleveragents.core.exceptions` in `src/cleveragents/tool/lifecycle.py` - [ ] Change `class ToolRuntimeError(Exception)` to `class ToolRuntimeError(CleverAgentsError)` - [ ] Verify all 11 `ToolRuntimeError` subclasses transitively satisfy `issubclass(X, CleverAgentsError)` - [ ] Verify top-level `except CleverAgentsError` handlers now correctly catch tool lifecycle exceptions (add/update Behave scenario) - [ ] Remove `@tdd_expected_fail` tag once fix is in place and all scenarios pass - [ ] Run `nox -e typecheck` — Pyright must pass with no suppressions - [ ] Run `nox -e unit_tests` — all Behave scenarios pass - [ ] Run `nox -e coverage_report` — coverage ≥ 97% - [ ] Run `nox` (all default sessions) — all gates pass ## Definition of Done - [ ] `ToolRuntimeError` inherits from `CleverAgentsError` - [ ] All `ToolRuntimeError` subclasses transitively inherit from `CleverAgentsError` - [ ] `issubclass(ToolRuntimeError, CleverAgentsError)` passes - [ ] Existing tool lifecycle tests continue to pass - [ ] `nox -e typecheck` passes - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 22:32:18 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-05 22:33:37 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:34:53 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo added the

Points

label

2026-04-06 06:21:43 +00:00

freemo commented

2026-04-06 06:22:02 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Backlog (confirmed)
Story Points: 2 — S — Single-line inheritance change plus Behave test verification. The fix is trivial but important for exception hierarchy consistency.
MoSCoW: Should Have — The spec mandates all application exceptions inherit from CleverAgentsError. This is a spec compliance issue that affects structured error handling for all tool lifecycle operations. Similar to #3685 (PluginError hierarchy).
Parent Epic: #397

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Backlog (confirmed) - **Story Points**: 2 — S — Single-line inheritance change plus Behave test verification. The fix is trivial but important for exception hierarchy consistency. - **MoSCoW**: Should Have — The spec mandates all application exceptions inherit from CleverAgentsError. This is a spec compliance issue that affects structured error handling for all tool lifecycle operations. Similar to #3685 (PluginError hierarchy). - **Parent Epic**: #397 --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

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

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

freemo referenced this issue

2026-04-06 07:57:40 +00:00

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

freemo referenced this issue

2026-04-06 12:44:53 +00:00

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