feat: VCOP-13 per-harness hook responses (Claude, Codex, Gemini, Copilot)

vibecop hook now emits harness-native JSON on stdout instead of relying on
exit codes. None of Claude / Codex / Gemini / Copilot honor the legacy
exit-code contract — approve was a silent no-op and deny did not deny. This
implements the design at docs/superpowers/specs/2026-05-08-per-harness-hook-responses-design.md
and verifies the open detail (Codex/Copilot settings shapes) against current
official docs.

- internal/hooks/responder.go: pure-function WriteVerdict shapes the per-
  (harness, event, verdict) JSON payload. Exits 0 always — fail-open is the
  contract. Unknown combos suppress the [DENY]/[ESCALATE] stderr line.
- internal/hooks/hooks.go: NormalizedRequest gains Event; Codex/Copilot
  payload structs + parsers; DetectAndParse uses hook_event_name with
  per-harness defaults and a Codex-vs-Claude tiebreaker.
- internal/hooks/install.go: installCodexHooks registers under PreToolUse
  AND PermissionRequest (PreToolUse cannot allow on Codex);
  installCopilotHooks writes the flat preToolUse hook with the bash key.
- daemon.Request and daemon.Event gain Harness + HookEvent;
  vibecop.harness + vibecop.hook_event span attrs;
  vibecop.harness label on verdicts_total and evaluator_latency_ms.
- cmd/hook.go: replaces the verdict switch with
  os.Exit(WriteVerdict(...)). cmd/install.go: --harness enum gains
  codex|copilot; --all installs all four.
