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

Running the Agent Daemon

Delegated tasks are processed by the iris:agent daemon — a long-running command that polls for pending tasks:

php artisan iris:agent

The daemon picks up tasks as they're created, processes them sequentially, and handles rate limits automatically by backing off and retrying. It responds to SIGINT and SIGTERM for graceful shutdown.

If you're using composer dev, the agent daemon is already included — no extra setup needed.

IMPORTANT

Without the agent daemon running, delegated tasks will sit in a pending state indefinitely.

You can also process a single task and exit, which is useful for testing:

php artisan iris:agent --once

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 60 steps before stopping

Monitoring Tasks

You can keep tabs on delegated tasks directly from the chat header — no need to wait blindly for results.

Task Indicator

The bot icon in the header is always visible. When a task is actively running, a pink pulse badge appears on the icon. Click it to open a dropdown showing your 5 most recent tasks.

Real-Time Tool Tracking

Expand a running task to watch every tool call as it happens:

• Shell commands appear as they execute, with arguments and completion status
• Provider tools (web search, web fetch) are tracked with the same real-time visibility
• A pulsing dot indicates a tool is in progress; a checkmark means it completed

TIP

This is a great way to understand what the sub-agent is doing and catch issues early — if you see it heading in the wrong direction, you can cancel and refine your instructions.

Completed Task History

The dropdown shows your 5 most recent tasks regardless of status. Expand a completed task to fetch its full tool call history from the server, so you can review exactly what the sub-agent did.

Cancelling Tasks

Click the stop button next to any running task to cancel it. Cancelled tasks remain visible briefly before being automatically dismissed.

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 all tools configured in config/iris.php, including:

Tool	Type	Purpose
All configured tools	Custom	The full set of tools from iris.tools (memory, calendar, shell, etc.)
Web search	Provider	Find documentation, solutions, or current information
Web fetch	Provider	Retrieve content from specific URLs

All tool calls — both custom and provider — are tracked in real time and persisted for review after completion. 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),
    'provider' => 'anthropic',
    'model' => 'claude-sonnet-4-5',
    'max_steps' => 60,
    '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' => 100,
    ],
];

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 60 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,
    ],
];