8000 Add Codex as the fifth adapter, plus 4 backported fixes by simon-inkie · Pull Request #2 · simon-inkie/inkie-auto-mode · GitHub
[go: up one dir, main page]

Skip to content

Add Codex as the fifth adapter, plus 4 backported fixes - #2

Merged
simon-inkie merged 7 commits into
masterfrom
feat/codex-adapter-plus-backports
Aug 20, 2026
Merged

simon-inkie merged 7 commits into
masterfrom
feat/codex-adapter-plus-backports

Conversation

@simon-inkie
Copy link
Copy Markdown
Owner

Summary

Ports 5 real changes from the internal repo, reviewed twice end-to-end by Folio (independent model-diverse review) with a full builder-then-verify cycle at every stage.

  • Codex adapter: the fifth supported runtime, alongside Claude Code, Cursor, Antigravity, and OpenClaw. Same core/ classifier, same PreToolUse pattern.
  • SAFE_SUFFIXES fix: closes a real arbitrary-exec/write classifier bypass (tee, python3 -c).
  • .gitignore hardening: covers .env.* and *.age credential material.
  • API-key-chain fix: reads GOOGLE_GENERATIVE_AI_API_KEY with the correct fallback order across all three model-calling adapters.
  • Consent-receipt reader: lets the Claude Code adapter treat a signed Mission Control card-tap as out-of-band consent, upgrading an ask/block decision. Off unless both IO_AUTO_MODE_CONSENT_DIR and MC_CONSENT_HMAC_KEY are configured. Fully documented in this PR (README + INSTALL, including the receipt schema and threat boundary).

Review trail

Folio (independent review) held twice before approving:

  1. First pass found a real safety bug in the Codex adapter's apply_patch-abstention guard (a substring match that could let a genuine risk-flagged deny through as allow), missing documentation for the consent feature, and two low-severity fixture/comment leaks. All fixed.
  2. Second pass caught that the fix commits had scrubbed HEAD but left the leaked strings in earlier commits in the outgoing history. Rewritten so the full commit range is clean, verified by hash-identical tree content (nothing about the actual code changed, only how it's packaged into commits).

Final pass: approved, no further amendments.

Test plan

  • pnpm typecheck — clean
  • pnpm test — 314/314 passing
  • pnpm build — all five adapters emit
  • Full origin/master..HEAD object-range scan (patch content + commit messages) for internal references — zero hits
  • Smoke-tested the built Codex dist through the wrapper (deny, allow, apply_patch, MCP passthrough, fail-open fallback)

Simon and others added 7 commits August 20, 2026 17:09
SAFE_SUFFIXES entries are stripped from the command BEFORE evaluateStatic
runs the SHELL_CHAIN_PATTERN guard, so a listed suffix takes its pipe with
it. Two entries on that list conferred real capability:

  tee            arbitrary file write
  python3?\s+-c  arbitrary code execution

so any benign allow-listed prefix laundered an arbitrary payload into a
static ALLOW, and the LLM classifier never saw the command. Verified
before the fix: a bare interpreter call correctly fell through to the LLM,
but the same call behind a listing or read prefix returned a static allow
in 0ms, including the no-3 interpreter spelling and with a stderr
redirection stacked in front. The destination path and the code inside -c
were examined by nothing. This contradicts the file's own note that
interpreters are arbitrary code execution and must go to the LLM.

Both entries removed. The inert output filters (head, tail, wc, sort,
uniq, less, cat, tr, cut, column, jq, plus the separate grep, sed -n and
awk entries) are untouched and keep their static allow.

Tests pin both directions: 8 laundering cases must fall through, 15 inert
filter cases must still allow, so a future re-add fails loudly and so does
a future over-tightening.

Typecheck clean; 277 tests pass / 0 fail.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A bare .env left .env.production, .env.staging and friends committable.
No .env file is tracked in this repo, so the wildcard cannot untrack
anything; !.env.example keeps a documented template possible.

Verified functionally rather than via check-ignore: wrote canary files at
.env.production, .env.staging and probe.age, confirmed git status could not
see them, then removed the canaries.

Nothing has leaked; this closes a latent hole.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…vider

All three adapter model-call sites read only GEMINI_API_KEY / GOOGLE_API_KEY.
GOOGLE_GENERATIVE_AI_API_KEY, the canonical supported name, was never
consulted, so on an environment carrying only that name modelCall threw
before opening a socket and classify() degraded to its stage:"error"
fail-safe on every exec -- no network call, ever.

The lookup now tries GOOGLE_GENERATIVE_AI_API_KEY, then GEMINI_API_KEY, then
GOOGLE_API_KEY. Existing installs on the legacy names keep working.

The chain uses `||` and not `??`. This is load-bearing, not style: `??` only
falls through on null/undefined, so a set-but-empty var would be selected
over a populated later candidate and take the classifier down exactly as
before. The pre-fix chain already hit that trap one slot down, where an empty
GEMINI_API_KEY masked a populated GOOGLE_API_KEY.

Applied to adapters/claude-code/src/model-call.ts,
adapters/cursor/src/model-call.ts, and the inline modelCallFn in
adapters/openclaw/src/plugin.ts. The antigravity and codex adapters import
the claude-code model-call, so every adapter is covered.

tests/model-call-credentials.test.ts adds a deterministic regression guard
for the resolution order and the empty-string behaviour, asserting the key
that actually reaches the wire via a stubbed fetch.

README + INSTALL updated to document the canonical name and the fallbacks.

Typecheck clean; 285 tests pass / 0 fail (was 277).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…de ask/block

Adds an adapter-level layer that lets a human's Mission Control card-tap,
evidenced by a signed out-of-band receipt, upgrade an `ask` or `block`
verdict to `allow`. Strictly upgrade-only: an `allow` is never touched, and
the layer fails closed to a no-op on any error (missing config, malformed
receipt, bad HMAC, clock skew, rename race).

Binding keys, each of which fails independently:
- HMAC over a canonical key-sorted payload, verified with timingSafeEqual
- TTL window (tappedAt <= now <= expiresAt)
- explicit scope: tool name plus glob-lite command patterns. An absent or
  empty scope authorises nothing — a tap is consent to AN action, never to
  any action.

Friction classes map onto the core verdict:
- `block` (destructive): requires confirmed:true (the two-tap), and the
  receipt is CONSUMED via atomic rename to `<id>.used.json` BEFORE the allow
  is emitted, so one tap is one execution and concurrent callers have
  exactly one winner.
- `ask` (standard): multi-use within the TTL.

Disabled unless both IO_AUTO_MODE_CONSENT_DIR (or config.json consentDir)
and MC_CONSENT_HMAC_KEY are set, so existing installs are unaffected.

An optional leading `MC_ACTING_ON=<id>` assignment on the command only sets
receipt preference order; the scope match remains the real gate, so a lying
declaration buys nothing.

Threat model: defends against sloppy self-authorisation and prompt-injected
forgery, not against a shell adversary already running as the same uid.

tests/consent.test.ts covers the happy path, each binding key failing
independently, three forgery classes, two-tap plus single-use consumption,
and every fail-closed path.

Typecheck clean; 306 tests pass / 0 fail (was 285).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Brings the Codex runtime adapter into the public repo under adapters/codex/,
alongside claude-code, cursor, antigravity and openclaw. Same shape as the
Antigravity port: a single PreToolUse hook, a bash entry wrapper, an example
hooks.json, adapter package metadata, tests, build wiring and docs.

What ships:
- adapters/codex/src/pretooluse-hook.ts -- core handler, local imports to
  ../../../core/ and ../../claude-code/src/model-call.js
- adapters/codex/src/types.ts -- Codex PreToolUse wire types
- adapters/codex/bin/pretooluse-hook.sh -- bash entry, dist-then-tsx probe,
  fail-open
- adapters/codex/hooks/hooks.json -- example .codex/hooks.json wiring
- adapters/codex/package.json -- adapter package metadata
- tests/codex-pretooluse.test.ts -- 42 tests (in-process run() unit tests plus
  subprocess tests that assert the stdout body AND the exit code together)
- scripts/build.mjs -- codex adapter registered; builds dist/pretooluse-hook.js
- package.json -- io-auto-mode-codex-pretooluse bin entry, files list,
  description + keywords
- .gitignore -- adapters/codex/dist/ and prompts/ excluded
- README.md, INSTALL.md, docs/adapter-guide.md -- Codex documented as the
  fifth supported runtime

Wire contract, which is NOT the intuitive one and is the main thing to know
about this adapter: the exit code is ALWAYS 0, allow is an EMPTY body ({}),
and deny is hookSpecificOutput.permissionDecision:"deny" plus a non-empty
permissionDecisionReason. Emitting an explicit permissionDecision:"allow" is
rejected by Codex's parser as unsupported, and exiting 2 routes to a
different codepath that ignores stdout entirely and reads stderr as a raw
block reason. Getting either wrong means the deny path silently never blocks.

Classified scope is Bash AND apply_patch. Both carry their content under
tool_input.command. Classifying apply_patch closes a real bypass: a patch can
write a malicious script, overwrite the hook itself, or append to ~/.bashrc,
laundering a payload past a shell-only gate. Because the classifier's system
prompt is shell-shaped, a model refusal that objects only to the input's
FORMAT ("not a shell command") is treated as an abstention rather than a real
deny -- static analysis has already run over the patch content by that point.
MCP and every other tool passes through with a loud stderr warning recording
the real tool name, so a future scope-widening pass has real data.

ask collapses to deny (Codex has no hook-level ask state), matching the
Antigravity precedent. Every classified decision is written to the shared
~/.io-auto-mode/auto-mode-log.jsonl ledger tagged adapter:"codex". Infra
errors fail OPEN with a loud warn -- a broken classifier must never
hard-brick the agent.

Two stale lines in the bash wrapper were corrected against the contract above:
the header claimed "exits 2 on a deny", and the handler-missing fallback
emitted {"permissionDecision":"allow"}, which Codex rejects as unsupported.
The fallback now emits {}.

Build: pnpm build -- clean, emits adapters/codex/dist/pretooluse-hook.js.
Typecheck: tsc --noEmit -- clean.
Tests: 306 pass / 0 fail (42 new codex tests).
Smoke, built dist via the bash wrapper, throwaway HOME:
  rm -rf /   -> deny + reason, exit 0
  git status -> {}, exit 0, ledger entry tagged adapter:codex
  mcp__x__y  -> {}, exit 0, no ledger entry

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…, not a substring

Review finding: isPatchFormatRefusal() converts a classifier DENY into an
ALLOW, and it was a bare substring test. Any deny reason that merely CONTAINED
a format phrase was upgraded to allow -- including reasons that were also
reporting real risk. Concretely,

  "block: patch adds credential exfiltration and is not a shell command"

was allowed, because it contains "not a shell command". The model flagged
credential exfiltration and the adapter let the patch through anyway.

The guard is now subtractive and closed by default: strip the known refusal
phrases and the benign framing they are wrapped in, then require every
remaining token to be inert filler (determiners, copulas, connectives). One
unrecognised word -- "exfiltration", "bashrc", "appends" -- and the deny
stands. Widening FORMAT_FILLER_RE is now explicitly a security-relevant edit.

Also ports the apply_patch-aware prompts/system.txt from the internal repo,
which is the upstream half of this fix: the classifier's system prompt was
shell-shaped, which is what produced the format refusals the guard exists to
absorb in the first place. The prompt now tells the classifier that a patch
body under "command" is expected, that "isn't a shell command" is a format
observation and never a decision on its own, and to judge the patch's actual
file changes against the same risk taxonomy. Benign for the four shell-only
adapters, so it ships repo-wide rather than codex-only. Checked for internal
references before porting; the block is clean.

Tests: 8 new cases in tests/codex-pretooluse.test.ts. Five compound
risk-plus-format reasons pinned as staying DENY (and asserting the real reason
survives to the user rather than being swallowed), three pure format-only
reasons pinned as still abstaining to ALLOW so the guard cannot be
over-tightened into hard-denying benign patches.

Revert-to-red verified: restoring the old substring guard reds exactly the
five compound cases, 45 pass / 5 fail, while all three pure-format cases stay
green -- so the new tests fail for the right reason and are not trivially
passing.

Typecheck clean; 314 tests pass / 0 fail (was 306).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Review finding: the consent-receipt layer upgrades ask/block to allow, so it
is an authorisation bypass by design. Shipping it undocumented means users
cannot audit a control that can turn a block into an allow. Safe-configuration
docs are part of its safety contract, not optional polish.

INSTALL.md gains a full "Optional: Mission Control consent receipts"
subsection under Claude Code, opening with an explicit warning that the
feature can turn a block into an allow. It covers:
- both enabling settings and that the layer is inert unless BOTH are present,
  with no partial-enable state: the directory comes from either the
  IO_AUTO_MODE_CONSENT_DIR env var or consentDir in the config file, while
  MC_CONSENT_HMAC_KEY is env-only
- the receipt file format, with a worked JSON example and a per-field table
  covering which fields are required, which are audit-only, and the exact
  canonicalisation the HMAC is computed over, so a third party can write a
  compatible receipt writer
- the four binding conditions (HMAC, TTL, explicit tool scope, command
  pattern) and that an absent or empty scope authorises nothing
- the two friction classes side by side: ask is multi-use within its TTL,
  block additionally requires the confirmed:true two-tap and is consumed
  single-use by atomic rename before the allow is emitted
- the receipt-directory assumption stated as a security boundary: the consent
  dir must be write-denied to the agents being gated via fileZones, because an
  agent that can write its own receipts can authorise itself
- the threat boundary in both directions -- defends against sloppy
  self-authorisation and prompt-injected forgery, does NOT defend against an
  adversary already running as the same uid, because the symmetric HMAC means
  the verifier holds the signing key
- that MC_ACTING_ON only sets which receipt is tried first, so a lying
  declaration buys nothing

README.md gains a condensed version under Configuration so the feature is
discoverable from the front page rather than only in the install guide, and
links through to the full section.

Docs only; no behaviour change. Typecheck clean; 314 tests pass / 0 fail.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@simon-inkie
simon-inkie merged commit 3a3e71a into master Aug 20, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0