UAT: `SkillToolRefSchema` missing `override.capability` sub-object — spec-required per-tool capability overrides in skill `tools:` list not supported #2497

New issue

Open

opened 2026-04-03 18:39:30 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 18:39:30 +00:00

Owner

Metadata

Branch: feat/skill-tool-ref-capability-override
Commit Message: feat(skills): add override.capability sub-object to SkillToolRefSchema for per-tool capability overrides
Milestone: v3.6.0
Parent Epic: #392

Summary

The specification defines an override: sub-object on tool references in a skill's tools: list that allows overriding capability metadata (including human_approval_required) for a specific tool in the context of that skill. SkillToolRefSchema only supports name, description, writes, and checkpointable — the structured override: capability: sub-object is not supported.

Expected Behavior (from spec)

The specification (docs/specification.md, Skill Configuration section) shows:

skill:
  name: local/devops-toolkit
  
  tools:
    - local/run-migrations                  # Simple reference
    - name: local/deploy-staging            # Reference with capability override
      override:
        capability:
          human_approval_required: true     # Require approval in this skill context

This allows a skill to include a tool while adding additional safety constraints (like requiring human approval) that are specific to this skill's context, without modifying the tool's global registration.

Actual Behavior

SkillToolRefSchema only supports flat capability flags:

class SkillToolRefSchema(BaseModel):
    name: str
    description: str | None
    writes: bool | None        # Flat override
    checkpointable: bool | None  # Flat override
    # ← No override.capability sub-object!

A skill YAML with override: capability: human_approval_required: true fails:

pydantic.ValidationError: 1 validation error for SkillToolRefSchema
override
  Extra inputs are not permitted [type=extra_forbidden]

Impact

Skills cannot add safety constraints (human approval, write scope restrictions) to individual tool references. This is important for security — a skill that includes a deployment tool should be able to require human approval without modifying the tool's global registration.

Code Locations

src/cleveragents/skills/schema.py — SkillToolRefSchema missing override field
src/cleveragents/domain/models/core/skill.py — SkillToolRef domain model only has name field

Subtasks

Add SkillToolCapabilityOverrideSchema model with human_approval_required, write_scope, etc.
Add SkillToolOverrideContainerSchema with capability: SkillToolCapabilityOverrideSchema
Add override: SkillToolOverrideContainerSchema | None field to SkillToolRefSchema
Update SkillToolRef domain model to carry override data
Update SkillResolver to apply capability overrides when resolving tool refs
Add Behave unit tests for tool refs with override: capability:

Definition of Done

Skill YAML with override: capability: human_approval_required: true on a tool ref parses correctly
SkillResolver applies capability overrides to the resolved tool entry
nox -e unit_tests passes

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `feat/skill-tool-ref-capability-override` - **Commit Message**: `feat(skills): add override.capability sub-object to SkillToolRefSchema for per-tool capability overrides` - **Milestone**: v3.6.0 - **Parent Epic**: #392 ## Summary The specification defines an `override:` sub-object on tool references in a skill's `tools:` list that allows overriding capability metadata (including `human_approval_required`) for a specific tool in the context of that skill. `SkillToolRefSchema` only supports `name`, `description`, `writes`, and `checkpointable` — the structured `override: capability:` sub-object is not supported. ## Expected Behavior (from spec) The specification (`docs/specification.md`, Skill Configuration section) shows: ```yaml skill: name: local/devops-toolkit tools: - local/run-migrations # Simple reference - name: local/deploy-staging # Reference with capability override override: capability: human_approval_required: true # Require approval in this skill context ``` This allows a skill to include a tool while adding additional safety constraints (like requiring human approval) that are specific to this skill's context, without modifying the tool's global registration. ## Actual Behavior `SkillToolRefSchema` only supports flat capability flags: ```python class SkillToolRefSchema(BaseModel): name: str description: str | None writes: bool | None # Flat override checkpointable: bool | None # Flat override # ← No override.capability sub-object! ``` A skill YAML with `override: capability: human_approval_required: true` fails: ``` pydantic.ValidationError: 1 validation error for SkillToolRefSchema override Extra inputs are not permitted [type=extra_forbidden] ``` ## Impact Skills cannot add safety constraints (human approval, write scope restrictions) to individual tool references. This is important for security — a skill that includes a deployment tool should be able to require human approval without modifying the tool's global registration. ## Code Locations - `src/cleveragents/skills/schema.py` — `SkillToolRefSchema` missing `override` field - `src/cleveragents/domain/models/core/skill.py` — `SkillToolRef` domain model only has `name` field ## Subtasks - [ ] Add `SkillToolCapabilityOverrideSchema` model with `human_approval_required`, `write_scope`, etc. - [ ] Add `SkillToolOverrideContainerSchema` with `capability: SkillToolCapabilityOverrideSchema` - [ ] Add `override: SkillToolOverrideContainerSchema | None` field to `SkillToolRefSchema` - [ ] Update `SkillToolRef` domain model to carry override data - [ ] Update `SkillResolver` to apply capability overrides when resolving tool refs - [ ] Add Behave unit tests for tool refs with `override: capability:` ## Definition of Done - Skill YAML with `override: capability: human_approval_required: true` on a tool ref parses correctly - `SkillResolver` applies capability overrides to the resolved tool entry - `nox -e unit_tests` passes --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo commented

2026-04-03 18:41:00 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have — Spec compliance or quality improvement that should be included in the milestone.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have — Spec compliance or quality improvement that should be included in the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 18:43:28 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1571 — v3.7.0 #2516

freemo commented

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

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have (already set)

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have (already set) Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.7.0 milestone

2026-04-05 05:07:07 +00:00

freemo removed this from the v3.7.0 milestone

2026-04-07 00:48:56 +00:00