Sub Agents

Sub-Agents - External CLI AI Task Delegation

Spawns external CLI AIs (codex, claude, cursor-agent, glm, kimi, grok, antigravity, gemini, opencode, command-code, mcode, pi) as isolated sub-agents with dedicated context.

Workflow: discover available definitions, select one from the user request, execute it, and handle the JSON response.

Resources

• run_subagent.py - Main execution script
• codex.md - Read before first execution from Codex; covers permissions and timeout

Script Path: Use absolute path {SKILL_DIR}/scripts/run_subagent.py where {SKILL_DIR} is the directory containing this SKILL.md file.

Interpreting User Requests

Extract parameters from user's natural language request:

Example: "Run code-reviewer on src/" → --agent code-reviewer --prompt "Review src/" --cwd $(pwd)

Important: Permission and Timeout

This script executes external CLIs that require elevated permissions.

Before first execution:

1. Request elevated permissions via your CLI's tool parameters
2. Set tool timeout to match --timeout argument (default: 600000ms)

For Codex CLI (most common permission issues): See references/codex.md for exact JSON parameter format.

Workflow

Step 1: List Available Agents

Always list agents first to discover available definitions:

bashCopy code
{SKILL_DIR}/scripts/run_subagent.py --list

Output:

jsonCopy code
{"agents": [{"name": "code-reviewer", "description": "Reviews code..."}], "agents_dir": "/path/.agents"}

When the user provides an agent name, select it if it appears in the result. If it is absent, report the available definitions and wait for a selection. When the result is empty, provide the Agent Definition Format below and wait for the user to add a definition.

When the user leaves the agent selection open:

Step 2: Execute Agent

bashCopy code
{SKILL_DIR}/scripts/run_subagent.py \
  --agent <name> \
  --prompt "<task>" \
  --cwd <absolute-path>

Append --cli <backend> when the user specifies a backend. Append --timeout <milliseconds> when the user specifies a timeout.

Step 3: Handle Response

Parse JSON output and check status field:

jsonCopy code
{"result": "...", "exit_code": 0, "status": "success", "cli": "claude"}

By status:

For configuration or credential errors, retry after the required external configuration has changed.

If execution fails because run-agent is missing, retry with --cli set to the current client's backend.

By exit_code (when status is error):

Agent Definition Location

To customize: export SUB_AGENTS_DIR=/custom/path

Agent Definition Format

Place .md files in .agents/ directory:

markdownCopy code
---
run-agent: claude
model: sonnet
permission: safe-edit
---

# Agent Name

Brief description of agent's purpose.

## Task
What this agent does.

## Output Format
How results should be structured.

run-agent supplies the backend. Pass --cli only as an explicit one-run override; execution fails with a corrective error when neither is specified.

Frontmatter fields:

Backend-specific permission behavior:

• mcode: read-only and safe-edit both use --permission smart, which allows direct edits. A tool call that smart denies leaves the run going, so the run can still return success. yolo uses --permission full.
• pi: read-only enables only read, grep, find, and ls, so the agent has no shell or MCP tools. safe-edit and yolo both enable Pi's default tools, including bash, edit, and write.