Task Delegation

IMPORTANT

This feature is in beta and represents an initial implementation. The API and behavior may change or be removed in future releases.

Iris can delegate complex, multi-step tasks to an autonomous sub-agent. Instead of executing commands one at a time, the sub-agent works independently - handling errors, iterating on solutions, and returning results when the task is complete.

WARNING

Task delegation is disabled by default. It requires shell commands to also be enabled, as the sub-agent uses shell commands to accomplish tasks.

When to Use Task Delegation

Task delegation shines for complex operations that require multiple steps:

• Project scaffolding: "Set up a new Laravel project with authentication"
• Code refactoring: "Rename the User model to Account across the codebase"
• Build processes: "Run the full test suite and fix any failures"
• File migrations: "Reorganize the images folder by date"
• Complex installations: "Install and configure Tailwind CSS"

For quick, single commands, Iris uses the shell tool directly. Task delegation is for work that needs autonomous problem-solving.

Setup

Enable both task delegation and shell commands in your .env:

IRIS_SUBAGENT_ENABLED=true
IRIS_SHELL_ENABLED=true

Optionally set a default working directory:

IRIS_SUBAGENT_WORKING_DIR=/home/user/projects

Example Conversations

Project Setup

You: "Create a new Laravel project with Breeze authentication and Tailwind"

Iris: "I'll delegate this to a sub-agent. This involves several steps - creating the project, installing Breeze, running migrations, and building assets."

[sub-agent works autonomously for ~2 minutes]

Iris: "Done! Here's what I did:

• Created new Laravel project
• Installed Laravel Breeze with React
• Ran npm install and npm run build
• Ran migrations
• The app is ready at ~/projects/myapp"

Code Refactoring

You: "Rename all instances of 'getUserById' to 'findUser' in my project"

Iris: "I'll search for all occurrences and update them."

[sub-agent searches, identifies files, makes changes]

Iris: "Updated 12 files. I also updated the corresponding test files to use the new method name. Here's a summary of changes..."

Build and Fix

You: "Run the PHPStan analysis and fix any level 5 errors"

Iris: "I'll run the analysis and work through any issues."

[sub-agent runs PHPStan, reads errors, applies fixes, re-runs]

Iris: "Fixed 8 errors across 5 files. Most were missing return types - I added them based on the actual return values. PHPStan now passes at level 5."

How Sub-Agents Work

When Iris delegates a task:

1. Task creation: Iris creates a task definition with your requirements
2. Sub-agent spawn: A new agent starts with access to shell commands and web tools
3. Autonomous execution: The sub-agent works through the task, handling errors and iterating
4. Completion: Results are returned to Iris, who summarizes what happened

The sub-agent can:

• Execute shell commands (with the same security restrictions)
• Search the web for documentation or solutions
• Fetch content from URLs
• Iterate up to 30 steps before stopping

Success Criteria

You can give Iris specific conditions that define completion:

You: "Set up ESLint with the Airbnb config. Make sure it passes on the existing codebase."

Iris: [delegates with success criteria: "ESLint configured", "Airbnb preset installed", "No linting errors on existing code"]

The sub-agent uses these criteria to know when the task is truly done versus when it needs to keep working.

Writing Good Criteria

Verifiable conditions work best:

• "All tests pass" - verifiable with test runner
• "No TypeScript errors" - verifiable with tsc
• "Config file exists at config/myapp.php" - verifiable with ls
• "Database migrated successfully" - verifiable from command output

Vague conditions don't help:

• "Code is clean" - subjective
• "Everything works" - unverifiable
• "Looks good" - meaningless to an agent

One Task at a Time

To prevent resource exhaustion, each user can only have one active delegated task. If you try to start a new task while one is running:

You: "Also set up the deployment pipeline"

Iris: "You already have a task in progress (setting up the Laravel project). I'll handle the deployment pipeline once that completes, or you can wait for it to finish."

Timeouts

Tasks have configurable timeouts:

Setting	Default	Maximum
Task timeout	5 minutes	10 minutes

For long-running tasks, you can request more time:

You: "Run the full integration test suite - it takes about 8 minutes"

Iris: [delegates with 10 minute timeout]

If a task times out:

• The sub-agent is terminated
• Partial work may remain on disk
• Iris will explain what happened and suggest next steps

What the Sub-Agent Can Access

The sub-agent has access to:

Tool	Purpose
Shell commands	Execute commands with the same security restrictions as direct shell access
Web search	Find documentation, solutions, or current information
Web fetch	Retrieve content from specific URLs

The sub-agent inherits all shell security settings - blocked commands, blocked patterns, and environment sanitization.

Configuration

Customize sub-agent behavior in config/iris.php:

'subagent' => [
    'enabled' => env('IRIS_SUBAGENT_ENABLED', false),
    'model' => 'claude-sonnet-4-5',
    'max_steps' => 30,
    'default_working_directory' => env('IRIS_SUBAGENT_WORKING_DIR'),
    'request_timeout' => 120,
    'default_timeout' => 300,
    'max_timeout' => 600,
],

Allowing More Iterations

For complex tasks that need many steps:

// config/iris-custom.php
return [
    'subagent' => [
        'max_steps' => 50,
    ],
];

Longer Default Timeout

If your tasks typically run long:

// config/iris-custom.php
return [
    'subagent' => [
        'default_timeout' => 600,  // 10 minutes
    ],
];

Task Delegation vs Shell Commands

Situation	Use
Single command	Shell commands
Quick file check	Shell commands
Multi-step process	Task delegation
Needs iteration and error handling	Task delegation
Build/test/deploy workflows	Task delegation
Interactive feedback needed	Shell commands

When in doubt, start with shell commands. Iris will suggest task delegation when a task would benefit from autonomous execution.

Troubleshooting

Task seems stuck: Tasks have a maximum of 30 steps. Very complex tasks may hit this limit. Try breaking the work into smaller pieces.

Unexpected results: Ask Iris to show you what the sub-agent did. The full output is available after completion.

Timeout on long tasks: Request a longer timeout explicitly, or break the task into phases.

"Task already in progress": Wait for the current task to complete, or ask Iris about its status.

Disabling Task Delegation

To disable (the default), ensure your .env doesn't enable it:

# .env
IRIS_SUBAGENT_ENABLED=false

Or disable just the delegation tool while keeping shell commands:

// config/iris-custom.php
return [
    'disabled_tools' => [
        App\Tools\Agent\DelegateTaskTool::class,
    ],
];