#agents/ Role Directory

agents/ stores worker/subagent definitions. A3S Code scans ~/.claude/agents, ~/.a3s/agents, <workspace>/.claude/agents, and <workspace>/.a3s/agents automatically, in that order. ACL agent_dirs load before these, and session agentDirs and workerAgents load after them; a later definition with the same name replaces an earlier one. Prefer .a3s/agents/ for new projects; .claude/agents/ is read for compatibility. Directories are scanned recursively for .md, .yaml, and .yml files, and symlinks that resolve outside the directory are skipped.

repo/
└── .a3s/
    └── agents/
        ├── explorer.md
        ├── security-reviewer.md
        └── verification-runner.md

These files are worker definitions. They are invoked by the model-visible task tool, the session.task(...) and session.tasks(...) host helpers, or autoDelegation. The parent session still owns final synthesis, verification, and permission boundaries.

#Agent File

---
name: security-reviewer
description: Use for permission, secret, and external side-effect review
tools: Read, Search, Bash(rg *)
disallowedTools:
  - Write
  - Bash(git push *)
---

Review security risks first. Return blockers, evidence paths, and required verification.

name is the call name. description drives automatic routing. The body describes the worker role. Tool fields narrow visible capabilities; do not rely on the worker merely promising not to do risky things.

• tools (also allowedTools or allowed_tools) becomes an allow-only permission policy for the child run.
• disallowedTools (also disallowed-tools or disallowed_tools) adds deny rules that win over the allowlist.
• Either field accepts a comma-separated string or a YAML list. When one is set, the child's confirmation inheritance defaults to auto_approve.
• A kind field (read_only, planner, implementer, verifier, reviewer, or custom) parses the file as a worker agent spec, the same shape accepted by workerAgents.

#Manual Delegation

const session = agent.session('/repo', {
  agentDirs: ['./.a3s/agents'],
  maxParallelTasks: 4,
});

await session.task({
  agent: 'security-reviewer',
  description: 'Review release side effects',
  prompt: 'Check changed auth, permission, and external API paths.',
});

Fixed flows are better as manual delegation or programmable orchestration. Automatic delegation fits goals where the parent agent should choose specialists.

#Automatic Delegation

const session = agent.session('/repo', {
  agentDirs: ['./.a3s/agents'],
  autoDelegation: { enabled: true, minConfidence: 0.72, maxTasks: 4 },
});

Automatic delegation scores the request locally against each agent's name and description; there is no model call in the routing step. Write descriptions that say when to use the agent, not just what the role is called. See Tasks for the scoring and fan-out limits.

#Practices

• Keep one role per file.
• Make descriptions useful for routing and bodies useful for execution.
• Ask workers to return evidence, risks, and next steps.
• Keep publish, delete, push, and other high-risk permissions out of default workers.
• Use workerAgents or registerWorkerAgent() for dynamic one-off workers.