Agents are the core execution units in Weave. Each agent is a specialized AI worker with a defined role, tool permissions, and behavioral constraints. Weave ships with 8 builtin agents that form a complete multi-agent system for software development.

An agent is a named configuration block that declares:

• Role and behavior via a prompt (inline or file-based)
• Model preferences as an ordered list
• Tool permissions via an abstract capability policy
• Delegation targets when the agent can spawn subagents
• Specialization triggers that help routers decide when to use this agent

Agents are declared in .weave config files and composed by the engine before being materialized by adapters into concrete harness sessions.

Weave uses a coordinator-specialist pattern:

1. Loom (main orchestrator) receives user requests and decides whether to handle them directly or delegate to specialists
2. Tapestry (plan executor) coordinates multi-step plans by delegating tasks to domain specialists
3. Specialists (Shuttle, Pattern, Thread, Spindle, Weft, Warp) execute bounded work and report results back

Delegation is explicit and controlled by tool policy. Agents with delegate: allow can spawn subagents. Leaf workers like Shuttle have delegate: deny and cannot spawn further agents.

User Request
    ↓
  Loom (orchestrator)
    ↓
  ┌─────────────┬─────────────┬─────────────┐
  ↓             ↓             ↓             ↓
Shuttle      Pattern      Thread       Spindle
(implement)  (plan)       (explore)    (research)
    ↓
  Tapestry (execute plan)
    ↓
  Shuttle (implement tasks)
    ↓
  Weft/Warp (review)

Role: Conversational router and coordinator. Handles user requests, decides whether to answer directly or delegate to specialists, and summarizes results.

Mode: primary
Temperature: 0.1
Delegation: allow

Tool Policy:

• Read: allow
• Write: allow
• Execute: allow
• Network: ask
• Delegate: allow

When to use: Loom is the default entry point for all user interactions. It routes work to specialists based on complexity and domain.

Role: Drives structured implementation plans to completion by sequencing steps, delegating to specialists, and tracking progress. Does not implement anything itself.

Mode: primary
Temperature: 0.1
Delegation: allow

Tool Policy:

• Read: allow
• Write: allow
• Execute: allow
• Network: deny
• Delegate: allow

When to use: Tapestry executes plans created by Pattern. It reads the plan file, delegates each task to the appropriate specialist, verifies results, and marks tasks complete.

Role: Leaf worker that executes bounded implementation tasks. Receives structured task envelopes from coordinators and completes them without further delegation.

Mode: subagent
Temperature: 0.2
Delegation: deny

Tool Policy:

• Read: allow
• Write: allow
• Execute: allow
• Network: deny
• Delegate: deny

Triggers:

• Implementation: Bounded coding tasks, file edits, feature work
• Testing: Writing and running tests
• Debugging: Diagnosing and fixing bugs in a specific area
• Refactoring: Improving code structure without changing behavior

When to use: For single-file changes, bug fixes, or clearly scoped implementation tasks.

Role: Analyzes requirements, researches the codebase, and produces detailed implementation plans. Never implements, only plans.

Mode: subagent
Temperature: 0.3
Delegation: deny

Tool Policy:

• Read: allow
• Write: allow (plan files only)
• Execute: deny
• Network: deny
• Delegate: deny

Triggers:

• Planning: Creating structured implementation plans before execution
• Architecture: Designing system structure, component boundaries, and data flow
• Decomposition: Breaking complex goals into discrete, sequenced tasks

When to use: For multi-file features, complex refactors, or work spanning 5+ steps.

Role: Read-only codebase navigator. Traces symbols, call graphs, and data flow. Produces structured reports for other agents.

Mode: subagent
Temperature: 0.0
Delegation: deny

Tool Policy:

• Read: allow
• Write: deny
• Execute: deny
• Network: deny
• Delegate: deny

Triggers:

• Exploration: Tracing symbols, call graphs, and data flow across the codebase
• Discovery: Locating where a concept, pattern, or behavior is implemented
• Audit: Surveying existing code before planning a change

When to use: For fast codebase exploration before routing to implementation agents. Read-only and cheap.

Role: Fetches and synthesizes external documentation, API references, library guides, and standards. Read-only.

Mode: subagent
Temperature: 0.1
Delegation: deny

Tool Policy:

• Read: allow
• Write: deny
• Execute: deny
• Network: allow
• Delegate: deny

Triggers:

• Research: Fetching external documentation, API references, or library guides
• Verification: Confirming facts, versions, or behaviors against authoritative sources
• Discovery: Finding relevant third-party tools, packages, or standards

When to use: When facts need verification against official sources or when exploring external options.

Role: Critical, skeptical code reviewer. Read-only. Returns strict merge verdicts (APPROVE or REJECT).

Mode: subagent
Temperature: 0.1
Delegation: deny

Tool Policy:

• Read: allow
• Write: deny
• Execute: deny
• Network: deny
• Delegate: deny

Triggers:

• Code Review: Reviewing code quality, correctness, and maintainability
• Gate: Approving or requesting changes before a task is considered complete
• Feedback: Providing structured critique on a plan, design, or implementation

When to use: After non-trivial changes (3+ files, or when quality matters) as a quality gate.

Role: Security and specification compliance auditor. Read-only. Returns structured verdicts (APPROVE or BLOCK). Skeptical by default.

Mode: subagent
Temperature: 0.1
Delegation: deny

Tool Policy:

• Read: allow
• Write: deny
• Execute: deny
• Network: deny
• Delegate: deny

Triggers:

• Security: Auditing code for vulnerabilities, misconfigurations, or unsafe patterns
• Gate: Security approval checkpoint before shipping or merging
• Threat Modeling: Identifying attack surfaces and risk areas in a design or implementation

When to use: MANDATORY when changes touch auth, crypto, tokens, secrets, sessions, CORS, CSP, or input validation.

The tool_policy block declares abstract capabilities. Adapters map these to harness-specific tool names and permission models.

tool_policy {
  read    allow
  write   allow
  execute allow
  delegate deny
  network ask
}

See Tool Policy for the full evaluation semantics and adapter mapping rules.

The routing block provides per-agent control over delegation behavior.

agent loom {
  routing {
    delegation_exclude ["spindle", "warp"]
  }
}

This is useful when you want to prevent specific agents from being offered as delegation targets to a particular coordinator, without globally disabling those agents.

You can override any builtin agent by declaring an agent with the same name in your project or global config. The override is a deep merge: you only need to specify the fields you want to change.

Example: Change Shuttle’s model and temperature

agent shuttle {
  models ["openai/gpt-4o"]
  temperature 0.3
}

This overrides only the models and temperature fields. All other fields (prompt, tool policy, triggers) remain unchanged from the builtin definition.

Example: Add a custom prompt append to Loom

agent loom {
  prompt_append """
  ## Project-Specific Rules
  - Always use the project's error-handling pattern from `src/errors.ts`
  - Never use `any` types; prefer `unknown` and type guards
  """
}

This appends project-specific guidance to Loom’s builtin prompt without replacing the entire prompt.

You can define custom agents for project-specific workflows or specialized domains.

Example: Custom documentation agent

agent docs-writer {
  description "Documentation Specialist"
  prompt_file "docs-writer.md"
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  temperature 0.2

  tool_policy {
    read allow
    write allow
    execute deny
    delegate deny
    network deny
  }

  triggers [
    { domain "Documentation" trigger "Writing or updating user-facing documentation" routing_hint "Use for README, guides, and API docs" }
    { domain "Examples" trigger "Creating code examples and tutorials" routing_hint "Use when examples need to be written or updated" }
  ]
}

The prompt file lives at .weave/prompts/docs-writer.md (project scope) or ~/.weave/prompts/docs-writer.md (global scope).

Example: Custom agent with inline prompt

agent sql-reviewer {
  description "SQL Query Reviewer"
  prompt """
  You are a SQL query reviewer. Review SQL queries for:
  - Injection vulnerabilities
  - Missing indexes on WHERE/JOIN columns
  - N+1 query patterns
  - Overly broad SELECT * usage

  Return APPROVE or REJECT with specific line-level feedback.
  """
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  temperature 0.1

  tool_policy {
    read allow
    write deny
    execute deny
    delegate deny
    network deny
  }
}

Custom agents can be invoked by Loom or Tapestry when their triggers match the work being routed.

The delegation flow determines who can delegate to whom:

1. Loom can delegate to any subagent (Tapestry, Shuttle, Pattern, Thread, Spindle, Weft, Warp)
2. Tapestry can delegate to any subagent (Shuttle, Pattern, Thread, Spindle, Weft, Warp)
3. Subagents (Shuttle, Pattern, Thread, Spindle, Weft, Warp) cannot delegate further (leaf workers)

This hierarchy prevents infinite delegation loops and keeps execution bounded.

Delegation filtering rules:

• An agent cannot delegate to itself
• Disabled agents are excluded from delegation targets
• mode: primary agents are not treated as delegation targets
• Shuttle agents do not advertise other shuttle agents as delegation targets

The review_models field allows you to nominate alternative models as independent reviewer variants. Each nominated model is materialized as a first-class agent descriptor (named {agent}-{model}, with / replaced by -) whenever config is loaded.

Example: Multi-model security review

agent warp {
  description "Warp (Security Reviewer)"
  prompt_file "warp.md"
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent

  review_models ["openai/gpt-4o", "anthropic/claude-opus-4-5"]
}

This generates three agent descriptors:

• warp (base reviewer, uses claude-sonnet-4-5)
• warp-openai-gpt-4o (variant, uses gpt-4o)
• warp-anthropic-claude-opus-4-5 (variant, uses claude-opus-4-5)

Loom and Tapestry prompts route review requests to the base reviewer plus all generated variants. All reviewers run in parallel, and their findings are collated into a unified verdict.

Key behaviors:

• Partial failures (some variants fail) are logged as warnings; the step still completes from successful variants
• All variants failing causes the step to fail
• Builtin agents omit review_models by default to avoid unexpected cost; users opt in explicitly

• DSL Configuration - Full .weave syntax reference
• Prompt Composition - How agent prompts are composed
• Tool Policy - Tool permission evaluation rules
• Workflows - Multi-step execution pipelines
• Categories - Domain-scoped shuttle agents