cleveragents/cleveragents-core

Fork 3

UAT: sandbox_root parameter missing from builtin file tool input schemas #4035

New issue

Open

opened 2026-04-06 08:55:48 +00:00 by freemo · 1 comment

freemo commented

2026-04-06 08:55:48 +00:00

Owner

Summary

All 6 builtin file tools in src/cleveragents/tool/builtins/file_tools.py accept a sandbox_root parameter in their handlers but do not declare it in their input_schema. This means agents and LLMs cannot discover or properly pass the sandbox_root parameter, and schema validation tools will reject it as an unknown parameter.

Metadata

Branch: fix/builtin-file-tool-sandbox-root-schema
Commit Message: fix(tool): add sandbox_root to builtin file tool input schemas
Milestone: Backlog (no milestone assigned)
Parent Epic: TBD — requires manual linking

Subtasks

Add sandbox_root property to FILE_READ_SPEC.input_schema
Add sandbox_root property to FILE_WRITE_SPEC.input_schema
Add sandbox_root property to FILE_EDIT_SPEC.input_schema
Add sandbox_root property to FILE_DELETE_SPEC.input_schema
Add sandbox_root property to FILE_LIST_SPEC.input_schema
Add sandbox_root property to FILE_SEARCH_SPEC.input_schema
Add tests verifying sandbox_root is in each tool's schema

Description

Root Cause

The module docstring for file_tools.py explicitly states:

"All file tools accept an optional sandbox_root input parameter that constrains file operations to a specific directory."

However, none of the 6 tool specs declare sandbox_root in their input_schema.properties. The handlers correctly read inputs.get("sandbox_root"), but since it's not in the schema, it is an undocumented hidden parameter.

Affected Code

src/cleveragents/tool/builtins/file_tools.py

All 6 specs (FILE_READ_SPEC, FILE_WRITE_SPEC, FILE_EDIT_SPEC, FILE_DELETE_SPEC, FILE_LIST_SPEC, FILE_SEARCH_SPEC) are missing sandbox_root from their input_schema.properties.

Example — FILE_READ_SPEC currently:

FILE_READ_SPEC = ToolSpec(
    name="builtin/file-read",
    input_schema={
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "File path to read"},
            "encoding": {...},
            "offset": {...},
            "limit": {...},
            # MISSING: "sandbox_root": {...}
        },
        "required": ["path"],
    },
    ...
)

Fix

Add sandbox_root to each tool's input_schema.properties:

"sandbox_root": {
    "type": "string",
    "description": "Sandbox root directory to constrain file operations. Defaults to current working directory.",
},

Note: sandbox_root should NOT be in required since it is optional.

Steps to Reproduce

from cleveragents.tool.builtins.file_tools import FILE_READ_SPEC
props = FILE_READ_SPEC.input_schema.get("properties", {})
assert "sandbox_root" in props  # FAILS

Expected Behavior

All 6 builtin file tool input schemas should declare sandbox_root as an optional string property.

Actual Behavior

None of the 6 builtin file tool input schemas declare sandbox_root. The parameter is silently accepted by handlers but invisible to schema consumers (agents, LLMs, validators).

Impact

Agents and LLMs using tool discovery cannot learn about the sandbox_root parameter
Schema validators may reject inputs containing sandbox_root as an unknown property
The module docstring's claim that "all file tools accept an optional sandbox_root input parameter" is not reflected in the schemas

Definition of Done

All 6 builtin file tool specs have sandbox_root in their input_schema.properties
Tests added verifying sandbox_root is in each tool's schema
PR merged
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation on milestone UAT Testing. 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

