feat: external model routing (devflow proxy) + per-agent model config (devflow agents)

[dean0x]

Summary

Adds integrated support for routing GPT model IDs through your OpenAI/Codex subscription:

• devflow proxy: Interactive CLI (--enable/--disable/--status) that routes configured GPT model IDs (gpt-5.6-sol/terra/luna, gpt-5.5) through a local relay to ANTHROPIC_BASE_URL; all other models pass through to Anthropic
• devflow agents: Interactive TUI + CLI (--list/--set/--reset) for per-agent model/effort overrides, stored deviations-only in ~/.devflow/agent-models.json and converged into installed agent frontmatter

Key Design Points

• Preflight hard-gate on enable: Validates Codex CLI auth, port identity, and foreign-gateway refusal
• Crash-safe enable ordering: Relay startup and system integration are ordered for resilience
• Disable semantics: Reverts GPT-mapped agents but remembers the mapping; re-enable restores previous state
• Relay lifecycle: Running relay is never killed by disable/uninstall (loopback-only, dies at reboot)
• Auto-revival: ensure-proxy hook (SessionStart synchronous + UserPromptSubmit probe) revives the relay with ≤8s bounded window
• Dormancy semantics: GPT model mappings materialize only while routing is enabled; effort overrides always apply
• Advanced-only init: Feature available only in Advanced mode during init; default OFF
• State-aware re-init: Preserves prior proxy state and agent model mappings across re-initialization
• Effect timing: Changes take effect in new Claude Code sessions (not mid-session)

Implementation

New modules and integration:

• src/core/{external-models,proxy-state,agent-frontmatter,agent-models}.ts: Pure, agent-neutral external model routing and agent configuration logic (ADR-013)
• src/cli/commands/{proxy,agents}.ts: CLI command entrypoints
• src/cli/agents-view/: Pure reducer + renderer + thin terminal shell for TUI
• src/targets/claude-code/hooks/ensure-proxy: Bash 3.2-safe, bounded, exit-0 hook for relay auto-revival (SessionStart + UserPromptSubmit)
• Init and uninstall wiring: Feature toggles in interactive flow; state cleanup on uninstall
• Documentation: README sections, cli-reference, agent-design updates, CLAUDE.md additions

Quality Gates

Fully implemented and tested through 4-phase sequential pipeline:

1. Validator: Build clean, zero warnings
2. Simplifier: Code clarity review
3. Scrutinizer: 9-pillar quality gate (fixed init reapply-ordering dormancy bug + TUI stdin hang)
4. Evaluator: Alignment and docs (2 doc-fix rounds completed)
5. QA Tester: 32 black-box scenarios; caught and fixed a --disable env-strip short-circuit bug with regression tests
6. Full suite: 2,253 tests passing

Note: Local Snyk scan unavailable (broken npx wrapper on this machine); relying on the PR's Snyk CI check for security verification.

Test Plan

• Unit coverage: External model routing, proxy state management, agent model resolution
• Shell hook coverage: ensure-proxy hook behavior and relay auto-revival
• Integration coverage: Enable/disable state transitions, agent frontmatter convergence, init/uninstall wiring
• Black-box E2E scenarios: 32 scenarios exercising enable, disable, re-enable, session restart, relay crash recovery, port conflicts, auth failures, env cleanup
• Manual E2E (maintainer): Live Codex auth with real session routing, mid-session crash revival, and session restart behavior (deferred—requires live credentials)

Related Issues

Closes: external model routing feature request

[dean0x]

Findings Summary

This PR adds comprehensive external model routing support. The code quality is generally strong with well-defended security boundaries and pure/testable architecture. The review found several issues worth addressing before merge:

HIGH-Confidence Blocking Issues (≥80%)

1. Remembered-port logic is dead (proxy.ts:492, TypeScript Review, 85% confidence)

The --port option declares a default value, which defeats the remembered-port feature:

.option('--port <n>', 'Port for the local relay (default: 4141)', String(DEFAULT_PROXY_PORT))

Because Commander fills options.port = '4141' when the flag is absent, the logic at lines 682-687 that checks if (portOption !== undefined) will always execute. The prior port from proxy.json is computed at line 673 but immediately discarded.

Expected behavior: devflow proxy --enable --port 5000, disable, then re-enable without --port should re-enable on port 5000.
Actual behavior: Enables on 4141 instead, spawning a second relay.

Fix: Drop the default so omission is detectable:

.option('--port <n>', 'Port for the local relay (default: remembered or 4141)')
// portOption stays undefined → priorPort is used

---

2. Preflight production implementations duplicated (Architecture Review, 90%; Complexity Review, 88%)

The three production preflight dependencies (realTcpConnectable, realHttpGet, realSpawnDoctor) are implemented identically in two places:

• src/cli/commands/proxy.ts lines 402–476 (module-private functions)
• src/cli/commands/init.ts lines 1258–1301 (inline inside preflight block)

