CodeDocs Vault

LLM Leverage Patterns

How Omnigent gets useful, governable work out of coding agents it does not own. Omnigent is a meta-harness: it wraps Claude Code, Codex, Cursor, OpenCode, Kimi, Qwen, Goose, Hermes, Pi and more, and bolts cross-agent oversight, policy, cost control, and a shared web UI onto each one — without forking the agent.

The clever parts are almost all about injection without ownership and normalizing chaos into one interface. This is the stuff worth stealing for any system that has to drive someone else's agent.

All citations are repo-root-relative and machine-verified.

1. Inject Without Owning: CLI-Flag Config Injection

Idea (one line). Don't mutate the target agent's config files — pass Omnigent's hooks and MCP server as inline JSON on the launch command line.

Claude Code parses --settings and --mcp-config as inline JSON arguments, not just files. Omnigent exploits this: it builds its hook + MCP config at spawn time and hands it to claude on the command line. The user's ~/.claude config is never touched.

The injected MCP server is a bare Python module invocation — no pre-installed binary needed:

# omnigent/claude_native_bridge.py:968-991  build_mcp_config()
"mcpServers": {
    _MCP_SERVER_NAME: {
        "command": python,
        "args": ["-I", "-m", "omnigent.claude_native_bridge",
                 "serve-mcp", "--bridge-dir", str(bridge_dir)],

The same launch (augment_claude_args, omnigent/claude_native_bridge.py:1254) appends --mcp-config and --settings (:1310-1312). Hooks register as command subprocesses (python -m omnigent.claude_native_hook) that Claude calls synchronously and reads stdout from for a decision.

Why it's clever. Zero mutation of the target's persistent config. Nothing to clean up, nothing to corrupt, no race with the user's own edits. The injection surface is exactly the agent's documented extension API.

Pitfall. A hook is a fork + Python interpreter startup per event. Cheap to reason about, not cheap to run. And the hook channel is request/response stdin/stdout only — no streaming — so anything that needs to wait for a human (approval) has to park server-side, not in the hook (see §4).

Swisscheese. This is the meta-harness move. If Swisscheese drives Claude Code / Codex as workers, inline-flag injection is how you attach your review/policy layer without forking the agent or fighting its upgrade cadence.

2. Inject Without Owning: Four Different Doors, Same House

Each agent exposes a different extension seam. Omnigent uses whatever the agent already offers, and never patches the agent's code:

Agent Injection seam Channel
Claude Code CLI --settings + --mcp-config inline JSON command-hook subprocesses
Codex a hooks.json written into a private per-session CODEX_HOME command-hook subprocesses + Unix-socket app-server
OpenCode a loopback opencode serve subprocess the runner spawns HTTP POST /session/{id}/message + SSE
Cursor read its SQLite chat store; never inject at all poll store.db, deliver verdicts as keystrokes

Codex's seam is a private home directory. Omnigent writes a hooks.json (_CODEX_HOOKS_FILE, omnigent/codex_native_app_server.py:53) into a per-session CODEX_HOME that Codex loads on startup as a "user"-layer source. Codex's hook-trust model means this only works on new enough Codex, so Omnigent version-gates up front:

# omnigent/codex_native_app_server.py:79
_MIN_POLICY_HOOK_CODEX_VERSION = (0, 129, 0)

Cursor has no hook system and no event socket — its conversation lives in a content-addressed SQLite store. So Omnigent doesn't inject; it tails:

# omnigent/cursor_native_forwarder.py:14-16
# cursor-agent has neither a JSONL transcript nor an event
# socket; its conversation lives in a **content-addressed SQLite store** at
# ``~/.cursor/chats/<md5(cwd)>/<chat-id>/store.db``.

It tracks a high-water rowid and only advances it after a successful POST (:59), so a dropped message is retried rather than lost.

Why it's clever. One product, four wildly different agents, zero forks. The guiding rule is "use the agent's own interface as the source of truth, add a parallel observer." When detection fails, the agent's native behavior is the benign fallback.

Pitfall. Reading a private store (Cursor) or app-server protocol (Codex) is a moving target across upstream versions. Omnigent's own history shows this — it moved Cursor detection from pane-scraping a regex to reading the transcript store because the regex "silently missed any prompt whose wording fell outside" it (omnigent/cursor_native_permissions.py:21-26).

3. One Transport Protocol for Many Wire Formats

Idea (one line). A single Python Protocol (NativeServerTransport) hides "Codex speaks WebSocket JSON-RPC" vs "OpenCode speaks HTTP+SSE" behind send_prompt() / abort(), so one executor drives both.

# omnigent/native_server_harness.py:1-14 (docstring)
# It is deliberately thin and transport-agnostic — the same orchestration drives
# both codex-native (WS JSON-RPC) and opencode-native (HTTP + SSE)

run_turn does the same three steps for every native-server agent: resolve the session id from bridge state, build a NativePrompt, inject it through the transport. Streaming is left to a runner-side forwarder. The prompt builder is a pluggable Callable, so the only per-agent code is the message converter and the concrete transport (OpenCodeHttpTransport etc.).

This is the Strix lesson ("lowest common denominator is text with structure") applied a level up: the lowest common denominator across agents is "inject-a-prompt / abort / stream-events." Everything provider-specific is pushed into a thin adapter.

Why it's clever. Structural typing (Protocol), no base-class inheritance chain. Adding an agent = one transport + one prompt builder. The orchestration never changes.

Pitfall. The abstraction punts on streaming — supports_streaming() -> False for these harnesses; rendering is decoupled onto the runner-side forwarder. Fine here, but it means the harness can't itself react to mid-turn output.

4. Two Gates, Never Collapsed: Policy ≠ User Consent

Idea (one line). Omnigent's policy verdict and the agent's own permission prompt are two independent gates — and the hook is careful to never silence one with the other.

Omnigent translates each agent's hook payload into one neutral EvaluationRequest, POSTs it to /policies/evaluate, and maps the verdict back. The subtlety is in what it doesn't emit. On PreToolUse, a policy ALLOW returns None ("no opinion"), not "allow":

# omnigent/native_policy_hook.py:163-170 (docstring)
# Emitting ``"allow"`` here would auto-approve the
# tool and suppress the harness's native permission prompt ... collapsing
# two independent gates — the deployment's policy gate and the user's own
# consent gate — into one. The policy layer may block (DENY) or demand
# approval (ASK); it must not silence the user's consent.

A DENY maps to permissionDecision: "deny"; a stray ASK that reaches the hook fails closed to "deny" rather than the old "defer" — because defer would hand control back to the harness's permission_mode, which acceptEdits / bypassPermissions would auto-approve, re-opening the very bypass it closes (omnigent/native_policy_hook.py:212-222).

A related gem: in Claude's bypassPermissions mode the PermissionRequest hook never fires, so a built-in AskUserQuestion would be silently swallowed. Omnigent intercepts it via PreToolUse (which fires in all modes), routes the question to the web UI, and rewrites the answer back into Claude's expected updatedInput shape (omnigent/claude_native_hook.py:623-714).

Why it's clever. It recognizes that "the company's policy allows this" and "the human at the keyboard consents to this" are different questions, and that a naive harness collapses them. It also closes a real bypass-mode oversight hole.

Pitfall. Two gates = two approval UIs the user might see (web card + native prompt). And the design depends on each harness honoring "no output = no opinion."

EU AI Act. Article 14 (human oversight) is exactly this distinction: automated policy enforcement must not replace the human's ability to intervene. Keeping policy and consent as separate, non-collapsible gates is a clean structural expression of that.

5. Fail-Closed by Phase, Not by Default

Idea (one line). When policy evaluation is unreachable, fail closed for the pre-execution gate and fail open everywhere else — because by the result phase the side effect already happened.

The native hook is the sole enforcement point for native tools, so a transient server outage must not let a gated call through. But blanket fail-closed would also block already-committed results pointlessly. Omnigent makes the default phase-aware:

# omnigent/native_policy_hook.py:279-287  fail_closed_hook_output()
if hook_event == _PRE_TOOL_USE:
    return {"hookSpecificOutput": {
        "hookEventName": _PRE_TOOL_USE,
        "permissionDecision": "deny",
        "permissionDecisionReason": _EVAL_UNAVAILABLE_REASON}}
return None  # UserPromptSubmit / PostToolUse fail OPEN

This mirrors the server-side contract, which names exactly one phase as fail-closed:

# omnigent/policies/types.py:44-55
# Only ``PHASE_TOOL_CALL`` qualifies ... an unevaluable policy must not
# let the call through.
FAIL_CLOSED_PHASES: tuple[str, ...] = ("PHASE_TOOL_CALL",)

The evaluate POST retries 5xx/connect errors within a 30s budget (post_evaluate_with_retry, omnigent/native_policy_hook.py:290) to absorb brief hiccups before falling closed.

Why it's clever. It distinguishes "block before it happens" (worth failing closed for) from "complain after it happened" (failing closed only blocks an already-incurred side effect). The asymmetry is the whole point.

Pitfall. A real outage denies every tool call until the server returns. That is the safe direction, but it halts the workflow — the retry budget is the only cushion.

EU AI Act. Articles 9/12: a deny-on-uncertainty default for consequential actions, with the choice itself documented per phase, is a defensible risk-management posture and an audit-friendly invariant.

6. One Policy Verdict, N Native Permission Dialects

Idea (one line). A single policy decision (ALLOW / DENY / ASK) is re-encoded into each agent's native approval mechanism — a keystroke here, a JSON token there, a digit-key there.

The server produces one verdict; per-agent mappers translate it:

All of them fail closed: an unmapped verdict yields no auto-reply, forcing a human decision (omnigent/opencode_native_permissions.py:13-15).

Why it's clever. The hard part of guardrails on a foreign agent isn't the decision — it's delivering the decision through whatever surface the agent actually has. Omnigent treats each agent's native UI as a device driver.

Pitfall. Keystroke/pane delivery is fragile and racy: if the user answers in the terminal first, the "loser" verdict is harmlessly dropped, but the timing window is real. Pane-scraping mappers (Hermes/Goose) break on cosmetic UI changes; the transcript-based ones (Cursor) are sturdier but tied to a private schema.

7. Cost Cap as a Model-Downgrade Gate, Not a Kill Switch

Idea (one line). When a session blows its budget, don't stop it — deny tool calls only while on an expensive model, so the user can downgrade with /model and keep going.

# omnigent/policies/builtins/cost.py:103
_DEFAULT_EXPENSIVE_MODELS = ("fable", "opus", "gpt-5")
# :113
_DEFAULT_EXPENSIVE_EXCLUDES = ("-mini", "-nano")

Model matching is substring-based, so one token ("opus") covers databricks-claude-opus-4-8, future point releases, and the bare tier alias alike — with -mini / -nano carved back out as cheap. Unknown model → blocked (fail closed). Soft ask_thresholds_usd checkpoints fire an ASK the first time each is crossed, and an approved checkpoint is recorded in session state so it doesn't re-prompt; a declined one re-asks next turn.

Why it's clever. The exit from the gate is "switch to a cheaper model," not "give up." It keeps the session alive and the user in control of the cost/quality tradeoff, instead of a hard wall. Substring matching means no per-spelling configuration.

Pitfall. It can only budget what it can price — if MLflow pricing is missing for a model, total_cost_usd stays 0 and the cap never trips. And "expensive" is a hardcoded token list that drifts as model lineups change.

Swisscheese. Running many parallel agents, a per-session downgrade-don't-kill cap lets a fleet keep making progress on cheap models after the expensive budget is spent, rather than stalling.

8. Two Surfaces, One Approval Future

Idea (one line). A budget checkpoint can be answered either in a terminal popup or in the web UI — both POST to the same elicitation-resolve endpoint, so whichever answers first wins and the other clears.

# omnigent/native_cost_popup.py (module docstring)
# ... POSTs the verdict to the Omnigent server's elicitation-resolve endpoint —
# the **same** endpoint the web ``ApprovalCard`` uses, so the two surfaces
# resolve one shared elicitation Future (whichever answers first wins; the
# other clears).

The popup runs inside a tmux display-popup overlaid on the agent's pane, one per attached client. AP routing (URL + bearer) is read from a --config-file, not argv, so the token never lands in the process list. Dismissing the popup (Esc/Ctrl-C) posts nothing, leaving the elicitation open for the web card or the server timeout.

For Codex, the elicitation id is deterministic — a sha256 of (session, method, request_id) — so a later serverRequest/resolved notification can clear the exact web card even when another client answered it:

# omnigent/codex_native_elicitation.py:52-53
digest = hashlib.sha256(payload).hexdigest()[:_CODEX_ELICITATION_ID_DIGEST_LENGTH]
return f"elicit_codex_{digest}"

And when a hook's long-poll is severed by a proxy, the retry re-sends one stable _omnigent_elicitation_id so the server re-parks the same elicitation rather than spawning a duplicate approval card (omnigent/native_policy_hook.py:332-337).

Why it's clever. A human can approve from wherever they're looking — terminal or browser — and the system guarantees exactly one resolution even across reconnects and multiple clients. The deterministic id is the trick that makes "clear the right card" survive multi-client races.

Pitfall. The "first POST wins" race is fine for a single human, but it means a verdict can resolve out from under a surface that's still rendering the prompt.

EU AI Act. Article 14 again: oversight that follows the operator across surfaces, with a single auditable resolution per decision, is a strong traceability property.

9. Subscription Agents Still Show Usage

Idea (one line). Agents billed by subscription expose no per-token cost — so surface token counts via the same usage event channel the priced agents use, even when the dollar cost renders as "—".

Cursor fires a per-turn hook; Omnigent records a normalized line to cursor_usage.jsonl, and a runner-owned poller accumulates it (deduped by generation_id) and POSTs the same external_session_usage event that claude-native and codex-native already emit:

# omnigent/cursor_native_usage.py:17-21 (docstring)
# ... appends one line to ``<bridge_dir>/cursor_usage.jsonl``. The runner-owned
# poller ... POSTs an ``external_session_usage`` event — the SAME server
# contract claude-native and codex-native [use]

Dedup by generation_id (add_line, :159) means a poller restart re-reading the append-only file doesn't double-count.

Why it's clever. New agent, zero server changes — it speaks an existing contract. And it gives users some resource visibility for subscription agents that otherwise show nothing.

Pitfall. The agent's model id (claude-4-sonnet) may not match the pricing catalog (claude-sonnet-4-5), so tokens show but cost stays unpriceable until an alias map exists.

10. Push Model Override Down Into a Subscription-Auth'd Agent — Safely

Idea (one line). A per-session model override has to cross a spawn boundary into a CLI you don't control, so treat it as untrusted, shell-shaped data and validate it to a conservative charset before it ever reaches argv.

The override reaches native CLIs as a --model argv element and SDK harnesses as a HARNESS_<H>_MODEL env var. The charset is chosen so the value can never read as a flag:

# omnigent/model_override.py:24
_MODEL_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/\[\]-]*$")

First char must be alphanumeric, so --model --evil is rejected; the tail still admits real shapes (openai/gpt-4o, vendor:tag, claude-opus-4-8[1m]).

Layered on top is a family guard that fails loud at dispatch instead of leaking an unroutable model into a spawn. Codex is GPT-only, Claude harnesses Claude-only, antigravity is Gemini-native and rejects Claude/GPT/databricks- ids (model_family_mismatch, omnigent/model_override.py:110-156). And a mechanical normalizer prepends/strips the databricks- gateway prefix per the child's resolved provider so the same logical model routes correctly whether the child uses the gateway or vendor-direct auth (normalize_model_for_provider, :192).

Why it's clever. It recognizes that "set the model" is a security boundary crossing — the string lands on a command line in a process you don't own. Charset validation + fail-loud family check + provider-aware spelling is defense in depth for a one-line feature.

Pitfall. The family lists are vendor-token heuristics ("contains 'claude'") and the SDK-harness set must stay manually in sync with the runner's env-key map (:27-41) — drift would silently drop an override.

11. Per-Turn LLM Judge Picks the Brain Model — User Pin Always Wins

Idea (one line). Before each user turn, a cheap LLM judge sizes the turn's difficulty and picks one model for the orchestrator's own brain — but an explicit user /model pin always overrides the judge.

# omnigent/runner/cost_advisor.py:21-23 (docstring)
# Precedence: an explicit USER model pin ... BEATS the advisor — the verdict
# is still recorded (``applied=False``) but the brain runs on the user's choice

The verdict (tier + concrete model + rationale) is serialized into one conversation label (cost_control.plan) for UI and replay (omnigent/cost_plan.py). In advise mode it's shadow-only telemetry; in optimize mode it's applied via the inner executor's set_model (no subprocess respawn) — and only for the claude-sdk brain; other harnesses get the label but no application.

Why it's clever. Auto-rightsizing cost without taking the wheel from the user: the human pin is supreme, the judge fills the gap when there's no pin, and even an unapplied verdict is recorded for auditing what the system would have chosen.

Pitfall. A judge call per turn is its own (small) cost, and "difficulty → tier" is a stochastic LLM call — telemetry mode exists precisely to watch it before trusting it.

12. The Secretless Credential Proxy

Idea (one line). A sandboxed tool authenticates to GitHub/SaaS without the real token ever entering the sandbox — the mandatory egress MITM proxy injects the credential on the way out.

The default is swap-on-access: the tool makes its request with no Authorization header, and the proxy recognizes the bound host and injects Authorization: <scheme> <real> outbound. git clone, curl, python — any HTTP client — authenticates with nothing credential-shaped in the sandbox to leak (designs/SANDBOX_CREDENTIAL_PROXY.md, code at omnigent/inner/egress/proxy.py).

For clients that refuse to call without a local token (notably gh, which short-circuits before touching the network), the parent mints a random single-use placeholder prefixed oa_cred_ and injects only that. The proxy swaps it for the real secret — and a placeholder presented for a host it isn't bound to is rejected 403 (the leak guard). The real secret lives only in the parent process and the proxy's in-memory rewrite table, never serialized into the sandbox policy, argv, or disk.

Why it's clever. It inverts the usual "inject the token and hope" model. A prompt-injected tool that reads its own environment finds either nothing (swap-on-access) or a host-bound, non-secret placeholder that 403s anywhere else. The MITM proxy was already mandatory for egress allow-listing, so this is "free" capability reuse.

Pitfall. It requires a hard-isolating backend (linux_bwrap / darwin_seatbelt) so a tool can't open a raw socket around the proxy — the parser rejects the config otherwise. HTTP(S) Bearer/Basic only; SSH remotes are out of scope.

Swisscheese. Worker agents that touch private repos need credentials but are exactly the agents you least trust with a raw token. Swap-on-access is the right shape: the credential is a property of the egress path, not of the sandbox.

EU AI Act. Minimizing secret exposure to autonomous components is a clean security-by-design story for an auditor.

13. Wrapper Labels: Terminal-First UI Without UI Code

Idea (one line). A session carries two tiny string labels — one naming the owning agent, one switching the web UI to terminal-first — so presentation is metadata, not markup.

# omnigent/_wrapper_labels.py:36-37
UI_MODE_LABEL_KEY = "omnigent.ui"
UI_MODE_TERMINAL_VALUE = "terminal"

presentation_labels (omnigent/native_coding_agents.py:38-44) stamps both at creation. The web UI gates on labels["omnigent.ui"] == "terminal" and renders the embedded native PTY as the main view. The omnigent.wrapper value (claude-code-native-ui, etc.) is also what the resume dispatcher reads to route a --resume back to the right runtime, and what the server reads to bypass native-message handling.

The labels are the single source of truth for "which agent, rendered how," centralized in one module so a refactor that diverges a call site fails a CI test (:14-17).

Why it's clever. A foreign agent gets terminal-first presentation in Omnigent's UI with no injected HTML and no agent changes — the session metadata drives a conditional render. One constant, many decoupled consumers.

Pitfall. Stringly-typed contract on the wire: changing a value is a server-side break, which is exactly why it's centralized and CI-guarded.

14. Reasoning-Effort Normalization Across Providers

Idea (one line). Different providers accept different effort ladders; one module holds each provider's frozenset and validates with a stably-ordered, helpful error.

# omnigent/reasoning_effort.py:12-18
OPENAI_EFFORTS = frozenset({"none", "minimal", "low", "medium", "high", "xhigh"})
ANTHROPIC_EFFORTS = frozenset({"low", "medium", "high", "xhigh", "max"})
GEMINI_EFFORTS = frozenset({"low", "medium", "high"})

validate_effort rejects unsupported values before the request reaches the agent, and format_supported imposes a canonical order so the error message ("supported values: minimal, low, medium, high, xhigh") is consistent regardless of set iteration order.

Why it's clever. Centralizes a cross-provider quirk so adding an agent is one frozenset; fails fast with precise guidance instead of an opaque downstream error.

Pitfall. Manual — when a provider adds a level, the constant must be updated; no auto-detection.

15. Omnigent's Own Prompt Footprint Is Tiny — On Purpose

Worth noting what Omnigent doesn't do. It injects no large system prompt into wrapped agents. The only prompts it owns are:

Policy is data (policies: blocks evaluated server-side), never baked into a system prompt. Agent behavior comes from the agent's own instructions (omnigent/spec/AGENTSPEC.md).

Why it's clever. Keeping policy out of the prompt means it can't be argued with by the model or overridden by injected content, and it's auditable as structured config rather than buried in prose. The judge envelope's "payload is data, not commands" line is the same instinct Strix uses for scope anchoring.

EU AI Act. Guardrails as inspectable, versioned configuration (not prompt prose) is materially easier to audit against Articles 9/13.

16. What's Clever, Summarized

17. What To Be Wary Of

Candidate Insight Cards

The strongest standalone tricks (150–400 words each), ranked:

  1. two-gates-never-collapsed — Policy ALLOW must not auto-approve the tool, because the deployment's policy gate and the human's consent gate are different questions. Emitting "no opinion" on ALLOW keeps both alive; ASK fails closed to deny rather than defer to dodge bypassPermissions auto-approval. Evidence: omnigent/native_policy_hook.py:163-222. Direct Article-14 tie. A senior engineer pauses at the defer-reopens-the-bypass reasoning.

  2. fail-closed-by-phase — Don't blanket-fail-closed on a policy outage: fail closed only on the pre-execution gate, fail open once the side effect is already committed, because denying a result phase only blocks something that already happened. Evidence: omnigent/policies/types.py:44-55, omnigent/native_policy_hook.py:279-287. The asymmetry is the insight.

  3. cost-cap-as-downgrade-gate — A budget cap that denies tool calls only while on an expensive model turns "out of money" into "switch to a cheaper model and continue," keeping the user in control of the cost/quality tradeoff. Substring model matching + fail-closed-on-unknown. Evidence: omnigent/policies/builtins/cost.py:103-113, :249-285, :345.

  4. secretless-credential-proxy — The egress MITM proxy (already mandatory for allow-listing) injects credentials on the way out, so nothing credential-shaped enters the sandbox; gating clients get a host-bound oa_cred_* placeholder that 403s anywhere else. Evidence: designs/SANDBOX_CREDENTIAL_PROXY.md, omnigent/inner/egress/proxy.py. Capability reuse + threat-model inversion that a security-minded reader appreciates.