Skip to content

feat(subagents): accept @server.tool / server.tool / bare id in subagent tools[]#120

Merged
Minitour merged 1 commit into
mainfrom
feat/subagent-tool-ref-forms
Jun 16, 2026
Merged

feat(subagents): accept @server.tool / server.tool / bare id in subagent tools[]#120
Minitour merged 1 commit into
mainfrom
feat/subagent-tool-ref-forms

Conversation

@Minitour

Copy link
Copy Markdown
Contributor

Summary

Follow-up to #118 and #119.

Until now subagents[].tools required the bare local tool id, while skills[].def.requires used the @-prefixed qualified form:

# skills.requires — qualified, with @
requires:
  - '@dbx.sql_read_only'

# subagents.tools — bare local id only
tools:
  - sql_read_only

Users who learned requires first wrote @dbx.sql_read_only under a subagent, hit the new unknown-tool warning from #119, and concluded capa is broken — when in fact they'd just used the wrong dialect. The warning made the asymmetry more visible, not less.

This PR adds a resolver that accepts all three equivalent forms for the same tool and routes the three consumers through it:

subagents:
  - id: data-analyst
    tools:
      - sql_read_only           # bare local id (existing form)
      - dbx.sql_read_only       # qualified
      - '@dbx.sql_read_only'    # @-prefixed (requires-style)

All three resolve to the same Tool. Pick whichever reads best in context.

Changes

  • src/types/capabilities.ts — new resolveSubagentToolRef(ref, tools) next to getQualifiedToolName. Tries qualified-name match first (handles @server.tool / server.tool / ungrouped command tools), then falls back to bare-id match.
  • src/server/mcp-handler.ts:260 — filtered MCP endpoint uses the resolver instead of tools.find(t => t.id === toolId), so subagents with @-prefixed refs can actually call their tools.
  • src/shared/providers/handlers.ts (resolveTool) — renderer uses the resolver so all three input forms produce the same canonical <group>.<tool> bullet.
  • src/cli/commands/install-tasks/helpers/tool-warnings.ts (collectSubagentRefWarnings) — validator uses the resolver and the warning copy now lists the three accepted forms.
  • skills/capabilities-manager/references/capabilities-schema.md — documents all three forms with examples and notes the install-time validation.

Tests

  • src/types/__tests__/resolveSubagentToolRef.test.ts (new) — 7 cases covering MCP tool, grouped/ungrouped command tools, and unresolved refs in all three input shapes.
  • src/cli/commands/install-tasks/helpers/__tests__/tool-warnings.test.ts — new cases: mixed-form happy path produces no warnings; @-prefixed ref that doesn't resolve still warns with the original ref intact.

Test plan

  • bun test — 1095/1095 pass (8 new)
  • Built the binary and verified end-to-end against a real project: sql_read_only, dbx.poll_sql_result, and @dbx.sql all rendered the same canonical bullet; only an unresolvable @dbx.does_not_exist produced a warning
  • Reviewer: skim the schema doc wording in capabilities-manager — that's the surface external users learn from

…ent tools[]

Until now subagents[].tools required a bare local tool id, while skills'
requires[] used the @-prefixed qualified form. Users who learned `requires`
syntax first would write `@dbx.sql_read_only` under a subagent, hit the new
unknown-tool warning, and conclude capa is broken.

Add `resolveSubagentToolRef(ref, tools)` that accepts all three equivalent
forms — `@server.tool`, `server.tool`, and `tool_id` — and route the three
consumers through it:

  - MCP handler filtered endpoint (mcp-handler.ts)
  - Subagent file renderer (handlers.ts resolveTool)
  - Install-time validator (collectSubagentRefWarnings)

Update the capabilities-manager skill's schema reference to document all
three forms and the new validation. New unit tests cover the resolver and
the mixed-form path through the warning collector.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@Minitour Minitour merged commit 31a1178 into main Jun 16, 2026
13 of 16 checks passed
@Minitour Minitour deleted the feat/subagent-tool-ref-forms branch June 16, 2026 19:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant