@freibergergarcia/phone-a-friend 2.2.1 → 2.3.1

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.2.1",
+  "version": "2.3.1",
   "author": {
     "name": "Bruno Freiberger"
   }

package/README.md

@@ -116,7 +116,7 @@ Delegate a task to any backend and get the result back:
 
 ```bash
 phone-a-friend --to codex --prompt "Review this code"
-phone-a-friend --to gemini --prompt "Analyze the architecture" --model gemini-2.5-flash
+phone-a-friend --to gemini --prompt "Analyze the architecture"
 phone-a-friend --to claude --prompt "Refactor this module"
 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)
@@ -218,6 +218,7 @@ Ollama configuration via environment variables:
 Phone-a-friend environment variables:
 - `PHONE_A_FRIEND_INCLUDE_DIFF=false` -- disable diff inclusion globally (equivalent to `--no-include-diff` on every call).
 - `PHONE_A_FRIEND_HOST=opencode` -- mark the calling process as OpenCode for the recursion guard (set automatically by the OpenCode shims).
+- `PHONE_A_FRIEND_GEMINI_DEAD_CACHE=false` -- bypass the Gemini dead-model cache (debugging stale entries).
 
 OpenCode configuration via TOML:
 ```toml
@@ -325,6 +326,14 @@ npm test                 # Run tests (vitest)
 npm run typecheck        # Type check (tsc --noEmit)
 ```
 
+## Privacy
+
+Phone a Friend does not collect, transmit, or store any data on servers operated by this project. There is no telemetry and no analytics.
+
+Prompts and repository context are passed only to backends you have installed and authenticated yourself: the Claude, Codex, Gemini, and OpenCode CLIs, or a local Ollama instance. Each backend is governed by its own provider's privacy policy and terms.
+
+Local state (config, sessions, jobs, agentic transcripts, and the web dashboard event log) is written only to `~/.config/phone-a-friend/` on your machine. The web dashboard is served on `localhost` and is not exposed to the network.
+
 ## License
 
 Apache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

package/commands/curiosity-engine.md

@@ -351,28 +351,33 @@ Present the full session summary:
 <2-3 questions raised during the rally that weren't followed up on, worth exploring in a future session>
 ```
 
-## Gemini Model Priority
+## Gemini model selection
 
-When BACKEND=gemini, always pass `--model` using the first available model from this list:
+For BACKEND=gemini, **omit `--model` by default** and let Gemini CLI's
+auto-routing pick. Set `--model` only when reproducibility, specific
+capability, or debugging requires a pin.
 
-1. `gemini-2.5-flash` — reliable, confirmed working
-2. `gemini-2.5-pro` — higher capability, frequently at capacity (429)
-3. `gemini-2.5-flash-lite` — last resort
+**Binary mode** (preferred — when a pinned model returns a strong 404
+`ModelNotFoundError`, PaF caches it for 24h at
+`~/.config/phone-a-friend/gemini-models.json` and surfaces a clear error
+with cache path, expiry, and bypass instructions; no auto-substitution):
 
-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 $PAF_NO_DIFF --prompt "<relay-prompt>"
+phone-a-friend --to gemini --repo "$PWD" --sandbox read-only --fast $PAF_NO_DIFF --prompt "<relay-prompt>"
 ```
 
-**Direct mode:**
+To bypass the cache: `PHONE_A_FRIEND_GEMINI_DEAD_CACHE=false`. Or delete the
+cache file to clear it.
+
+**Direct mode** (no PaF wrapper — orchestrator handles retry):
 ```bash
-gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m gemini-2.5-flash --prompt "<relay-prompt>"
+gemini --sandbox --yolo --include-directories "$PWD" --output-format text --prompt "<relay-prompt>"
 ```
 
-On capacity/transient errors (429, 500, 503), try the next model before treating as round failure.
-Do NOT use aliases like `auto`, `pro`, or `flash` — always use the full model name.
+In direct mode, on capacity/transient errors (429, 500, 503), retry with a
+different model before treating as round failure. On `ModelNotFoundError`,
+surface immediately. Either omit `--model` entirely or pass a concrete
+model name; do NOT use aliases like `auto`, `pro`, or `flash`.
 
 ## Constraints
 

package/commands/phone-a-friend.md

@@ -169,9 +169,9 @@ 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>" $PAF_NO_DIFF [--fast] [--session <id>]
-   # For gemini, always include --model (see "Gemini Model Priority" below).
+   # For gemini, omit --model by default (let auto-routing pick); see "Gemini model selection" 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]
+   phone-a-friend --to gemini --repo "$PWD" --prompt "<relay-prompt>" --context-text "<context-payload>" $PAF_NO_DIFF [--fast]
    ```
 
    `$PAF_NO_DIFF` comes from the probe in "Diff suppression" above. It
@@ -186,8 +186,8 @@ I'm working on this task and got the above response. Please review it and return
    ```bash
    # Codex:
    codex exec -C "$PWD" --skip-git-repo-check --sandbox read-only "<combined-prompt>" < /dev/null
-   # Gemini (always include -m, see "Gemini Model Priority" below):
-   gemini --sandbox --yolo --include-directories "$PWD" --output-format text -m <model> --prompt "<combined-prompt>"
+   # Gemini (omit -m for auto-routing; pin only when reproducibility/capability is needed):
+   gemini --sandbox --yolo --include-directories "$PWD" --output-format text --prompt "<combined-prompt>"
    ```
 
    In direct mode, build `<combined-prompt>` using the template from the
@@ -284,51 +284,55 @@ 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
+## Gemini model selection
 
-When using `--to gemini`, **always** pass `--model` using the first model from
-this priority list. Never use aliases (`auto`, `pro`, `flash`) — use concrete
-model names only:
+By default, **omit `--model`** for `--to gemini` and let Gemini CLI's
+auto-routing pick. This mirrors how `--to codex` and `--to claude` are used
+in this command — the CLI's own default is the right default. Pinning
+`--model` ages docs poorly; auto-routing tracks deployed models for you.
 
-### Why we bypass auto-routing
+Set `--model` explicitly only when you need:
 
-Gemini CLI has built-in model fallback via auto mode, but it does NOT work in
-headless/non-interactive mode. `--yolo` (and `--approval-mode yolo`) only
-auto-approve tool calls, not model switch prompts. When Gemini hits a capacity
-error in headless mode, it tries to prompt for consent and fails
-(`google-gemini/gemini-cli#13561`). By passing `--model` explicitly, we bypass
-this broken behavior and handle retry/fallback ourselves.
+- **Reproducibility** — pinning produces deterministic behavior across runs.
+- **Capability** — a more capable model for a specific task (e.g.,
+  `--model gemini-2.5-pro` for a hard review, accepting more 429s).
+- **Debugging** — isolating model behavior from auto-routing changes.
 
-### Priority rationale
+### Cache-aware failure for explicit pins
 
-As of 2026-02-22, `gemini-3.1-pro-preview-*` models return 404 (not yet
-deployed) and `gemini-2.5-pro` is perpetually at capacity (429). Based on
-empirical testing across 10+ relay sessions, `gemini-2.5-flash` is the only
-model that reliably works. Lead with what works; fall forward to newer models
-as they become available.
+When you pin a model and it returns a strong 404 (`ModelNotFoundError`),
+PaF caches it as unavailable for 24h at
+`~/.config/phone-a-friend/gemini-models.json` and surfaces a clear error
+that includes the cache path, expiry timestamp, and bypass instructions.
+PaF does **not** auto-substitute another model — explicit pins surface
+explicit failures so the caller decides whether to retry, switch model,
+or omit `--model` and rely on auto-routing.
 
-1. `gemini-2.5-flash` — reliable, fast, confirmed working
-2. `gemini-2.5-pro` — higher capability but frequently at capacity (429)
-3. `gemini-2.5-flash-lite` — last resort
-4. `gemini-3.1-pro-preview-customtools` — not yet deployed (404 as of 2026-02-22)
-5. `gemini-3.1-pro-preview` — not yet deployed (404 as of 2026-02-22)
+What is and isn't cached:
 
