UAT: `agents skill tools --format json` omits `read_only`, `writes`, and `checkpoint` fields for non-inline tools #2067

New issue

Open

opened 2026-04-03 03:47:43 +00:00 by freemo · 0 comments

freemo commented

2026-04-03 03:47:43 +00:00

Owner

Metadata

Branch: fix/skill-tools-json-capability-fields
Commit Message: fix(cli): include read_only, writes, checkpoint fields for all tool types in skill tools JSON output
Milestone: v3.7.0
Parent Epic: #936

Background and Context

The agents skill tools <NAME> --format json command is part of the skill composition and management feature area. Per the specification (§agents skill tools JSON output), every tool entry in the JSON output must include capability metadata fields: read_only, writes, and checkpoint. These fields are defined as part of the core Tool architecture — tools are atomic units of execution that carry capability metadata alongside their name and source information.

Currently, the JSON output path in src/cleveragents/cli/commands/skill.py only populates these fields for inline (anonymous) tools via the rich output path (_print_skill_tools). For all other tool types — builtin, mcp, and agent_skill — these fields are entirely absent from the JSON output. Additionally, the field naming in the implementation (source_skill, is_direct, is_inline) does not match the spec (from_skill with null for direct tools).

Current Behavior

When running agents skill tools local/test-skill --format json with a skill containing builtin tool references, the JSON output omits read_only, writes, and checkpoint for non-inline tools:

{
  "data": {
    "tools": [
      {
        "name": "read_file",
        "source_skill": "local/test-skill",
        "source": "builtin",
        "is_direct": true,
        "is_inline": false
      }
    ]
  }
}

Steps to Reproduce:

name: local/test-skill
description: Test skill
tools:
  - name: builtin/read_file

Run agents skill tools local/test-skill --format json
Observe that read_only, writes, and checkpoint are absent from the output.

Code Location: src/cleveragents/cli/commands/skill.py, tools() command, non-rich output section:

data.append(
    {
        "name": entry.name,
        "source_skill": entry.source_skill,
        "source": source_type,
        "is_direct": entry.source_skill == skill.name,
        "is_inline": entry.is_inline,
        # BUG: read_only, writes, checkpoint are missing for non-inline tools
    }
)

Root Cause: The JSON output path does not populate capability metadata for non-inline tools. The ResolvedToolEntry for non-inline tools doesn't carry capability information from the Tool Registry, but the output must still include these fields (with null for unknown/non-inline tools). Additionally, the field names diverge from the spec.

Expected Behavior

Per the specification (§agents skill tools JSON output), every tool entry must include read_only, writes, and checkpoint, and the parent skill reference must use from_skill (with null for direct tools):

{
  "data": {
    "tools": [
      {
        "name": "read_file",
        "source": "builtin",
        "from_skill": null,
        "read_only": true,
        "writes": false,
        "checkpoint": null
      },
      {
        "name": "write_file",
        "source": "builtin",
        "from_skill": "local/file-ops",
        "read_only": false,
        "writes": true,
        "checkpoint": "file"
      }
    ]
  }
}

Acceptance Criteria

agents skill tools <NAME> --format json includes read_only, writes, and checkpoint for all tool types (builtin, mcp, agent_skill, and inline).
For tool types where capability metadata is not available, these fields are present with null values (not absent).
The JSON output uses from_skill (with null for direct/own-skill tools) instead of source_skill + is_direct.
The is_direct and is_inline fields are removed from the JSON output (not in spec).
All existing and new Behave scenarios for skill tools --format json pass.
All nox sessions pass (nox).
Coverage remains ≥ 97%.

Supporting Information

Spec Reference: §agents skill tools JSON output
Severity: High — JSON consumers relying on capability metadata will silently receive incomplete data.
Feature Area: Skill composition and management
Affected Tool Types: builtin, mcp, agent_skill (inline tools are partially handled but also need verification)
Related Epic: #936 (Epic: Output Rendering Pipeline Integration)

Subtasks

Audit ResolvedToolEntry to determine which tool types carry capability metadata and which do not
Update the JSON output path in tools() command to include read_only, writes, checkpoint for all tool types (use null where not available)
Rename source_skill → from_skill in JSON output, using null for direct tools
Remove is_direct and is_inline fields from JSON output
Tests (Behave): Add/update scenarios covering JSON output for builtin, mcp, agent_skill, and inline tool types
Tests (Behave): Add scenario asserting from_skill is null for direct tools and populated for inherited tools
Tests (Robot): Add/update integration test for agents skill tools --format json capability field presence
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(cli): include read_only, writes, checkpoint fields for all tool types in skill tools JSON output), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/skill-tools-json-capability-fields).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage ≥ 97%.

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

