@freibergergarcia/phone-a-friend 2.0.1 → 2.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "phone-a-friend",
   "description": "CLI relay that lets AI coding agents collaborate by sending prompts and repository context to backend agents.",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "author": {
     "name": "Bruno Freiberger"
   }

package/README.md

@@ -20,7 +20,7 @@ Relay tasks to any backend, spin up multi-model teams, or run persistent multi-a
 
 | Mode | What it does | Best for |
 |------|-------------|----------|
-| **Relay** | One-shot delegation to Codex, Gemini, Ollama, or Claude | Quick second opinions, code reviews, analysis |
+| **Relay** | One-shot delegation to Codex, Gemini, Ollama, Claude, or OpenCode | Quick second opinions, code reviews, analysis |
 | **Team** | Iterative multi-backend refinement over N rounds | Collaborative review, converging on a solution |
 | **Agentic** | Persistent multi-agent sessions with @mention routing | Autonomous collaboration, adversarial review, deep analysis |
 
@@ -44,6 +44,7 @@ Relay tasks to any backend, spin up multi-model teams, or run persistent multi-a
 - [Codex CLI](https://developers.openai.com/codex/quickstart/)
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
 - [Ollama](https://ollama.com/download)
+- [OpenCode](https://opencode.ai/docs)
 
 **Install:**
 
@@ -52,7 +53,7 @@ npm install -g @freibergergarcia/phone-a-friend
 phone-a-friend    # first run shows a guided menu — choose Setup
 ```
 
-The setup wizard detects your backends, installs the Claude Code plugin, and verifies everything works.
+The setup wizard detects your backends, offers to install detected host integrations, and verifies everything works.
 
 **Claude Code marketplace (commands and skills only):**
 
@@ -77,6 +78,20 @@ This fetches the latest version from npm automatically. To update later:
 > the web dashboard on localhost, install globally with
 > `npm install -g @freibergergarcia/phone-a-friend`.
 
+**OpenCode commands and skills:**
+
+If you use [OpenCode](https://opencode.ai/docs), install the same Phone-a-Friend skills plus thin slash-command shims into your OpenCode config:
+
+```bash
+phone-a-friend plugin install --opencode
+```
+
+This installs to `~/.config/opencode/skills/` and `~/.config/opencode/commands/` (or `$XDG_CONFIG_HOME/opencode/...`). From OpenCode, ask naturally, for example:
+
+```
+Ask Codex through phone-a-friend for a short sanity review of this repo; do not edit files.
+```
+
 **From source:**
 
 ```bash
@@ -86,7 +101,7 @@ npm install && npm run build
 ./dist/index.js   # first run guides you through setup
 ```
 
-Then from Claude Code, just talk naturally — the plugin loads the skills automatically:
+Then from Claude Code or OpenCode, just talk naturally — the host integration loads the skills automatically:
 
 ```
 Ask Gemini to review the error handling in relay.ts
@@ -98,7 +113,7 @@ Build a team with Claude and Ollama. Have them review the website copy,
 loop through 3 rounds, and converge on final suggestions.
 ```
 
-No slash commands needed. Once the plugin is installed (the setup wizard does this automatically), Claude loads the `/phone-a-friend` and `/phone-a-team` skills. Mention one backend and Claude routes through `/phone-a-friend`; mention multiple and Claude can use `/phone-a-team` for iterative refinement. You can also invoke either skill explicitly.
+No slash commands needed. Once the host integration is installed (the setup wizard offers to do this), the host can route single-backend tasks through `/phone-a-friend`. In Claude Code, mention multiple backends and Claude can use `/phone-a-team` for iterative multi-agent refinement; `/phone-a-team` is Claude-only because it depends on Claude Agent Teams primitives. In OpenCode, use repeated `/phone-a-friend` calls and synthesize the results manually. You can explicitly invoke `/phone-a-friend` in both hosts, and `/phone-a-team` in Claude Code only.
 
 > [!TIP]
 > **Power-user setup:** Run Claude Code in [**tmux**](https://formulae.brew.sh/formula/tmux) and enable [**bypass permissions**](https://docs.anthropic.com/en/docs/claude-code/security) (`⏵⏵`) for trusted repos. [**Agent teams**](https://docs.anthropic.com/en/docs/claude-code/agent-teams) show up in split panes, so you can watch agents work in parallel without approval pauses. Pair it with **phone-a-friend agentic mode** for fully autonomous multi-agent sessions.
@@ -117,7 +132,9 @@ phone-a-friend --to ollama --prompt "Explain this function"
 phone-a-friend --to opencode --prompt "Audit this repo" --model qwen3-coder  # Local agentic (OpenCode + Ollama)
 phone-a-friend --to claude --prompt "Review this code" --stream   # Stream tokens live
 phone-a-friend --to codex --prompt "Audit the auth module" --quiet # Run silently, save result
-phone-a-friend --to claude --prompt "Explain this" --fast          # Skip project context (faster)
+phone-a-friend --to opencode --prompt "Explain this" --fast        # Skip OpenCode plugins (faster)
+phone-a-friend --to codex --prompt "Review my fix" --include-diff   # Append `git diff HEAD` to the prompt
+phone-a-friend --to codex --prompt "Quick question" --no-include-diff  # Override defaults.include_diff = true
 ```
 
 ### Structured output
@@ -141,7 +158,7 @@ phone-a-friend --to codex --prompt "Review the auth module" --session auth-revie
 phone-a-friend --to codex --prompt "Now fix those issues" --session auth-review
 ```
 
-Sessions work reliably with Claude, Codex, and OpenCode. Ollama replays history (may hit token limits on long conversations). Gemini session resume is best-effort.
+Sessions work reliably with Claude, Codex, and OpenCode. Ollama replays history (may hit token limits on long conversations). Gemini sessions are currently unsupported.
 
 ### Job tracking
 
@@ -164,6 +181,11 @@ phone-a-friend --to codex --review --base develop  # Review against a specific b
 phone-a-friend --to opencode --review              # Review with local model (reads repo via tools)
 ```
 
+`--review` is the diff-scoped review mode (uses the backend's native review path when available). For ad-hoc prompts where you want the working-tree diff appended, use `--include-diff` with normal prompt mode. To override a `defaults.include_diff = true` config setting on a single call, use `--no-include-diff` (or set `PHONE_A_FRIEND_INCLUDE_DIFF=false` in the environment for older binaries).
+
+> [!TIP]
+> Don't paste code into `--prompt` just to review it — the backend can read the repo directly via `--repo "$PWD"` (default: current working directory). Pasting risks leaking uncommitted edits and burns tokens for content the backend can fetch itself.
+
 ### Agentic
 
 Spawn multiple agents that collaborate via @mentions (see [Agentic Mode](#agentic-mode) below):
@@ -180,11 +202,15 @@ phone-a-friend agentic dashboard           # Launch web dashboard (localhost:777
 ```bash
 phone-a-friend                 # Interactive TUI dashboard (TTY only)
 phone-a-friend setup           # Guided setup wizard
-phone-a-friend doctor          # Health check all backends
+phone-a-friend doctor          # Health check all backends + host install status
+phone-a-friend plugin install --claude    # Install Claude Code plugin
+phone-a-friend plugin install --opencode  # Install OpenCode commands and skills
 phone-a-friend config show     # Show resolved config
 phone-a-friend config edit     # Open in $EDITOR
 ```
 
+`doctor` reports CLI backends, local backends (Ollama), host integration status (Claude / OpenCode plugin install state), and a summary count. The OpenCode CLI is treated as optional: if you only use Claude Code and don't have OpenCode installed, doctor will not flag that as a degraded state.
+
 ## Backends
 
 | Backend | Type | Streaming | How it works |
@@ -193,11 +219,16 @@ phone-a-friend config edit     # Open in $EDITOR
 | **Gemini** | CLI subprocess | No | Runs `gemini --prompt` with `--yolo` auto-approve |
 | **Ollama** | HTTP API | Yes (NDJSON) | POSTs to `localhost:11434/api/chat` via native fetch |
 | **Claude** | CLI subprocess | Yes (JSON) | Runs `claude` with sandbox-to-tool mapping |
+| **OpenCode** | CLI subprocess | Yes (NDJSON) | Runs `opencode run` with repo-local tool access |
 
 Ollama configuration via environment variables:
 - `OLLAMA_HOST` -- custom host (default: `http://localhost:11434`)
 - `OLLAMA_MODEL` -- default model (overridden by `--model` flag)
 
+Phone-a-friend environment variables:
+- `PHONE_A_FRIEND_INCLUDE_DIFF=false` -- disable diff inclusion across every relay; equivalent to passing `--no-include-diff` on every command. Useful when `defaults.include_diff = true` in your config but you want a session without the diff. Also the canonical mechanism used by OpenCode shims for stale-binary compatibility (the `--no-include-diff` flag was added in v2.2.0+; older binaries reject it but accept this env var since v1.7.2).
+- `PHONE_A_FRIEND_HOST=opencode` -- mark the calling process as OpenCode for the recursion guard. Set automatically by the OpenCode shims; only relevant if you're invoking PaF programmatically from inside an OpenCode session.
+
 OpenCode configuration via TOML:
 ```toml
 [backends.opencode]
@@ -270,7 +301,7 @@ Full usage guide, examples, CLI reference, and configuration details:
 npm uninstall -g @freibergergarcia/phone-a-friend
 ```
 
-The Claude Code plugin is removed automatically.
+The Claude Code plugin and OpenCode commands/skills are removed automatically when installed through the CLI.
 
 ## Contributing
 

package/commands/curiosity-engine.md

@@ -1,15 +1,45 @@
 ---
 name: curiosity-engine
-description: Structured Q&A rally between Claude and a backend model. Both sides must always reply with ANSWER: and QUESTION:. Seeded by topic, runs for N rounds.
+description: Structured Q&A rally between the host orchestrating model and a backend model. Both sides must always reply with ANSWER: and QUESTION:. Seeded by topic, runs for N rounds.
 argument-hint: --topic "<topic>" [--rounds N] [--backend codex|gemini|ollama]
 ---
 
 # /curiosity-engine
 
-A structured ping-pong Q&A game between Claude and a backend model.
+A structured ping-pong Q&A game between the host orchestrating model (the
+agent running this skill — Claude in Claude Code, the OpenCode model in
+OpenCode) and a backend model.
 Both sides MUST produce an ANSWER: and a QUESTION: every round.
 The game is seeded with a topic and runs for N rounds (default 3, max 6).
 
+## Execution rules
+
+- The host model running this skill is the orchestrator. It serves the
+  opening question and answers each round directly. Do NOT call
+  `phone-a-friend --to claude` (or any other backend) to generate the
+  orchestrator's questions or answers — that would relay the orchestrator
+  role to a different model.
+- One backend per relay call. Never pass comma-separated values to `--to`
+  (e.g. `phone-a-friend --to codex,gemini`).
+- `curiosity-engine` is a host slash command / Agent Skill, not a PaF CLI
+  subcommand. Never run `phone-a-friend curiosity-engine`.
+- `--backend` is an argument to this skill, not a PaF CLI flag. Do not pass
+  `--backend` to `phone-a-friend`.
+- Suppress the working-tree diff on every binary-mode relay (see "Diff
+  suppression" below). Curiosity rounds are seeded with self-contained
+  prompts; the diff would be noise.
+- Do NOT dump repo files or git output (`git show`, `git diff`,
+  `git status`, etc.) into the relay prompt. Curiosity rounds are seeded
+  with self-contained prompts; if the round needs file context,
+  repo-aware backends (codex, gemini) can read the repo via
+  `--repo "$PWD"`. For `ollama` (no repo file access), pick a repo-aware
+  backend instead, or ask before sending a minimal excerpt. Inlining
+  repo content can leak uncommitted edits or committed secrets and is
+  not needed for a Q&A rally. The opening question and round
+  transcripts are narrative context that the orchestrator generates and
+  inlines into the relay prompt; that is the intended use, not file
+  dumping.
+
 ## Inputs
 
 - Arguments: `$ARGUMENTS`
@@ -52,6 +82,35 @@ Request:
 No "Additional Context" section is needed for curiosity-engine (prompts are
 self-contained).
 
+Note: do NOT pass PaF flags like `--no-include-diff`, `--fast`, or
+`--session` in direct mode. They are CLI flags on the `phone-a-friend`
+binary; the underlying backend CLIs do not accept them.
+
+## Diff suppression
+
+`/curiosity-engine` rounds use self-contained prompts; the working-tree diff
+would be irrelevant noise. PaF reads `defaults.include_diff` from user
+config, so without explicit suppression a user with `include_diff = true`
+would silently leak the diff into every relay round.
+
+The cleanest flag is `--no-include-diff`, added in phone-a-friend v2.2.0.
+Older binaries reject the flag with `unknown option '--no-include-diff'`.
+Probe once before Round 1, then reuse the gate across every binary-mode
+relay (initial round, follow-up rounds, and the schema re-prompt):
+
+```bash
+if phone-a-friend relay --help 2>/dev/null | grep -q -- '--no-include-diff'; then
+  PAF_NO_DIFF="--no-include-diff"
+else
+  export PHONE_A_FRIEND_INCLUDE_DIFF=false
+  PAF_NO_DIFF=""
+fi
+```
+
+Append `$PAF_NO_DIFF` to every binary-mode `phone-a-friend` invocation in
+the steps below. The env var fallback works in v1.7.2 and later; the
+explicit flag is preferred when available.
+
 ## Step 1 — Parse Arguments
 
 Extract `--topic`, `--rounds`, and `--backend` from `$ARGUMENTS`.
@@ -102,24 +161,29 @@ If `RELAY_MODE = binary`, the binary handles model selection internally.
 
 ## Step 3 — Serve Round 1
 
-Claude serves first. Claude's opening move:
+The orchestrating agent (the host model running this skill) serves first.
+It produces the opening move directly, without relaying to any backend:
 
 ```
 ANSWER: N/A — I'm serving first.
-QUESTION: <Claude's opening question on TOPIC — make it genuinely curious and specific>
+QUESTION: <orchestrator's opening question on TOPIC — make it genuinely curious and specific>
 ```
 
 Display to user:
 ```
 --- Round 1 of <MAX_ROUNDS> | Topic: <TOPIC> ---
-🤖 Claude  QUESTION: <question>
+🤖 <orchestrator>  QUESTION: <question>
 ```
 
+`<orchestrator>` is the host model's display label (e.g., "Claude" in
+Claude Code, the OpenCode model name in OpenCode). Pick one that the user
+will recognize.
+
 Then relay to backend:
 
 **Binary mode** (`RELAY_MODE = binary`):
 ```bash
-phone-a-friend --to <BACKEND> --repo "$PWD" --sandbox read-only --fast [--model <model>] --prompt "<relay-prompt>"
+phone-a-friend --to <BACKEND> --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF [--model <model>] --prompt "<relay-prompt>"
 ```
 
 **Direct mode** (`RELAY_MODE = direct`):
@@ -137,17 +201,17 @@ curl -s http://localhost:11434/api/chat -H "Content-Type: application/json" \
 Where `<relay-prompt>` is:
 
 ```
-You are playing The Curiosity Engine — a structured Q&A rally with Claude.
+You are playing The Curiosity Engine — a structured Q&A rally with another agent.
 Topic: <TOPIC>
 Round: 1 of <MAX_ROUNDS>
 
-Claude's question for you:
+The orchestrating agent's question for you:
 <QUESTION>
 
 You MUST respond in EXACTLY this format — no exceptions, no extra text:
 
-ANSWER: <your answer to Claude's question, 2-4 sentences>
-QUESTION: <a new question for Claude on the same topic, that you are genuinely curious about>
+ANSWER: <your answer to the orchestrator's question, 2-4 sentences>
+QUESTION: <a new question for the orchestrator on the same topic, that you are genuinely curious about>
 
 Do not add any text before ANSWER: or after the QUESTION line.
 ```
@@ -175,7 +239,7 @@ Send one correction relay if `ANSWER:` or `QUESTION:` is missing:
 
 **Binary mode** (`RELAY_MODE = binary`):
 ```bash
-phone-a-friend --to <BACKEND> --repo "$PWD" --sandbox read-only --fast [--model <model>] --prompt "<re-prompt>"
+phone-a-friend --to <BACKEND> --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF [--model <model>] --prompt "<re-prompt>"
 ```
 
 **Direct mode** (`RELAY_MODE = direct`):
@@ -197,7 +261,7 @@ Your previous response did not follow the required format.
 You MUST respond with EXACTLY this structure:
 
 ANSWER: <your answer>
-QUESTION: <your question for Claude>
+QUESTION: <your question for the orchestrator>
 
 No other text. Try again.
 ```
@@ -219,34 +283,38 @@ Display backend's response:
 
 If this was the final round (ROUND == MAX_ROUNDS) → jump to Step 6 (Synthesis).
 
-Otherwise, increment ROUND. Claude now responds:
+Otherwise, increment ROUND. The orchestrating agent (the host model)
+now responds directly — no relay:
 
 ```
-🤖 Claude  ANSWER: <Claude's genuine answer to backend's question, 2-4 sentences>
-           QUESTION: <Claude's new question for backend on TOPIC>
+🤖 <orchestrator>  ANSWER: <orchestrator's genuine answer to backend's question, 2-4 sentences>
+                   QUESTION: <orchestrator's new question for backend on TOPIC>
 ```
 
-Relay Claude's question to backend using this template (same structure as Step 3, substituting current values):
+Relay the orchestrator's question to backend using this template (same
+structure as Step 3, substituting current values, and reusing
+`$PAF_NO_DIFF` for binary mode):
 
 ```
-You are playing The Curiosity Engine — a structured Q&A rally with Claude.
+You are playing The Curiosity Engine — a structured Q&A rally with another agent.
 Topic: <TOPIC>
 Round: <ROUND> of <MAX_ROUNDS>
 
-Claude's question for you:
+The orchestrating agent's question for you:
 <QUESTION>
 
 You MUST respond in EXACTLY this format — no exceptions, no extra text:
 
-ANSWER: <your answer to Claude's question, 2-4 sentences>
-QUESTION: <a new question for Claude on the same topic, that you are genuinely curious about>
+ANSWER: <your answer to the orchestrator's question, 2-4 sentences>
+QUESTION: <a new question for the orchestrator on the same topic, that you are genuinely curious about>
 
 Do not add any text before ANSWER: or after the QUESTION line.
 ```
 
 Repeat Step 4 and Step 5 until MAX_ROUNDS reached or early termination.
 
-**Claude's discipline:** Claude ALWAYS provides both ANSWER: and QUESTION: — never skips either field, never breaks the schema itself.
+**Orchestrator discipline:** the host model ALWAYS provides both ANSWER:
+and QUESTION: — never skips either field, never breaks the schema itself.
 
 ## Step 6 — Final Synthesis
 
@@ -274,7 +342,7 @@ Present the full session summary:
 
 ### Most Interesting Exchange
 
-<Claude picks the sharpest Q&A pair from the transcript and explains in 2-3 sentences why it was the most interesting — what tension, insight, or surprise it revealed>
+<orchestrator picks the sharpest Q&A pair from the transcript and explains in 2-3 sentences why it was the most interesting — what tension, insight, or surprise it revealed>
 
 ---
 
@@ -295,7 +363,7 @@ When BACKEND=gemini, the relay command must include `--model`:
 
 **Binary mode:**
 ```bash
-phone-a-friend --to gemini --model gemini-2.5-flash --repo "$PWD" --sandbox read-only --fast --prompt "<relay-prompt>"
+phone-a-friend --to gemini --model gemini-2.5-flash --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF --prompt "<relay-prompt>"
 ```
 
 **Direct mode:**
@@ -309,7 +377,7 @@ Do NOT use aliases like `auto`, `pro`, or `flash` — always use the full model
 ## Constraints
 
 - MAX_ROUNDS clamped to [1, 6]. Never exceed.
-- Both sides must always produce ANSWER: and QUESTION:. Claude never breaks the schema.
+- Both sides must always produce ANSWER: and QUESTION:. The orchestrator never breaks the schema.
 - One re-prompt allowed per round on schema violation. Two strikes = early termination.
 - No nested curiosity-engine sessions.
 - phone-a-friend is used as a black box — do not modify its internals.

package/commands/phone-a-friend.md

@@ -1,6 +1,6 @@
 ---
 name: phone-a-friend
-description: Relay task context + latest response to a backend (Codex, Gemini, or Ollama) for feedback, then continue with that feedback.
+description: Ask Codex, Gemini, Claude, or Ollama for a second opinion through the phone-a-friend CLI while preserving the user's request in --prompt.
 argument-hint: [optional review focus]
 ---
 
@@ -10,7 +10,34 @@ Use this command after an assistant reply you want reviewed by another AI.
 
 ## Goal
 
-Send compact task context + the latest assistant reply to a backend (Codex, Gemini, or Ollama) using `phone-a-friend`, then bring the feedback back into the current conversation.
+Send compact task context + the latest assistant reply to a backend (Codex,
+Gemini, Claude, or Ollama) using `phone-a-friend`, then bring the feedback back
+into the current conversation.
+
+## Execution rules
+
+- Preserve the user's actual request in `--prompt`. Do not drop it.
+- Do not run a bare `phone-a-friend --to <backend> --review` unless the user
+  explicitly asks to review the current diff, branch changes, or staged changes.
+- If the user asks for a repo sanity check, architecture opinion, plan critique,
+  or general second opinion, use normal prompt mode with `--repo "$PWD"`.
+- If the user says not to edit files, keep that instruction in `--prompt`.
+- Suppress the working-tree diff by default (see "Diff suppression" below);
+  only include the diff when the user explicitly asked to review the diff,
+  branch changes, or staged changes.
+- One backend per call. Never pass comma-separated values to `--to` (e.g.
+  `phone-a-friend --to codex,gemini`). To consult multiple models, run
+  separate `phone-a-friend` calls. The `/phone-a-team` slash command
+  orchestrates that for you in Claude Code.
+- `curiosity-engine` is a host slash command / Agent Skill, not a PaF CLI
+  subcommand. Never run `phone-a-friend curiosity-engine`. Same shape rule
+  applies to any other slash command: never invoke them as PaF
+  subcommands (e.g. `phone-a-friend phone-a-team`).
+- `--backend` is a `/phone-a-team` skill argument, not a PaF CLI flag. Do
+  not pass `--backend` to `phone-a-friend`.
+- Do NOT dump repo files or git output into `--context-file` or
+  `--context-text`. Repo-aware backends read files via `--repo "$PWD"`
+  using their own tools. See "Context hygiene" below.
 
 ## Inputs
 
@@ -53,9 +80,65 @@ Additional Context:
 <context-payload>
 ```
 
-In direct mode, also verify the backend CLI is available (`command -v codex` or
-`command -v gemini`) before calling it. If not found, tell the user how to
-install it and stop.
+In direct mode, also verify the backend CLI is available (`command -v codex`
+or `command -v gemini`) before calling it. If not found, tell the user how
+to install it and stop.
+
+Note: do NOT pass PaF flags like `--no-include-diff`, `--fast`, or
+`--session` in direct mode. Those are CLI flags on the `phone-a-friend`
+binary; the underlying backend CLIs do not accept them.
+
+## Context hygiene
+
+Do not generate `--context-file` or `--context-text` from repository files,
+`git show`, `git diff`, `git status`, or other local file/git output. Do
+not create temp files just to pass repo content. For repo-aware backends
+(codex, gemini, claude, opencode), pass `--repo "$PWD"` and let the
+backend inspect files with its own tools.
+
+`--context-file` and `--context-text` are reserved for **narrative
+context that is not already in the repo** — for example: conversation
+history that the backend cannot see, your own analysis, user constraints,
+prior model output you want reviewed. These remain valid and useful.
+
+Inlining repo content is wasteful, can leak tracked uncommitted edits or
+committed secrets into the relay payload, and bypasses the backend's
+normal file-access controls.
+
+Backend exception: `ollama` has `localFileAccess: false` and cannot read
+the repo on its own. For Ollama specifically, ask the user before sending
+file content, and send a minimal excerpt rather than bulk-dumping files
+or git output.
+
+## Diff suppression
+
+PaF reads `defaults.include_diff` from user config. If a user has
+`include_diff = true` set, every relay would silently leak the working-tree
+diff into the prompt. To prevent that, every binary-mode relay must suppress
+the diff explicitly.
+
+The cleanest flag is `--no-include-diff`, which was added in
+phone-a-friend v2.2.0 (the same release that introduced this command).
+Older binaries reject the flag with `unknown option '--no-include-diff'`.
+Probe once at the start of the workflow, then reuse the gate:
+
+```bash
+if phone-a-friend relay --help 2>/dev/null | grep -q -- '--no-include-diff'; then
+  PAF_NO_DIFF="--no-include-diff"
+else
+  export PHONE_A_FRIEND_INCLUDE_DIFF=false
+  PAF_NO_DIFF=""
+fi
+```
+
+Then append `$PAF_NO_DIFF` to every binary-mode `phone-a-friend` invocation.
+The env var fallback works in v1.7.2 and later; the explicit flag is
+preferred when available because it doesn't leak the override into child
+processes.
+
+Only when the user explicitly asked to review the diff, branch changes, or
+staged changes, swap `$PAF_NO_DIFF` for `--include-diff` (and prefer
+`phone-a-friend ... --review` for branch-level reviews).
 
 ## Workflow
 
@@ -85,11 +168,17 @@ I'm working on this task and got the above response. Please review it and return
 
    **Binary mode** (`RELAY_MODE = binary`):
    ```bash
-   phone-a-friend --to codex --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" [--fast] [--session <id>]
-   # For gemini, always include --model (see "Gemini Model Priority" below):
-   phone-a-friend --to gemini --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" --model <model> [--fast] [--session <id>]
+   phone-a-friend --to codex --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" $PAF_NO_DIFF [--fast] [--session <id>]
+   # For gemini, always include --model (see "Gemini Model Priority" below).
+   # Do NOT pass --session to gemini — it will error (see "Session continuity" below):
+   phone-a-friend --to gemini --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" --model <model> $PAF_NO_DIFF [--fast]
    ```
 
+   `$PAF_NO_DIFF` comes from the probe in "Diff suppression" above. It
+   resolves to `--no-include-diff` on new binaries and an empty string on
+   stale binaries (with `PHONE_A_FRIEND_INCLUDE_DIFF=false` exported as
+   the fallback).
+
    See "Speed optimization" and "Session continuity" below for when to
    include `--fast` and `--session`.
 
@@ -105,7 +194,9 @@ I'm working on this task and got the above response. Please review it and return
    "Direct call reference" section, substituting `<relay-prompt>` and
    `<context-payload>` into the template.
 
-   Note: `--fast` and `--session` are only available in binary mode.
+   Note: `--fast`, `--session`, and `--no-include-diff` are PaF CLI flags
+   only available in binary mode. Do not append them to direct-mode
+   invocations of `codex` or `gemini`.
 
 5. Return backend feedback in concise review format:
    - Critical issues
@@ -122,13 +213,14 @@ When building binary-mode relay commands, add `--fast` if ALL of these are true:
   CLAUDE.md rules that the backend needs to read
 - The task does NOT need MCP tools (GitHub API, Slack, database queries)
 
-`--fast` skips loading project context (CLAUDE.md, MCP servers, skills,
-hooks) for the Claude backend. It is a no-op for Codex, Gemini, and Ollama,
-but safe to include regardless of backend.
+`--fast` maps to `--pure` for OpenCode, skipping external plugins. It is a
+no-op for Claude, Codex, Gemini, and Ollama. Claude intentionally does not
+use `--bare` because bare mode skips OAuth/keychain reads and can break
+subscription auth.
 
 Most `/phone-a-friend` relay calls are self-contained reviews where the
-context is already in the prompt. Default to including `--fast` unless the
-task clearly needs project context.
+context is already in the prompt. Default to including `--fast`; it is
+harmless for Claude/Codex/Gemini/Ollama and meaningful for OpenCode.
 
 ## Session continuity
 
@@ -144,7 +236,7 @@ wants the same backend to apply fixes or dig deeper), reuse the session:
 3. On **subsequent** relays to the **same backend** in the same
    conversation, reuse the same session ID. The backend remembers previous
    turns.
-4. If switching backends (e.g., first call to codex, second to gemini),
+4. If switching backends (e.g., first call to codex, second to ollama),
    generate a new session ID for the new backend. Sessions are
    backend-specific.
 
@@ -152,13 +244,20 @@ Benefits: the backend keeps full conversation history, so follow-up prompts
 can be shorter (no need to re-send context from previous turns).
 
 **Backend-specific behavior:**
-- **Claude, Codex**: native session resume. Follow-up prompts can send
-  deltas only.
-- **Ollama**: replays full history each call. Sessions work but prompt size
-  grows with each turn. Keep follow-ups concise.
-- **Gemini**: session resume is best-effort (may start fresh). Always
-  include enough context for Gemini to answer independently, even in
-  follow-up calls.
+- **Codex, Claude, OpenCode**: native session resume. Follow-up prompts
+  can send deltas only.
+- **Ollama**: replays full history each call. Sessions work but prompt
+  size grows with each turn. Keep follow-ups concise.
+- **Gemini**: `--session` is **not supported**. PaF rejects it with a
+  RelayError (`--session is not supported by the gemini backend ...`).
+  Each Gemini relay call must be self-contained. Do not pass `--session`
+  with `--to gemini`.
+
+On the FIRST relay under a new session label, PaF prints an informational
+stderr line: `[phone-a-friend] Session label "..." not found in store.
+Starting a fresh session under this label.` This is expected. The hint
+about `--backend-session` in that line is for advanced use (see below)
+and not relevant to the typical `/phone-a-friend` flow.
 
 **Omit `--session`** for one-off relays where no follow-up is expected.
 This is the common case. Only add `--session` when the user explicitly
@@ -166,6 +265,25 @@ asks for a follow-up or continuation of a previous relay.
 
 Session continuity is only available in binary mode (`RELAY_MODE = binary`).
 
+### Advanced: `--backend-session` (raw thread ID adoption)
+
+If the user explicitly provides a Codex/Claude/OpenCode backend thread ID
+that PaF did not create (e.g., from another tool or a previous CLI run),
+attach to it with `--backend-session <id>` instead of `--session <id>`.
+Combine with `--session <label>` to also start tracking under a label.
+
+```bash
+# Resume a raw backend thread once (no PaF persistence):
+phone-a-friend --to codex --repo "$PWD" --backend-session <thread-id> --prompt "<...>" $PAF_NO_DIFF
+
+# Adopt: resume AND start tracking under a PaF label going forward:
+phone-a-friend --to codex --repo "$PWD" --session <label> --backend-session <thread-id> --prompt "<...>" $PAF_NO_DIFF
+```
+
+This is rarely the right move from inside a Claude Code conversation — the
+common case is `--session <label>` with a fresh label. Only use
+`--backend-session` when the user supplied a specific backend thread ID.
+
 ## Gemini Model Priority
 
 When using `--to gemini`, **always** pass `--model` using the first model from
@@ -214,6 +332,10 @@ This does NOT apply to `--to codex`.
 
 ## Notes
 
-- Prefer `--context-text` for small payloads.
+- Prefer `--context-text` for small narrative payloads.
 - `--context-file` and `--context-text` are mutually exclusive.
-- If context is too large for inline args, use a repo-local temp file.
+- If your narrative context is too large for inline args, write it to a
+  temp file outside the repo (e.g. under `/tmp`). Do NOT use a repo-local
+  temp file — it muddies git status and risks accidental commit. Repo
+  content itself does not need a temp file at all; see "Context hygiene"
+  above.