Intern

Run the ACP client script to delegate tasks:

<skill-path> is this skills location on disk.

Background Execution (Default)

Tasks run in background by default, returning a task ID immediately:

bash
1# Launch task (background is default)
2python <skill-path>/scripts/acp_client.py "<project_path>" "<prompt>" --json
3# Returns: {"task_id": "abc123", "status": "launched"}
4
5# Check status
6python <skill-path>/scripts/acp_client.py --status abc123 --json
7
8# Get result when complete
9python <skill-path>/scripts/acp_client.py --result abc123 --json
10
11# Wait for completion (blocking)
12python <skill-path>/scripts/acp_client.py --wait abc123 --json --timeout 600
13
14# List all tasks
15python <skill-path>/scripts/acp_client.py --list-tasks --json
16python <skill-path>/scripts/acp_client.py --list-tasks --filter running --json
17
18# Cancel a running task
19python <skill-path>/scripts/acp_client.py --cancel abc123
20
21# Clean up old completed tasks
22python <skill-path>/scripts/acp_client.py --cleanup

Synchronous Execution

For simple tasks where you want to wait for the result:

bash
1python <skill-path>/scripts/acp_client.py "<project_path>" "<prompt>" --sync --json

Parse the JSON result directly. The project_path is usually the current working directory.

Response Format

json
1{
2  "success": true,
3  "response": "Agent's response text",
4  "tools": [{"name": "bash", "status": "completed"}],
5  "errors": [],
6  "agent_status": "end_turn"
7}

Agent Status Values

Task Status Values (Background Mode)

Parameters

Execution Options

• project_path (required for sync): Absolute path to project
• prompt (required for sync): Task description (max 100KB)
• --agent: Agent name (default: intern)
• --timeout: Overall timeout in seconds (default: 300)
• --activity-timeout: Max seconds without activity (default: 120)
• --json: JSON output (always use this)
• --debug: Enable debug logging to stderr
• --background: Run task in background (default)
• --sync: Run task synchronously, wait for completion

Task Management Options

• --status TASK_ID: Check status of a background task
• --list-tasks: List all background tasks
• --filter STATUS: Filter tasks by status (pending/running/completed/failed/cancelled)
• --result TASK_ID: Get the result of a completed task
• --cancel TASK_ID: Cancel a running task
• --wait TASK_ID: Wait for a task to complete
• --cleanup: Remove old completed tasks (>24 hours)

Errors

Features

• Thread-safe request handling: Safe for concurrent operations
• Background task execution: Launch tasks asynchronously, check status later
• Activity timeout detection: Detects hung agents that stop responding
• Process health monitoring: Detects if agent process crashes
• Session cancellation: Properly cancels stuck sessions per ACP protocol
• Error status detection: Detects and reports agent errors
• Debug mode: Enable --debug for troubleshooting
• Partial response capture: Returns partial responses even on failure
• Windows path normalization: Automatically converts C:\path to C:/path in prompts

Best Practices

1. Always use --json for reliable parsing of results
2. Use background mode for tasks >2 minutes to avoid blocking
3. Check task status periodically rather than using long timeouts
4. Use --debug when troubleshooting to see protocol messages
5. Keep prompts focused - delegate one clear task at a time
6. Clean up old tasks periodically with --cleanup