omlx-claude forwards auto-accept unchanged, and a local-model session under it hangs or crashes

[kiki830621]

Problem

Original text:
「我發現如果用qwen 3.8街上claude code的話，必須要把auto mode關掉，否則會出問題」
— Source: pasted text, session of 2026-08-18

(Quoted verbatim. "街上" is a typo for "接上" — "connect qwen 3.8 to Claude Code";
"qwen 3.8" is a local model served by oMLX.)

Running Claude Code on an oMLX-served local model through omlx-claude only works if
auto-accept mode is turned off by hand. Nothing in this command says so, and nothing
stops it.

This is a usage-1 finding. It says nothing about usage 2 (OmlxConnectorMCP), where
Claude is still the agent and the permission model is unchanged — the whole point of the
distinction in CLAUDE.md is that capability measured under one does not transfer.

Type

bug

Priority: P0.

Expected

omlx-claude knows one thing plain claude does not: the model about to drive this
session is a local one whose planning and tool-call formatting are weaker than the hosted
models the permission defaults were designed around. The command already re-asserts
settings a user cannot be trusted to have right (LaunchSettings.overrides) and already
declines to launch in one case where a warning was judged insufficient
(managedBaseURLVerdict). An auto-accepting permission mode belongs somewhere on that
same scale — at minimum named at launch, plausibly refused behind an explicit opt-in the
way OMLX_ALLOW_REMOTE=1 works for the loopback gate.

Actual

Every permission flag is forwarded verbatim, unexamined:

// Sources/OmlxClaude/main.swift
let forwarded = Array(CommandLine.arguments.dropFirst())
// ...
let argv = ["omlx", "launch", "claude", "--settings", settings] + forwarded
execvp("omlx", &cargs)

and the shipped help text states the pass-through as a feature:

Sources/OmlxClaude/Help.swift:26
    --continue, --permission-mode and the rest behave as they always do.

grep -rniE 'permission-mode|permissionMode|acceptEdits|bypassPermissions|dangerously' Sources/
returns that one line and nothing else. There is no gate, no warning, no default, and no
test — ProbeTarget scans argv in an argparse-compatible way for --host/--port, so
the machinery to see a flag exists and is simply not pointed at this one.

Observed with auto mode left on:

• the session hangs or loops — the tool loop repeats the same action, and with
  auto-accept there is no human breakpoint at which it stops;
• malformed tool calls crash the session — the local model emits a tool call that
  does not conform, and it is executed rather than reviewed.

The two are one failure with a common cause: with the confirmation step removed, nothing
sits between a badly formed tool call and its execution.

Impact

The command's stated audience is someone who types omlx-claude and gets a working local
session. Today that person gets a working session only if they already know to disable a
mode the help text tells them behaves normally. The failure is not quiet — it hangs or
crashes — but it is unattributed: nothing in the output connects it to the permission
mode, so the natural conclusion is that the local model, or omlx-claude itself, is
broken.

Not yet captured

No transcript was recorded at the time, so the two symptoms above are reported, not
reproduced here. Reproducing one before designing a gate is part of diagnose — per this
repo's own rule, a fix wants a test that could have failed on the defect, and neither
symptom has a fixture yet.

Open question for diagnose

Whether the right shape is warn, refuse-with-opt-in, or force the mode off. Forcing
it is the only one that cannot be ignored and the only one that overrides a deliberate
choice; the loopback gate reached for refuse-with-opt-in for a reason worth re-reading
here.

Sister concern

#12 — same source message, same command, different defect. They compound: auto-accept
plus a configuration shared with the operator's ordinary sessions is what turns "a local
model made a mistake" into "a local model edited my setup".

Clarity Surface(idd-clarify run 2026-08-18T06:18:43Z)

Type	Source	Question for you	Status
terminology	「必須要把auto mode關掉」	「auto mode」是指 Claude Code 裡的哪一個？shift+tab 切的 auto-accept edits、--permission-mode acceptEdits、還是 bypassPermissions？（三者要擋的範圍不同，決定 gate 攔在哪一層）	resolved @ 2026-08-18T06:24:54Z (reason: 使用者確認：指 shift+tab 切的互動式 auto-accept edits（session 內切換，非啟動 flag）)
terminology	「用qwen 3.8」	oMLX 上這個模型的實際 model id 是什麼？（決定這條 gate 是對所有 oMLX 模型一律套用，還是只在特定模型上觸發）	resolved @ 2026-08-18T06:24:54Z (reason: 改判為套用範圍決策；使用者確認：一律套用於所有 omlx-claude session，另提供環境變數 opt-out（比照 OMLX_ALLOW_REMOTE）)

---

Current Status

Phase: needs-fix
Last updated: 2026-08-19 by idd-verify

Key Decisions

