sub-agent

# Sub-Agent (opensquilla process tools)

Generic "spawn a sub-Agent" entry point for delegating self-contained
tasks to Codex / Claude Code / OpenCode / Pi via background process.
Wrapping CLIs are coding-oriented, but the skill itself is used as
the generic sub-Agent slot by meta-skill DAGs for any LLM-driven
sub-task (file edits, document generation, policy review, etc.).

Use opensquilla's `exec_command`, `background_process`, and `process` tools for coding agent work. OpenSquilla does not expose a `bash` tool; do not use the legacy bash tool-call DSL.

## Non-Interactive CLI Mode

OpenSquilla's process tools do not expose a `pty` parameter. Prefer non-interactive command modes that run and exit cleanly:

```bash
# ✅ Correct for Codex/Pi/OpenCode
exec_command(command="codex exec 'Your prompt'")
```

For **Claude Code** (`claude` CLI), use `--print --permission-mode bypassPermissions` instead.
`--dangerously-skip-permissions` with PTY can exit after the confirmation dialog.
`--print` mode keeps full tool access and avoids interactive confirmation:

```bash
# ✅ Correct for Claude Code (no PTY needed)
cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task'

# For background execution: use background_process

# ❌ Wrong for Claude Code
exec_command(command="claude --dangerously-skip-permissions 'task'")
```

### OpenSquilla Tool Parameters

| Tool | Key parameters | Description |
| ---- | -------------- | ----------- |
| `exec_command` | `command`, `workdir`, `timeout` | Run a foreground shell command. |
| `background_process` | `command`, `workdir`, `timeout` | Start a long-running command and return `session_id`. |
| `process` | `action`, `session_id`, `data`, `offset`, `limit` | Poll, log, write to, or stop a background process. |

### Process Tool Actions (for background sessions)

| Action      | Description                                          |
| ----------- | ---------------------------------------------------- |
| `list`      | List all running/recent sessions                     |
| `poll`      | Check if session is still running                    |
| `log`       | Get session output (with optional offset/limit)      |
| `write`     | Send raw data to stdin                               |
| `submit`    | Send data + newline (like typing and pressing Enter) |
| `eof`       | Close stdin                                          |
| `remove`    | Remove a finished session from the process list      |
| `kill`      | Terminate the session                                |

---

## Quick Start: One-Shot Tasks

For quick prompts/chats, create a temp git repo and run:

```bash
# Quick chat (Codex needs a git repo!)
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"

# Or in a real project
exec_command(workdir="~/Projects/myproject", command="codex exec 'Add error handling to the API calls'")
```

**Why git init?** Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.

---

## The Pattern: workdir + background_process

For longer tasks, use `background_process`:

```bash
# Start agent in target directory.
background_process(workdir="~/project", command="codex exec --full-auto 'Build a snake game'")
# Returns session_id for tracking

# Monitor progress
process(action="log", session_id="XXX")

# Check if done
process(action="poll", session_id="XXX")

# Send input (if agent asks a question)
process(action="write", session_id="XXX", data="y")

# Submit with Enter (like typing "yes" and pressing Enter)
process(action="submit", session_id="XXX", data="yes")

# Kill if needed
process(action="kill", session_id="XXX")
```

**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).

---

## Codex CLI

**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)

### Flags

| Flag            | Effect                                             |
| --------------- | -------------------------------------------------- |
| `exec "prompt"` | One-shot execution, exits when done                |
| `--full-auto`   | Sandboxed but auto-approves in workspace           |
| `--yolo`        | NO sandbox, NO approvals (fastest, most dangerous) |

### Building/Creating

```bash
# Quick one-shot
exec_command(workdir="~/project", command="codex exec --full-auto 'Build a dark mode toggle'")

# Background for longer work
background_process(workdir="~/project", command="codex exec --full-auto 'Refactor the auth module'")
```

### Reviewing PRs

**⚠️ CRITICAL: Never review PRs in OpenSquilla's own project folder!**
Clone to temp folder or use git worktree.

```bash
# Clone to temp for safe review
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
exec_command(workdir="$REVIEW_DIR", command="codex review --base origin/main")
# Clean up after: trash $REVIEW_DIR

# Or use git worktree (keeps main intact)
git worktree add /tmp/pr-130-review pr-130-branch
exec_command(workdir="/tmp/pr-130-review", command="codex review --base main")
```

### Batch PR Reviews (parallel army!)

```bash
# Fetch all PR refs first
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# Deploy the army - one Codex per PR
background_process(workdir="~/project", command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'")
background_process(workdir="~/project", command="codex exec 'Review PR #87. git diff origin/main...origin/pr/87'")

# Monitor all
process(action="list")

# Post results to GitHub
gh pr comment <PR#> --body "<review content>"
```

---

## Claude Code

```bash
# Foreground
exec_command(workdir="~/project", command="claude --permission-mode bypassPermissions --print 'Your task'")

# Background
background_process(workdir="~/project", command="claude --permission-mode bypassPermissions --print 'Your task'")
```

---

## OpenCode

```bash
exec_command(wor