fix: add Claude CLI flag passthrough and relax /spec permission mode enforcement

Author: maxritter

README.md

@@ -218,14 +218,24 @@ Investigation-first workflow for targeted fixes. Finds the root cause before tou
 
 Just chat — no plan, no approval gate. Quality hooks and TDD enforcement still apply. Best for small tasks and exploration. For anything that needs a plan, use `/spec` — not Claude Code's built-in plan mode.
 
+### Claude CLI Flag Passthrough
+
+All Claude Code CLI flags work directly with `pilot` — current and future. Pilot forwards any flag it doesn't recognize to the Claude CLI automatically.
+
+```bash
+pilot --channels plugin:telegram@claude-plugins-official
+pilot --model opus --verbose
+pilot --resume
+```
+
 ### Headless Mode
 
-Run Pilot non-interactively with `-p` for CI/CD pipelines, scripts, and automated workflows. All Claude Code CLI flags work — `--output-format`, `--allowedTools`, `--continue`, `--bare`, etc.
+Run Pilot non-interactively with `-p` for CI/CD pipelines, scripts, and automated workflows. All Claude Code CLI flags work — `--output-format`, `--allowedTools`, `--channels`, `--continue`, `--bare`, etc.
 
 ```bash
 pilot -p "Run tests and fix failures" --allowedTools "Bash,Read,Edit"
 pilot -p "Summarize this project" --output-format json
-pilot -p "Review this PR for security issues" --bare --allowedTools "Read"
+pilot --channels plugin:telegram@official -p "Check messages"
 ```
 
 ### /setup-rules — Generate Modular Rules

docs/docusaurus/docs/features/cli.md

@@ -10,6 +10,23 @@ Command reference for the `pilot` binary at `~/.pilot/bin/pilot`.
 
 Run `pilot` or `ccp` with no arguments to start Claude with Pilot enhancements. Most commands support `--json` for structured output. Multiple sessions can run in parallel on the same project.
 
+## Claude CLI Flag Passthrough
+
+Pilot forwards any unrecognized flags directly to the Claude CLI. This means all current and future Claude Code flags work out of the box — no Pilot update required.
+
+```bash
+# Use any Claude CLI flag directly
+pilot --channels plugin:telegram@claude-plugins-official
+pilot --model opus --verbose
+pilot --resume
+pilot --continue
+
+# 'run' is an explicit alias — same behavior
+pilot run --channels plugin:telegram@claude-plugins-official
+```
+
+Pilot only intercepts its own subcommands (`activate`, `status`, `worktree`, etc.) and flags (`--version`, `--skip-update-check`). Everything else passes through to `claude`.
+
 ## Headless Mode
 
 Run Pilot non-interactively with `-p` (or `--print`). Wraps `claude -p` with license validation and the Pilot plugin — use it in CI/CD pipelines, scripts, or automated workflows.
@@ -24,8 +41,8 @@ pilot -p "Summarize this project" --output-format json
 # Auto-approve specific tools
 pilot -p "Run tests and fix failures" --allowedTools "Bash,Read,Edit"
 
-# Streaming output
-pilot -p "Explain recursion" --output-format stream-json --verbose
+# With channels
+pilot --channels plugin:telegram@claude-plugins-official -p "Check messages"
 
 # Continue a previous conversation
 pilot -p "Now focus on the database queries" --continue
@@ -34,15 +51,16 @@ pilot -p "Now focus on the database queries" --continue
 pilot -p "Summarize this file" --bare --allowedTools "Read"
 ```
 
-All [Claude Code CLI flags](https://code.claude.com/docs/en/cli-reference) work with `-p`, including `--output-format`, `--allowedTools`, `--continue`, `--resume`, `--append-system-prompt`, `--json-schema`, and `--bare`. Pilot-specific flags like `--skip-update-check` are stripped automatically.
+All [Claude Code CLI flags](https://code.claude.com/docs/en/cli-reference) work with `-p`, including `--output-format`, `--allowedTools`, `--continue`, `--resume`, `--channels`, `--append-system-prompt`, `--json-schema`, and `--bare`. Pilot-specific flags like `--skip-update-check` are stripped automatically.
 
 ## Session & Context
 
 | Command | Description |
 |---------|-------------|
 | `pilot` | Start Claude with Pilot enhancements, auto-update, and license check |
+| `pilot [claude-flags...]` | Start Claude with any Claude CLI flags passed through |
 | `pilot -p "prompt" [flags...]` | Headless mode — run non-interactively with Pilot plugin (CI/CD, scripts) |
-| `pilot run [args...]` | Same as interactive, with optional flags (`--skip-update-check`) |
+| `pilot run [flags...]` | Explicit alias for starting Claude (all flags passed through) |
 | `ccp` | Alias for pilot |
 | `pilot check-context --json` | Get current context usage percentage |
 | `pilot register-plan <path> <status>` | Associate a plan file with the current session |

docs/docusaurus/docs/features/remote-control.md

@@ -84,6 +84,29 @@ For the SSH/Termius approach, you need network connectivity to your computer. In
 | **Quick check** | Glance at a running session from your phone without going back to your desk |
 | **Multi-device** | Heavy coding from terminal, lighter interactions from browser, quick approvals from phone |
 
+## Channels — Telegram, Discord & iMessage
+
+[Channels](https://code.claude.com/docs/en/channels) push messages from external platforms directly into your running Pilot session. Claude reads the message, acts on it with your full local environment, and replies back through the same platform.
+
+```bash
+# Start Pilot with a channel enabled
+pilot --channels plugin:telegram@claude-plugins-official
+pilot --channels plugin:discord@claude-plugins-official
+pilot --channels plugin:imessage@claude-plugins-official
+```
+
+Channels require [Bun](https://bun.sh/) and a one-time bot setup (Telegram/Discord) or macOS (iMessage). Each channel maintains a sender allowlist — only paired users can push messages.
+
+| Channel | Setup | Pairing |
+| ------- | ----- | ------- |
+| **Telegram** | [Create a bot](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram), pass token during install | Send any message to the bot → approve pairing code in terminal |
+| **Discord** | [Create a bot](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord), pass token during install | Send any message to the bot → approve pairing code in terminal |
+| **iMessage** | [macOS only](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage), no token needed | Texting yourself works automatically |
+
+**Channels vs Remote Control:** Remote Control gives you a window into your session from the Claude App or browser. Channels let external platforms push events *into* your session — they're complementary. Use both together: channels for incoming messages, Remote Control for monitoring and steering.
+
+**Team/Enterprise:** Channels are off by default. Admins enable them via [claude.ai Admin settings](https://claude.ai/admin-settings/claude-code). See the full [Channels documentation](https://code.claude.com/docs/en/channels) and [Channels reference](https://code.claude.com/docs/en/channels-reference) for building custom channels.
+
 ## Troubleshooting
 
 If Remote Control doesn't connect or shows authentication errors, run `/logout` followed by `/login` inside Claude Code. This re-authenticates your session and resolves most connection issues.

launcher/cli.py

@@ -35,14 +35,11 @@ model: sonnet
 
 ## 0.0 Permission Mode Pre-Flight Check
 
-**⛔ Before ANY other step, check if the spec_mode_guard hook injected a permission mode warning.** If you see a system-reminder containing "Current permission mode is" or "requires 'bypassPermissions' mode", you MUST:
+**Before proceeding, check if the spec_mode_guard hook injected a permission mode note.** If you see a system-reminder containing "Current permission mode is", briefly warn the user:
 
-1. Tell the user their current mode is not optimal for `/spec` autonomous execution
-2. Instruct them to press **Shift+Tab** to cycle to **Bypass Permissions** mode
-3. **STOP** — do NOT read env vars, invoke any skill, or proceed with the workflow
-4. Wait for the user to confirm they have switched, then re-invoke `/spec` with the same arguments
+> "Your current permission mode is **{mode}**. For uninterrupted `/spec` execution, **Bypass Permissions** mode is recommended (Shift+Tab to cycle). Proceeding — the workflow may pause for permission prompts."
 
-**This check takes priority over all workflow steps below.** The hook warning is authoritative — never override it.
+**Then continue with the workflow.** Do not stop or wait for the user to switch. The user's mode choice is respected — bypass permissions is recommended, not required.
 
 ---
 

launcher/config.py

@@ -51,10 +51,10 @@ def run_spec_mode_guard() -> int:
                     "hookSpecificOutput": {
                         "hookEventName": "UserPromptSubmit",
                         "additionalContext": (
-                            f"WARNING: Current permission mode is '{permission_mode}'. "
-                            "The /spec workflow requires 'bypassPermissions' mode for autonomous execution. "
-                            "Tell the user to press Shift+Tab to cycle to 'Bypass Permissions' mode before proceeding. "
-                            "Do NOT invoke the /spec skill until the user confirms they have switched."
+                            f"NOTE: Current permission mode is '{permission_mode}'. "
+                            "For uninterrupted /spec execution, 'bypassPermissions' mode is recommended "
+                            "(Shift+Tab to cycle). In the current mode the workflow may pause for "
+                            "permission prompts. Briefly warn the user, then proceed with the workflow."
                         ),
                     }
                 }

launcher/tests/unit/test_cli.py

@@ -64,20 +64,32 @@ def test_warns_in_default_mode(self):
         ctx = result["hookSpecificOutput"]["additionalContext"]
         assert "default" in ctx
         assert "bypassPermissions" in ctx
+        assert "proceed" in ctx.lower()
 
     def test_warns_in_accept_edits_mode(self):
         code, output = _run_with_input("/spec fix bug", "acceptEdits")
         assert code == 0
         result = json.loads(output)
         ctx = result["hookSpecificOutput"]["additionalContext"]
         assert "acceptEdits" in ctx
+        assert "proceed" in ctx.lower()
 
     def test_warns_in_dont_ask_mode(self):
         code, output = _run_with_input("/spec fix bug", "dontAsk")
         assert code == 0
         result = json.loads(output)
         ctx = result["hookSpecificOutput"]["additionalContext"]
         assert "dontAsk" in ctx
+        assert "proceed" in ctx.lower()
+
+    def test_warning_does_not_block(self):
+        """Non-bypass modes must NOT instruct the LLM to stop."""
+        for mode in ("default", "acceptEdits", "dontAsk"):
+            code, output = _run_with_input("/spec fix bug", mode)
+            assert code == 0
+            ctx = json.loads(output)["hookSpecificOutput"]["additionalContext"]
+            assert "Do NOT" not in ctx
+            assert "STOP" not in ctx
 
 
 class TestNonSpecPrompts:

pilot/commands/spec.md

@@ -118,6 +118,8 @@ This rule is about git commands, not file operations. Editing files is always al
 
 **⛔ Never selectively unstage.** Commit ALL staged changes as-is.
 
+**⛔ Always `git push -u` on new branches.** When pushing a newly created branch for the first time, use `git push -u origin <branch>` (or `--set-upstream`) so the local branch tracks the correct remote. Without `-u`, the upstream stays on the old branch (e.g. `origin/master`), breaking subsequent pushes from IDEs and CLI.
+
 **Read commands — always allowed:** `git status`, `diff`, `log`, `show`, `branch`
 
 **Exceptions:** Explicit user override ("checkout branch X") and worktree during `/spec` (`Worktree: Yes`).