@sabaiway/agent-workflow-kit 1.23.0 → 1.25.0

package/bridges/codex-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: codex-cli-bridge
 description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
 metadata:
-  version: '2.0.0'
+  version: '2.1.0'
 ---
 
 # codex-cli-bridge
@@ -77,7 +77,7 @@ Drive codex only through the two wrappers (installed on `PATH`), run from the ta
 # EXECUTION (workspace-write sandbox, network OFF, never prompts):
 codex-exec docs/plans/<slug>.md                 # drive a plan file
 echo "apply review fix: ..." | codex-exec -      # ad-hoc instruction from stdin
-codex-exec <file|-> -- <unguarded codex flags...> # passthrough codex flags after `--` (guarded ones rejected)
+codex-exec <file|-> -- <extra codex flags...>     # GUARDED passthrough after `--` (policy/model/capture flags rejected; some relaxed only under CODEX_PROBE=1)
 
 # RESUME (iterate on the SAME session without re-sending context):
 codex-exec --resume-last docs/plans/<slug>.md    # continue the last session (id from the sidecar)

package/bridges/codex-cli-bridge/bin/codex-exec.sh

@@ -40,6 +40,40 @@
 #   CODEX_PROBE=1 CODEX_MODEL=<slug> codex-exec <file>   # throwaway probe (relaxes the guard)
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no codex, no login, no git tree needed) -------
+# Keyed ONLY on the FIRST argument — never a scan of all args, else a passthrough
+# payload like `codex-exec f - -- --help` would be intercepted.
+# The contract below is drift-guarded against capability.json roles.execute.contract.
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+codex-exec — delegate plan/instruction EXECUTION to the OpenAI Codex CLI (subscription-only; workspace-write sandbox, network OFF, git writes blocked — the orchestrator commits).
+
+Usage:
+  codex-exec <plan-file|->
+  codex-exec <plan-file|-> -- <extra codex flags...>
+
+Grounding:
+  automatic — the root AGENTS.md (Hard Constraints) is auto-merged into codex's
+  context and the wrapper prepends the orchestrator execution contract; no
+  grounding flags
+
+Round-2 / resume:
+  codex-exec --resume-last <plan-file|->
+  codex-exec --resume <session-id> <plan-file|->
+  (resume continues the recorded session without re-sending context; takes no '--' passthrough)
+
+Guarded passthrough after '--':
+  blocked always: -c* --config* -s* --sandbox* --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust --full-auto --oss --local-provider* -p* --profile* -m* --model* -o* --output-last-message* --json* --color* --output-schema* --ephemeral*
+  relaxed only under CODEX_PROBE=1: --add-dir* -C* --cd* --skip-git-repo-check --ignore-rules --enable* --disable*
+
+Environment: CODEX_HARD_TIMEOUT (seconds, default 3600), CODEX_PROBE=1 (throwaway probe only).
+Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
+HELP
+    exit 0
+    ;;
+esac
+
 DEFAULT_CODEX_MODEL="gpt-5.5"   # frontier coding model (verified locally) — pinned
 DEFAULT_CODEX_EFFORT="xhigh"    # maximum reasoning effort — pinned
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"

package/bridges/codex-cli-bridge/bin/codex-exec.test.mjs

@@ -149,7 +149,8 @@ describe('codex-exec.sh — quality-first model/effort guard (1.1)', () => {
 // capture flags: rejected ALWAYS, even under CODEX_PROBE=1.
 const ALWAYS_BLOCKED = [
   ['-s', 'read-only'], ['--sandbox', 'danger-full-access'], ['-c', 'k=v'], ['--config', 'k=v'],
-  ['--full-auto'], ['--dangerously-bypass-approvals-and-sandbox'], ['--oss'], ['--local-provider', 'x'],
+  ['--full-auto'], ['--dangerously-bypass-approvals-and-sandbox'], ['--dangerously-bypass-hook-trust'],
+  ['--oss'], ['--local-provider', 'x'],
   ['-p', 'prof'], ['--profile', 'prof'], ['-m', 'gpt-5.5'], ['--model', 'gpt-5.5'],
   ['-o', '/x'], ['--output-last-message', '/x'], ['--json'], ['--color', 'always'],
   ['--output-schema', '/x'], ['--ephemeral'],
@@ -591,3 +592,161 @@ describe('codex-exec.sh — session id absent', () => {
     assert.match(r.stdout, /FAKE_FINAL_MESSAGE/, 'the run still succeeds');
   });
 });
+
+// ── driving contract: --help ⟷ manifest ⟷ real arg-parsing (drift-guarded) ─────
+// The manifest roles.execute.contract is the single machine-readable source of the
+// driving contract; these suites pin (a) --help renders it verbatim (set-EQUALITY,
+// both directions, incl. the TIERED guarded-passthrough sets), (b) the wrapper's
+// REAL parser arms equal the declared sets (source-level reverse guard — the
+// git-shim heredoc's own `case` arms are NOT CLI modes and must be skipped).
+// Helpers are inline — each bridge test file stays standalone (mirror byte-equality).
+
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'capability.json'), 'utf8'));
+const EXEC_CONTRACT = MANIFEST.roles.execute.contract;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+const setEq = (got, want, msg) => assert.deepEqual([...got].sort(), [...want].sort(), msg);
+const leadingFlag = (descriptor) => {
+  const m = norm(descriptor).match(/(^|\s)(--[a-z-]+)/);
+  assert.ok(m, `descriptor "${descriptor}" carries no --flag token`);
+  return m[2];
+};
+
+// Run `--help`/-h with PATH stripped of codex/agy/git, from a non-git cwd with no
+// AGENTS.md — proving the short-circuit fires BEFORE every preflight.
+const runHelp = (arg) => {
+  const root = mkdtempSync(join(tmpdir(), 'codex-exec-help-'));
+  const nongit = join(root, 'nongit');
+  mkdirSync(nongit, { recursive: true });
+  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const r = spawnSync('bash', [WRAPPER, arg], {
+    cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
+  });
+  rmSync(root, { recursive: true, force: true });
+  return r;
+};
+
+// The lines of a labelled --help section (header line → the next blank line).
+const helpSection = (text, header) => {
+  const lines = text.split('\n');
+  const i = lines.findIndex((l) => l.trim() === header);
+  assert.notEqual(i, -1, `--help must carry a "${header}" section`);
+  const out = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (lines[j].trim() === '') break;
+    out.push(lines[j].trim());
+  }
+  return out;
+};
+
+// Source-level parser-arm extractor — the reverse drift guard. Scans ONLY `case`
+// statements whose SUBJECT is a CLI-argument variable (allowlisted), skipping
+// heredoc bodies (codex-exec's git-shim heredoc carries its own `case "$verb"`
+// git-verb arms that are NOT CLI modes). Returns Map(subject → [raw arm label, …]).
+const ARG_SUBJECTS = new Set(['"$mode"', '"${1:-}"', '"$1"', '"$_arg"']);
+const extractArgCaseArms = (source) => {
+  const arms = new Map();
+  const stack = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    if (raw.trimStart().startsWith('#')) continue; // a comment line may carry a stray ')'
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    const cs = raw.match(/^\s*case\s+(\S+)\s+in\b/);
+    if (cs) { stack.push(cs[1]); continue; }
+    if (/^\s*esac\b/.test(raw)) { stack.pop(); continue; }
+    if (stack.length && ARG_SUBJECTS.has(stack[stack.length - 1])) {
+      const arm = raw.match(/^\s*([^)(\s][^)(]*)\)/);
+      if (arm) {
+        const subject = stack[stack.length - 1];
+        if (!arms.has(subject)) arms.set(subject, []);
+        arms.get(subject).push(arm[1].trim());
+      }
+    }
+  }
+  return arms;
+};
+const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
+
+describe('codex-exec.sh — --help contract (manifest-pinned)', () => {
+  it('--help and -h exit 0 pre-preflight (no codex, no git, no AGENTS.md)', () => {
+    for (const arg of ['--help', '-h']) {
+      const r = runHelp(arg);
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.match(r.stdout, /Usage:/, `${arg} prints the contract to stdout`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+    }
+  });
+
+  it('Usage set-EQUALS the manifest invocation descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Usage:').filter((l) => l.startsWith('codex-exec')).map(norm);
+    assert.ok(EXEC_CONTRACT.invocations.length > 0, 'manifest invocations must be non-empty');
+    setEq(got, EXEC_CONTRACT.invocations.map(norm), 'help Usage ⟷ manifest invocations');
+  });
+
+  it('Grounding renders the manifest grounding note verbatim', () => {
+    const help = runHelp('--help').stdout;
+    assert.equal(norm(helpSection(help, 'Grounding:').join(' ')), norm(EXEC_CONTRACT.grounding));
+  });
+
+  it('Round-2 / resume set-EQUALS the manifest continue descriptors', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Round-2 / resume:').filter((l) => l.startsWith('codex-exec')).map(norm);
+    assert.ok(EXEC_CONTRACT.continue.length > 0, 'manifest continue must be non-empty');
+    setEq(got, EXEC_CONTRACT.continue.map(norm), 'help continue ⟷ manifest continue');
+  });
+
+  it('the guarded-passthrough TIERS set-EQUAL the manifest tiers (never a flat set)', () => {
+    const help = runHelp('--help').stdout;
+    const section = helpSection(help, "Guarded passthrough after '--':");
+    const tier = (prefix) => {
+      const line = section.find((l) => l.startsWith(prefix));
+      assert.ok(line, `passthrough section must carry a "${prefix}" line`);
+      return line.slice(prefix.length).trim().split(/\s+/);
+    };
+    assert.ok(EXEC_CONTRACT.passthrough.blocked.length > 0, 'manifest blocked tier must be non-empty');
+    assert.ok(EXEC_CONTRACT.passthrough.probeRelaxed.length > 0, 'manifest probe tier must be non-empty');
+    setEq(tier('blocked always:'), EXEC_CONTRACT.passthrough.blocked, 'help tier-1 ⟷ manifest blocked');
+    setEq(tier('relaxed only under CODEX_PROBE=1:'), EXEC_CONTRACT.passthrough.probeRelaxed, 'help tier-2 ⟷ manifest probeRelaxed');
+  });
+
+  it('--help after the -- separator is passthrough payload, never intercepted', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['-', '--', '--help'], input: 'go' });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stdout, /Usage:/, 'help is keyed on the FIRST argument only');
+    assert.match(r.argv, /(^|\n)--help(\n|$)/, 'the payload --help reaches codex argv');
+  });
+});
+
+describe('codex-exec.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
+  const arms = extractArgCaseArms(readFileSync(WRAPPER, 'utf8'));
+
+  it('the first-arg entrypoints are exactly --help/-h + the manifest resume flags', () => {
+    const declared = EXEC_CONTRACT.continue.map(leadingFlag);
+    assert.ok(declared.length > 0, 'manifest resume set must be non-empty');
+    setEq(new Set(splitArms(arms.get('"${1:-}"'))), new Set(['--help', '-h', ...declared]));
+  });
+
+  it('the real passthrough tier arms equal the manifest tiers (git-shim heredoc excluded)', () => {
+    const tierArms = arms.get('"$_arg"') ?? [];
+    assert.equal(tierArms.length, 2, 'exactly two passthrough tiers: always-blocked, probe-relaxed');
+    setEq(tierArms[0].split('|'), EXEC_CONTRACT.passthrough.blocked, 'tier-1 arm ⟷ manifest blocked');
+    setEq(tierArms[1].split('|'), EXEC_CONTRACT.passthrough.probeRelaxed, 'tier-2 arm ⟷ manifest probeRelaxed');
+  });
+
+  it('the in-test tier samples cover every manifest tier pattern (behavioural forward guard)', () => {
+    // ALWAYS_BLOCKED / PROBE_RELAXABLE drive the real behaviour suite above; pin them
+    // to the manifest so a tier edit cannot leave the behavioural samples stale.
+    const sample = (patterns) => patterns.map((p) => p.replace(/\*$/, ''));
+    const covered = (flags, patterns) =>
+      sample(patterns).every((p) => flags.some(([f]) => f === p || f.startsWith(p)));
+    assert.ok(covered(ALWAYS_BLOCKED, EXEC_CONTRACT.passthrough.blocked), 'every blocked pattern has a behavioural sample');
+    assert.ok(covered(PROBE_RELAXABLE, EXEC_CONTRACT.passthrough.probeRelaxed), 'every probe pattern has a behavioural sample');
+  });
+});

package/bridges/codex-cli-bridge/bin/codex-review.sh

@@ -31,6 +31,34 @@
 # on disk remain readable under read-only — read-scoping is a prompt concern).
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no codex, no login, no git tree needed) -------
+# Keyed ONLY on the FIRST argument — never a scan of all args (uniform rule across
+# the four wrappers, so an open wrapper's passthrough payload is never intercepted).
+# The contract below is drift-guarded against capability.json roles.review.contract.
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+codex-review — read-only ADVISORY review by the OpenAI Codex CLI (subscription-only; frontier model at max effort).
+
+Usage:
+  codex-review plan <plan-file>
+  codex-review code [extra focus...]
+
+Grounding:
+  automatic — the wrapper precomputes the full working-tree change set (repo map,
+  status, diffs, untracked contents) and codex auto-merges the root AGENTS.md;
+  no grounding flags
+
+Round-2 / resume:
+  (none — one-shot; a follow-up review is a fresh run)
+
+Environment: CODEX_REVIEW_SCHEMA=1 (structured JSON findings), CODEX_HARD_TIMEOUT (seconds, default 1800), CODEX_PROBE=1 (throwaway probe only).
+Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
+HELP
+    exit 0
+    ;;
+esac
+
 DEFAULT_CODEX_MODEL="gpt-5.5"
 DEFAULT_CODEX_EFFORT="xhigh"
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"

package/bridges/codex-cli-bridge/bin/codex-review.test.mjs

@@ -540,3 +540,130 @@ describe('codex-review.sh — assemble & output edge cases', () => {
     assert.match(r.stdout, /FAKE_FINAL_MESSAGE/);
   });
 });
+
+// ── driving contract: --help ⟷ manifest ⟷ real arg-parsing (drift-guarded) ─────
+// The manifest roles.review.contract is the single machine-readable source of the
+// driving contract; these suites pin (a) --help renders it verbatim (set-EQUALITY,
+// both directions), (b) the wrapper's REAL parser arms equal the declared sets
+// (source-level reverse guard), (c) each declared mode is really accepted.
+// Helpers are inline — each bridge test file stays standalone (mirror byte-equality).
+
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'capability.json'), 'utf8'));
+const REVIEW_CONTRACT = MANIFEST.roles.review.contract;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+const setEq = (got, want, msg) => assert.deepEqual([...got].sort(), [...want].sort(), msg);
+
+// Run `--help`/-h with PATH stripped of codex/agy/git, from a non-git cwd with no
+// AGENTS.md — proving the short-circuit fires BEFORE every preflight.
+const runHelp = (arg) => {
+  const root = mkdtempSync(join(tmpdir(), 'codex-review-help-'));
+  const nongit = join(root, 'nongit');
+  mkdirSync(nongit, { recursive: true });
+  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const r = spawnSync('bash', [WRAPPER, arg], {
+    cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
+  });
+  rmSync(root, { recursive: true, force: true });
+  return r;
+};
+
+// The lines of a labelled --help section (header line → the next blank line).
+const helpSection = (text, header) => {
+  const lines = text.split('\n');
+  const i = lines.findIndex((l) => l.trim() === header);
+  assert.notEqual(i, -1, `--help must carry a "${header}" section`);
+  const out = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (lines[j].trim() === '') break;
+    out.push(lines[j].trim());
+  }
+  return out;
+};
+
+// Source-level parser-arm extractor — the reverse drift guard. Scans ONLY `case`
+// statements whose SUBJECT is a CLI-argument variable (allowlisted), skipping
+// heredoc bodies (a heredoc may carry non-CLI `case` arms — e.g. codex-exec's
+// git-shim). Returns Map(subject → [raw arm label, …]) in source order.
+const ARG_SUBJECTS = new Set(['"$mode"', '"${1:-}"', '"$1"', '"$_arg"']);
+const extractArgCaseArms = (source) => {
+  const arms = new Map();
+  const stack = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    if (raw.trimStart().startsWith('#')) continue; // a comment line may carry a stray ')'
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    const cs = raw.match(/^\s*case\s+(\S+)\s+in\b/);
+    if (cs) { stack.push(cs[1]); continue; }
+    if (/^\s*esac\b/.test(raw)) { stack.pop(); continue; }
+    if (stack.length && ARG_SUBJECTS.has(stack[stack.length - 1])) {
+      const arm = raw.match(/^\s*([^)(\s][^)(]*)\)/);
+      if (arm) {
+        const subject = stack[stack.length - 1];
+        if (!arms.has(subject)) arms.set(subject, []);
+        arms.get(subject).push(arm[1].trim());
+      }
+    }
+  }
+  return arms;
+};
+const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
+
+describe('codex-review.sh — --help contract (manifest-pinned)', () => {
+  it('--help and -h exit 0 pre-preflight (no codex, no git, no AGENTS.md)', () => {
+    for (const arg of ['--help', '-h']) {
+      const r = runHelp(arg);
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.match(r.stdout, /Usage:/, `${arg} prints the contract to stdout`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+    }
+  });
+
+  it('Usage set-EQUALS the manifest invocation descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Usage:').filter((l) => l.startsWith('codex-review')).map(norm);
+    assert.ok(REVIEW_CONTRACT.invocations.length > 0, 'manifest invocations must be non-empty');
+    setEq(got, REVIEW_CONTRACT.invocations.map(norm), 'help Usage ⟷ manifest invocations');
+  });
+
+  it('Grounding renders the manifest grounding note verbatim', () => {
+    const help = runHelp('--help').stdout;
+    assert.equal(norm(helpSection(help, 'Grounding:').join(' ')), norm(REVIEW_CONTRACT.grounding));
+  });
+
+  it('Round-2 / resume set-EQUALS the manifest continue descriptors (empty — one-shot)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Round-2 / resume:').filter((l) => l.startsWith('codex-review')).map(norm);
+    setEq(got, (REVIEW_CONTRACT.continue ?? []).map(norm), 'help continue ⟷ manifest continue');
+    assert.deepEqual(REVIEW_CONTRACT.continue, [], 'codex-review is one-shot — no continue descriptor');
+  });
+});
+
+describe('codex-review.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
+  const arms = extractArgCaseArms(readFileSync(WRAPPER, 'utf8'));
+
+  it('the real mode arms equal the manifest modes (adding a mode without the manifest fails here)', () => {
+    const modes = splitArms(arms.get('"$mode"')).filter((a) => a !== '*');
+    assert.ok(MANIFEST.roles.review.modes.length > 0, 'manifest modes must be non-empty');
+    setEq(new Set(modes), MANIFEST.roles.review.modes, 'parser mode arms ⟷ manifest modes');
+  });
+
+  it('the first-arg entrypoints are exactly --help/-h (no undeclared resume/flag entrypoint)', () => {
+    setEq(new Set(splitArms(arms.get('"${1:-}"'))), ['--help', '-h']);
+  });
+
+  it('every manifest mode is really accepted (forward guard)', () => {
+    const drive = { plan: ['plan', 'plan.md'], code: ['code'] };
+    for (const mode of MANIFEST.roles.review.modes) {
+      assert.ok(drive[mode], `no test drive for manifest mode "${mode}" — add one`);
+      const sb = makeSandbox();
+      const r = run(sb, { args: drive[mode] });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, `mode ${mode}: ${r.stderr}`);
+    }
+  });
+});