## Metadata - **Branch**: `fix/skill-tools-json-capability-fields` - **Commit Message**: `fix(cli): include read_only, writes, checkpoint fields for all tool types in skill tools JSON output` - **Milestone**: v3.7.0 - **Parent Epic**: #936 ## Background and Context The `agents skill tools <NAME> --format json` command is part of the skill composition and management feature area. Per the specification (§agents skill tools JSON output), every tool entry in the JSON output must include capability metadata fields: `read_only`, `writes`, and `checkpoint`. These fields are defined as part of the core Tool architecture — tools are atomic units of execution that carry capability metadata alongside their name and source information. Currently, the JSON output path in `src/cleveragents/cli/commands/skill.py` only populates these fields for inline (anonymous) tools via the rich output path (`_print_skill_tools`). For all other tool types — `builtin`, `mcp`, and `agent_skill` — these fields are entirely absent from the JSON output. Additionally, the field naming in the implementation (`source_skill`, `is_direct`, `is_inline`) does not match the spec (`from_skill` with `null` for direct tools). ## Current Behavior When running `agents skill tools local/test-skill --format json` with a skill containing builtin tool references, the JSON output omits `read_only`, `writes`, and `checkpoint` for non-inline tools: ```json { "data": { "tools": [ { "name": "read_file", "source_skill": "local/test-skill", "source": "builtin", "is_direct": true, "is_inline": false } ] } } ``` **Steps to Reproduce:** 1. Register a skill with builtin tool references: ```yaml name: local/test-skill description: Test skill tools: - name: builtin/read_file ``` 2. Run `agents skill tools local/test-skill --format json` 3. Observe that `read_only`, `writes`, and `checkpoint` are absent from the output. **Code Location:** `src/cleveragents/cli/commands/skill.py`, `tools()` command, non-rich output section: ```python data.append( { "name": entry.name, "source_skill": entry.source_skill, "source": source_type, "is_direct": entry.source_skill == skill.name, "is_inline": entry.is_inline, # BUG: read_only, writes, checkpoint are missing for non-inline tools } ) ``` **Root Cause:** The JSON output path does not populate capability metadata for non-inline tools. The `ResolvedToolEntry` for non-inline tools doesn't carry capability information from the Tool Registry, but the output must still include these fields (with `null` for unknown/non-inline tools). Additionally, the field names diverge from the spec. ## Expected Behavior Per the specification (§agents skill tools JSON output), every tool entry must include `read_only`, `writes`, and `checkpoint`, and the parent skill reference must use `from_skill` (with `null` for direct tools): ```json { "data": { "tools": [ { "name": "read_file", "source": "builtin", "from_skill": null, "read_only": true, "writes": false, "checkpoint": null }, { "name": "write_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" } ] } } ``` ## Acceptance Criteria - `agents skill tools <NAME> --format json` includes `read_only`, `writes`, and `checkpoint` for **all** tool types (`builtin`, `mcp`, `agent_skill`, and inline). - For tool types where capability metadata is not available, these fields are present with `null` values (not absent). - The JSON output uses `from_skill` (with `null` for direct/own-skill tools) instead of `source_skill` + `is_direct`. - The `is_direct` and `is_inline` fields are removed from the JSON output (not in spec). - All existing and new Behave scenarios for `skill tools --format json` pass. - All nox sessions pass (`nox`). - Coverage remains ≥ 97%. ## Supporting Information - **Spec Reference**: §agents skill tools JSON output - **Severity**: High — JSON consumers relying on capability metadata will silently receive incomplete data. - **Feature Area**: Skill composition and management - **Affected Tool Types**: `builtin`, `mcp`, `agent_skill` (inline tools are partially handled but also need verification) - **Related Epic**: #936 (Epic: Output Rendering Pipeline Integration) ## Subtasks - [ ] Audit `ResolvedToolEntry` to determine which tool types carry capability metadata and which do not - [ ] Update the JSON output path in `tools()` command to include `read_only`, `writes`, `checkpoint` for all tool types (use `null` where not available) - [ ] Rename `source_skill` → `from_skill` in JSON output, using `null` for direct tools - [ ] Remove `is_direct` and `is_inline` fields from JSON output - [ ] Tests (Behave): Add/update scenarios covering JSON output for `builtin`, `mcp`, `agent_skill`, and inline tool types - [ ] Tests (Behave): Add scenario asserting `from_skill` is `null` for direct tools and populated for inherited tools - [ ] Tests (Robot): Add/update integration test for `agents skill tools --format json` capability field presence - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(cli): include read_only, writes, checkpoint fields for all tool types in skill tools JSON output`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/skill-tools-json-capability-fields`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 03:47:48 +00:00

freemo added a new dependency

2026-04-03 03:49:01 +00:00

#936 Epic: Output Rendering Pipeline Integration — Wire Commands to OutputSession Framework

freemo referenced this issue

2026-04-03 03:51:15 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 691 — v3.7.0 #2079

freemo referenced this issue

2026-04-03 03:57:57 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue