Merge pull request #2 from shinpr/fix/improve-error-reporting

Improve error reporting, timeout, and Codex support

Author: shinpr

.gitignore

@@ -3,6 +3,7 @@
 
 # Python
 __pycache__/
+.venv/
 *.py[cod]
 *$py.class
 .pytest_cache/

README.md

@@ -287,7 +287,7 @@ To customize: `export SUB_AGENTS_DIR=/custom/path`
 | `--agent` | Yes* | Agent definition name from --list |
 | `--prompt` | Yes* | Task description to delegate |
 | `--cwd` | Yes* | Working directory (absolute path) |
-| `--timeout` | No | Timeout ms (default: 300000) |
+| `--timeout` | No | Timeout ms (default: 600000) |
 | `--cli` | No | Force CLI: `claude`, `cursor-agent`, `codex`, `gemini` |
 
 *Required when not using --list

skills/sub-agents/SKILL.md

@@ -11,56 +11,81 @@ Spawns external CLI AIs (claude, cursor-agent, codex, gemini) as isolated sub-ag
 ## Resources
 
 - **[run_subagent.py](scripts/run_subagent.py)** - Main execution script
-- **[cli-formats.md](references/cli-formats.md)** - CLI output format details
+- **[codex.md](references/codex.md)** - Codex-specific setup (permissions, timeout)
 
-**Execution**: Run scripts using absolute path from this skill's directory with your environment's Python.
+**Script Path**: Use absolute path `{SKILL_DIR}/scripts/run_subagent.py` where `{SKILL_DIR}` is the directory containing this SKILL.md file.
+
+## CLI-Specific Notes
+
+Check the corresponding reference for your environment:
+- **Codex**: Read [references/codex.md](references/codex.md) BEFORE first execution
 
 ## Interpreting User Requests
 
 Extract parameters from user's natural language request:
 
 | Parameter | Source |
 |-----------|--------|
-| --agent | Agent name from user request (if not specified, use --list to show candidates and ask user) |
+| --agent | Agent name from user request (see selection rules below) |
 | --prompt | Task instruction part (excluding agent specification) |
