@damian87/omp 0.9.2 → 0.12.0

package/docs/plans/verification-plan.md

@@ -0,0 +1,104 @@
+# Verification Plan — PR #31 (skill audit fixes + Copilot-native hooks)
+
+> Purpose: prove every change in PR #31 actually works against a real Copilot CLI
+> session. Split into what is ALREADY verified (no re-run needed) and the DEFERRED
+> live checks that need Copilot model quota (Free tier resets Jul 1; or use Pro).
+
+## Legend
+- ✅ done = already executed and green this cycle (do not redo)
+- ⏳ deferred = needs Copilot model quota; run when available
+
+## Verification log — 2026-06-13 (live, no model quota needed)
+**B1 (hooks fire) EXECUTED and a real bug was found + fixed.**
+- Copilot CLI 1.0.61 DOES load+run plugin hooks (logged `Invalid hooks config … hooks must be an object` on the old Claude-format file; accepted the new v1 format with no error).
+- First live run: every hook fired but failed — `HookExitCodeError: code 1` — because the command used `${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}`, which Copilot does NOT set. Captured the hook runtime env: Copilot exposes **`COPILOT_PLUGIN_ROOT`** (and `PLUGIN_ROOT` / `CLAUDE_PLUGIN_ROOT`).
+- Fix (commit e7658d8): manifest now uses `${COPILOT_PLUGIN_ROOT:-…}`.
+- Re-run after fix: `.omp/state/hooks.log` recorded `SessionStart` (correct `directory`), `UserPromptSubmit`, and `errorOccurred` (caught the quota error); **zero new HookExitCodeError**. → B1 PASS.
+- Still ⏳: `agentStop` firing on a *completed* turn + Copilot honoring `{decision:"block"}` re-prompt — the turn quota-errored (→ errorOccurred) instead of completing, so the loop re-prompt is unexercised until quota.
+
+---
+
+## A. Already verified (evidence on record)
+
+| Check | How | Result |
+|---|---|---|
+| Build from clean | `rm -rf dist && npm run build` | ✅ |
+| Unit/integration suite | `npx vitest run` | ✅ 508/508 |
+| Type safety | `npx tsc -p tsconfig.json --noEmit` | ✅ clean |
+| Skill lint | `node dist/src/cli.js lint:skills --root .` | ✅ 0 issues |
+| Catalog | `node dist/src/cli.js catalog validate` | ✅ pass |
+| Every hook script emits valid JSON | pipe Copilot payload to each `scripts/*.mjs` | ✅ 7/7 |
+| `preToolUse` safe (no spurious deny) | pipe payload | ✅ allow |
+| `agent-stop` fails OPEN on bad input | `echo '' \| node scripts/agent-stop.mjs` | ✅ allow |
+| `agent-stop` loop math | stdin pipe: 1/3→2/3→allow+clear on sentinel; unit tests | ✅ |
+| `comms send` submits (C-m→Enter) | live `omp comms send … --json` | ✅ ok=True submitted=True |
+| doctor validates manifest | `omp doctor --json` | ✅ "Copilot v1, 7 events (agentStop present)" |
+| Fixed skills reference omp CLI | grep | ✅ ralph/ultrawork/ultraqa/jira |
+
+These do NOT need re-running unless code changes.
+
+---
+
+## B. Deferred live verification (needs Copilot model quota)
+
+### Prerequisites
+1. Quota available (Jul 1 reset, or Copilot Pro). Confirm: a trivial `omp comms ask --text "say OK" --wait` returns a model reply, not `quota_exceeded`.
+2. Plugin synced to this branch: `rsync -a --delete .github/ ~/.copilot/installed-plugins/oh-my-copilot/oh-my-copilot/.github/` and copy `hooks/`, `plugin.json`, `scripts/` (or reinstall the plugin from this branch).
+3. Restart Copilot so it loads the new hooks + skills.
+
+### B1 — Hooks actually fire (the claim the old memory said was impossible)
+Install a throwaway diagnostic that writes a file, then start a session.
+- **sessionStart**: file written on boot (past trust prompt). PASS = file exists.
+- **agentStop**: file written when the agent finishes a turn. PASS = file exists.
+- **preToolUse/postToolUse**: file written around a tool call.
+- Acceptance: ≥ sessionStart + agentStop fire. (If none fire, the `${OMP_PLUGIN_ROOT}` env resolution in `hooks/hooks.json` is the suspect — see design doc risk.)
+
+### B2 — Native memory injection (sessionStart)
+- `omp goal set "ship v1"`, start a fresh session, ask the model "what is the repo goal?".
+- Acceptance: model reports the goal from `additionalContext` (not only from copilot-instructions.md). Confirm by temporarily blanking the instructions block and re-testing.
+
+### B3 — agentStop loop driver (headline feature)
+- `omp ralph start "add a --version flag to the omp CLI" --max-iterations 3`.
+- Drive one short task turn; let the agent stop WITHOUT emitting `RALPH_COMPLETE`.
+- Acceptance:
+  - agentStop returns `{decision:"block"}` and Copilot takes another turn with the `[RALPH ITERATION n/3]` prompt.
+  - `.omp/state/ralph.json` iteration increments each turn.
+  - On emitting `RALPH_COMPLETE` (or hitting 3) → `{decision:"allow"}`, loop stops, state cleared.
+- Repeat for `ultraqa` (cycleCount) and `ultrawork`.
+
+### B4 — 23-skill behavioral re-run (audit Gate 2)
+Re-run the existing harness against both models Copilot exposes:
+```bash
+node .review/driver.mjs --session <copilot-tmux> --model gpt5mini --skills all
+node .review/driver.mjs --session <copilot-tmux> --model haiku45  --skills all
+```
+Score each transcript 0–3: (a) skill loaded (`● skill(x)`), (b) followed phase/contract, (c) produced contracted output, (d) avoided its own "do not use" anti-pattern.
+
+Targeted acceptance for the previously-broken skills:
+| skill | must observe live |
+|---|---|
+| ralph | runs `omp ralph start` before the work loop |
+| ultrawork | runs `omp ultrawork start` |
+| ultraqa | runs `omp ultraqa start` + `omp ultraqa cycle` per cycle |
+| jira-ticket | runs `omp jira render` (dry-run) — does NOT improvise raw REST/create |
+| research-codebase | uses native glob/grep/read (NO `task`/`view`/`explore` tool calls) |
+| caveman | output is actually compressed (the static gate showed plain prose — confirm fixed or file a bug) |
+| grill-me | asks exactly ONE question |
+
+### B5 — `/team` end-to-end
+- `omp team 2:copilot "<small task>" --name vtest`; confirm workers receive prompts (already verified delivery live), DO the task, and the leader aggregates results. Then `omp team shutdown vtest`.
+
+---
+
+## C. Sign-off checklist
+- [ ] B1 sessionStart + agentStop fire
+- [ ] B2 goal visible via hook injection
+- [ ] B3 ralph/ultraqa/ultrawork loops re-prompt and stop correctly
+- [ ] B4 all 5 previously-broken skills exhibit corrected behavior; 23-skill scores recorded to `.review/`
+- [ ] B5 team completes a task end-to-end
+- [ ] Any new defect filed; report appended to `.review/REPORT.md`
+
+## D. Notes
+- Cloud agents only load `.github/hooks/` (not plugin hooks) — B1–B3 target the local CLI.
+- Keep all transcripts under `.review/transcripts/` for reproducibility.
+EOF

