Agent Configuration

Every Weave agent can be individually configured with an agent block in your .weave config. You can override the model list, adjust temperature, inject skills, append to the prompt, set tool policies, and add delegation triggers.

Configuration Fields

Field	Type	Description
description	string	Human-readable label shown in harness UI
prompt	string	Inline prompt text. Mutually exclusive with prompt_file.
prompt_file	string	Path to a .md file, resolved relative to the config scope's prompts/ directory. Mutually exclusive with prompt.
prompt_append	string	Inline text appended after the primary prompt. Mutually exclusive with prompt_append_file.
prompt_append_file	string	Path to a .md file appended after the primary prompt. Mutually exclusive with prompt_append.
models	string[]	Ordered model preference list. Adapters translate to concrete harness model fields.
review_models	string[]	Optional. One or more model identifiers used as independent reviewers in gate workflow steps. See Review Models.
temperature	number	Sampling temperature hint passed to adapters.
mode	primary | subagent | all	Adapter-facing context hint. See Agent Mode.
tool_policy	block	Abstract capability map. See Tool Policy.
triggers	array	Delegation metadata for router agents.
skills	string[]	Skill names to load for this agent.

prompt vs. prompt_append

prompt completely replaces the agent's built-in prompt and the agent's core behavior is gone. Use prompt_append instead unless you have a strong reason to take full control. See Prompt Append.

Agent Mode

The mode field is a hint to adapters about how an agent should appear in a harness:

Mode	Meaning
primary	Main or user-facing agent. Adapters typically show it in the main agent selector.
subagent	Delegated specialist. Adapters typically hide it from the direct selector.
all	Usable in both contexts.

Built-in defaults: Loom and Tapestry are primary. Shuttle is all. Pattern, Thread, Spindle, Weft, and Warp are subagent.

TIP

For custom agents, mode defaults to subagent. Set mode all or mode primary if you want the agent to appear in the main selector.

Tool Policy

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
}

Capability	Values	Meaning
read	allow | deny | ask	File/resource read access
write	allow | deny | ask	File/resource write access
execute	allow | deny | ask	Process/command execution
delegate	allow | deny | ask	Spawning subagents
network	allow | deny | ask	Network/HTTP access

Available Agents

Name	Role
loom	Main orchestrator. The primary user-facing interface that understands requests, routes work, and coordinates results
tapestry	Plan execution coordinator. Delegates plan tasks to Shuttle, verifies results, and tracks progress
shuttle	Domain specialist worker. Handles delegated implementation and analysis tasks
pattern	Strategic planner. Produces .weave/plans/ files
thread	Codebase explorer. Fast, read-only analysis and search
spindle	External researcher. Web fetching and research
weft	Quality reviewer and auditor
warp	Security auditor

Examples

Set models and temperature per agent:

agent loom {
  models ["anthropic/claude-opus-4"]
  temperature 0.1
}

agent thread {
  models ["anthropic/claude-3-haiku"]
  temperature 0.0
}

Inject skills and append instructions:

agent shuttle {
  skills ["company-standards", "testing"]
  prompt_append "Always run `npm test` before marking any task complete."
}

agent pattern {
  skills ["planning-guidelines"]
  prompt_append "Every plan must have at least 3 acceptance criteria per task."
}

Set tool policy:

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

Disable an agent:

disable agents ["warp"]

Add delegation triggers:

agent my-helper {
  prompt "You are a documentation specialist."
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  temperature 0.2

  triggers [
    { domain "Documentation" trigger "README updates, API docs, user guides" }
  ]
}

Review Models

review_models lets an agent recruit additional models as independent reviewers in a workflow gate step. When a gate step with completion review_verdict runs and the assigned agent has review_models set, the engine fans out the review prompt to every model in the list, then collates the results into a single approve-or-reject verdict.

agent warp {
  models ["anthropic/claude-opus-4"]
  review_models ["openai/gpt-5", "anthropic/claude-sonnet-4-5"]
}

This is useful when you want multiple independent perspectives on a security audit or code review before the workflow advances.

How it works:

• Each entry in review_models runs as a read-only subagent variant named {agentName}-review-{sanitizedModel} (e.g. warp-review-openai-gpt-5). Non-identifier characters such as / are replaced with -.
• Variant agents inherit the base agent's prompt and read permission, but write, execute, delegate, and network are all set to deny.
• If at least one variant succeeds, the collated result is returned and any failures are recorded as warnings.
• If every variant fails, the step resolves as a rejection with a typed error listing each failure.

Cost note: review_models triggers additional model invocations per gate step. The built-in agents (warp, weft, and others) intentionally omit review_models by default. Add it explicitly when the extra coverage is worth the cost.

# Enable multi-model review for security gates
agent warp {
  review_models ["openai/gpt-5"]
}

This override merges with the built-in warp declaration; all other fields are preserved.

models vs. review_models

models is the preference list for the agent's own execution. review_models is a separate, optional list that only applies during gate steps with completion review_verdict. The two fields are independent and may coexist.

Custom Agents the built-in agents, you can define entirely new agents with the same agent block syntax. Custom agents support all the same fields as built-in agents.

agent docs-writer {
  description "Technical 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 "README updates, API docs, user guides, changelog entries" }
  ]
}

Custom agents appear alongside built-ins in the delegation table. They appear in the selector only if mode is primary or all.

Full Guide

See Custom Agents for the complete reference, including naming rules, prompt sources, and practical examples.