Add local handoff executor

Author: rebel

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.28.0
+
+- Added `codexpro execute-handoff` as an opt-in local executor for `.ai-bridge/current-plan.md`.
+- Added built-in local adapters for `opencode`, `pi`, and `codex`, plus a restricted `--command` template path for custom agents.
+- Added `--dry-run`, `--yes`, timeout handling, stdout/stderr capture, `agent-status.md`, `implementation-diff.patch`, and `execution-log.jsonl` output.
+- Kept `handoff_to_agent` planning-only; local execution is not exposed as a remote MCP tool.
+- Added smoke coverage for dry-run previews, custom command validation, execution status, diff collection, and structured execution logging.
+
 ## 0.27.2
 
 - Added `handoff_to_agent` for file-based handoffs to Codex, OpenCode, Pi, or custom local implementation agents without executing local commands.

README.md

@@ -113,6 +113,10 @@ CodexPro does not bypass, increase, or modify ChatGPT, Codex, or OpenAI rate lim
 - `handoff_to_agent` — write `.ai-bridge/current-plan.md` for Codex, OpenCode, Pi, or a custom local implementation agent without executing local commands.
 - `handoff_to_codex` — compatibility wrapper for `handoff_to_agent` with `agent=codex`.
 
+Local-only companion command:
+
+- `codexpro execute-handoff` — run a previously written `.ai-bridge/current-plan.md` through a local agent, then collect status, logs, and git diff. This is intentionally a CLI command, not a remote MCP tool.
+
 ## Visual ChatGPT cards
 
 v0.8+ registers a reusable Apps SDK widget resource:
@@ -446,13 +450,58 @@ In handoff mode, ChatGPT can create a plan for a local implementation agent with
 .ai-bridge/execution-log.jsonl
 ```
 
-Then run your local agent manually against `.ai-bridge/current-plan.md`, for example:
+Then run the implementation locally with `codexpro execute-handoff`:
 
 ```bash
-opencode run --model provider/cheap-model "$(cat .ai-bridge/current-plan.md)"
+codexpro execute-handoff --agent opencode --model provider/cheap-model
+```
+
+Dry-run first if you want to inspect the exact command:
+
+```bash
+codexpro execute-handoff --agent opencode --model provider/cheap-model --dry-run
+```
+
+Pi adapter:
+
+```bash
+codexpro execute-handoff --agent pi --model provider/cheap-model
+```
+
+Custom adapter:
+
+```bash
+codexpro execute-handoff \
+  --agent custom \
+  --command "my-agent --model {{model}} --task-file {{plan_file}}" \
+  --model provider/cheap-model
 ```
 
-Have the implementation agent update `.ai-bridge/agent-status.md`, write the final review diff to `.ai-bridge/implementation-diff.patch` when practical, and then let ChatGPT review those files through `read_handoff` or `codex_context`.
+Template placeholders:
+
+```text
+{{model}}      model passed with --model
+{{plan_file}}  absolute path to .ai-bridge/current-plan.md
+{{plan_text}}  full plan text as one argument
+{{root}}       workspace root
+```
+
+By default, `execute-handoff` asks for local confirmation before running. Use `--yes` only in trusted scripts. After execution, CodexPro writes:
+
+```text
+.ai-bridge/agent-status.md
+.ai-bridge/implementation-diff.patch
+.ai-bridge/execution-log.jsonl
+```
+
+Then let ChatGPT review those files through `read_handoff` or `codex_context`.
+
+Manual fallback:
+
+```bash
+opencode run --model provider/cheap-model "$(cat .ai-bridge/current-plan.md)"
+git diff --no-ext-diff -- > .ai-bridge/implementation-diff.patch
+```
 
 For debugging whether ChatGPT is actually reaching the local server, add:
 

SECURITY.md

@@ -21,13 +21,15 @@ CodexPro can expose:
 - `.ai-bridge` planning files
 - optional shell command execution through the `bash` tool
 - optional write/edit capability depending on `CODEXPRO_WRITE_MODE`
+- optional local handoff execution through `codexpro execute-handoff`, run from the user's terminal only
 
 The main risks are:
 
 - connecting an untrusted MCP client
 - exposing the server through a public tunnel without auth
 - running with `CODEXPRO_BASH_MODE=full`
 - running with `CODEXPRO_WRITE_MODE=workspace` on an important repo
+- executing an untrusted `.ai-bridge/current-plan.md` or custom `execute-handoff --command`
 - adding overly broad allowed roots
 - leaking a `codexpro_token` or Cloudflare tunnel token
 - trusting a downloaded `cloudflared` binary without understanding where it came from
@@ -72,6 +74,8 @@ codexpro start \
 - Do not commit printed connector URLs that include `codexpro_token`.
 - Do not commit Cloudflare tunnel tokens.
 - Use `--mode handoff` for planning workflows where ChatGPT should not edit source files.
+- Preview local handoff execution with `codexpro execute-handoff --dry-run` before running an unfamiliar adapter or custom command.
+- Keep `execute-handoff` local. Do not wrap it in a remote MCP tool unless you add a stronger approval and sandbox story.
 - Use default agent mode only with trusted ChatGPT sessions and repo-specific roots.
 - Use `--bash full` only for trusted local repos.
 - Prefer a repo-specific `--root` instead of `--allow-home`.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "codexpro",
-  "version": "0.27.2",
+  "version": "0.28.0",
   "description": "A local MCP/App SDK-style connector that lets ChatGPT inspect, edit, and hand off work to Codex inside a local dev workspace.",
   "type": "module",
   "license": "MIT",
@@ -58,7 +58,7 @@
     "start:http": "node dist/http.js",
     "dev:stdio": "tsx src/stdio.ts",
     "dev:http": "tsx src/http.ts",
-    "smoke": "node scripts/smoke.mjs && node scripts/http-smoke.mjs && node scripts/pro-smoke.mjs && node scripts/doctor-smoke.mjs && node scripts/settings-smoke.mjs",
+    "smoke": "node scripts/smoke.mjs && node scripts/http-smoke.mjs && node scripts/pro-smoke.mjs && node scripts/doctor-smoke.mjs && node scripts/settings-smoke.mjs && node scripts/execute-handoff-smoke.mjs",
     "doctor": "node scripts/codexpro.mjs doctor",
     "connect": "node scripts/codexpro.mjs",
     "connect:setup": "node scripts/codexpro.mjs setup",