package/hooks/hooks.json

@@ -1,74 +1,61 @@
 {
-  "SessionStart": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node \"${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}\"/scripts/session-start.mjs",
-          "timeout": 5
-        }
-      ]
-    }
-  ],
-  "UserPromptSubmit": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node \"${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}\"/scripts/prompt-submit.mjs",
-          "timeout": 5
-        }
-      ]
-    }
-  ],
-  "PreToolUse": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node \"${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}\"/scripts/pre-tool-use.mjs",
-          "timeout": 5
-        }
-      ]
-    }
-  ],
-  "PostToolUse": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node \"${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}\"/scripts/post-tool-use.mjs",
-          "timeout": 5
-        }
-      ]
-    }
-  ],
-  "SessionEnd": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node \"${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}\"/scripts/session-end.mjs",
-          "timeout": 5
-        }
-      ]
-    }
-  ],
-  "Error": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node \"${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}\"/scripts/error.mjs",
-          "timeout": 5
-        }
-      ]
-    }
-  ]
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "bash": "node \"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}}}}\"/scripts/session-start.mjs",
+        "timeoutSec": 5
+      }
+    ],
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "bash": "node \"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}}}}\"/scripts/prompt-submit.mjs",
+        "timeoutSec": 5
+      }
+    ],
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "node \"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}}}}\"/scripts/pre-tool-use.mjs",
+        "timeoutSec": 5
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "node \"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}}}}\"/scripts/post-tool-use.mjs",
+        "timeoutSec": 5
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "type": "command",
+        "bash": "node \"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}}}}\"/scripts/post-tool-use-failure.mjs",
+        "timeoutSec": 5
+      }
+    ],
+    "sessionEnd": [
+      {
+        "type": "command",
+        "bash": "node \"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}}}}\"/scripts/session-end.mjs",
+        "timeoutSec": 5
+      }
+    ],
+    "agentStop": [
+      {
+        "type": "command",
+        "bash": "node \"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}}}}\"/scripts/agent-stop.mjs",
+        "timeoutSec": 10
+      }
+    ],
+    "errorOccurred": [
+      {
+        "type": "command",
+        "bash": "node \"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${OMP_PLUGIN_ROOT:-$OMC_PLUGIN_ROOT}}}}\"/scripts/error.mjs",
+        "timeoutSec": 5
+      }
+    ]
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damian87/omp",
-  "version": "0.9.2",
+  "version": "0.12.0",
   "description": "Multi-agent orchestration for GitHub Copilot CLI — autonomous loops (Autopilot, Ralph, UltraQA, Ultrawork), parallel tmux agent teams, a weighted-consensus model council, a Slack chat bridge, durable scheduled jobs, and in-session skills + custom agents. Zero learning curve.",
   "type": "module",
   "publishConfig": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "oh-my-copilot",
   "description": "Multi-agent orchestration skills for GitHub Copilot CLI — autopilot, ralph, ultrawork, ultraqa, team, council, code-review and more as in-session slash skills + custom agents.",