-### Fallback rule
+- **Cached** (24h): strong 404 (`ModelNotFoundError` from gemini-cli's own classifier).
+- **Not cached**: ambiguous 404s (could be a missing project / file, not the model), 429 / RESOURCE_EXHAUSTED, authentication failures, any other error class.
+- **Not consulted**: when `--model` is unset (auto-routing), or during session resume (`--resume`).
 
-On Gemini relay failure, retry with the next model **only** for transient or
-capacity errors:
+To bypass the cache (debugging stale entries, testing recovery):
 
-- **Retry with next model**: HTTP 429, 499, 500, 503, 504; RESOURCE_EXHAUSTED;
-  "high demand"; model not found; transient/timeout errors
-- **Do NOT retry**: authentication failures, invalid arguments, prompt errors,
-  permission errors
-- **Default**: if an error cannot be confidently classified as transient, do
-  NOT model-fallback — report the error immediately
+```bash
+PHONE_A_FRIEND_GEMINI_DEAD_CACHE=false phone-a-friend --to gemini --model X --prompt "..."
+```
+
+Or delete `~/.config/phone-a-friend/gemini-models.json` to clear it.
+
+### Direct Gemini CLI mode
+
+When the orchestrator is calling `gemini` directly (no PaF wrapper), the
+dead-model cache does NOT apply — the orchestrator is responsible for any
+retry. Retry rules in direct mode:
 
-After exhausting all models, stop and report the error with the list of
-attempted models.
+- **Retry**: HTTP 429, 499, 500, 503, 504; RESOURCE_EXHAUSTED; transient/timeout errors.
+- **Do NOT retry**: authentication failures, invalid arguments, permission errors, model-not-found.
+- **Default**: if an error cannot be confidently classified as transient, surface it immediately.
 
-This does NOT apply to `--to codex`.
+This does NOT apply to `--to codex` or `--to claude`.
 
 ## Notes
 

package/commands/phone-a-team.md

@@ -269,7 +269,7 @@ Resolution matrix:
 | Friend backend | Include when |
 |----------------|--------------|
 | `codex`        | `command -v codex` AND `codex --version` succeeds |
-| `gemini`       | `command -v gemini` succeeds (auth verified at first relay; transient errors handled by Gemini Model Priority retry rules) |
+| `gemini`       | `command -v gemini` succeeds (auth verified at first relay; transient errors handled by Gemini auto-routing) |
 | `ollama`       | `curl -sf "${OLLAMA_HOST:-http://localhost:11434}/api/tags"` succeeds AND parsed `models[]` has at least one entry |
 | `claude`       | `command -v claude` AND `claude --version` succeeds. Claude is excluded by default when this skill is running inside Claude Code (we are already orchestrating with Claude). Include only when the user explicitly asked for Claude in addition |
 | `opencode`     | `command -v opencode` succeeds AND the host is NOT OpenCode (`PHONE_A_FRIEND_HOST=opencode` means we are inside OpenCode; relaying back to opencode is blocked by the recursion guard regardless) |
@@ -525,7 +525,7 @@ Delegate the task to the backend via the relay. The lead's job is to
   "Direct call reference" section. If `--include-diff` is used, run
   `git diff HEAD` and append the output to the template's "Git Diff" section.
 
-  For gemini, always include `--model` / `-m` per the Gemini Model Priority section.
+  For gemini, omit `--model` by default and let auto-routing pick (see "Gemini model selection" section).
   For ollama, always include `--model` / model field using `OLLAMA_SELECTED_MODEL` from preflight.
 - **Both backends**: Relay to each backend (in parallel if using teams,
   sequentially otherwise). You may give them the same task or different
@@ -804,53 +804,45 @@ happened and whether the result is complete.
   targets *unsolicited* repo-content dumps, not user-requested
   diff-scoped reviews.
 
-## Gemini Model Priority
+## Gemini model selection
 
-When using `--to gemini` (including the gemini side of `--backend both`),
-**always** pass `--model` using the first model from this priority list. Never
-use aliases (`auto`, `pro`, `flash`) — use concrete model names only:
+For `--to gemini` (including the gemini side of `--backend both`), **omit
+`--model` by default** and let Gemini CLI's auto-routing pick. This mirrors
+how `--to codex` and `--to claude` are used in this command — the CLI's own
+default is the right default.
 
-### Why we bypass auto-routing
+Set `--model` explicitly only when reproducibility, specific capability, or
+debugging requires a pin.
 
-Gemini CLI has built-in model fallback via auto mode, but it does NOT work in
-headless/non-interactive mode. `--yolo` (and `--approval-mode yolo`) only
-auto-approve tool calls, not model switch prompts. When Gemini hits a capacity
-error in headless mode, it tries to prompt for consent and fails
-(`google-gemini/gemini-cli#13561`). By passing `--model` explicitly, we bypass
-this broken behavior and handle retry/fallback ourselves.
+### Cache-aware failure for explicit pins
 
-### Priority rationale
+PaF binary mode (`phone-a-friend --to gemini --model X`) caches strong 404s
+(`ModelNotFoundError`) at `~/.config/phone-a-friend/gemini-models.json` for
+24h and surfaces a clear error with the cache path, expiry, and bypass
+instructions. PaF does **not** auto-substitute another model — explicit
+pins surface explicit failures.
 
-As of 2026-02-22, `gemini-3.1-pro-preview-*` models return 404 (not yet
-deployed) and `gemini-2.5-pro` is perpetually at capacity (429). Based on
-empirical testing across 10+ relay sessions, `gemini-2.5-flash` is the only
-model that reliably works. Lead with what works; fall forward to newer models
-as they become available.
+What is and isn't cached:
 
-1. `gemini-2.5-flash` — reliable, fast, confirmed working
-2. `gemini-2.5-pro` — higher capability but frequently at capacity (429)
-3. `gemini-2.5-flash-lite` — last resort
-4. `gemini-3.1-pro-preview-customtools` — not yet deployed (404 as of 2026-02-22)
-5. `gemini-3.1-pro-preview` — not yet deployed (404 as of 2026-02-22)
+- **Cached** (24h): strong 404 (`ModelNotFoundError` from gemini-cli's own classifier).
+- **Not cached**: ambiguous 404s, 429 / RESOURCE_EXHAUSTED, authentication failures, any other error class.
+- **Not consulted**: when `--model` is unset (auto-routing), or during session resume.
 
-### Fallback rule
+To bypass the cache: `PHONE_A_FRIEND_GEMINI_DEAD_CACHE=false`. Or delete the
+cache file to clear it.
 
-On Gemini relay failure, retry with the next model **only** for transient or
-capacity errors:
+### Direct Gemini CLI mode
 
-- **Retry with next model**: HTTP 429, 499, 500, 503, 504; RESOURCE_EXHAUSTED;
-  "high demand"; model not found; transient/timeout errors
-- **Do NOT retry**: authentication failures, invalid arguments, prompt errors,
-  permission errors
-- **Default**: if an error cannot be confidently classified as transient, do
-  NOT model-fallback — treat as immediate round failure
+When invoking `gemini` directly (no PaF wrapper), the dead-model cache does
+NOT apply. Orchestrator-level retry rules:
 
-Model fallback happens **within the current round** (see Step 7 precedence
-rule). After exhausting all models in a round, escalate to round-level retry
-or stop per Step 7. Each new round resets to model #1.
+- **Retry**: HTTP 429, 499, 500, 503, 504; RESOURCE_EXHAUSTED; transient/timeout.
+- **Do NOT retry**: auth failures, invalid args, permission errors, model-not-found.
+- **Default**: surface unclassified errors immediately, do not loop.
 
-When reporting errors in synthesis, list all attempted models and the error
-from each.
+Round-level retry: each new round can attempt a different `--model` if the
+prior round failed (see Step 7). When reporting errors in synthesis, list
+the attempted models and each error.
 
 This does NOT apply to `--to codex` or `--to ollama`.