The comment at init.ts:1257 acknowledges this: "see proxy.ts for identical patterns". This creates:

• DRY violation: A timeout or error-handling fix applied in one will silently drift from the other
• Bloated init.ts: Already a large orchestrator file, now with duplicated I/O code
• Import duplication: init.ts pulls in net/http/https/spawn purely to reconstruct behavior already in proxy.ts

Fix: Export a factory from proxy.ts:

export function buildRealPreflightDeps(
  settingsPath: string,
  onWarn?: (msg: string) => void,
): ProxyPreflightDeps {
  return {
    resolveProxyBin,
    fileExists: async (p) => { try { await fs.access(p); return true; } catch { return false; } },
    tcpConnectable: realTcpConnectable,
    httpGet: realHttpGet,
    readSettingsJson: () => fs.readFile(settingsPath, 'utf-8').catch(() => '{}'),
    spawnDoctor: realSpawnDoctor,
    onWarn,
  };
}

Then both runEnable (proxy.ts) and init's preflight block call it.

---

3. Inconsistent CLI error exit codes (Consistency Review, 85%)

The devflow proxy command exits 0 on errors (lines 683–686 and others), while the sibling devflow agents command (same PR) always sets process.exitCode = 1 on failures:

// proxy.ts - exits 0 even on preflight failure
if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
  p.log.error(`Invalid port: ${portOption}`);
  return;  // ← no exit code
}

This breaks failure detection in CI or scripts. Impact: devflow proxy --enable in a CI pipeline that fails preflight still exits 0.

Fix: Set process.exitCode = 1 before return on all hard-failure paths, matching agents.ts.

---

4. ensure-proxy hook sources json-parse without diagnostic (Consistency Review, 82%)

Line 28 of ensure-proxy:

source "$SCRIPT_DIR/json-parse" || { exit 0; }

All 11 sibling hooks (including preamble, the closest UserPromptSubmit sibling) use:

source "$SCRIPT_DIR/json-parse" || { echo "<hook>: failed to source json-parse" >&2; exit 1; }

The ensure-proxy form is silent, making a broken hook invisible during debugging. The exit 0 fail-open is defensible given proxy's optional nature, but the missing diagnostic message is a pure inconsistency.

Fix: Emit the diagnostic:

source "$SCRIPT_DIR/json-parse" || { echo "ensure-proxy: failed to source json-parse" >&2; exit 0; }

---

5. ensure-proxy uses curl despite claiming portability (Consistency Review, 80%)

Line 110–111 (TCP probe) avoids curl:

# TCP probe (bash built-in, no nc/curl, Bash 3.2-safe)
exec 3<>/dev/tcp/127.0.0.1/$_p 2>/dev/null

But line 131 unconditionally uses curl:

HEALTH_BODY=$(curl -s --max-time 2 "http://127.0.0.1:${PROXY_PORT}/__subswitch/health")

This creates:

• Portability deviation: Within one file the author avoids curl for portability, then depends on it
• Unguarded dependency: No command -v curl check; on a system without curl, substitution yields empty body, triggering a false "port squatted" warning even when the relay is ours

Fix: Either drop the health-check identity check on the hook side (the CLI --status already does a real check) or use /dev/tcp for the GET, matching the file's stated philosophy. At minimum:

if command -v curl >/dev/null 2>&1; then
  HEALTH_BODY=$(curl -s --max-time 2 "http://127.0.0.1:${PROXY_PORT}/__subswitch/health")
  # ... health check
else
  # Assume ours if curl unavailable
  :
fi

---

Additional Findings

Medium-Confidence Items (60–79% confidence) are summarized in the full review reports and available for reference. High-level:

• Long functions (runEnable 182 lines, runStatus 142 lines) are extraction opportunities
• Scattered magic timeouts (2000, 10_000, 50×100ms) merit named constants
• Dormancy predicate (isGpt && !proxyEnabled) re-expressed at 4 sites
• Spawn error listeners missing (affects crash-safety under fd exhaustion)
• Test coverage gaps in terminal.ts, proxy-state.ts, and runEnable relay-spawn paths

All review reports are available in .devflow/docs/reviews/feat-external-model-routing/2026-07-24_2302/.

---

Next Steps: Address the 5 blocking items above, then re-run the review to verify fixes. The codebase quality is strong; these are refinements to robustness and consistency.

CC devflow-kit maintainer | Review cycle 1

[dean0x]

Line 492: Remembered-port logic is dead (TypeScript Review, 85%)

The default value defeats the remembered-port feature. When --port is omitted, Commander fills options.port = '4141', making the check at line 680 (if (portOption !== undefined)) always true. The prior port from proxy.json (computed at line 673) is discarded.

Expected: Re-enable on the remembered port
Actual: Re-enables on 4141, spawning a second relay

Fix: Drop the default:

.option('--port <n>', 'Port for the local relay (default: remembered or 4141)')