-  "version": "0.9.2",
+  "version": "0.12.0",
   "author": {
     "name": "Damian Borek",
     "email": "borekdamian@yahoo.pl"

package/scripts/agent-stop.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Copilot CLI `agentStop` hook: drives the omp persistence loops (ralph /
+// ultrawork / ultraqa). When a loop is active and not yet complete, returns
+// {decision:"block", reason:"<next-turn prompt>"} so Copilot takes another turn;
+// otherwise {decision:"allow"}. Fail-OPEN (never traps the user in a loop).
+import { existsSync, readFileSync, writeFileSync, statSync, openSync, readSync, closeSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readStdin } from "./lib/stdin.mjs";
+import { hookCwd, printStopDecision, appendHookLog } from "./lib/hook-output.mjs";
+import { decideLoop, LOOP_MODES } from "./lib/loop-driver.mjs";
+
+const HOOK_NAME = "agentStop";
+const TRANSCRIPT_TAIL_BYTES = 64 * 1024;
+
+// Match the omp CLI's modeStatePath (src/mode-state/paths.ts): literal resolved
+// cwd, NOT ompRoot — so the hook reads/writes the exact files `omp ralph start`
+// wrote, even when invoked from a subdirectory.
+function stateFile(root, mode) {
+  return join(root, ".omp", "state", `${mode}.json`);
+}
+
+function readState(root, mode) {
+  const p = stateFile(root, mode);
+  if (!existsSync(p)) return undefined;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+// Read only the tail of the transcript — it can be large, and a completion
+// sentinel from this turn lives at the end.
+function readTranscriptTail(path) {
+  if (!path || !existsSync(path)) return "";
+  try {
+    const size = statSync(path).size;
+    const start = Math.max(0, size - TRANSCRIPT_TAIL_BYTES);
+    const len = size - start;
+    const fd = openSync(path, "r");
+    try {
+      const buf = Buffer.alloc(len);
+      readSync(fd, buf, 0, len, start);
+      return buf.toString("utf8");
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return "";
+  }
+}
+
+(async () => {
+  try {
+    const raw = await readStdin();
+    const data = raw ? JSON.parse(raw) : {};
+    const directory = hookCwd(data);
+    const root = resolve(directory);
+
+    const states = {};
+    for (const m of LOOP_MODES) states[m.key] = readState(root, m.key);
+
+    const transcript = readTranscriptTail(data.transcriptPath ?? data.transcript_path);
+    const result = decideLoop(states, transcript);
+
+    // Persist counter increment (block) or clear the loop (allow on complete/cap).
+    if (result.patch) {
+      const s = states[result.patch.mode];
+      if (s) {
+        s[result.patch.counter] = result.patch.value;
+        try { writeFileSync(stateFile(root, result.patch.mode), JSON.stringify(s, null, 2)); } catch { /* best effort */ }
+      }
+    } else if (result.clear) {
+      const s = states[result.clear];
+      if (s) {
+        s.active = false;
+        try { writeFileSync(stateFile(root, result.clear), JSON.stringify(s, null, 2)); } catch { /* best effort */ }
+      }
+    }
+
+    appendHookLog(directory, HOOK_NAME, { decision: result.decision, reason: result.reason });
+    printStopDecision(result.decision, result.decision === "block" ? result.reason : "");
+  } catch (err) {
+    console.error(`[hook ${HOOK_NAME}] failed: ${err?.message ?? err}`);
+    printStopDecision("allow"); // fail-open: never trap the loop on an error
+  }
+})();

package/scripts/error.mjs

@@ -2,17 +2,19 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { readStdin } from "./lib/stdin.mjs";
+import { failOpen } from "./lib/hook-output.mjs";
+import { parseHookInput } from "./lib/hook-input.mjs";
 
 const HOOK_NAME = "Error";
 
 (async () => {
   try {
     const raw = await readStdin();
-    const data = raw ? JSON.parse(raw) : {};
-    const sessionId = data.sessionId ?? data.session_id ?? "unknown";
-    const directory = data.directory ?? process.cwd();
-    const toolName = data.toolName ?? data.tool_name ?? "unknown";
-    const errorMessage = data.error?.message ?? data.message ?? "unknown";
+    const input = parseHookInput(raw);
+    const sessionId = input.sessionId;
+    const directory = input.cwd;
+    const toolName = input.toolName;
+    const errorMessage = input.error ?? "unknown";
     const logFile = join(directory, ".omp", "state", "hooks.log");
     try {
       mkdirSync(dirname(logFile), { recursive: true });
@@ -23,9 +25,9 @@ const HOOK_NAME = "Error";
     } catch {
       // best effort
     }
-    console.log(JSON.stringify({ continue: true }));
+    failOpen();
   } catch (err) {
     console.error(`[hook ${HOOK_NAME}] failed: ${err?.message ?? err}`);
-    console.log(JSON.stringify({ continue: true }));
+    failOpen();
   }
 })();

package/scripts/lib/cost-ledger.mjs

@@ -0,0 +1,91 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ompRoot } from "./omp-root.mjs";
+
+export function normalizeTokenInput(value) {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+
+export function countTokens(value) {
+  const text = normalizeTokenInput(value);
+  if (text.length === 0) return 0;
+  return Math.ceil(text.length / 4);
+}
+
+function costDir(cwd) {
+  return join(ompRoot(cwd), ".omp", "state", "cost");
+}
+
+function safeSessionId(sessionId) {
+  return (
+    String(sessionId || "unknown")
+      .trim()
+      .replace(/[^a-zA-Z0-9._-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "unknown"
+  );
+}
+
+export function costLedgerPath(cwd, sessionId) {
+  return join(costDir(cwd), `${safeSessionId(sessionId)}.jsonl`);
+}
+
+function normalizeRecord(record = {}) {
+  return {
+    ts: record.ts ?? new Date().toISOString(),
+    sessionId: record.sessionId || "unknown",
+    event: record.event,
+    toolName: record.toolName,
+    model: record.model,
+    inTokens: Number.isFinite(record.inTokens) ? Math.max(0, Number(record.inTokens)) : 0,
+    outTokens: Number.isFinite(record.outTokens) ? Math.max(0, Number(record.outTokens)) : 0,
+    rawOutTokens: Number.isFinite(record.rawOutTokens) ? Math.max(0, Number(record.rawOutTokens)) : undefined,
+    savedTokens: Number.isFinite(record.savedTokens) ? Math.max(0, Number(record.savedTokens)) : undefined,
+    rawPath: typeof record.rawPath === "string" ? record.rawPath : undefined,
+    estUSD: Number.isFinite(record.estUSD) ? Number(record.estUSD) : undefined,
+    note: record.note,
+  };
+}
+
+export function appendCostRecord(cwd, record) {
+  const normalized = normalizeRecord(record);
+  const file = costLedgerPath(cwd, normalized.sessionId);
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(file, `${JSON.stringify(normalized)}\n`, "utf8");
+  return file;
+}
+
+function readFileRecords(file) {
+  if (!existsSync(file)) return [];
+  const records = [];
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === "object" && typeof parsed.event === "string") records.push(normalizeRecord(parsed));
+    } catch {
+      // ignore corrupt rows
+    }
+  }
+  return records;
+}
+
+export function readCostRecords(cwd, options = {}) {
+  const dir = costDir(cwd);
+  const todayPrefix = new Date().toISOString().slice(0, 10);
+  const files = options.sessionId
+    ? [costLedgerPath(cwd, options.sessionId)]
+    : existsSync(dir)
+      ? readdirSync(dir)
+          .filter((file) => file.endsWith(".jsonl"))
+          .sort()
+          .map((file) => join(dir, file))
+      : [];
+  const records = files.flatMap(readFileRecords);
+  return options.today ? records.filter((record) => String(record.ts ?? "").startsWith(todayPrefix)) : records;
+}

package/scripts/lib/hook-input.mjs

@@ -0,0 +1,51 @@
+function parseMaybeJson(value) {
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (!trimmed) return value;
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return value;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+
+function normalizeResult(raw) {
+  if (!raw || typeof raw !== "object") return undefined;
+  const resultType = raw.resultType ?? raw.result_type;
+  const textResultForLlm = raw.textResultForLlm ?? raw.text_result_for_llm;
+  if (resultType == null && textResultForLlm == null) return undefined;
+  return {
+    resultType: resultType ?? "success",
+    textResultForLlm: textResultForLlm == null ? "" : String(textResultForLlm),
+  };
+}
+
+export function normalizeHookInput(data = {}, options = {}) {
+  const payload = data && typeof data === "object" ? data : {};
+  const cwd = payload.cwd ?? payload.directory ?? options.cwd ?? process.cwd();
+  const toolResult = normalizeResult(payload.toolResult ?? payload.tool_result ?? payload.toolOutput);
+  const error = payload.error?.message ?? payload.error ?? payload.message;
+  return {
+    raw: payload,
+    hookEventName: payload.hookEventName ?? payload.hook_event_name,
+    sessionId: payload.sessionId ?? payload.session_id ?? "unknown",
+    timestamp: payload.timestamp,
+    cwd,
+    directory: cwd,
+    prompt: payload.prompt ?? payload.message?.content ?? "",
+    toolName: payload.toolName ?? payload.tool_name ?? "unknown",
+    toolArgs: parseMaybeJson(payload.toolArgs ?? payload.tool_input ?? payload.toolInput),
+    toolResult,
+    error: error == null ? undefined : String(error),
+    transcriptPath: payload.transcriptPath ?? payload.transcript_path,
+    stopReason: payload.stopReason ?? payload.stop_reason,
+    trigger: payload.trigger,
+    customInstructions: payload.customInstructions ?? payload.custom_instructions,
+  };
+}
+
+export function parseHookInput(raw, options = {}) {
+  const data = raw ? JSON.parse(raw) : {};
+  return normalizeHookInput(data, options);
+}

package/scripts/lib/hook-output.mjs

@@ -2,19 +2,90 @@ import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { ompRoot } from "./omp-root.mjs";
 
+// Hook scripts run under BOTH GitHub Copilot CLI (camelCase events, top-level
+// `additionalContext` / `{decision,reason}` / `{permissionDecision}`) and Claude
+// Code (`{continue, hookSpecificOutput}` / `{decision, reason}`). The injection
+// path (`printContinue`) dual-emits: every output object carries both
+// vocabularies, and each host ignores the keys it does not recognize. See
+// docs/plans/copilot-native-hooks.md.
+//
+// The cost/minification path uses the documented Copilot builder shapes
+// (`buildContinueOutput`/`buildAdditionalContextOutput`/`buildModifiedResultOutput`/
+// `buildPermissionDecisionOutput`). An empty `{}` is a no-op "continue" for both
+// hosts, so these builders coexist with the dual-emit injection path.
+
+/** Project directory from hook input — Copilot sends `cwd`, Claude sends `directory`. */
+export function hookCwd(data) {
+  return data?.cwd ?? data?.directory ?? process.cwd();
+}
+
+export function buildContinueOutput() {
+  return {};
+}
+
+export function buildAdditionalContextOutput(additionalContext = "") {
+  return additionalContext ? { additionalContext } : buildContinueOutput();
+}
+
+export function buildModifiedResultOutput(textResultForLlm, additionalContext = "", resultType = "success") {
+  return {
+    modifiedResult: {
+      resultType,
+      textResultForLlm,
+    },
+    ...(additionalContext ? { additionalContext } : {}),
+  };
+}
+
+export function buildPermissionDecisionOutput(permissionDecision, permissionDecisionReason, modifiedArgs) {
+  return {
+    permissionDecision,
+    ...(permissionDecisionReason ? { permissionDecisionReason } : {}),
+    ...(modifiedArgs == null ? {} : { modifiedArgs }),
+  };
+}
+
+/**
+ * sessionStart / userPromptSubmitted injection. When there is context to inject,
+ * dual-emit it for both hosts (Copilot top-level `additionalContext` + Claude
+ * `continue`/`hookSpecificOutput`). With nothing to inject, emit an empty `{}` —
+ * a no-op "continue" understood by both hosts and the zero-cost default.
+ */
 export function printContinue(hookEventName, additionalContext = "") {
-  const output = additionalContext
-    ? { continue: true, hookSpecificOutput: { hookEventName, additionalContext } }
-    : { continue: true };
-  console.log(JSON.stringify(output));
+  if (!additionalContext) {
+    console.log(JSON.stringify(buildContinueOutput()));
+    return;
+  }
+  console.log(
+    JSON.stringify({
+      continue: true,
+      additionalContext, // Copilot CLI
+      hookSpecificOutput: { hookEventName, additionalContext }, // Claude Code
+    }),
+  );
+}
+
+/** agentStop (Copilot) / Stop (Claude): both honor {decision, reason}. */
+export function printStopDecision(decision, reason = "") {
+  const out = { decision }; // "block" forces another turn; "allow" lets it stop
+  if (reason) out.reason = reason; // serves as the next-turn prompt when blocked
+  console.log(JSON.stringify(out));
+}
+
+/** preToolUse (Copilot): allow | deny | ask, with optional reason / modified args. */
+export function printPermission(permissionDecision, reason = "", modifiedArgs) {
+  const out = { permissionDecision };
+  if (reason) out.permissionDecisionReason = reason;
+  if (modifiedArgs) out.modifiedArgs = modifiedArgs;
+  console.log(JSON.stringify(out));
 }
 
 export function printBlock(reason) {
-  console.log(JSON.stringify({ continue: false, reason }));
+  console.log(JSON.stringify(buildPermissionDecisionOutput("deny", reason)));
 }
 
 export function failOpen() {
-  console.log(JSON.stringify({ continue: true }));
+  console.log(JSON.stringify(buildContinueOutput()));
 }
 
 export function appendHookLog(directory, hookName, payload) {

package/scripts/lib/loop-driver.mjs

@@ -0,0 +1,44 @@
+// Pure decision logic for the agentStop loop driver. Given the current loop-mode
+// states and the session transcript text, decide whether Copilot should stop
+// (`allow`) or take another turn (`block` + a next-turn `reason`). Kept side-effect
+// free so it is unit-testable; file I/O lives in scripts/agent-stop.mjs.
+
+// Priority order: a single-owner ralph loop wins over a QA cycle over a batch.
+export const LOOP_MODES = [
+  { key: "ralph", sentinel: "RALPH_COMPLETE", counter: "iteration", max: "maxIterations", defMax: 10 },
+  { key: "ultraqa", sentinel: "ULTRAQA_COMPLETE", counter: "cycleCount", max: "maxCycles", defMax: 5 },
+  { key: "ultrawork", sentinel: "ULTRAWORK_COMPLETE", counter: "iteration", max: "maxIterations", defMax: 20 },
+];
+
+/**
+ * @param {Record<string, any>} states  e.g. { ralph: {active, iteration, maxIterations}, ... }
+ * @param {string} transcriptText        recent transcript text to scan for a completion sentinel
+ * @returns {{decision:"allow"|"block", reason?:string, clear?:string, patch?:{mode:string,counter:string,value:number}}}
+ */
+export function decideLoop(states = {}, transcriptText = "") {
+  for (const m of LOOP_MODES) {
+    const s = states[m.key];
+    if (!s || !s.active) continue;
+
+    // The model signals completion by emitting the sentinel token — let it stop.
+    if (transcriptText.includes(m.sentinel)) {
+      return { decision: "allow", clear: m.key, reason: `${m.key} complete (sentinel seen)` };
+    }
+
+    const cur = Number(s[m.counter] ?? 0);
+    const max = Number(s[m.max] ?? m.defMax);
+    // Safety cap: never loop past the configured maximum, even without a sentinel.
+    if (cur + 1 >= max) {
+      return { decision: "allow", clear: m.key, reason: `${m.key} reached max (${max})` };
+    }
+
+    const next = cur + 1;
+    const reason =
+      `[${m.key.toUpperCase()} ITERATION ${next}/${max}] Not finished. Continue the task. ` +
+      `When ALL acceptance criteria pass, output the exact token ${m.sentinel} on its own line.`;
+    return { decision: "block", patch: { mode: m.key, counter: m.counter, value: next }, reason };
+  }
+
+  // No active loop — normal stop.
+  return { decision: "allow" };
+}