UAT: builtin/shell_execute tool is completely absent — spec requires a built-in shell execution tool with writes=True and checkpoint=snapshot #4092

Open
opened 2026-04-06 10:17:11 +00:00 by freemo · 0 comments
Owner

Metadata

  • Branch: fix/builtin-shell-execute-tool
  • Commit Message: feat(tool): implement builtin/shell_execute tool
  • Milestone: (none — backlog)
  • Parent Epic: #392

Backlog note: This issue was discovered during UAT of the Built-in Tools feature area. It is placed in the backlog for human review and future milestone assignment.

Background and Context

The specification (docs/specification.md) explicitly lists shell_execute as a required built-in tool. It appears in multiple places in the spec:

  • Line 7025: shell_execute builtin yes snapshot
  • Line 7262: shell_execute builtin (direct) — ✓ snapshot
  • Line 7351: { "name": "shell_execute", "source": "builtin", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "snapshot" }
  • Line 32857: - name: builtin/shell_execute (in skill YAML example)

The spec also references builtin/shell_execute in test fixtures:

  • features/steps/skill_cli_steps.py line 95: - name: builtin/shell_execute
  • features/steps/skill_schema_steps.py line 64: - name: builtin/shell_execute
  • robot/helper_skill_cli.py line 44: - name: builtin/shell_execute

However, there is no implementation of this tool anywhere in the codebase. The src/cleveragents/tool/builtins/ directory contains only:

  • file_tools.py — 6 file operation tools
  • git_tools.py — 4 git operation tools
  • subplan_tool.py — 1 subplan tool
  • adapter.py — BuiltinAdapter
  • changeset.py — ChangeSet capture

There is no shell_tools.py or equivalent.

Current Behavior

The builtin/shell_execute tool does not exist. Attempting to reference it in a skill YAML will fail with a "tool not found" error. The BuiltinAdapter.discover() returns only 11 tools (6 file + 4 git + 1 subplan), missing the shell execution tool.

Expected Behavior (from spec)

Per docs/specification.md, builtin/shell_execute should:

  • Have source: "builtin"
  • Have writes: true (not read-only)
  • Have checkpoint: "snapshot" (uses snapshot sandbox strategy)
  • Be registered in the BuiltinAdapter alongside file and git tools
  • Execute shell commands within the project sandbox

Code Locations

  • src/cleveragents/tool/builtins/ — directory where the implementation should be added
  • src/cleveragents/tool/builtins/__init__.py — registration helpers to update
  • src/cleveragents/tool/builtins/adapter.pyBuiltinAdapter.discover() to update
  • docs/specification.md lines 7025, 7262, 7351, 32857 — spec references

Subtasks

  • Create src/cleveragents/tool/builtins/shell_tools.py with SHELL_EXECUTE_SPEC implementing builtin/shell_execute
  • Implement the handler with sandbox path validation, subprocess execution, timeout handling, and output capture
  • Set capabilities=ToolCapability(writes=True, checkpointable=True) with checkpoint_scope="snapshot"
  • Add ALL_SHELL_TOOLS list and register_shell_tools() helper function
  • Update src/cleveragents/tool/builtins/__init__.py to export the new tool
  • Update src/cleveragents/tool/builtins/adapter.py BuiltinAdapter.discover() to include shell tools
  • Write Behave test scenarios in features/ covering: basic execution, stdout/stderr capture, non-zero exit code handling, timeout handling, sandbox path validation
  • Run nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e coverage_report

Definition of Done

  • builtin/shell_execute tool exists and is registered in BuiltinAdapter
  • Tool has writes=True and checkpointable=True with checkpoint_scope="snapshot"
  • Tool executes shell commands within sandbox boundaries
  • Skill YAML referencing builtin/shell_execute resolves correctly
  • All nox stages pass
  • Coverage >= 97%

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

## Metadata - **Branch**: `fix/builtin-shell-execute-tool` - **Commit Message**: `feat(tool): implement builtin/shell_execute tool` - **Milestone**: *(none — backlog)* - **Parent Epic**: #392 > **Backlog note:** This issue was discovered during UAT of the Built-in Tools feature area. It is placed in the backlog for human review and future milestone assignment. ## Background and Context The specification (`docs/specification.md`) explicitly lists `shell_execute` as a required built-in tool. It appears in multiple places in the spec: - Line 7025: `shell_execute builtin yes snapshot` - Line 7262: `shell_execute builtin (direct) — ✓ snapshot` - Line 7351: `{ "name": "shell_execute", "source": "builtin", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "snapshot" }` - Line 32857: `- name: builtin/shell_execute` (in skill YAML example) The spec also references `builtin/shell_execute` in test fixtures: - `features/steps/skill_cli_steps.py` line 95: `- name: builtin/shell_execute` - `features/steps/skill_schema_steps.py` line 64: `- name: builtin/shell_execute` - `robot/helper_skill_cli.py` line 44: `- name: builtin/shell_execute` However, there is **no implementation** of this tool anywhere in the codebase. The `src/cleveragents/tool/builtins/` directory contains only: - `file_tools.py` — 6 file operation tools - `git_tools.py` — 4 git operation tools - `subplan_tool.py` — 1 subplan tool - `adapter.py` — BuiltinAdapter - `changeset.py` — ChangeSet capture There is no `shell_tools.py` or equivalent. ## Current Behavior The `builtin/shell_execute` tool does not exist. Attempting to reference it in a skill YAML will fail with a "tool not found" error. The `BuiltinAdapter.discover()` returns only 11 tools (6 file + 4 git + 1 subplan), missing the shell execution tool. ## Expected Behavior (from spec) Per `docs/specification.md`, `builtin/shell_execute` should: - Have `source: "builtin"` - Have `writes: true` (not read-only) - Have `checkpoint: "snapshot"` (uses snapshot sandbox strategy) - Be registered in the `BuiltinAdapter` alongside file and git tools - Execute shell commands within the project sandbox ## Code Locations - `src/cleveragents/tool/builtins/` — directory where the implementation should be added - `src/cleveragents/tool/builtins/__init__.py` — registration helpers to update - `src/cleveragents/tool/builtins/adapter.py` — `BuiltinAdapter.discover()` to update - `docs/specification.md` lines 7025, 7262, 7351, 32857 — spec references ## Subtasks - [ ] Create `src/cleveragents/tool/builtins/shell_tools.py` with `SHELL_EXECUTE_SPEC` implementing `builtin/shell_execute` - [ ] Implement the handler with sandbox path validation, subprocess execution, timeout handling, and output capture - [ ] Set `capabilities=ToolCapability(writes=True, checkpointable=True)` with `checkpoint_scope="snapshot"` - [ ] Add `ALL_SHELL_TOOLS` list and `register_shell_tools()` helper function - [ ] Update `src/cleveragents/tool/builtins/__init__.py` to export the new tool - [ ] Update `src/cleveragents/tool/builtins/adapter.py` `BuiltinAdapter.discover()` to include shell tools - [ ] Write Behave test scenarios in `features/` covering: basic execution, stdout/stderr capture, non-zero exit code handling, timeout handling, sandbox path validation - [ ] Run `nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e coverage_report` ## Definition of Done - [ ] `builtin/shell_execute` tool exists and is registered in `BuiltinAdapter` - [ ] Tool has `writes=True` and `checkpointable=True` with `checkpoint_scope="snapshot"` - [ ] Tool executes shell commands within sandbox boundaries - [ ] Skill YAML referencing `builtin/shell_execute` resolves correctly - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
HAL9000 added this to the v3.5.0 milestone 2026-04-09 03:11:05 +00:00
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
#392 Epic: Actor YAML & Compiler
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#4092
No description provided.