/collaborating-with-claude

name: collaborating-with-claude
description: Delegate tasks to Claude Code CLI for prototyping, debugging, and code review. Supports multi-turn sessions via SESSION_ID.
metadata:
  short-description: Delegate to Claude Code CLI

Collaborating with Claude Code

Drive Claude Code headlessly as an independent collaborator while the calling agent stays responsible for verification, synthesis, and final user-facing decisions.

The bridge (`scripts/claude_bridge.py`) wraps `claude --print`, streams progress to stderr, returns structured JSON with telemetry, and manages multi-turn continuity via `SESSION_ID`. Always go through the bridge — don't invoke `claude` directly — so output parsing and session handling stay consistent.

Commands below write `<skill_dir>` for the absolute path of the directory containing this SKILL.md. Your harness usually reports that path when it loads the skill. If it does not, use this SKILL.md's own location. Substitute it before running, for example `~/.codex/skills/collaborating-with-claude`.

In Claude Code, run non-trivial calls in the background and watch the stderr progress:

Bash tool call:
  command: python3 <skill_dir>/scripts/claude_bridge.py --cd "/project" --PROMPT "Analyze auth flow in src/auth/"
  run_in_background: true

`run_in_background` is a host tool parameter, not a shell argument. Use the task-output view to monitor timestamped stderr progress (session, responses, tools, cost) and the final JSON result.

Safety

Default to read-only delegation: `--permission-mode plan` (analyze, no edits/commands) or `--tools "Read,Glob,Grep"`. Grant writes only deliberately (`acceptEdits`/`auto`), preferably in an isolated worktree. Do not hand secrets, private keys, or production data to Claude. Full permission-mode set and the worktree pattern: [cli-reference.md](references/cli-reference.md), [handoff-patterns.md](references/handoff-patterns.md).

Permissions and network (headless)

Headless `claude -p` cannot prompt: every gated action is denied on the spot and recorded in `permission_denials`, which the bridge surfaces (verified). Authority is therefore decided entirely up front via `--permission-mode`, `--tools`, and `--allowed-tools` — get user consent before granting anything beyond read-only.

Network is governed by tool policy, not an OS sandbox: `plan` mode denies `WebFetch`/`WebSearch` too (verified), while an allowed `Bash` can reach the network freely. Pick the posture per task:

• No network, read-only: `--permission-mode plan`, or `--tools "Read,Glob,Grep"`.
• Read-only plus targeted web research (verified): `--permission-mode dontAsk --tools "Read,Glob,Grep,WebFetch,WebSearch" --allowed-tools "WebFetch(domain:example.com)" --allowed-tools "WebSearch"`.
• Reads outside `--cd` are gated as well — grant extra roots with `--add-dir`.

Host-side approval (the bridge call itself)

Everything above governs the child Claude. The **host** agent's own permission layer gates the `python3 … claude_bridge.py` Bash call first — and under classifier-gated auto-approval (Claude Code `auto`/`dontAsk`, Codex non-interactive runs), a long-running script that spawns another agent over the codebase pattern-matches "high-risk" and can be **denied silently**: the delegation never starts. A host permission error instead of bridge JSON means the host blocked the bridge, not that Claude failed.

• **Pre-authorize the bridge instead of relying on the classifier.** Claude Code host: add `"Bash(python3 *collaborating-with-claude*bridge.py*)"` to `permissions.allow` in your `settings.json`. The wildcard form keeps matching wherever the skill is installed. Sandboxed hosts also need `"python3 *collaborating-with-claude*bridge.py*"` in `sandbox.excludedCommands`, because sandbox network policy blocks the child CLI's API traffic even after the command is allowed. Grok host: pass the same rule via `--allow`. Install and approval runbooks: [docs/setup/](https://github.com/appautomaton/agent-designer/tree/main/docs/setup) in the source repo.
• **Codex host: the sandbox is the second gate.** Both `read-only` and `workspace-write` block shell network, so the child CLI can't reach its API at all. Run the bridge call through an approved escalation, or knowingly grant network for that call.
• **Never degrade silently.** If the host denies the bridge call, report it and propose the allowlist fix — don't substitute your own answer for the independent second opinion that was requested.

When to use / not use

Use for: second opinions on design, edge cases, or test gaps; proposing or reviewing a unified diff; multi-turn analysis while you implement. Skip for: trivial one-shot edits (do them directly); tasks needing authoritative cited facts (Claude may guess); anything touching secrets or prod data.

Quick start

⚠️ Backticks / `$VARS` in prompts trigger shell expansion — use a single-quoted heredoc, or `--prompt-file` for large/generated prompts. See [shell-quoting.md](references/shell-quoting.md).

PROMPT="$(cat <<'EOF'
Review src/auth.py around login() and propose fixes.
OUTPUT: Unified Diff Patch ONLY.
EOF
)"
python3 <skill_dir>/scripts/claude_bridge.py \
  --cd "." --model sonnet --permission-mode plan --PROMPT "$PROMPT" --output-format stream-json

For large or shell-sensitive prompts, write the prompt to a file and pass `--prompt-file /tmp/prompt.md` (piped via stdin — no argv/quoting limits).

**Returns** (stdout JSON): `{ "success": true, "SESSION_ID": "...", "agent_messages": "...", "model": "...", "subtype": "success", "total_cost_usd": 0.03, "usage": {...}, "num_turns": 1 }` — plus `tools_used` / `tools_failed` / `tool_counts` / `permission_denials` / `structured_output` / `is_error` when relevant. Check `tools_failed` and `permission_denials` before trusting the answer: a denied tool means Claude reasoned without the evidence it asked for. Progress streams to **stderr**; the bridge exits non-zero on failure.

Multi-turn sessi