## Summary All 6 builtin file tools in `src/cleveragents/tool/builtins/file_tools.py` accept a `sandbox_root` parameter in their handlers but do not declare it in their `input_schema`. This means agents and LLMs cannot discover or properly pass the `sandbox_root` parameter, and schema validation tools will reject it as an unknown parameter. ## Metadata - **Branch**: `fix/builtin-file-tool-sandbox-root-schema` - **Commit Message**: `fix(tool): add sandbox_root to builtin file tool input schemas` - **Milestone**: Backlog (no milestone assigned) - **Parent Epic**: TBD — requires manual linking ## Subtasks - [ ] Add `sandbox_root` property to `FILE_READ_SPEC.input_schema` - [ ] Add `sandbox_root` property to `FILE_WRITE_SPEC.input_schema` - [ ] Add `sandbox_root` property to `FILE_EDIT_SPEC.input_schema` - [ ] Add `sandbox_root` property to `FILE_DELETE_SPEC.input_schema` - [ ] Add `sandbox_root` property to `FILE_LIST_SPEC.input_schema` - [ ] Add `sandbox_root` property to `FILE_SEARCH_SPEC.input_schema` - [ ] Add tests verifying `sandbox_root` is in each tool's schema ## Description ### Root Cause The module docstring for `file_tools.py` explicitly states: > "All file tools accept an optional `sandbox_root` input parameter that constrains file operations to a specific directory." However, none of the 6 tool specs declare `sandbox_root` in their `input_schema.properties`. The handlers correctly read `inputs.get("sandbox_root")`, but since it's not in the schema, it is an undocumented hidden parameter. ### Affected Code **`src/cleveragents/tool/builtins/file_tools.py`** All 6 specs (`FILE_READ_SPEC`, `FILE_WRITE_SPEC`, `FILE_EDIT_SPEC`, `FILE_DELETE_SPEC`, `FILE_LIST_SPEC`, `FILE_SEARCH_SPEC`) are missing `sandbox_root` from their `input_schema.properties`. Example — `FILE_READ_SPEC` currently: ```python FILE_READ_SPEC = ToolSpec( name="builtin/file-read", input_schema={ "type": "object", "properties": { "path": {"type": "string", "description": "File path to read"}, "encoding": {...}, "offset": {...}, "limit": {...}, # MISSING: "sandbox_root": {...} }, "required": ["path"], }, ... ) ``` ### Fix Add `sandbox_root` to each tool's `input_schema.properties`: ```python "sandbox_root": { "type": "string", "description": "Sandbox root directory to constrain file operations. Defaults to current working directory.", }, ``` Note: `sandbox_root` should NOT be in `required` since it is optional. ### Steps to Reproduce ```python from cleveragents.tool.builtins.file_tools import FILE_READ_SPEC props = FILE_READ_SPEC.input_schema.get("properties", {}) assert "sandbox_root" in props # FAILS ``` ### Expected Behavior All 6 builtin file tool input schemas should declare `sandbox_root` as an optional string property. ### Actual Behavior None of the 6 builtin file tool input schemas declare `sandbox_root`. The parameter is silently accepted by handlers but invisible to schema consumers (agents, LLMs, validators). ### Impact - Agents and LLMs using tool discovery cannot learn about the `sandbox_root` parameter - Schema validators may reject inputs containing `sandbox_root` as an unknown property - The module docstring's claim that "all file tools accept an optional `sandbox_root` input parameter" is not reflected in the schemas ## Definition of Done - [ ] All 6 builtin file tool specs have `sandbox_root` in their `input_schema.properties` - [ ] Tests added verifying `sandbox_root` is in each tool's schema - [ ] PR merged - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation on milestone UAT Testing. 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 commented

2026-04-06 08:56:14 +00:00

Author

Owner

⚠️ Orphan Issue — Manual Epic Linking Required

This issue was created without a known parent Epic. Per CONTRIBUTING.md, orphan issues are not permitted — every issue must be linked to a parent Epic using Forgejo's dependency system (child blocks parent).

Action required for a human reviewer:

Identify the appropriate parent Epic in the Actors/Skills/Tools workstream (likely the Epic covering builtin tool implementation or tool schema correctness).
Create the dependency link so that this issue (#4035) blocks the parent Epic.

The relevant API call to create the link once the parent Epic number is known:

curl -s -X POST "https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/issues/4035/blocks" \
  -H "Authorization: token <PAT>" \
  -H "Content-Type: application/json" \
  -d '{"owner": "cleveragents", "repo": "cleveragents-core", "index": <PARENT_EPIC_NUMBER>}'

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

⚠️ **Orphan Issue — Manual Epic Linking Required** This issue was created without a known parent Epic. Per CONTRIBUTING.md, orphan issues are not permitted — every issue must be linked to a parent Epic using Forgejo's dependency system (child **blocks** parent). **Action required for a human reviewer:** 1. Identify the appropriate parent Epic in the Actors/Skills/Tools workstream (likely the Epic covering builtin tool implementation or tool schema correctness). 2. Create the dependency link so that this issue (#4035) **blocks** the parent Epic. The relevant API call to create the link once the parent Epic number is known: ```bash curl -s -X POST "https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/issues/4035/blocks" \ -H "Authorization: token <PAT>" \ -H "Content-Type: application/json" \ -d '{"owner": "cleveragents", "repo": "cleveragents-core", "index": <PARENT_EPIC_NUMBER>}' ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo referenced this issue

2026-04-06 08:59:45 +00:00

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

freemo referenced this issue

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

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

freemo referenced this issue

2026-04-06 10:25:22 +00:00

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

freemo referenced this issue

2026-04-06 10:29:10 +00:00

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