package/bridges/codex-cli-bridge/capability.json

@@ -3,11 +3,44 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "provides": ["execute", "review"],
   "roles": {
-    "execute": { "cmd": "codex-exec", "source": "bin/codex-exec.sh", "output": "diff" },
-    "review": { "cmd": "codex-review", "source": "bin/codex-review.sh", "modes": ["plan", "code"], "output": "advisory" }
+    "execute": {
+      "cmd": "codex-exec",
+      "source": "bin/codex-exec.sh",
+      "output": "diff",
+      "contract": {
+        "invocations": [
+          "codex-exec <plan-file|->",
+          "codex-exec <plan-file|-> -- <extra codex flags...>"
+        ],
+        "grounding": "automatic — the root AGENTS.md (Hard Constraints) is auto-merged into codex's context and the wrapper prepends the orchestrator execution contract; no grounding flags",
+        "continue": [
+          "codex-exec --resume-last <plan-file|->",
+          "codex-exec --resume <session-id> <plan-file|->"
+        ],
+        "passthrough": {
+          "policy": "guarded",
+          "blocked": ["-c*", "--config*", "-s*", "--sandbox*", "--dangerously-bypass-approvals-and-sandbox", "--dangerously-bypass-hook-trust", "--full-auto", "--oss", "--local-provider*", "-p*", "--profile*", "-m*", "--model*", "-o*", "--output-last-message*", "--json*", "--color*", "--output-schema*", "--ephemeral*"],
+          "probeRelaxed": ["--add-dir*", "-C*", "--cd*", "--skip-git-repo-check", "--ignore-rules", "--enable*", "--disable*"]
+        }
+      }
+    },
+    "review": {
+      "cmd": "codex-review",
+      "source": "bin/codex-review.sh",
+      "modes": ["plan", "code"],
+      "output": "advisory",
+      "contract": {
+        "invocations": [
+          "codex-review plan <plan-file>",
+          "codex-review code [extra focus...]"
+        ],
+        "grounding": "automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags",
+        "continue": []
+      }
+    }
   },
   "detect": {
     "installed": {

package/bridges/codex-cli-bridge/references/driving-codex.md

@@ -50,7 +50,7 @@ object (raw-text fallback on failure).
 ```bash
 codex-exec docs/plans/<slug>.md                  # drive a plan file
 echo "apply review fix: tighten the guard in X, keep tests green" | codex-exec -
-codex-exec <file|-> -- <unguarded codex flags>   # passthrough AFTER `--` (policy/model/capture flags are rejected)
+codex-exec <file|-> -- <extra codex flags>       # GUARDED passthrough AFTER `--` (policy/model/capture flags rejected; some relaxed only under CODEX_PROBE=1)
 
 codex-exec --resume-last docs/plans/<slug>.md    # continue the last session, no re-send
 echo "now do step 2" | codex-exec --resume <id> -

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/tools/commands.mjs

@@ -113,7 +113,7 @@ const CATALOG = [
     invocation: invocationOf('procedures'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'Show a named activity’s steps and which recipe applies at each stage here.',
+    oneLine: 'Show a named activity’s steps, the recipe per stage, and each dispatched backend’s exact driving contract (invocation + grounding + round-2 delta).',
   },
   {
     key: 'set-recipe',

package/tools/detect-backends.mjs

@@ -60,6 +60,36 @@ const RAW_BACKENDS = [
     name: 'codex-cli-bridge',
     installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
     roleCmds: { execute: 'codex-exec', review: 'codex-review' },
+    // The per-role DRIVING CONTRACT (exact invocation descriptors + grounding + round-2 continue),
+    // mirroring the bridge manifest roles[role].contract byte-for-byte — drift-guarded like roleCmds.
+    // Scope = dispatchable recipe roles ONLY (review, execute): the probe role is never dispatched by
+    // an activity slot, so it carries NO contract here (wrapperContractFor(_, 'probe') → null).
+    roleContracts: {
+      execute: {
+        invocations: [
+          'codex-exec <plan-file|->',
+          'codex-exec <plan-file|-> -- <extra codex flags...>',
+        ],
+        grounding: "automatic — the root AGENTS.md (Hard Constraints) is auto-merged into codex's context and the wrapper prepends the orchestrator execution contract; no grounding flags",
+        continue: [
+          'codex-exec --resume-last <plan-file|->',
+          'codex-exec --resume <session-id> <plan-file|->',
+        ],
+        passthrough: {
+          policy: 'guarded',
+          blocked: ['-c*', '--config*', '-s*', '--sandbox*', '--dangerously-bypass-approvals-and-sandbox', '--dangerously-bypass-hook-trust', '--full-auto', '--oss', '--local-provider*', '-p*', '--profile*', '-m*', '--model*', '-o*', '--output-last-message*', '--json*', '--color*', '--output-schema*', '--ephemeral*'],
+          probeRelaxed: ['--add-dir*', '-C*', '--cd*', '--skip-git-repo-check', '--ignore-rules', '--enable*', '--disable*'],
+        },
+      },
+      review: {
+        invocations: [
+          'codex-review plan <plan-file>',
+          'codex-review code [extra focus...]',
+        ],
+        grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
+        continue: [],
+      },
+    },
     bin: 'codex',
     credential: { env: 'CODEX_HOME', default: '~/.codex', file: 'auth.json' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/codex-cli-bridge/setup/README.md',
@@ -72,6 +102,26 @@ const RAW_BACKENDS = [
     name: 'antigravity-cli-bridge',
     installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
     roleCmds: { review: 'agy-review', probe: 'agy-run' },
+    // Mirror of the manifest roles.review.contract (see the codex entry note). probe: NO contract.
+    roleContracts: {
+      review: {
+        invocations: [
+          'agy-review code [--facts @f] [--decided @f] [--focus "…"] [extra focus…]',
+          'agy-review plan <plan-file> [--facts @f] [--decided @f] [--focus "…"]',
+          'agy-review diff <diff-file> [--facts @f] [--decided @f] [--focus "…"]',
+        ],
+        grounding: 'grounded review — agy reads NOTHING by default, an ungrounded review GUESSES: --facts @f = the verified facts to review AGAINST; --decided @f = decisions already made, do NOT re-raise (anti-circling)',
+        flags: [
+          '--facts @f — verified facts the review runs AGAINST (omit ⇒ loud ungrounded-review warning)',
+          '--decided @f — already-decided / already-addressed list; do NOT re-raise (anti-circling; the round-2 payload)',
+          '--focus "…" — extra focus (repeatable; code mode also takes trailing focus words)',
+        ],
+        continue: [
+          'agy-review --continue [--decided @f] [--focus "…"]',
+          'agy-review --conversation <id> [--decided @f] [--focus "…"]',
+        ],
+      },
+    },
     bin: 'agy',
     credential: { env: null, default: '~/.gemini/antigravity-cli', file: 'antigravity-oauth-token' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/antigravity-cli-bridge/setup/README.md',
@@ -91,6 +141,15 @@ export const KNOWN_BACKENDS = RAW_BACKENDS.map((entry) => ({ ...entry, wrapperCm
 export const wrapperCmdFor = (backendName, role) =>
   KNOWN_BACKENDS.find((b) => b.name === backendName)?.roleCmds?.[role] ?? null;
 
+// Resolve a dispatched (backend, role) to its structured DRIVING CONTRACT — the registry mirror of
+// the bridge manifest roles[role].contract: exact invocation descriptor(s), the grounding note, the
+// closed flag set (when the wrapper's grammar is closed), the round-2/continue descriptor(s), and
+// the guarded passthrough tiers (codex-exec). The point-of-use advisor (procedures.mjs) renders this
+// VERBATIM so a driving agent never re-derives the contract from wrapper source. `null` when the
+// pair is unknown or the role carries no contract (probe — never dispatched by an activity slot).
+export const wrapperContractFor = (backendName, role) =>
+  KNOWN_BACKENDS.find((b) => b.name === backendName)?.roleContracts?.[role] ?? null;
+
 // ── pure helpers ─────────────────────────────────────────────────────────────
 
 // Expand a leading "~" / "~/x" against home; absolute and relative paths pass through untouched.

package/tools/manifest/schema.md

@@ -38,6 +38,21 @@ Each `roles.<role>` is an object:
 - `template` (string, optional) — an in-skill prompt/template path (e.g.
   `references/review-prompt.md`); repo-relative, **must exist**.
 - `modes`, `output` (optional) — e.g. `["plan","code"]`, `"advisory"`.
+- `contract` (object, optional; execution-backend bridges) — the machine-readable **driving
+  contract** for a dispatchable recipe role (`review` / `execute`; the `probe` role carries none).
+  Rides as a validator-tolerated extra field (format-checked by the bridge/kit drift-guard tests,
+  not by `validate.mjs`), and is the single source the point-of-use advisor
+  (`/agent-workflow-kit procedures`) and each wrapper's `--help` render verbatim:
+  - `invocations` (string[], non-empty) — exact copy-pasteable invocation descriptors, one per
+    mode/variant, incl. operand placeholders (`<plan-file>`, `[extra focus...]`).
+  - `grounding` (string) — the grounding note (e.g. agy's `--facts @f` / `--decided @f` levers, or
+    "automatic — …" when the wrapper grounds itself).
+  - `flags` (string[], optional) — the closed per-mode flag descriptor set (closed-grammar
+    wrappers only).
+  - `continue` (string[]) — round-2 / resume invocation descriptors; `[]` when one-shot.
+  - `passthrough` (object, optional) — the guarded `--` passthrough tiers:
+    `{ policy: "guarded", blocked: string[], probeRelaxed: string[] }`, matching the wrapper's
+    real case-arm patterns (pinned by the source-level reverse-guard test).
 
 ## Path-field rules (Windows-safe, traversal-safe)