-| --cwd | Current working directory |
+| --cwd | Current working directory (absolute path) |
+
+**Agent Selection Rules** (when user doesn't specify agent name):
+1. Run `--list` to get available agents
+2. **0 agents**: Inform user no agents available, show setup instructions (see [Agent Definition Format](#agent-definition-format))
+3. **1 agent**: Auto-select without asking
+4. **2+ agents**: Show list with descriptions, ask user to choose
 
 **Example**:
 "Run code-reviewer on src/"
 → `--agent code-reviewer --prompt "Review src/" --cwd $(pwd)`
 
 ## When to Use This Skill
 
-| Scenario | Use Sub-Agent | Reason |
-|----------|---------------|--------|
-| Complex multi-step task | **Yes** | Isolated context prevents interference |
-| Parallel investigation | **Yes** | Multiple agents can run simultaneously |
-| Task needs fresh context | **Yes** | Sub-agent starts without conversation history |
-| Specialized agent definition exists | **Yes** | Leverage pre-defined expert prompts |
-| Simple single-step task | No | Direct execution is faster |
-| Task requires current conversation context | No | Sub-agent cannot access parent context |
+**Use sub-agent when ANY of these apply:**
+- Complex multi-step task (isolated context prevents interference)
+- Parallel investigation (multiple agents can run simultaneously)
+- Task needs fresh context (sub-agent starts without conversation history)
+- Specialized agent definition exists (leverage pre-defined expert prompts)
+
+## Important: Permission and Timeout
+
+This script executes external CLIs that require elevated permissions.
+
+**Before first execution:**
+1. Request elevated permissions via your CLI's tool parameters
+2. Set tool timeout to match `--timeout` argument (default: 600000ms)
+
+**For Codex CLI** (most common permission issues): See [references/codex.md](references/codex.md) for exact JSON parameter format.
 
 ## Workflow
 
+### Step 0: Read CLI-Specific Setup (if applicable)
+
+If you are running on Codex, read [references/codex.md](references/codex.md) first.
+
 ### Step 1: List Available Agents
 
 **Always list agents first** to discover available definitions:
 
 ```bash
-python scripts/run_subagent.py --list
+scripts/run_subagent.py --list
 ```
 
 Output:
 ```json
 {"agents": [{"name": "code-reviewer", "description": "Reviews code..."}], "agents_dir": "/path/.agents"}
 ```
 
-**If agents list is empty**: Agent definitions must be placed in `{cwd}/.agents/` directory.
+**If agents list is empty**:
+1. Create `{cwd}/.agents/` directory
+2. Add agent definition file (see [Agent Definition Format](#agent-definition-format))
+3. Re-run `--list` to verify
 
 ### Step 2: Execute Agent
 
 ```bash
-python scripts/run_subagent.py \
+scripts/run_subagent.py \
   --agent <name> \
   --prompt "<task>" \
   --cwd <absolute-path>
@@ -74,11 +99,22 @@ Parse JSON output and check `status` field:
 {"result": "...", "exit_code": 0, "status": "success", "cli": "claude"}
 ```
 
+**By status:**
+
 | status | Meaning | Action |
 |--------|---------|--------|
 | `success` | Task completed | Use `result` directly |
 | `partial` | Timeout but has output | Review partial `result`, may need retry |
-| `error` | Execution failed | Check `error` field, fix and retry |
+| `error` | Execution failed | Check `error` field and `exit_code`, fix and retry |
+
+**By exit_code** (when status is `error`):
+
+| exit_code | Meaning | Resolution |
+|-----------|---------|------------|
+| 0 | Success | - |
+| 124 | Timeout | Increase `--timeout` or simplify task |
+| 127 | CLI not found | Install required CLI (claude, codex, etc.) |
+| 1 | General error | Check `error` field in response |
 
 ## Parameters
 
@@ -88,7 +124,7 @@ Parse JSON output and check `status` field:
 | `--agent` | Yes* | Agent definition name from --list |
 | `--prompt` | Yes* | Task description to delegate |
 | `--cwd` | Yes* | Working directory (absolute path) |
-| `--timeout` | No | Timeout ms (default: 300000) |
+| `--timeout` | No | Timeout ms (default: 600000) |
 | `--cli` | No | Force CLI: `claude`, `cursor-agent`, `codex`, `gemini` |
 
 *Required when not using --list
@@ -131,20 +167,11 @@ How results should be structured.
 3. Auto-detect caller environment
 4. Default: `codex`
 
-## Error Handling
-
-| exit_code | Meaning | Resolution |
-|-----------|---------|------------|
-| 0 | Success | - |
-| 124 | Timeout | Increase `--timeout` or simplify task |
-| 127 | CLI not found | Install required CLI (claude, codex, etc.) |
-| 1 | General error | Check `error` field in response |
-
-## Anti-patterns
+## Common Mistakes
 
-| Anti-pattern | Problem | Correct Approach |
-|--------------|---------|------------------|
-| Not listing agents first | Unknown agent name causes error | Always run `--list` first |
-| Relative path for --cwd | Validation fails | Use absolute path |
-| Ignoring status field | Missing errors | Always check status before using result |
+| Mistake | Result | Fix |
+|---------|--------|-----|
+| Skip `--list` before execution | Agent not found error | Always run `--list` first |
+| Use relative path for `--cwd` | Validation fails | Use absolute path |
+| Ignore `status` field in response | Undetected errors | Always check `status` before using `result` |
 | Very long prompts | May exceed CLI limits | Break into smaller tasks |

skills/sub-agents/references/cli-formats.md

@@ -0,0 +1,49 @@
+# Codex-Specific Notes
+
+Read this reference when executing sub-agents from Codex CLI.
+
+## Where to Set Parameters
+
+Codex CLI uses **Bash tool call parameters** for permissions and timeout. These are NOT command-line arguments—they are tool invocation settings.
+
+```json
+{
+  "tool": "Bash",
+  "parameters": {
+    "command": "/path/to/scripts/run_subagent.py --agent <name> --prompt \"<task>\" --cwd /absolute/path --timeout 600000",
+    "timeout_ms": 600000,
+    "sandbox_permissions": "require_escalated"
+  }
+}
+```
+
+## Permission: Request Escalated BEFORE First Execution
+
+Sub-agent CLIs require access to session files outside the sandbox.
+
+**Setting:** `"sandbox_permissions": "require_escalated"` in Bash tool parameters.
+
+Always request escalated permissions on the first run. Sandboxed runs fail with:
+```
+Error: Fatal error: Codex cannot access session files at ~/.codex/sessions (permission denied)
+```
+
+## Timeout: Match timeout_ms with --timeout
+
+Codex's Bash tool has its own timeout (`timeout_ms`), separate from the script's `--timeout` argument.
+
+**Setting:** `"timeout_ms": 600000` in Bash tool parameters (must match `--timeout` value).
+
+| --timeout | timeout_ms | Result |
+|-----------|------------|--------|
+| Not set | Not set | Script: 600000ms, Tool: ~10000ms → Tool kills script early |
+| 600000 | Not set | Same problem |
+| 600000 | 600000 | Correct: both aligned |
+
+## Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Operation not permitted (os error 1)` | Sandbox restriction | Use `sandbox_permissions:"require_escalated"` |
+| `(no output)` after few seconds | Tool timeout too short | Set `timeout_ms` to match `--timeout` |
+| `permission denied` on session files | Need elevated permissions | Request escalated permissions first |

skills/sub-agents/references/codex.md

@@ -3,8 +3,8 @@
 run_subagent.py - Execute external CLI AIs as sub-agents
 
 Usage:
-    python scripts/run_subagent.py --agent <name> --prompt "<task>" --cwd <path>
-    python scripts/run_subagent.py --list
+    scripts/run_subagent.py --agent <name> --prompt "<task>" --cwd <path>
+    scripts/run_subagent.py --list
 
 Supported CLIs: claude, cursor-agent, codex, gemini
 
@@ -302,7 +302,7 @@ def build_command(cli: str, prompt: str) -> tuple[str, list]:
 
 
 def execute_agent(
-    cli: str, system_context: str, prompt: str, cwd: str, timeout: int = 300000
+    cli: str, system_context: str, prompt: str, cwd: str, timeout: int = 600000
 ) -> dict:
     """
     Execute agent CLI and return result.
@@ -375,7 +375,10 @@ def execute_agent(
                 "cli": cli,
             }
             if status == "error":
-                response["error"] = f"CLI exited with code {exit_code}, no result returned"
+                error_msg = f"CLI exited with code {exit_code}"
+                if stderr and stderr.strip():
+                    error_msg += f": {stderr.strip()}"
+                response["error"] = error_msg
             return response
 
         except Exception as e:
@@ -414,7 +417,7 @@ def main():
     parser.add_argument("--cwd", help="Working directory (absolute path)")
     parser.add_argument("--agents-dir", help="Directory containing agent definitions")
     parser.add_argument(
-        "--timeout", type=int, default=300000, help="Timeout in ms (default: 300000)"
+        "--timeout", type=int, default=600000, help="Timeout in ms (default: 600000)"
     )
     parser.add_argument("--cli", help="Force specific CLI (claude, cursor-agent, codex, gemini)")