- docs/spec.md and AGENTS.md (invariant #3): replaced exit-code contract
  with the per-harness JSON contract.

Tests: 155 pass (62 new across responder, parser, install, daemon round-
trip, telemetry attrs).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Eugene Archibald

AGENTS.md

@@ -45,7 +45,7 @@ These are load-bearing. Spec sections in parentheses.
 
 1. **Fail-open everywhere** ("Failure Handling"). If anything in vibecop's own code fails — bad config, daemon down, parse error, LLM 500 — the hook MUST exit 0 so the user's coding agent is never blocked. The one exception: a *successful* `deny` or `escalate` verdict from the LLM exits 1.
 2. **Three consecutive evaluator failures → suspended pass-through** for the rest of the daemon's life (`cmd/start.go`, `maxConsecutiveFailures`). Resume requires `vibecop test` (or restart). Do not change this without updating spec + test (`cmd/handler_test.go`).
-3. **Exit-code contract** ("Exit code contract" table). `approve→0`, `deny→1`, `escalate→1`, timeout→1, daemon unreachable→0. Stderr text is part of the contract — Claude Code and Gemini CLI display it to the user.
+3. **Per-harness JSON response contract** ("Verdict → harness response contract" / "Per-harness JSON shapes" tables). `vibecop hook` always exits 0 — the harness keys off the JSON written to stdout. `approve` emits harness-native "allow" JSON; `deny` emits harness-native "deny" JSON plus `VibeCop [DENY]: <reason>` on stderr; `escalate` emits no JSON and lets the harness's normal flow run. Fail-open paths (parse error, daemon unreachable, unknown harness/event/verdict, marshal failure) emit no JSON and exit 0. The `[DENY]` / `[ESCALATE]` stderr line is gated on the JSON-shaping success path — never written when we couldn't actually emit the deny.
 4. **Project identity = SHA256 of absolute path** (`config.ProjectHash`). Do not hash the basename, do not normalize symlinks. Per-project storage at `~/.vibecop/projects/<hash>/`.
 5. **Activity log is ephemeral, audit log is permanent.** `activity.jsonl` is a rolling window of last `activity_window` verdicts (default 10) used as LLM context. `audit/YYYY-MM-DD.jsonl` is the permanent record, only written when `audit_enabled = true`. Never read audit logs back into prompts.
 6. **`think: false` for Ollama CoT models.** Local endpoints with reasoning models (`qwen3`, `deepseek-r1`) need this in the request body to avoid 30s+ latencies. The injection lives in `internal/evaluator/`.
@@ -66,12 +66,13 @@ These are load-bearing. Spec sections in parentheses.
 
 ## Adding a new harness (e.g. Deepseek)
 
-1. Add a payload struct + parser in `internal/hooks/hooks.go` (mirror `ClaudeCodePayload` / `GeminiCLIPayload`).
-2. Extend `DetectAndParse` and `parseWithFormat`.
-3. Add subprocess invocation in `internal/evaluator/init.go` for the Guardian-prompt generation step.
-4. Add idempotent settings-file patching in `internal/hooks/install.go`.
-5. Update spec.md, README.md, this file, and `cmd/install.go`'s `--harness` enum.
-6. Tests: payload parsing, install/uninstall round-trip.
+1. Add a payload struct + parser in `internal/hooks/hooks.go` (mirror `ClaudeCodePayload` / `GeminiCLIPayload` / `CodexPayload` / `CopilotPayload`).
+2. Extend `DetectAndParse`, `parseWithFormat`, and `defaultEventFor`.
+3. Add the harness's row to `WriteVerdict` in `internal/hooks/responder.go` for each `(event, verdict)` combination, plus table-test coverage in `responder_test.go`.
+4. Add subprocess invocation in `internal/evaluator/init.go` for the Guardian-prompt generation step.
+5. Add idempotent settings-file patching in `internal/hooks/install.go`.
+6. Update spec.md, README.md, this file, and `cmd/install.go`'s `--harness` enum.
+7. Tests: payload parsing, responder rows, install/uninstall round-trip.
 
 ## Adding a new LLM provider
 

README.md

@@ -91,7 +91,7 @@ vibecop tui                # (another terminal) watch verdicts in real-time
 Then for full integration with coding agents:
 
 ```sh
-vibecop install --all      # wire hooks into Claude Code and Gemini CLI
+vibecop install --all      # wire hooks into Claude Code, Codex, Gemini CLI, Copilot CLI
 vibecop init --harness claude   # generate Guardian prompt for this project
 ```
 

cmd/hook.go

@@ -21,78 +21,67 @@ var hookCmd = &cobra.Command{
 	Use:   "hook",
 	Short: "Hook entry point (called by installed scripts)",
 	Long: `Reads a harness permission request from stdin, sends it to the daemon,
-and exits with the verdict code (0 = approve, 1 = deny/escalate).
+and emits the harness-native JSON response on stdout.
 
-Auto-detects the harness format (Claude Code or Gemini CLI) from the
-payload shape. Override with --harness.
+Auto-detects the harness format (Claude Code, Codex, Gemini CLI, or Copilot
+CLI) from the payload shape. Override with --harness.
 
 If the daemon is unreachable, exits 0 silently (fail-open).`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		// Parse the harness payload from stdin.
 		nr, detected, err := hooks.DetectAndParse(os.Stdin, hookHarness)
 		if err != nil {
-			// If we can't parse the payload, fail-open.
+			// Fail-open: can't parse the payload, no JSON, exit 0.
 			fmt.Fprintf(os.Stderr, "VibeCop: %v\n", err)
-			os.Exit(1)
+			os.Exit(0)
 		}
 
-		_ = detected // harness identity available for logging if needed
-
-		// Build the daemon request.
+		// Build the daemon request, including which harness/event we saw so
+		// the evaluator's telemetry and audit log can record them.
 		req := daemon.Request{
 			Type:        daemon.TypePermissionRequest,
 			ProjectPath: nr.ProjectPathResolved(),
 			Tool:        nr.Tool,
 			Input:       nr.Input,
+			Harness:     detected,
+			HookEvent:   nr.Event,
 		}
 
 		// Connect to the daemon.
 		vibecopDir, err := config.VibecopDir()
 		if err != nil {
-			// Can't determine socket path — fail-open.
-			os.Exit(0)
+			os.Exit(0) // fail-open
 		}
 		socketPath := daemon.DefaultSocketPath(vibecopDir)
 
 		conn, err := net.DialTimeout("unix", socketPath, hookTimeout)
 		if err != nil {
-			// Daemon unreachable — fail-open, exit 0 silently.
+			// Daemon unreachable — fail-open, no JSON, exit 0.
 			os.Exit(0)
 		}
 		defer conn.Close()
 
-		// Send the request.
 		if err := json.NewEncoder(conn).Encode(req); err != nil {
-			// Send failed — fail-open.
 			os.Exit(0)
 		}
 
-		// Read the verdict.
 		var resp daemon.Verdict
 		if err := json.NewDecoder(conn).Decode(&resp); err != nil {
-			// No response — fail-open.
 			os.Exit(0)
 		}
 
-		// Apply the exit code contract.
-		switch resp.Verdict {
-		case "approve":
-			os.Exit(0)
-		case "deny":
-			fmt.Fprintf(os.Stderr, "VibeCop [DENY]: %s\n", resp.Reason)
-			os.Exit(1)
-		case "escalate":
-			fmt.Fprintf(os.Stderr, "VibeCop [ESCALATE]: %s\n", resp.Reason)
-			os.Exit(1)
-		default:
-			// Unknown verdict — fail-open.
-			os.Exit(0)
+		// Treat daemon-reported "error" as escalate for harness output: the
+		// evaluator failed but vibecop wants the harness's normal flow to run.
+		if resp.Verdict == "error" {
+			resp.Verdict = "escalate"
 		}
+
+		os.Exit(hooks.WriteVerdict(detected, nr.Event, resp, os.Stdout, os.Stderr))
 		return nil
 	},
 }
 
 func init() {
 	rootCmd.AddCommand(hookCmd)
-	hookCmd.Flags().StringVar(&hookHarness, "harness", "", "Harness format override (claude|gemini)")
+	hookCmd.Flags().StringVar(&hookHarness, "harness", "", "Harness format override (claude|gemini|codex|copilot)")
 }

cmd/install.go

@@ -19,7 +19,8 @@ var installCmd = &cobra.Command{
 	Use:   "install",
 	Short: "Install hook scripts into coding harness configs",
 	Long: `Install vibecop hook scripts into the specified harness.
-Use --harness to target one (claude, gemini) or --all for all supported harnesses.
+Use --harness to target one (claude, gemini, codex, copilot) or --all for all
+supported harnesses.
 
 By default the hook calls "vibecop hook" and relies on $PATH to find it. Pass
 --vibecop-path to point the hook at a specific binary instead — useful when
@@ -66,14 +67,19 @@ func resolveInstallTargets() []string {
 		return []string{installHarness}
 	}
 	if installAll {
-		return []string{hooks.HarnessClaude, hooks.HarnessGemini}
+		return []string{
+			hooks.HarnessClaude,
+			hooks.HarnessGemini,
+			hooks.HarnessCodex,
+			hooks.HarnessCopilot,
+		}
 	}
 	return nil
 }
 
 func init() {
 	rootCmd.AddCommand(installCmd)
-	installCmd.Flags().StringVar(&installHarness, "harness", "", "Harness to install into (claude|gemini) — use 'claude' for any claude-compatible wrapper")
+	installCmd.Flags().StringVar(&installHarness, "harness", "", "Harness to install into (claude|gemini|codex|copilot) — use 'claude' for any claude-compatible wrapper")
 	installCmd.Flags().BoolVar(&installAll, "all", false, "Install into all supported harnesses")
 	installCmd.Flags().StringVar(&installVibecopPath, "vibecop-path", "", "Path to a specific vibecop binary the hook should call (default: 'vibecop' via $PATH). Resolved to absolute.")
 }

cmd/start.go

@@ -124,7 +124,7 @@ func makePermissionHandler(
 		failMu.Unlock()
 
 		if isSuspended {
-			tp.RecordVerdict(context.Background(), "approve", req.Tool)
+			tp.RecordVerdict(context.Background(), "approve", req.Tool, req.Harness)
 			d.EmitEvent(daemon.Event{
 				Tool:      req.Tool,
 				Input:     req.Input,
@@ -133,13 +133,15 @@ func makePermissionHandler(
 				Timestamp: time.Now().UTC().Format(time.RFC3339),
 				Level:     "warn",
 				Message:   "VibeCop suspended after repeated failures — pass-through mode",
+				Harness:   req.Harness,
+				HookEvent: req.HookEvent,
 			})
 			return daemon.Verdict{Verdict: "approve"}
 		}
 
 		projectHash := config.ProjectHash(req.ProjectPath)
 
-		spanCtx, rootSpan := tp.StartPermissionSpan(context.Background(), req.Tool, projectHash)
+		spanCtx, rootSpan := tp.StartPermissionSpan(context.Background(), req.Tool, projectHash, req.Harness, req.HookEvent)
 		defer rootSpan.End()
 
 		// Get or create per-project activity store and audit logger.
@@ -162,7 +164,7 @@ func makePermissionHandler(
 			log.Printf("evaluator: prompt resolution error: %v", err)
 			rootSpan.SetStatus(codes.Error, "prompt resolution failed")
 			rootSpan.RecordError(err)
-			tp.RecordVerdict(spanCtx, "escalate", req.Tool)
+			tp.RecordVerdict(spanCtx, "escalate", req.Tool, req.Harness)
 			return daemon.Verdict{
 				Verdict: "escalate",
 				Reason:  "VibeCop: failed to load configuration",
@@ -259,6 +261,8 @@ func makePermissionHandler(
 			Reason:    reasonStr,
 			LatencyMs: latencyMs,
 			Timestamp: now.Format(time.RFC3339),
+			Harness:   req.Harness,
+			HookEvent: req.HookEvent,
 		})
 
 		// Telemetry — annotate root span and record metrics.
@@ -277,8 +281,8 @@ func makePermissionHandler(
 		if verdictStr == "deny" || verdictStr == "error" {
 			rootSpan.SetStatus(codes.Error, reasonStr)
 		}
-		tp.RecordVerdict(spanCtx, verdictStr, req.Tool)
-		tp.RecordEvaluatorLatency(spanCtx, latencyMs, verdictStr)
+		tp.RecordVerdict(spanCtx, verdictStr, req.Tool, req.Harness)
+		tp.RecordEvaluatorLatency(spanCtx, latencyMs, verdictStr, req.Harness)
 
 		return daemon.Verdict{
 			Verdict: verdictStr,

docs/spec.md

@@ -158,7 +158,7 @@ After subscribing, the daemon streams newline-terminated event objects to the TU
 
 ### Hook scripts
 
-`vibecop install` writes thin wrapper scripts that delegate entirely to `vibecop hook`:
+`vibecop install` writes thin wrapper config that delegates entirely to `vibecop hook`:
 
 **Claude Code** (`~/.claude/settings.json` — adds a `PreToolUse` hook):
 ```json
@@ -174,6 +174,20 @@ After subscribing, the daemon streams newline-terminated event objects to the TU
 }
 ```
 
+**Codex CLI** (`~/.codex/hooks.json` — registers under both `PreToolUse` and `PermissionRequest`; PreToolUse cannot allow on Codex, so PermissionRequest is the only event that can silently approve):
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "vibecop hook" }] }
+    ],
+    "PermissionRequest": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "vibecop hook" }] }
+    ]
+  }
+}
+```
+
 **Gemini CLI** (`~/.gemini/settings.json` — equivalent hook config):
 ```json
 {
@@ -183,19 +197,53 @@ After subscribing, the daemon streams newline-terminated event objects to the TU
 }
 ```
 
-`vibecop hook` reads the harness's JSON payload from stdin, normalizes it to the IPC request format, sends it to the daemon socket, and exits according to the exit code contract. The harness is auto-detected from the input payload shape; it can also be overridden with `--harness`.
+**Copilot CLI** (`~/.copilot/settings.json` — flat array of hook definitions, command lives under `bash`):
+```json
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      { "type": "command", "bash": "vibecop hook" }
+    ]
+  }
+}
+```
 
-### Exit code contract
+`vibecop hook` reads the harness's JSON payload from stdin, normalizes it to the IPC request format, sends it to the daemon socket, and emits the harness-native JSON response on stdout. The harness is auto-detected from the input payload shape; it can also be overridden with `--harness {claude|gemini|codex|copilot}`.
 
-| Verdict | Exit code | Stderr |
-|---|---|---|
-| `approve` | `0` | silent |
-| `deny` | `1` | `VibeCop [DENY]: <reason>` |
-| `escalate` | `1` | `VibeCop [ESCALATE]: <reason>` |
-| timeout | `1` | `VibeCop: timed out after <N>ms — escalating` |
-| daemon unreachable | `0` | silent (fail-open) |
+### Verdict → harness response contract
+
+`vibecop hook` always exits 0 — the JSON it writes to stdout is what the harness keys off. The exit code is reserved for fail-open: a parse error, a marshal failure, an unrecognized harness/event, or an unknown verdict all produce no stdout and exit 0 with a single-line stderr diagnostic.
+
+| Verdict    | Behavior                                                                                                                                                 |
+|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `approve`  | Emit harness-native "allow" JSON. Skips the harness's user prompt.                                                                                       |
+| `deny`     | Emit harness-native "deny" JSON. Tool is blocked. Stderr `VibeCop [DENY]: <reason>` is preserved for operator visibility.                                |
+| `escalate` | Emit no JSON. The harness's normal permission flow runs (typically prompts the user). Stderr `VibeCop [ESCALATE]: <reason>` is preserved when reason is non-empty. |
+
+`escalate` deliberately does not map to a harness's "ask" decision: vibecop's preference is "no objection, defer to whatever the harness would have done" rather than forcing a prompt the harness might otherwise have skipped under a user-defined rule.
+
+#### Per-harness JSON shapes
+
+Reason fields are omitted when the daemon's reason is empty.
+
+| (harness, event)             | `approve`                                                                                                              | `deny`                                                                                                                       |
+|------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| `claude`, `PreToolUse`       | `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"…"}}`    | `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"…"}}`           |
+| `codex`, `PreToolUse`        | (no stdout — Codex `PreToolUse` cannot allow; `PermissionRequest` is the approval channel)                             | `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"…"}}`           |
+| `codex`, `PermissionRequest` | `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}`                         | `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"…"}}}`                  |
+| `gemini`, `BeforeTool`       | `{"decision":"allow","reason":"…"}`                                                                                    | `{"decision":"deny","reason":"…"}`                                                                                           |
+| `copilot`, `preToolUse`      | `{"permissionDecision":"allow"}`                                                                                       | `{"permissionDecision":"deny","permissionDecisionReason":"…"}`                                                               |
+
+### Failure modes
+
+- **Daemon unreachable** — hook exits 0 silently (no stdout, no JSON).
+- **Unparseable stdin** — fail-open: stderr diagnostic, exit 0.
+- **JSON marshal failure in `WriteVerdict`** — fail-open: no stdout, exit 0.
+- **Unknown `(harness, event)` or unknown verdict** — fail-open: no stdout, single-line stderr diagnostic, exit 0. The `[DENY]` / `[ESCALATE]` stderr line is suppressed in this case so the operator's terminal isn't lying about a block that didn't happen.
+- **Three-consecutive evaluator failures** — daemon-side suspension (unchanged from "Failure Handling" below); the hook still emits per-harness responses, just always `approve`.
 
-Non-zero exit causes the coding harness to surface its own native permission prompt. The stderr text is displayed to the user as context. The human always has final say — `deny` is a strong recommendation, not a unilateral block.
+The human always has final say. `deny` is a strong recommendation that the harness can override (e.g. Claude Code's "approve anyway" affordance after seeing the deny reason).
 
 ### TUI
 

internal/daemon/daemon.go

@@ -30,6 +30,8 @@ type Request struct {
 	Tool        string `json:"tool,omitempty"`
 	Input       string `json:"input,omitempty"`
 	SessionID   string `json:"session_id,omitempty"`
+	Harness     string `json:"harness,omitempty"`
+	HookEvent   string `json:"hook_event,omitempty"`
 }
 
 // Verdict returned to a hook.
@@ -48,6 +50,8 @@ type Event struct {
 	Timestamp string `json:"timestamp,omitempty"`
 	Level     string `json:"level,omitempty"` // "info", "warn", "error"
 	Message   string `json:"message,omitempty"`
+	Harness   string `json:"harness,omitempty"`
+	HookEvent string `json:"hook_event,omitempty"`
 }
 
 // permissionHandler is called when a permission_request arrives.