collaborating-with-claude

# 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.

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

```text
Bash tool call:
  command: python3 skills/collaborating-with-claude/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 on 2.1.176). 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`.

## 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).

```bash
PROMPT="$(cat <<'EOF'
Review src/auth.py around login() and propose fixes.
OUTPUT: Unified Diff Patch ONLY.
EOF
)"
python3 skills/collaborating-with-claude/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 sessions

Capture `SESSION_ID` from the first call and pass it back (selectors are mutually exclusive):

```bash
# Turn 1
python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." --model sonnet --PROMPT "Analyze the bug in foo()." --output-format stream-json

# Turn 2 — resume by ID (use the same --cd)
python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." --model sonnet --SESSION_ID "<id>" --PROMPT "Propose a fix." --output-format stream-json

# Or resume the most recent session in this directory
python3 skills/collaborating-with-claude/scripts/claude_bridge.py \
  --cd "." --model sonnet --continue --PROMPT "What about edge cases?" --output-format stream-json
```

Use `stream-json` or `json` output to capture `SESSION_ID`.

## Bridge flags

**Core:** `--PROMPT` (or `--prompt-file`) · `--cd` (required) · `--model` (alias `haiku`/`sonnet`/`opus`/`fable`, or full id) · `--output-format` (`text`·`json`·`stream-json`, default `stream-json`).

**Sessions** (mutually exclusive): `--SESSION_ID` · `--session-id <uuid>` · `--continue`; plus `--fork-session`, `--no-session-persistence`.

**Permissions:** `--permission-mode` (`default`·`plan`·`acceptEdits`·`auto`·`dontAsk`·`bypassPermissions`) · `--tools` · `--allowed-tools` · `--disallowed-tools`. Footgun: the space in `Bash(git diff *)` is load-bearing.

**Reproducibility & cost:** `--bare` / `--safe-mode` (skip customizations; `--bare` needs `ANTHROPIC_API_KEY`) · `--effort` (`low`→`max`) · `--max-budget-usd` · `--max-turns` · `--timeout <seconds>`.

**Context & advanced:** `--prompt-file` · `--system-prompt[-file]` · `--append-system-prompt[-file]` · `--add-dir` · `--json-schema` · `--mcp-config` · `--settings` · `--agent`/`--agents` · `--return-all-messages` · `--verbose`.

Full semantics in [cli-reference.md](references/cli-reference.md). Set the host's `timeout_ms` to **600000** (10 min) when invoking via a command runner.

## Tune performance

`--model haiku` for quick checks, `sonnet` for routine work, `opus` or `fable` for hard tasks; `--effort low→max` trades depth for speed/cost; `--max-budget-usd` caps