• Verify FAIL — 1 blocking, 4 in-scope fixes, 4 follow-ups, 5 withdrawn. Report: #issuecomment-5332342767. No idd-11-verified tag (tag is PASS-only).
• BLOCK-1: the disableAutoMode assertion is very likely inert for this launcher's own sessions, by two independently documented paths — CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC (asserted three lines above it) disables feature-flag fetching, which already forces Manual; and auto mode requires a model Claude Code recognizes, which an oMLX-served id never is. The mechanism is fine; README, the AUTO MODE help section and the main.swift notice all misattribute auto mode being off to it. Same treatment as CLAUDE_CODE_DISABLE_1M_CONTEXT is a no-op for oMLX-served models, so the #2716 workaround does not bound the session (sister concern from #2) #6: keep the key, stop calling it the reason.
• Unresolved tension, must not be settled by assertion: the reporter's experience says auto mode was on; the documentation says it should not have been available. No live session was observed — the same condition under which #2716's misattribution shipped. Run a real omlx-claude --permission-mode auto session and record the mode indicator before rewriting the prose.
• Three in-scope fixes (IS-1, IS-2, IS-4) are the same defect the change itself was fixing: a notice sentence true only for the key population imagined when it was written. Third instance in this change alone.
• Five claims withdrawn as mechanically impossible, including a HIGH built on misreading autoMode (a classifier-rules object, not a switch). Acting on them would have broken correct code.

Scope Changes

• (none) — no scope creep found; omlx-claude shares the operator's Claude Code configuration, so a local-model run edits their real setup (sister concern from #11) #12 and A user-supplied --settings lands after ours and nothing detects it #10 boundaries held.

Blocking

• BLOCK-1 attribution rewrite, gated on a live-session observation.
• IS-1 the address sentence still fires for credential-only managed conflicts (2/3 of the trigger set), and the new tests cannot go red on it.
• IS-2 managedConflicts fires on presence not value, so a managed policy that agrees with us is reported as defeating us.
• IS-3 with OMLX_ALLOW_AUTO_MODE=1 the notice claims we asserted a key we deliberately did not.
• IS-4 the doc comment and CLAUDE.md give a false reason for the notice change — false before omlx-claude forwards auto-accept unchanged, and a local-model session under it hangs or crashes #11 too, for eight pre-existing keys.

Verify engine (degraded — recorded, not hidden)

• Cross-model Codex leg disabled (unavailable at operator's request) → no blind check outside the Claude family.
• Devil's Advocate errored on the first attempt; re-run via workflow resume and completed. Findings are post-DA. The pre-DA table contained a HIGH that would have sent the author to change working code.

Commits

• 27cdd03, 07c2b8d, 924b5bc, 3f152d1, 9d12a56, 6543db0 — all verified against FROZEN 6543db0 (freshness gate passed)

[kiki830621]

Diagnosis

Type

bug

Root Cause / Analysis

"auto mode" is not a loose description. It is a named Claude Code permission mode, and
on Pro / Max / Team plans it is the built-in mode a session starts in.

From the current Claude Code documentation (code.claude.com/docs/en/permission-modes):

On Pro, Max, and Team plans, the built-in starting mode is auto mode.

| auto | Everything, with background safety checks | Long tasks, reducing prompt fatigue |

In auto mode, a second model, the classifier, reviews actions instead of you.

and on which mode a session starts in:

1. The --permission-mode flag, or --dangerously-skip-permissions
2. permissions.defaultMode in a settings file
3. The built-in default

The built-in auto default requires Claude Code v2.1.228 or later on macOS, Linux, and WSL.

So the chain is:

1. omlx-claude swaps out which model drives the session — that is its entire purpose.
2. It does nothing about the permission mode, so the session lands on the built-in
   default, which on these plans is auto: everything runs, reviewed by a classifier
   rather than by the operator.
3. Auto mode's premise is that the acting model is competent enough that a second-model
   review is the right level of oversight. Replacing the acting model with a local one
   invalidates that premise, and nothing in the launch path notices.
4. Both reported symptoms follow directly. Loops — auto mode is documented for
   "long tasks, reducing prompt fatigue", so the confirmation step that would have broken a
   repeating tool loop is gone. Malformed tool calls crashing the session — the
   classifier reviews whether an action is allowed, not whether the call is well-formed,
   so a malformed call is not something it is positioned to stop.

The precise defect is narrower than "no gate exists", and that is the useful part.

Claude Code already ships the exact key needed:

disableAutoMode — Set to "disable" to prevent auto mode from being activated.
Removes auto from the Shift+Tab cycle, and any session that would otherwise start
in auto mode, whether from --permission-mode auto, a settings file, or the built-in
default, starts in default instead. Also accepted under permissions as
permissions.disableAutoMode.

That covers the case the reporter actually identified — the interactive Shift+Tab toggle,
which a command that execs and disappears otherwise has no way to reach.

And omlx-claude already passes a --settings payload that outranks the user's own
settings files. The reason it cannot carry this key is structural:

// Sources/OmlxClaude/LaunchSettings.swift
static func settingsJSON(baseURL: String, authToken: ProbeTarget.AuthToken) throws -> String {
    let payload = ["env": overrides(baseURL: baseURL, authToken: authToken)]
    // ...
}

The payload is shaped as an env block and nothing else. disableAutoMode is a
top-level settings key, not an environment variable, so there is no slot for it — and by
extension no slot for any other non-env setting this launcher might ever need to assert.
LaunchSettings is documented around a single axis ("override what we can determine
independently, report the rest"), and that axis was implicitly scoped to environment
variables only.

Root cause, one sentence: the --settings override payload is env-vars-only, so the
one documented key that would keep a local-model session out of auto mode has nowhere to go,
and no other part of the launch path looks at permission mode at all.

Impact

• Files: Sources/OmlxClaude/LaunchSettings.swift (payload shape + the new key + opt-in
  parsing), Sources/OmlxClaude/Help.swift (document the behaviour and the opt-out),
  Tests/ (see Strategy), README.md / CLAUDE.md (the override is described in both).
• User flow: every omlx-claude session on a Pro / Max / Team plan running Claude Code
  v2.1.228+, unless the operator already knows to Shift+Tab out. The help text currently
  tells them the opposite — that permission flags "behave as they always do".
• Harness-specific: the reporter notes that the common pattern is wiring a local model
  into Hermes, whereas this is wiring it into Claude Code. That choice is why this bites:
  Claude Code's default oversight level is calibrated for a hosted model, and omlx-claude
  changes the model without changing the calibration.

Strategy

Step 1 is a verification step and must come first. The documentation enumerates the
scopes that read autoMode ("user settings, the --settings flag, and managed settings")
but does not enumerate them for disableAutoMode. Asserting the key and assuming it
lands is exactly the mistake this repo already recorded once, with
CLAUDE_CODE_DISABLE_1M_CONTEXT (#6): a key that Claude Code accepts and silently ignores,
shipped under a claim that it was the fix, while the disproving evidence sat unread in the
run output. Do not repeat the shape.

• Verify empirically that --settings '{"disableAutoMode":"disable"}' takes effect.
  Launch a real session with it and confirm auto is gone from the Shift+Tab cycle and
  the session starts in default. If it is not honoured there, stop and re-plan — the
  fallback (injecting --permission-mode default into argv) is a different design and
  collides with a user-supplied flag.
• Widen settingsJSON from ["env": …] to a payload that can carry top-level keys.
  This is the actual structural change; the new key is a consequence of it.
• Assert disableAutoMode: "disable" by default for every omlx-claude launch,
  independent of which model oMLX ends up serving. Deciding per model id would mean
  replicating oMLX's model selection — the fork this repo exists to avoid, and the same
  reasoning as modelDependentKeys.
• Add the opt-out, mirroring OMLX_ALLOW_REMOTE: an explicit env var that restores auto
  mode. Accept only the literal 1, so a stray true does not open the door —
  LoopbackPolicy already establishes this and has the tests for it.
• Warn when we downgrade a deliberate choice. A user who passes --permission-mode auto
  is documented to be silently downgraded to default by this key. Silence there is the
  failure mode this repo keeps rediscovering; name it, the way unwinnableConflicts names
  what it cannot win.
• Tests. Each must be able to fail on the defect: a payload-shape test that fails against
  the current env-only shape; an opt-out test asserting OMLX_ALLOW_AUTO_MODE=true does
  not open it; and at least one positive case — the key must not be asserted
  unconditionally in a way that "refuses everything" and passes every negative test.
• Update Help.swift, README.md, CLAUDE.md. The current help line
  ("--permission-mode and the rest behave as they always do") becomes false.

Depends on #10. #10 records that a user-supplied --settings lands after ours and
nothing detects it. If that is true, a user passing their own --settings can override
disableAutoMode and this fix silently reverts. The guarantee here is bounded by #10 and
should say so rather than claim more.

Not covered: managed (MDM) settings outrank --settings, so a policy that enables auto
mode wins. That is the same population managedConflicts already reports on; whether this
key deserves the stronger managedBaseURLVerdict treatment (refuse to launch) is a Plan
decision, not a foregone one.

Conflict Class

C_shared_module_coord — shares Sources/OmlxClaude/LaunchSettings.swift and the
settingsJSON payload shape with #12 (config isolation), which also has to decide what the
launch asserts versus what it exports as real environment before execvp. Sequencing the two
avoids two different answers to "what shape is the launch configuration".

Complexity

Plan

Layer P signals triggered:

• Decision-heavy, 2+ valid approaches — top-level disableAutoMode vs
  permissions.disableAutoMode; whether to also assert permissions.defaultMode; warn vs
  refuse on a deliberate --permission-mode auto; and an entirely different design if Step 1
  shows the key is not honoured via --settings.
• Risk-sensitive boundary — this is the permission boundary. Getting it wrong in the
  permissive direction reproduces the reported crashes; in the restrictive direction it
  silently overrides a deliberate operator choice.
• 5+ ordered steps with real dependencies — verification gates the payload change, which
  gates the key, which gates the opt-out and the tests.

Layer 1: not applicable (behaviour change, not narrative). Layer 2 (published contract for
future callers): not met — the new env var is operator-facing config, the same category as
the existing OMLX_ALLOW_REMOTE, which did not warrant Spectra.

Layer V: V1=2 V4=3 — not triggered (both axes ≤ 3). Both axes scored after the Clarity Surface rows were resolved: WHAT is now specific (assert one documented key + an env opt-out), ACCEPTANCE is stated as a runnable check (auto absent from the Shift+Tab cycle; session starts in default; opt-out accepts only "1").

Hard-gate: not triggered — the change is one concept living in one type (LaunchSettings); the other touched files are its help text, its tests and the two docs that describe it, which is the ordinary impl+test+doc shape the N=5 threshold was chosen not to catch. settingsJSON has one production caller (main.swift), below the ≥2 shared-abstraction bar.

Risks

• The key is not read from --settings. Highest-impact unknown; Step 1 exists for it.
• Asserting it makes omlx-claude less usable than plain omlx launch claude for someone
  who wanted auto mode. Mitigated by the opt-out, but the default is a real choice being made
  on the operator's behalf.
• The fix is bounded by A user-supplied --settings lands after ours and nothing detects it #10. A user-supplied --settings may override it.
• No CI-observable effect. Whether auto is even the built-in default depends on plan
  tier and feature flags, so the end-to-end behaviour cannot be asserted in the hermetic
  suite. What can be tested is the payload we emit — and per this repo's own note, the
  wiring in main.swift has no unit test and must be checked by hand.

Residue

The issue's intent is "make omlx-claude safe to hand to someone who just types it". Part of
that does not operationalize: no permission mode makes a local model emit well-formed tool
calls or stop looping. Disabling auto mode converts unattended damage into prompts — it
relocates the failure to where a human can see it, which is the honest claim, and is less than
"fixes the problem". The reporter's second symptom in particular (malformed tool calls) is a
model-capability fact that this change surfaces rather than removes.

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

Four candidates surfaced during root-cause analysis. None filed as new issues — each is
either already tracked or is in-scope for this one. Recorded so the decision is auditable
rather than silent:

Candidate	Disposition
A user-supplied --settings lands after ours and can override disableAutoMode	Already filed — #10. Linked from Strategy as a dependency; this fix's guarantee is bounded by it. No new issue.
The ["env": …] payload shape blocks every non-env settings key, not just this one	In scope here. It is the root cause, not a sibling — filing it separately would split one defect across two issues.
Asserting the key silently downgrades a deliberate --permission-mode auto	In scope here. Added to Strategy as a warn step; it is a property of this change, and would not exist without it.
Managed (MDM) settings can enable auto mode and outrank --settings — should this get the managedBaseURLVerdict refuse-to-launch treatment?	Deferred to Plan, recorded under Strategy "Not covered". It is a decision the plan must make, not an independent defect.

[kiki830621]

Implementation Plan (Plan tier)

Step 0 — Verification gate (blocks everything below)

Not a task in the plan; a precondition for it. The documentation enumerates the scopes
that read autoMode and does not do so for disableAutoMode, so the whole design rests
on an unverified premise. Shipping first and finding out later is the
CLAUDE_CODE_DISABLE_1M_CONTEXT / #6 shape exactly.

claude --settings '{"disableAutoMode":"disable"}'
# then press Shift+Tab through the cycle

• Pass — auto is absent from the cycle and the session starts in Manual (default).
  Proceed.
• Fail — stop and re-plan. The fallback is injecting --permission-mode default into
  argv, which collides with a user-supplied --permission-mode and is a different design,
  not an adjustment to this one.
• Partial — if only permissions.disableAutoMode works, swap the spelling in step 2 and
  carry on; nothing else changes.

Record the result and the Claude Code version in the Implementation Complete comment. It is
the only evidence this key does anything.

Files & Changes

• Sources/OmlxClaude/LaunchSettings.swift — the substantive change, in three parts:
  • Widen the payload past env. settingsJSON currently builds ["env": overrides(...)];
    it becomes a function that assembles a top-level dictionary of which env is one member.
    This is the actual defect being fixed — the key is a consequence.
  • Add autoModeOptIn(environment:) -> Bool, true only for the literal "1". Mirrors
    LoopbackPolicy's opt-in, deliberately, including that "true" does not count.
  • Emit "disableAutoMode": "disable" unless opted in.
• Sources/OmlxClaude/main.swift — note when we downgrade a deliberate choice: if the
  forwarded argv carries --permission-mode auto (or --permission-mode=auto), say so on
  stderr, in the register unwinnableConflicts already uses. Respect --; nothing past it
  is a flag. Untestable by the suite (this file execs), so hand-check it.
• Sources/OmlxClaude/Help.swift — three edits: the line "--permission-mode and the
  rest behave as they always do" becomes false and must go; OMLX_ALLOW_AUTO_MODE joins the
  ENVIRONMENT block; a short section states that auto mode is off by default here and why.
• Tests/OmlxConnectorMCPTests/LauncherTests.swift — see Test Plan.
• README.md, CLAUDE.md — both describe the --settings override as an env
  mechanism. After this it carries non-env keys, and the split "override what we can
  determine / report what we cannot" gains a third category: defaults we set on the
  operator's behalf.

Family-wide scope (shared-abstraction hard-gate trigger only)

n/a — the hard gate did not trigger on shared abstraction. settingsJSON has one production
caller (main.swift), below the ≥2 bar.

Sequencing & Dependencies

1. Step 0 gate. Nothing below is worth writing until it passes.
2. autoModeOptIn + its tests. No dependency on the payload change; land first so step 3 has
   something to condition on.
3. Payload shape widened, with the existing env contents asserted unchanged. The
   regression risk here is not the new key, it is silently dropping an existing one during
   the refactor.
4. The key itself, conditioned on step 2.
5. The argv note in main.swift. Independent of 2–4; last because it is the only piece with
   no automated coverage.
6. Docs, once the shipped behaviour is settled.

Branch and PR are idd-implement's job (pr_policy: always); the branch should come off
main, not off the current feat/2-unified-omlx-claude-module.

Decision Points

Decision	Pick	Why
Top-level disableAutoMode vs permissions.disableAutoMode	Top-level	The docs give it as the primary spelling and note the nested one is "also accepted". Step 0 overrides this if only the nested form works.
Also assert permissions.defaultMode: "default"?	No	It would override an operator's deliberate acceptEdits default, which this issue is not about. disableAutoMode targets exactly the reported mode and nothing else.
Warn or refuse on a deliberate --permission-mode auto?	Warn	Refusing would break a launch that plain omlx launch claude allows — a regression against the thing we wrap, which this repo has already made once (the 401 preflight) and reverted. Refusal is reserved for the content-stays-local invariant (managedBaseURLVerdict); auto mode is a safety default, not that invariant.
Apply per model, or always?	Always	Branching on model id means replicating oMLX's model selection — the fork this repo exists to avoid. Same reasoning as modelDependentKeys.
Opt-out accepts what?	The literal "1" only	LoopbackPolicy already set this precedent and has the test that a stray "true" does not open the door.
Solve it via the isolated config dir instead?	No — see #12	Confirmed with the operator. CLAUDE_CONFIG_DIR is undocumented; if it silently stopped working the session would fall back to the real ~/.claude and both isolation and the auto-mode guarantee would die at the same moment. Independent mechanisms fail independently.

Risks & Mitigations

• The premise is wrong — Step 0 exists for this, and it gates rather than warns.
• A managed policy re-enables auto mode. Not fixed, and deliberately not escalated to the
  managedBaseURLVerdict refuse-to-launch treatment: that is reserved for the address
  invariant. It should be named, which managedConflicts will do once the key is added to
  the list it checks.
• Bounded by A user-supplied --settings lands after ours and nothing detects it #10. A user-supplied --settings lands after ours. The docs and the help
  text must claim only what A user-supplied --settings lands after ours and nothing detects it #10 permits — not "auto mode is off", but "this launch asserts it
  off".
• Refactor drops an env key. Step 3's regression assertion is the guard, and it is the
  reason step 3 is separate from step 4 rather than one commit.
• The main.swift note is unverifiable by the suite. The repo already records that its
  wiring has no unit test and that a mutation there stayed green. Hand-check, and say in the
  Implementation Complete comment that it was hand-checked.

Test Plan

In Tests/OmlxConnectorMCPTests/LauncherTests.swift. Every case below must be run against
the current code first and observed to fail for the right reason:

Test	Invariant	RED against today
testPayloadCarriesDisableAutoModeAtTopLevel	the emitted JSON has disableAutoMode == "disable" outside env	today the payload is ["env": …]; the key cannot exist
testOptInSuppressesTheKey	with OMLX_ALLOW_AUTO_MODE=1 the key is absent	the one positive case. Without it, hardcoding the key unconditionally passes every negative test — the "a check that refuses everything passes every negative test" failure this repo has already had once
testOptInAcceptsOnlyLiteralOne	"true", "yes", "01", " 1", "1 ", "", unset → key still emitted	fails against any truthy/non-nil parse
testEnvOverridesSurviveThePayloadChange	every key overrides produced before is still present, same values	fails if the refactor drops one
testDeliberateAutoFlagDetected	--permission-mode auto and --permission-mode=auto detected; --permission-mode default not; auto after -- not	fails against a naive contains("auto")

Fixtures must not all break in the same place — the near-miss cases ("1 ", --permission-mode default, auto after --) exist precisely because the last three rounds of this repo shipped tests whose fixtures were drawn from the same mental model as the code and so could not disconfirm it.

Plus, by hand and recorded: Step 0's Shift+Tab check, and one real launch confirming the
main.swift note fires.

Out-of-scope (will NOT be touched)

• Config isolation / CLAUDE_CONFIG_DIR — omlx-claude shares the operator's Claude Code configuration, so a local-model run edits their real setup (sister concern from #11) #12. Verified mechanism recorded there.
• Detecting a user-supplied --settings — A user-supplied --settings lands after ours and nothing detects it #10. This plan depends on it and does not fix it.
• permissions.defaultMode, acceptEdits, bypassPermissions — a different decision
  about a different mode. Only auto mode was reported.
• Anything that makes the local model produce better tool calls. Per the diagnosis
  Residue: this relocates the failure to where a human can see it; it does not remove it.

Tangential Observations (filed mid-plan, v2.42.0+ #524)

One surfaced, none filed as new:

• The operator's separate-config proposal, and the empirical verification of
  CLAUDE_CONFIG_DIR — already has an issue (omlx-claude shares the operator's Claude Code configuration, so a local-model run edits their real setup (sister concern from #11) #12); recorded there as a note
  (#issuecomment-5324595291) rather than duplicated. It answers omlx-claude shares the operator's Claude Code configuration, so a local-model run edits their real setup (sister concern from #11) #12's open question 1 and
  adds an undocumented-dependency risk that was not in its body.

[kiki830621]

Implementation Complete

Step 0 verification gate — passed

The premise this plan was gated on, checked before any code was written:

claude --settings '{"disableAutoMode":"disable"}'

auto is absent from the Shift+Tab cycle and the session starts in Manual. Claude Code
2.1.234. The key is honoured through --settings, so the documented spelling stands and
the permissions.disableAutoMode fallback was not needed.

This is recorded rather than assumed because the docs enumerate the scopes that read
autoMode and not the ones that read disableAutoMode — and because #6 is what shipping
an unverified key looks like.

Checklist (synced from TaskList)

• autoModeOptIn, literal 1 only → 27cdd03
• Payload widened past env; disableAutoMode emitted; managedConflicts extended → 07c2b8d
• Note when a deliberate --permission-mode auto is overridden → 924b5bc
• --help, README, CLAUDE.md → 3f152d1, 6543db0
• Managed-conflict notice no longer claims an address problem it may not have → 9d12a56

Legend: - [x] done · - [~] skipped · - [-] won't fix

Plan steps 3 and 4 landed in one commit. They were separated in the plan for review
clarity, but TDD-wise they are one change: the only test that can go red is "the payload
carries a top-level key", and making it green is widening the shape. Splitting them would
have meant faking a RED — the env-preservation test is characterization, green before and
after, and it is labelled as such in the suite.

Changes

• 27cdd03 the opt-in, with LoopbackPolicy's strictness
• 07c2b8d payload shape + disableAutoMode + managed registration
• 924b5bc the downgrade note, ahead of the preflight
• 3f152d1 help / README / CLAUDE.md
• 9d12a56 the managed notice's address sentence made conditional
• 6543db0 CLAUDE.md: the rule 9d12a56 followed — move text out of main.swift so it can be asserted on

Where the commits went

Onto feat/2-unified-omlx-claude-module, carried by PR #7 — not a new branch. main
has no Sources/OmlxClaude/ at all; the whole command is unmerged, so #11 is a defect in
code PR #7 introduces and that has never shipped. The plan said "branch off main", which
was written without checking and would have produced a tree where this change cannot exist.
Operator's call, recorded here because the plan file still says otherwise.

Two inert-mechanism traps, both avoided by testing first

Each looked exactly like the obvious implementation, and each would have been a check that
can never fire — the CLAUDE_CODE_DISABLE_1M_CONTEXT shape one level down:

1. managedConflicts filters managedSettings["env"]. Registering disableAutoMode
   there, as the plan's wording invited, would never have matched: it is a top-level
   settings key, not an environment variable. It is now read from the top level and from
   permissions.disableAutoMode, since Claude Code documents both and a policy using the
   unwatched spelling would go unnamed.
2. ProbeTarget.value cannot scan for --permission-mode. It resolves every token
   through matchOption, which only recognizes omlxOptions, so it returns nil for any
   Claude Code flag under every input. Reusing it would have produced a detector that never
   fires. deliberateAutoModeRequested scans separately, matching exactly — Claude Code's
   parser takes no argparse-style prefixes.

Both are recorded in CLAUDE.md, because finding them a third time costs more than writing
them down.

One defect introduced and fixed inside this change

Adding disableAutoMode to managedConflicts made an existing sentence false: the notice
ended with "the address checked above may not be the address the session uses", which is
true only while every key it can name is an address or credential. 9d12a56 moves the text
into LaunchSettings.managedConflictNotice — testable, unlike everything in main.swift —
and makes the address sentence conditional.

Verification

make test — 112 Swift tests, 21 shell assertions, 0 failures. (One pre-existing skip:
the verify-download.sh positive case needs DEVELOPER_ID.)

Every new guard was watched failing first, and the three behavioural ones were
mutation-proven with the mutation asserted before its result was read — this repo has
already been fooled by a sed that silently did not match:

Mutation	Goes red
emit disableAutoMode unconditionally	testOptInSuppressesTheKey
relax == "1" to != nil	testOptInAcceptsOnlyLiteralOne (true, TRUE, yes, …)
restore the unconditional address sentence	testAddressSentenceAppearsOnlyWhenAnAddressKeyIsNamed

Each has a paired positive case, so none of them is a check that refuses everything and
passes every negative test.

Hand-checked against the built binary, since main.swift has no unit test and a
mutation there leaves the suite green:

--permission-mode auto              → note fires
--permission-mode default           → silent
-- --permission-mode auto           → silent (terminator honoured)
-p "tell me about auto mode"        → silent (bare word is not a flag)
OMLX_ALLOW_AUTO_MODE=1  … auto      → silent
OMLX_ALLOW_AUTO_MODE=true … auto    → still fires

The last two are the pair that matters: the opt-in has to reach the call site, not only the
payload, and stay strict on the way.

Not verified end to end. No oMLX server was running, so no session was launched on a
local model with this build. What is proven is that the key works through --settings and
that the payload contains it; that a real omlx-claude session starts in Manual has not
been observed.

Scope Compliance

In scope. One thing was added that the plan did not list — the managedConflictNotice
extraction — and it is not creep: it repairs a claim this change itself made false.

The plan's Out-of-scope held. CLAUDE_CONFIG_DIR isolation stayed in #12, --settings
detection stayed in #10, and no other permission mode was touched.

Sister Bugs Filed (mid-impl, v2.44.0+ #526)

• Generated .claude/.idd/attachments/ is untracked and shows up as dirt in git status (sister concern from #11) #13 — generated .claude/.idd/attachments/ is untracked and dirties git status.
  One line of .gitignore; unrelated to auto mode, so it is not folded in here.

Considered and not filed: the stale .build from a Swift 6.2.4 → 6.3.3 toolchain change
(local environment, not this repo) and the non-reusability of ProbeTarget.value (a
documented design fact now, not a defect).

Next: verification pending

[kiki830621]

Verify: #11

Engine

pai-ensemble 2.20.0 (canonical, #207) — 4 IDD lenses + Devil's Advocate, model: opus.

This run is degraded, in two ways, and neither is hidden:

• Cross-model blind check absent. The Codex leg (gpt-5.x) was disabled at the operator's
  request — it was unavailable. Every reviewer here is Claude, so a blind spot shared across
  the model family would not be caught by anyone.
• The Devil's Advocate errored on the first attempt, leaving 35 findings from four lenses
  with nothing challenging them. It was re-run via workflow resume (the four lenses replayed
  from cache) and completed on the second attempt. The findings below are post-DA. The
  first-attempt table would have sent the author to change working code — see "Withdrawn".

Freshness gate: FROZEN 6543db0 == HEAD 6543db0 — ensemble judged the shipped snapshot.

Aggregate

FAIL — 1 blocking, 4 in-scope fixes, 4 follow-ups, 5 withdrawn.

The implementation does what the plan said. What it does not do is what the prose says it
does, and one of those claims is load-bearing enough to block.

Requirements coverage

Acceptance	Verdict
(a) session does not start in auto mode	Achieved — but not by this change. See BLOCK-1.
(b) opt-out accepts only the literal 1	FULLY addressed, mutation-proven
(c) a deliberate --permission-mode auto is named	Addressed; three argv edge cases misfire (FU-4)
(d) docs stop claiming permission flags pass through	Addressed, but replaced with a different false claim (BLOCK-1)

---

BLOCK-1 — the mechanism is very likely inert here, and three places say it is the reason auto mode is off

Devil's Advocate; missed by all four lenses; independently re-verified against the Claude
Code documentation before being accepted.

Claude Code's permission-modes reference gives the built-in starting mode as a
first-match-wins table:

How you run Claude Code	Built-in starting mode
Any settings file sets disableAutoMode to "disable"	default
Feature-flag fetching is off, or first session after install/upgrade	default
claude -p or the Agent SDK	default

Row 1 is what this change adds. Row 2 was already true for every omlx-claude session,
because the payload asserts CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" — three lines
above the new key, in the same dictionary — and the env-vars reference says of it:

Also disables feature-flag fetching, which makes […] features that need feature-flag
fetching unavailable.

There is a second, independent path to the same place. Auto mode is available only when the
model supports it:

Model: […] Claude Opus 4.6 or later, Sonnet 4.6 or later, or Fable 5. Older models […]
are not supported on any provider.

When the flag, a settings file, or the built-in default selects auto but auto mode isn't
available to the session, Claude Code starts the session in Manual instead. Auto mode is
unavailable when a settings file turns it off or the model doesn't support it.

This repository already establishes, in three separate places (Help.swift,
LaunchSettings.swift, UpstreamWorkaround.swift), that oMLX-served model ids are never
recognized by Claude Code.

This is the CLAUDE_CODE_DISABLE_1M_CONTEXT / #2716 shape, and the diff cites that scar
twice while stepping into it one level up. The mechanism is harmless and correct if a model
is ever recognized. The defect is the claim: README, the new AUTO MODE help section, and
the main.swift notice all attribute auto mode being off to this assertion.

What blocks: the attribution, not the code. Same treatment #6 already established — keep
the key, stop calling it the reason.

Unresolved, and it must not be resolved by assertion. The reporter's own experience is
that auto mode had to be turned off by hand, which means it was on. The documentation says
it should not have been available. One of those is wrong, and no live session was observed —
the same condition under which #2716's misattribution shipped. Run a real
omlx-claude --permission-mode auto session and record what the mode indicator says before
rewriting the prose; doing it in the other order risks writing the correction twice.

---

In-scope fixes

#	Severity	Finding	Source
IS-1	MEDIUM	The address sentence still fires for credential-only conflicts. addressKeys contains ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY, so a managed policy that sets only a credential still gets "the address checked a moment ago may not be the address the session uses". Two thirds of the trigger set emits the false sentence that 9d12a56 was written to remove, and ManagedConflictNoticeTests cannot go red on it — every fixture is a key list.	logic + regression, confirmed by DA
IS-2	MEDIUM	managedConflicts fires on presence, not value. A managed disableAutoMode: "disable" agrees with us; the notice then tells the operator we were defeated. The plan's own scoping said only a policy that enables auto mode is worth naming. On a managed Mac this is the common path, not an edge case.	requirements + regression + security, confirmed by DA
IS-3	MEDIUM	With OMLX_ALLOW_AUTO_MODE=1 the notice claims we asserted something we deliberately did not. managedConflicts is blind to the opt-in.	logic, confirmed by DA
IS-4	MEDIUM	The doc comment and CLAUDE.md give a false reason for the notice change. "It used to be unconditional, which was true while every key this could name was an address or a credential" — that was already false before #11, for eight pre-existing model-dependent keys, for which the launcher asserts nothing at all.	regression, confirmed and sharpened by DA

IS-1 and IS-4 are the same defect I introduced in 9d12a56 and in the commit that documented
it: a sentence true only for the key population imagined when it was written. Third instance
in this change alone.

---

Follow-up

#	Finding	Note
FU-1	Docs state the auto-mode premise without the version qualifier the diagnosis quoted (v2.1.228+ / 2.1.233 on native Windows)	Fold into the BLOCK-1 rewrite
FU-2	The opt-out is completely silent when set — the operator cannot tell which oversight level they got	DA downgraded from HIGH: isomorphic with OMLX_ALLOW_REMOTE, which is riskier and equally silent. Fix both together or neither; a new issue, not this one
FU-3	isValidJSONObject pre-check not added when the payload became [String: Any]	DA downgraded: this payload cannot trigger the ObjC exception. Hardening against the loosened type, not a defect
FU-4	Three argv-scanner edge cases	Real — verified by execution, see below

FU-4 evidence. I extracted deliberateAutoModeRequested and ran the disputed inputs:

FAIL  ["--permission-mode", "--", "--permission-mode", "auto"]        → true  (want false)
FAIL  ["--permission-mode", "auto", "--permission-mode", "--verbose"] → false (want true)
FAIL  ["--model", "--permission-mode=auto"]                           → true  (want false)

One root cause: the scanner consumes the next token unconditionally. So -- in value
position is stepped over before the terminator check sees it, and a malformed repeat erases
a real auto — the second line is a false negative that swallows the notice this change
exists to produce.

The fix is next door and was not used: ProbeTarget.looksLikeValue exists for exactly this,
negative numbers included. The commit message claimed "the discipline is shared, the mechanism
is not" — the discipline was not, in fact, shared. My own tests missed all three because every
fixture came from the same mental model as the code, which is the failure this repo has
recorded three rounds running.

---

Withdrawn (mechanism does not hold — acting on these would break correct code)

Claim	Why it fails
A managed autoMode: true re-enables auto mode and goes unnamed (HIGH)	autoMode is not a switch. The settings reference: "Customize what the auto mode classifier blocks and allows. Contains environment, allow, soft_deny, and hard_deny arrays of prose rules." Scanning for it would manufacture false conflicts. Verified independently by the coordinator and by the DA
The code invented permissions.disableAutoMode	The reference states: "Also accepted under permissions as permissions.disableAutoMode"
Asserting disableAutoMode also changes plan mode	No documentation supports it
"the session starts in default instead" is an outcome the code cannot guarantee (three findings)	The documentation says exactly that. What is wrong is the attribution (BLOCK-1), not the strength of the claim

That the first-attempt run — DA errored — would have shipped a HIGH built on a misread of a
settings key is the argument for the adversarial pass, stated as evidence rather than as
policy.

Scope check

No scope creep. The file set matches the plan; CLAUDE_CONFIG_DIR stayed in #12 and
--settings detection stayed in #10. The sister-bug deferral (#13) and the outside-diff note
on #12 both check out against the diff.

Prompt-injection scan

Clean. Five independent passes agree: the diff and the context block are technical prose and
Swift/Markdown, with nothing attempting to redirect a reviewer's task.

Next

/idd-implement #11 for BLOCK-1 + IS-1..4, then re-verify. Do the live-session observation
first — it decides how the prose is rewritten.