---

name: droid-exec description: Spawn focused subagent tasks via droid exec. Use for parallel processing, isolated operations, or delegating work that benefits from fresh context.

Droid Exec Subagent Spawning

When to Use

Spawn a subagent when:

• Task is isolated (doesn't need your current context)
• Task can run in parallel with your work
• Task benefits from fresh context window (large file processing)
• You need different model characteristics (speed vs reasoning)

Do NOT spawn when:

• Task requires your conversation context
• You need to iterate interactively on results
• Simple operation you can do directly

Invocation

Copydroid exec [options] "<prompt>"

Async Execution (Fire-and-Forget)

To spawn without blocking, use the fireAndForget parameter in your Execute tool call:

Copy{
  "command": "droid exec --auto low \"<task>\"",
  "fireAndForget": true
}

The subagent runs independently. Check results via output files or session continuation.

Autonomy Levels

⚠️ --skip-permissions-unsafe — Only in disposable containers. Bypasses ALL checks.

Output Formats

For Human Consumption (default)

Copydroid exec "summarize changes"

For Programmatic Parsing

Copyresult=$(droid exec --output-format json "analyze deps")
# Returns: {"type":"result","subtype":"success","result":"...","session_id":"...","duration_ms":...}

# Extract fields:
message=$(echo "$result" | jq -r '.result')
session=$(echo "$result" | jq -r '.session_id')

For Real-Time Monitoring

Copydroid exec --output-format stream-json "complex task" | while IFS= read -r line; do
  case $(echo "$line" | jq -r '.type') in
    tool_call) echo "Tool: $(echo "$line" | jq -r '.toolName')" ;;
    completion) echo "Done: $(echo "$line" | jq -r '.finalText')" ;;
  esac
done

Model Selection

Copydroid exec -m claude-sonnet-4-5-20250929 "fast task"      # Speed
droid exec -m claude-opus-4-5-20251101 "complex task"     # Default, high capability
droid exec -m gpt-5.1-codex "coding task"                 # Alternative

Custom Models

Custom models are configured in ~/.factory/settings.json under customModels:

Copy{
  "customModels": [
    {
      "model": "gemini-3-flash-preview",
      "displayName": "google://gemini-3-flash",
      "baseUrl": "http://127.0.0.1:8317/v1",
      "apiKey": "your-key",
      "provider": "openai"
    }
  ]
}

Reference as custom:<displayName-with-dashes>-<index>:

Copydroid exec -m "custom:google://gemini-3-flash-2" "task"

Reasoning Effort

Copydroid exec -r high "complex reasoning task"   # More thinking
droid exec -r low "simple task"               # Faster

Effective Prompts

Pattern 1: Concrete Before/After Examples

Copydroid exec --auto low "
Fix error messages to be user-friendly.

BEFORE: throw new Error('EINVAL');
AFTER:  throw new Error('Invalid email format. Example: user@domain.com');

Apply to all files in src/errors/
"

Pattern 2: Explicit Steps + Constraints

Copydroid exec --auto low "
1. Find all .ts files in src/ missing JSDoc
2. Add @param and @return tags
3. Preserve existing code exactly
4. Write summary to jsdoc-report.md
"

Pattern 3: Artifact Output

Copydroid exec --auto low "Analyze dependencies and write findings to deps-analysis.json"

Always request file output for results you need to process.

Session Continuation

Copy# Start task, capture session
result=$(droid exec --output-format json "begin auth refactor")
session=$(echo "$result" | jq -r '.session_id')

# Continue with context
droid exec -s "$session" "now add tests for the refactored code"

Parallel Execution

Copy# Process files concurrently
find src -name "*.ts" -print0 | xargs -0 -P 4 -I {} \
  droid exec --auto low "Modernize {}"

# Background jobs
for pkg in packages/*; do
  droid exec --cwd "$pkg" --auto low "Run lint and write report.md" &
done
wait

Scoping

Copydroid exec --cwd packages/auth "analyze this module"  # Constrain to directory

Tool Control

Copydroid exec --list-tools                              # See available tools
droid exec --enabled-tools ApplyPatch,Read "task"    # Whitelist
droid exec --disabled-tools execute-cli "task"       # Blacklist

Spec Mode

Plan before executing:

Copydroid exec --use-spec --auto low "refactor auth module"
droid exec --use-spec --spec-model claude-haiku-4-5-20251001 --auto medium "implement feature"

Error Handling

Copyif ! result=$(droid exec --auto low "risky operation" 2>&1); then
  echo "Failed: $result" >&2
  exit 1
fi

Exit codes: 0 = success, non-zero = failure (permission violation, tool error, unmet objective)

Quick Decision Matrix