/ 
Claude-Agent-0.12
/ Claude::Agent::Subagent

NAME

Claude::Agent::Subagent - Subagent definitions for Claude Agent SDK

SYNOPSIS

use Claude::Agent::Subagent;
use Claude::Agent::Options;

my $options = Claude::Agent::Options->new(
    allowed_tools => ['Read', 'Glob', 'Grep', 'Task'],
    agents => {
        'code-reviewer' => Claude::Agent::Subagent->new(
            description => 'Expert code review specialist. Use for quality, security, and maintainability reviews.',
            prompt      => 'You are a code review specialist with expertise in security, performance, and best practices.',
            tools       => ['Read', 'Glob', 'Grep'],
            model       => 'sonnet',
        ),
        'test-runner' => Claude::Agent::Subagent->new(
            description => 'Runs and analyzes test suites. Use for test execution and coverage analysis.',
            prompt      => 'You are a test execution specialist.',
            tools       => ['Bash', 'Read', 'Grep'],
        ),
    },
);

DESCRIPTION

Subagents are separate agent instances that your main agent can spawn to handle focused subtasks. Use subagents to:

  • Isolate context for focused subtasks

  • Run multiple analyses in parallel

  • Apply specialized instructions without bloating the main prompt

  • Restrict tool access for safety

HOW IT WORKS

When you define subagents and include 'Task' in allowed_tools, Claude can invoke subagents via the Task tool. Claude decides which subagent to use based on the description field, or you can explicitly request one by name in your prompt.

ATTRIBUTES

description

Natural language description of when to use this agent. Claude uses this to decide when to delegate tasks to the subagent. Write clear, specific descriptions so Claude can match tasks appropriately.

prompt

The agent's system prompt defining its role and behavior. This is the context and instructions the subagent receives.

tools

ArrayRef of allowed tool names. If omitted, the subagent inherits all tools from the parent (except Task - subagents cannot spawn their own subagents).

Common tool combinations:

  • Read-only analysis: ['Read', 'Grep', 'Glob']

  • Test execution: ['Bash', 'Read', 'Grep']

  • Code modification: ['Read', 'Edit', 'Write', 'Grep', 'Glob']

model

Model override for this agent. Options:

  • 'sonnet' - Use Claude Sonnet

  • 'opus' - Use Claude Opus

  • 'haiku' - Use Claude Haiku

  • 'inherit' - Use the same model as parent (default)

METHODS

to_hash

my $hash = $subagent->to_hash;

Convert to a hashref for passing to the SDK.

EXAMPLES

Security Review Agent

Claude::Agent::Subagent->new(
    description => 'Security code reviewer for vulnerability analysis',
    prompt      => <<'PROMPT',
You are a security specialist. When reviewing code:
- Identify security vulnerabilities (OWASP Top 10)
- Check for injection risks
- Verify input validation
- Look for authentication/authorization issues
Be thorough but concise in your feedback.
PROMPT
    tools => ['Read', 'Grep', 'Glob'],
    model => 'opus',  # Use stronger model for security
);

Documentation Generator

Claude::Agent::Subagent->new(
    description => 'Documentation specialist for generating API docs',
    prompt      => 'Generate clear, comprehensive API documentation.',
    tools       => ['Read', 'Glob'],
);

AUTHOR

LNATION, <email at lnation.org>

LICENSE

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under The Artistic License 2.0 (GPL Compatible).