Subagents
Peregrine spawns sub-agents as independent threads to handle specialized or parallel work. Each sub-agent maintains its own conversation history and state while inheriting the parent’s model, sandbox, approval policy, and working directory.
Invoke sub-agents through tool calls. The parent agent delegates tasks, waits for results, and integrates findings.
Prerequisites
Install bubblewrap on Linux and WSL2 when you run long tasks inside sub-agents.
Enable features.multi_agent_v2 in config.toml when you require the full collaboration tool surface.
How sub-agents work
Peregrine treats every spawned agent as a separate thread with a unique ID.
Reference sub-agents by ID or nickname when you send input or wait for completion.
Sub-agents respect the same permission profiles as the parent unless the role overrides them.
Peregrine enforces a spawn depth limit. You reach the limit when nested spawns exceed the configured maximum.
Audit agents
Peregrine uses an orchestrator for each autonomous security audit. The orchestrator drives the entire audit process. It manages the stages of the audit and spawns specialist sub-agents to handle distinct parts of the work.
The orchestrator is the central agent that coordinates everything. It decides when to bring in specialists, supplies them with the right context, waits for their contributions, and uses their outputs to advance the audit.
When you launch an audit, Peregrine starts the orchestrator in a dedicated thread.
The orchestrator
The orchestrator alone controls the high-level flow of the audit. It never hands off overall responsibility to the specialists.
It works through these phases:
- It identifies the next piece of work that needs to be done.
- When a piece of work requires specialized analysis, it brings in the appropriate sub-agent.
- It provides the sub-agent with focused context from the audit so far.
- It waits for the sub-agent to complete its task.
- It incorporates the sub-agent’s findings before moving to the next step.
- It sequences the specialists in a deliberate order so that discovery, proof, challenge, and validation all occur.
- It ensures that the final audit results are based on contributions from multiple perspectives.
The orchestrator keeps a record of its progress so you can follow the audit as it unfolds.
Audit Agent Interaction Flow
The following diagram shows how the orchestrator interacts with specialist sub-agents during an audit:
Specialist audit sub-agents
The four specialist roles exist only as sub-agents that the orchestrator brings in as needed. You do not run them directly as the main agent for an audit.
These specialists each play a focused part in building a reliable audit result. The orchestrator calls on them at the right moments in the process.
Researcher
Bring in the researcher for discovery work.
The researcher examines the target, maps out possible areas of concern, identifies key security properties that should hold, and develops initial ideas about where problems might exist.
The researcher focuses on exploration and forming ideas. It does not treat its ideas as proven issues.
The orchestrator typically involves the researcher early, when the audit needs to understand the system and surface potential problems.
Exploiter
Bring in the exploiter to develop concrete demonstrations.
The exploiter takes promising ideas from discovery and turns them into practical tests or demonstrations. This includes creating plans, test cases, or other ways to check whether a problem actually exists.
The exploiter works inside controlled areas set aside for the audit. It does not change the original code under review.
The orchestrator calls on the exploiter once there are ideas worth testing.
Skeptic
Bring in the skeptic for critical challenge.
The skeptic reviews the work done so far and looks for weaknesses. It questions whether ideas are well supported, points out missing pieces, and helps weed out claims that do not hold up.
The skeptic acts as a check on over-optimism or incomplete reasoning.
The orchestrator often uses the skeptic alongside or right after the exploiter to strengthen the overall result.
Judge
Bring in the judge for final validation.
The judge reviews the evidence gathered by the other specialists. It determines which ideas stand up after testing and challenge.
The judge only accepts a finding when there is solid support from more than one line of checking, including actual demonstrations.
The judge receives only the cleaned-up evidence and conclusions. It does not see internal thinking from the other agents.
The orchestrator brings in the judge toward the end of a stage so that conclusions can be properly confirmed before the audit moves forward.
The orchestrator makes sure the specialists contribute in order and that their outputs are combined before any part of the audit is considered complete.
Generic sub-agents
Peregrine also supports generic sub-agents that you can use for collaboration and parallel work outside of formal audit processes.
General collaborator
Direct Peregrine to spawn a general sub-agent to help with part of a task. The sub-agent works with its own focus while staying connected to the main conversation.
Worker
Use a worker sub-agent when you want to break a larger task into independent pieces that can run at the same time.
Workers are given clear areas of responsibility. They must account for changes made by other agents and avoid undoing each other’s work.
Typically use workers when a task naturally splits into separate modules or steps.
Explorer
Use an explorer sub-agent when you need open-ended investigation or reconnaissance.
The explorer follows a systematic approach to exploring code or behavior without being tied to a fixed checklist.
Bring in an explorer when you want broad understanding before focusing on specific problems.
Invoking sub-agents
Ask the main agent to spawn a sub-agent whenever a task would benefit from dedicated focus or parallel effort.
In an audit, the orchestrator automatically decides when to spawn specialist sub-agents and manages their involvement as part of the overall flow. The specialists only ever run as sub-agents under the orchestrator.
Peregrine keeps sub-agents connected to the main thread so their results flow back into the larger audit or task.
Managing sub-agents
Communicate with a running sub-agent, wait for it to finish, or end it early if needed.
Peregrine keeps you informed about the status of active sub-agents.
When a sub-agent completes its work, its results are brought back into the main conversation or audit record.
Limits and behavior
Peregrine limits how deeply sub-agents can be nested to keep the process manageable.
Sub-agents inherit the main session’s model, permissions, and environment settings. Specialized roles receive additional guidance on top of those settings.
Sub-agents are always aware that they are working as part of a larger effort.
Follow the creation and activity of sub-agents through the main interface and logs.