@mirnoorata/codexa 0.2.2 → 0.3.0

package/integrations/claude-code/README.md

@@ -0,0 +1,177 @@
+# Codexa for Claude Code
+
+Ships Codexa's edit-safety loop into Claude Code the way it already ships into
+Codex. One install, both tools wired to the same engine and the same
+`<repo>/.codex/` state.
+
+## What it does
+
+When Claude Code is running in a Codexa-wired repo (one that contains
+`<repo>/.codex/config.toml`), this plugin:
+
+- **MCP server** — exposes the Codexa query tools (`task_brief`,
+  `change_plan`, `post_edit_review`, `impact`, `search`, …) directly to
+  Claude through the plugin's `.mcp.json`. The launcher resolves the repo
+  from the session's project directory and the CLI from `CODEXA_CLI`, the
+  package's own `dist/cli.js`, or a global install.
+- **SessionStart** — injects a short Codexa freshness status and the top
+  read-first files from `.codex/codebase/README.md` into Claude's session
+  context.
+- **PreToolUse** — before `Edit`/`Write`/`MultiEdit`/`NotebookEdit` lands on a
+  file inside the wired repo, saves an implicit pre-edit baseline via
+  `codexa hook-pre-edit` when no change-plan snapshot exists yet, so the
+  post-edit drift review always has a pre-edit reference. Falls back to an
+  advisory nudge when the CLI is unavailable. Never blocks the edit.
+- **Stop** — at the end of every assistant turn, if a snapshot exists and
+  has not been reviewed on this session yet, runs `codexa post-edit-review`
+  and prints the drift summary to stderr. When the review ran against an
+  **explicit** `change_plan` snapshot and the verdict is `replan` or a
+  blocking `inspect`, the summary is surfaced to the model through the Stop
+  hook's `{"decision":"block","reason":…}` contract so Claude can act on the
+  drift. Reviews against hook-saved implicit baselines never block — saving
+  a plan is the opt-in — and neither do parent-scan reviews of other
+  workspace repos: only the repo the session is working inside can block.
+  Clean and advisory verdicts stay quiet. Debounced
+  per session+repo+dirty-tree state, with a `stop_hook_active` re-entrancy
+  guard, so it blocks at most once per stop and never loops. Set
+  `CLAUDIO_STOP_BLOCK=0` for stderr-only behavior.
+
+Slash commands available to Claude:
+
+| Command            | Wraps                                |
+| ------------------ | ------------------------------------ |
+| `/codexa-status`   | `codexa status <repo>`               |
+| `/codexa-brief`    | `codexa brief <repo> --diff`         |
+| `/codexa-plan`     | `codexa change-plan --save-snapshot` |
+| `/codexa-review`   | `codexa post-edit-review`            |
+| `/codexa-impact`   | `codexa impact` / `diff-impact`      |
+
+Current Codexa packets are proof-carrying. Impact and symbol lookups can include
+edge evidence, confidence labels, stale/degraded flags, and structured
+`nextTools` entries that name the next read-only or cache-writing Codexa call.
+Post-edit review compares against planned-test provenance from the saved
+snapshot, degrades legacy or scope-mismatched tests, and persists compact local
+outcomes that may visibly influence future ranking/test recommendations.
+
+## Thin Adapter Contract
+
+Claude Code commands and hooks are adapters over the shared Codexa engine.
+They do not maintain a separate index, ranking layer, planner, or source-editing
+path. The primary Codexa path stays:
+
+```text
+session_context -> task_brief -> change_plan(saveSnapshot) -> post_edit_review -> test_plan
+```
+
+Use `symbol_context`, `impact`, `callers`, and `callees` when Claude needs to
+audit who uses a symbol, what may break, and which tests are relationship-backed.
+For non-TypeScript/JavaScript/Python repositories, the shared engine can consume
+`CodexaSymbolReportV1` reports through
+`codexa static-analysis <repo> --symbol-report <path>` and labels those
+relationships as report-backed derived evidence.
+
+The adapter may write Codexa-owned `.codex/cache/` state through the CLI, but it
+must not introduce source-mutating MCP tools or host-only behavior that bypasses
+the shared Codexa MCP/CLI contract.
+
+## Install
+
+Treat `codexa/integrations/` as a local Claude Code plugin marketplace. It
+ships inside the npm package, so both a git checkout and an npm install work
+as the marketplace source.
+
+### Quick, supported path (persistent)
+
+From a Claude Code session:
+
+```text
+/plugin marketplace add <codexa-root>/integrations
+/plugin install codexa@codexa-integrations
+```
+
+`<codexa-root>` is either a local checkout (example: `~/code/codexa`) or the
+installed npm package root — for a global install that is
+`$(npm root -g)/@mirnoorata/codexa`.
+
+Under the hood, `<codexa-root>/integrations/.claude-plugin/marketplace.json`
+registers this directory as the `codexa-integrations` marketplace, and the
+plugin `codexa` lives at `./claude-code` relative to that manifest. After
+install, restart Claude Code so the MCP server and the SessionStart,
+PreToolUse, and Stop hooks load.
+
+### MCP-only alternative (no plugin)
+
+If you only want the Codexa tools (no hooks or slash commands), skip the
+plugin and run `codexa init <repo> --claude` instead — it writes the codexa
+MCP server into the repo's `.mcp.json`. Use the plugin **or** `init
+--claude`, not both, to avoid registering the server twice.
+
+### Development (per-session)
+
+No install, one-shot:
+
+```bash
+claude --plugin-dir <codexa-checkout>/integrations/claude-code
+```
+
+## Requirements
+
+- Node.js >= 22 on `$PATH` (override with `CLAUDIO_NODE_BIN`)
+- Codexa must be locatable one of three ways (tried in this order):
+  1. `CODEXA_CLI` env var set to an absolute path to `dist/cli.js`
+  2. `<codexa-checkout>/dist/cli.js` auto-detected from the plugin's own
+     location (works when the plugin is loaded via `--plugin-dir
+     <codexa-checkout>/integrations/claude-code`)
+  3. `codexa` on `$PATH` (works after the public package is published and the
+     user ran `npm install -g @mirnoorata/codexa`; recommended when the plugin
+     is installed via `/plugin marketplace add`, which copies the plugin out of
+     the source checkout)
+- `awk`, `python3`, `shasum` (or `md5sum`). GNU coreutils `timeout` is used
+  when present; on stock macOS (bash 3.2, no `timeout`) the hooks fall back
+  to a `python3` timeout wrapper, so no Homebrew packages are required.
+
+## Configuration
+
+Environment variables the hooks honor:
+
+| Variable                           | Default                                | Purpose                                                                      |
+| ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| `CODEXA_CLI`                       | `<codexa-checkout>/dist/cli.js` (auto) | Path to the built CLI                                                        |
+| `CLAUDIO_NODE_BIN`                 | `node` on `$PATH`                      | Node binary to run the CLI                                                   |
+| `CLAUDIO_DEBUG`                    | unset                                  | Set to `1` for `[claudio]` stderr traces                                     |
+| `CLAUDIO_STOP_BLOCK`               | `1`                                    | Set to `0` to keep drift verdicts stderr-only (never block)                  |
+| `CODEXA_REPO`                      | session project dir                    | Repository the plugin MCP server serves                                      |
+| `CODEXA_PLUGIN_TOOLS`              | `core`                                 | MCP tool profile served by the plugin (`full` exposes all 20 tools)          |
+| `CODEXA_PLUGIN_AUTO_REFRESH`       | `1`                                    | Set to `0` to stop the MCP server refreshing stale indexes                   |
+| `CODEXA_PLUGIN_ALLOW_NPX_FALLBACK` | unset                                  | Set to `1` to let the MCP launcher fall back to `npx -y @mirnoorata/codexa`  |
+
+## Safety properties
+
+- Every hook has a hard Claude hook timeout (SessionStart 6s, PreToolUse 10s,
+  Stop 35s). The shell scripts also wrap Codexa CLI calls with shorter
+  subprocess budgets (`timeout(1)` or the python3 fallback).
+- Every hook exits 0 on any error — Claude sessions are never blocked by a
+  Codexa outage. The Stop hook's drift block is a JSON decision on a clean
+  exit, gated to replan/blocking-inspect verdicts parsed against a strict
+  enum allowlist; raw CLI output never flows into the block reason.
+- Hooks never write to the user's repo. Codexa's own `.codex/cache/` state
+  is managed by the CLI, not the hooks.
+- Repo detection refuses to climb above `$HOME` or treat `/` as a wired repo.
+- Re-entrancy guard on the Stop hook via `stop_hook_active`.
+- Slash-command argument parsing routes through `python3 shlex.split` — no
+  `eval`, no word-splitting of user input — and `/codexa-review` allowlists
+  the flags that can reach the CLI.
+
+## Testing
+
+```bash
+bash integrations/claude-code/tests/hook-smoke.sh
+bash integrations/claude-code/tests/cmd-smoke.sh
+```
+
+Hook smoke: non-wired cwd, empty/malformed payloads, read-first extraction,
+snapshot presence/absence, `MultiEdit`/`NotebookEdit` dispatch, relative-path
+rejection, Stop debouncing, re-entrancy, failed post-edit passthrough.
+
+Command smoke: `shlex` parsing of quoted tasks and paths with spaces,
+unknown-flag rejection, path-traversal-like tokens, empty arguments.

package/integrations/claude-code/commands/codexa-brief.md

@@ -0,0 +1,14 @@
+---
+description: Get a Codexa task brief for the current dirty tree + a user task
+argument-hint: "<task description>"
+disable-model-invocation: true
+allowed-tools: Bash(bash:*)
+---
+
+Ask Codexa for a focused task brief. This is the first call before any
+non-trivial codexa-wired edit. It bundles impact, risks, covering tests,
+freshness, read-first files, relationship evidence where available, quality
+signals, and structured `nextTools` for the stated task plus the existing dirty
+diff.
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/brief.sh" "$ARGUMENTS"`

package/integrations/claude-code/commands/codexa-impact.md

@@ -0,0 +1,14 @@
+---
+description: Show Codexa blast-radius impact for a file/symbol, or diff-impact when no argument
+argument-hint: "[path or symbol]"
+disable-model-invocation: true
+allowed-tools: Bash(bash:*)
+---
+
+Show Codexa impact evidence. With an argument, query `impact` for that file or
+symbol. Without an argument, show `diff-impact` for the current dirty tree.
+Relationship-backed results may include edge evidence ids, confidence labels,
+stale/degraded flags, and structured next Codexa tools for symbol context,
+change planning, or targeted tests.
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/impact.sh" "$ARGUMENTS"`

package/integrations/claude-code/commands/codexa-plan.md

@@ -0,0 +1,20 @@
+---
+description: Save a Codexa change-plan snapshot before editing concrete files
+argument-hint: '"<task>" [file ...]'
+allowed-tools: Bash(bash:*)
+---
+
+Save a Codexa change-plan snapshot so the post-edit review can compute drift
+afterward. Quote the task so it is parsed as a single argument, then list the
+files you intend to edit. The saved snapshot includes planned-test provenance,
+verification recipes, freshness, and dirty-file hashes so the later review can
+distinguish trusted coverage from degraded legacy or stale evidence.
+
+Examples:
+
+```
+/codexa-plan "fix auth bug" src/auth.py
+/codexa-plan "redesign frame header" web/src/App.tsx web/src/styles.css
+```
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/plan.sh" "$ARGUMENTS"`

package/integrations/claude-code/commands/codexa-review.md

@@ -0,0 +1,23 @@
+---
+description: Run Codexa post-edit review against the saved change-plan snapshot
+argument-hint: "[--change-type <type>] [--ran-test <path> ...] [--ran-command <cmd> ...]"
+allowed-tools: Bash(bash:*)
+---
+
+Compare the current dirty tree against the saved Codexa change-plan snapshot.
+Reports tests still unaccounted for, drift signals, and known gaps. Saved
+planned tests now carry provenance; legacy, stale, or scope-mismatched snapshot
+tests are reported as degraded instead of silently trusted. Passing structured
+command reports lets Codexa account for verification and persist compact local
+outcomes for future visible ranking/test boosts.
+
+Allowlisted flags (others are rejected): `--change-type`, `--ran-test`, `--ran-command`, `--ran-command-report`, `--waive-check`, `--waiver`, `--file`, `--symbol`, `--budget`, `--limit`, `--snippets`, `--no-snippets`, `--auto-refresh`, `--no-auto-refresh`, `--task-id`.
+
+Common use:
+
+```
+/codexa-review --change-type style
+/codexa-review --change-type behavior --ran-test tests/test_queue.py --ran-command "pytest tests/"
+```
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/review.sh" "$ARGUMENTS"`

package/integrations/claude-code/commands/codexa-status.md

@@ -0,0 +1,10 @@
+---
+description: Show Codexa index freshness for the current repo
+argument-hint: ""
+disable-model-invocation: true
+allowed-tools: Bash(bash:*)
+---
+
+Show the Codexa index freshness, commit, indexed-at, and dirty-file count for the repo you are focused on. Return the output verbatim.
+
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/cmd/status.sh"`

package/integrations/claude-code/hooks/hooks.json

@@ -0,0 +1,39 @@
+{
+  "description": "Codexa integration for Claude Code.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh\"",
+            "timeout": 6
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-edit.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/stop.sh\"",
+            "timeout": 35
+          }
+        ]
+      }
+    ]
+  }
+}

package/integrations/claude-code/scripts/cmd/brief.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+raw_args="${1-}"
+if [[ -z "$raw_args" ]]; then
+  printf 'Usage: /codexa-brief <task description>\n' >&2
+  exit 2
+fi
+
+# Task may include shell metacharacters; treat the whole string as the task.
+task="$raw_args"
+
+repo="$(cmd_require_codexa_repo)" || exit 1
+cmd_require_codexa_cli
+exec "$NODE_BIN" "$CODEXA_CLI" brief "$repo" --task "$task" --diff

package/integrations/claude-code/scripts/cmd/impact.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+raw_args="${1-}"
+
+repo="$(cmd_require_codexa_repo)" || exit 1
+cmd_require_codexa_cli
+
+if [[ -z "$raw_args" ]]; then
+  exec "$NODE_BIN" "$CODEXA_CLI" diff-impact "$repo"
+fi
+
+declare -a tokens
+if ! cmd_shlex_split "$raw_args" tokens; then
+  exit 2
+fi
+
+if [[ ${#tokens[@]} -ne 1 ]]; then
+  printf 'Usage: /codexa-impact [path or symbol]\n' >&2
+  exit 2
+fi
+
+target="${tokens[0]}"
+cmd_validate_path_token "$target"
+
+# If the argument resolves to a real file (relative to repo or absolute),
+# treat it as a path; otherwise fall back to --symbol.
+if [[ -e "$repo/$target" ]] || [[ -e "$target" ]]; then
+  exec "$NODE_BIN" "$CODEXA_CLI" impact "$repo" --file "$target"
+else
+  exec "$NODE_BIN" "$CODEXA_CLI" impact "$repo" --symbol "$target"
+fi

package/integrations/claude-code/scripts/cmd/lib.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Shared helpers for the /codexa-* slash-command implementations.
+#
+# Every slash-command `.md` file passes the raw "$ARGUMENTS" string as the
+# single first positional argument. We do NOT eval it or let the shell
+# word-split it — shlex handles quoting and shell metacharacters safely.
+
+set -u
+
+CMD_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+CMD_LIB_INTEGRATION_ROOT="$(cd "$CMD_LIB_DIR/../.." && pwd -P)"
+# shellcheck source=../lib/codexa-repo.sh
+. "$CMD_LIB_INTEGRATION_ROOT/scripts/lib/codexa-repo.sh"
+
+# Populate a bash array from shell-like tokenization of a single string.
+# Usage: cmd_shlex_split "quoted string \"with escapes\"" arr_name
+# After the call, ${arr_name[@]} holds the parsed tokens. Tokens may include
+# newlines/tabs — we use a NUL delimiter end-to-end. Returns 2 on malformed
+# input (unbalanced quotes, etc.), with the error written to stderr.
+cmd_shlex_split() {
+  local raw="${1:-}"
+  # No `local -n` nameref: that is bash 4.3+, and stock macOS ships bash
+  # 3.2. The array name is allowlist-validated before any eval so untrusted
+  # input can never reach the evaluated identifier.
+  local arr_name="${2:-}"
+  case "$arr_name" in
+    "" | *[!a-zA-Z0-9_]*) return 2 ;;
+  esac
+  eval "$arr_name=()"
+  [[ -z "$raw" ]] && return 0
+  local tokens_file err_file
+  tokens_file="$(mktemp)" || return 2
+  err_file="$(mktemp)" || { rm -f "$tokens_file"; return 2; }
+  python3 - "$raw" >"$tokens_file" 2>"$err_file" <<'PY'
+import shlex, sys
+try:
+    tokens = shlex.split(sys.argv[1])
+except ValueError as exc:
+    sys.stderr.write("argument parse error: " + str(exc) + "\n")
+    sys.exit(2)
+for t in tokens:
+    sys.stdout.write(t)
+    sys.stdout.write("\0")
+PY
+  local rc=$?
+  if [[ $rc -ne 0 ]]; then
+    cat "$err_file" >&2
+    rm -f "$tokens_file" "$err_file"
+    return "$rc"
+  fi
+  rm -f "$err_file"
+  local token
+  while IFS= read -r -d '' token; do
+    eval "$arr_name+=(\"\$token\")"
+  done <"$tokens_file"
+  rm -f "$tokens_file"
+  return 0
+}
+
+# Resolve the target codexa-wired repo for a slash command.
+#
+# Resolution order:
+#   (1) Walk up from PWD looking for .codex/config.toml (existing behavior).
+#   (2) If no ancestor is wired, scan direct children of PWD for wired repos.
+#       If exactly one, auto-pick it and note the choice on stderr so the
+#       user sees which repo the command ran against. If more than one,
+#       error with the list so the user can disambiguate by cd-ing in.
+#
+# Writes the repo root to stdout and returns 0 on success. On failure writes
+# a diagnostic to stderr and returns 1 — callers use `|| exit 1` in command
+# substitution so the parent script actually exits.
+cmd_require_codexa_repo() {
+  local repo
+  repo="$(claudio_find_codexa_repo "$PWD")"
+  if [[ -n "$repo" ]]; then
+    printf '%s' "$repo"
+    return 0
+  fi
+
+  local -a children=()
+  local line
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    children+=("$line")
+  done < <(claudio_list_child_codexa_repos "$PWD")
+
+  case "${#children[@]}" in
+    0)
+      printf 'No codexa-wired repo (.codex/config.toml) found from %s.\n' "$PWD" >&2
+      return 1
+      ;;
+    1)
+      printf '[codexa] no wired repo at %s; auto-selected sole child: %s\n' \
+        "$PWD" "${children[0]}" >&2
+      printf '%s' "${children[0]}"
+      return 0
+      ;;
+    *)
+      printf 'Ambiguous codexa target: %s has %d wired child repos.\n' \
+        "$PWD" "${#children[@]}" >&2
+      printf 'cd into one of these and re-run:\n' >&2
+      local child
+      for child in "${children[@]}"; do
+        printf '  - %s\n' "$child" >&2
+      done
+      return 1
+      ;;
+  esac
+}
+
+# Require a usable codexa CLI and print a clear error if missing.
+cmd_require_codexa_cli() {
+  if ! claudio_codexa_available; then
+    printf 'codexa CLI not available at %s (NODE=%s).\n' "$CODEXA_CLI" "$NODE_BIN" >&2
+    exit 127
+  fi
+}
+
+# Reject tokens that look like path-traversal or obvious shell injection
+# before passing them through to --file flags. Call once per user-supplied
+# file path. We do not try to sandbox — just block the dumb cases.
+cmd_validate_path_token() {
+  local tok="${1:-}"
+  if [[ -z "$tok" ]]; then
+    return 0
+  fi
+  case "$tok" in
+    *$'\n'*|*$'\r'*|*$'\t'*)
+      printf 'rejecting path with control character: %q\n' "$tok" >&2
+      exit 2
+      ;;
+  esac
+  # Allow relative .. under repo root (valid monorepo paths may include it)
+  # but disallow an absolute path outside known workspace, home, or repo roots.
+  return 0
+}

package/integrations/claude-code/scripts/cmd/plan.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+raw_args="${1-}"
+if [[ -z "$raw_args" ]]; then
+  cat >&2 <<'USAGE'
+Usage: /codexa-plan "<task>" [file ...]
+
+The task must be a quoted string. Additional tokens are treated as file
+paths to snapshot. Examples:
+
+  /codexa-plan "fix auth bug" src/auth.py
+  /codexa-plan "redesign frame header" web/src/App.tsx web/src/styles.css
+USAGE
+  exit 2
+fi
+
+declare -a tokens
+if ! cmd_shlex_split "$raw_args" tokens; then
+  exit 2
+fi
+
+if [[ ${#tokens[@]} -eq 0 ]]; then
+  printf 'Parsed zero tokens from arguments.\n' >&2
+  exit 2
+fi
+
+task="${tokens[0]}"
+files=("${tokens[@]:1}")
+
+if [[ -z "$task" ]]; then
+  printf 'First argument (task description) must be non-empty.\n' >&2
+  exit 2
+fi
+
+# Validate file tokens BEFORE touching codexa.
+for f in "${files[@]}"; do
+  cmd_validate_path_token "$f"
+done
+
+repo="$(cmd_require_codexa_repo)" || exit 1
+cmd_require_codexa_cli
+
+cli_args=(change-plan "$repo" --task "$task" --save-snapshot)
+for f in "${files[@]}"; do
+  cli_args+=(--file "$f")
+done
+
+exec "$NODE_BIN" "$CODEXA_CLI" "${cli_args[@]}"

package/integrations/claude-code/scripts/cmd/review.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+raw_args="${1-}"
+
+repo="$(cmd_require_codexa_repo)" || exit 1
+cmd_require_codexa_cli
+
+if [[ ! -f "$repo/.codex/cache/codexa-tasks/latest.json" ]]; then
+  printf 'No change-plan snapshot found at %s/.codex/cache/codexa-tasks/latest.json.\nRun /codexa-plan first.\n' "$repo" >&2
+  exit 1
+fi
+
+declare -a tokens
+if ! cmd_shlex_split "$raw_args" tokens; then
+  exit 2
+fi
+
+# Only allow a known flag set through. The CLI has many flags; we allow
+# the post-edit-relevant ones and refuse anything else so a stray argument
+# can't slip a shell metachar or an unknown subcommand.
+allowed_flags=(--change-type --ran-test --ran-command --ran-command-report \
+               --waive-check --waiver --file --symbol --budget --limit \
+               --snippets --no-snippets --auto-refresh --no-auto-refresh \
+               --task-id)
+is_allowed() {
+  local candidate="$1"
+  for f in "${allowed_flags[@]}"; do
+    if [[ "$candidate" == "$f" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+i=0
+cli_args=(post-edit-review "$repo")
+while [[ $i -lt ${#tokens[@]} ]]; do
+  tok="${tokens[$i]}"
+  if [[ "$tok" == --* ]]; then
+    if ! is_allowed "$tok"; then
+      printf 'refusing unknown flag %q\n' "$tok" >&2
+      exit 2
+    fi
+    cli_args+=("$tok")
+    # flags with a value: consume next token too unless it's the start of
+    # another flag or we're at end of list.
+    if [[ $((i + 1)) -lt ${#tokens[@]} ]]; then
+      next="${tokens[$((i + 1))]}"
+      if [[ "$next" != --* ]]; then
+        cli_args+=("$next")
+        i=$((i + 2))
+        continue
+      fi
+    fi
+    i=$((i + 1))
+  else
+    printf 'positional arguments are not supported for /codexa-review: %q\n' "$tok" >&2
+    exit 2
+  fi
+done
+
+exec "$NODE_BIN" "$CODEXA_CLI" "${cli_args[@]}"

package/integrations/claude-code/scripts/cmd/status.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# /codexa-status
+#
+# Single-repo case: walks up from PWD for an ancestor with .codex/config.toml
+# and runs `codexa status` on it. That matches the common "terminal is inside
+# the repo" workflow.
+#
+# Multi-repo case: when PWD is above a set of wired children (e.g. an IDE
+# opened at a workspace root with two sibling projects both wired via
+# `codexa init`), we fan out and run `codexa status` on every wired child
+# rather than erroring on ambiguity. The IDE-workspace-root view is
+# "show me everything."
+set -u
+CMD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck source=lib.sh
+. "$CMD_DIR/lib.sh"
+
+cmd_require_codexa_cli
+
+ancestor="$(claudio_find_codexa_repo "$PWD")"
+if [[ -n "$ancestor" ]]; then
+  exec "$NODE_BIN" "$CODEXA_CLI" status "$ancestor"
+fi
+
+declare -a children=()
+while IFS= read -r line; do
+  [[ -z "$line" ]] && continue
+  children+=("$line")
+done < <(claudio_list_child_codexa_repos "$PWD")
+
+case "${#children[@]}" in
+  0)
+    printf 'No codexa-wired repo (.codex/config.toml) found from %s.\n' "$PWD" >&2
+    exit 1
+    ;;
+  1)
+    exec "$NODE_BIN" "$CODEXA_CLI" status "${children[0]}"
+    ;;
+  *)
+    printf '[codexa] no wired repo at %s; fanning out status across %d wired children:\n' \
+      "$PWD" "${#children[@]}" >&2
+    rc=0
+    for child in "${children[@]}"; do
+      printf '=== %s ===\n' "$(claudio_display_path "$child")"
+      if ! "$NODE_BIN" "$CODEXA_CLI" status "$child"; then
+        rc=1
+      fi
+      printf '\n'
+    done
+    exit "$rc"
+    ;;
+esac