Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice

HagiCode integrated Reasonix 1.x with DeepSeek V4, revealing a semantic migration challenge where startup parameters were reduced to a single `-model` flag, with credentials and policies moved to `reasonix.toml`. The adaptation layer uses a 'field preservation, semantic migration' pattern, preserving legacy fields but ignoring them at runtime.

This article discusses how to switch Reasonix 1.x, a local ACP CLI provider, to DeepSeek V4 in HagiCode. The focus isn't really on "getting it in," but rather on the semantic changes from Reasonix 0.x to 1.x—startup parameters were cut down to just one -model , credentials and policies moved to reasonix.toml . Let's walk through the pitfalls encountered and the verification path, bit by bit. Recently someone asked a pretty specific question: how to integrate Reasonix 1.x version to use DeepSeek V4 in HagiCode. At first glance it looked like a configuration question, but digging into the code revealed it's actually a CLI semantic migration problem. Reasonix is a local ACP Agent Communication Protocol CLI within HagiCode's multi-Agent Provider system. Its position in HagiCode's three-tier architecture is clear: ReasonixProvider , ReasonixOptions , wrapping reasonix acp process startup, ACP handshake, streaming notification mapping. ReasonixCliProvider thin adapter, AIProviderType.ReasonixCli = 12 , ReasonixGrain , Hero parameter mapping, health monitoring.The entire integration chain is already implemented in the archived proposal openspec/changes/archive/2026-06-06-integrate-reasonix-agent-provider . So the question isn't "how to get Reasonix into the system" anymore, but "once it's in, how to switch the model to DeepSeek V4". The key turning point is: Reasonix 1.x and 0.x have fundamentally different ACP bootstrap semantics. This change directly determines how you configure DeepSeek V4. After all, once semantics change, even if the surface looks similar, it's a different beast entirely. I'll leave that hanging: to untangle this complexity of multiple providers and multiple models, HagiCode adopted a "field preservation, semantic migration" design at the Reasonix adaptation layer. I'll explain exactly why this trade-off was chosen later. The solution shared in this article comes from our practical experience in the HagiCode project.HagiCode is an AI coding assistant project supporting multiple local/remote Agent Providers. Code is open sourced at HagiCode-org/site . Look directly at ReasonixProvider.BuildCommandArguments : internal virtual IReadOnlyList<string BuildCommandArguments ReasonixOptions options { var arguments = new List<string { "acp" }; // Reasonix 1.x reduced ACP bootstrap to a transport-scoped provider selector. AppendOption arguments, "-model", options.Model ; foreach var argument in NormalizeExtraArguments options.ExtraArguments arguments.Add argument ; return arguments; } That comment is the key: 1.x condensed ACP bootstrap to a "transport-scoped provider selector." In plain English—the only flag still meaningful at startup is -model . Those legacy flags from the 0.x era are explicitly filtered out: private static readonly HashSet<string FilteredBootstrapFlags = new StringComparer.OrdinalIgnoreCase { "-model", "-m", "--model", "-dir", "--dir", "-effort", "--effort", "-budget", "--budget", "-transcript", "--transcript", "-mcp", "--mcp", "-mcp-prefix", "--mcp-prefix", "-yolo", "--yolo", "--dangerously-skip-permissions", "--no-proxy" }; Unit tests directly prove this. Pass in a bunch of legacy flags, the command line comes out clean, no errors, just silently dropped: arguments.ShouldBe "acp", "-model", "deepseek-v4-flash" ; Here's an interesting design choice. Fields like Effort , BudgetUsd , TranscriptPath , EnableYolo , McpServerSpecs , McpPrefix in ReasonixOptions are all preserved, but each comment honestly states "Reasonix 1.x ACP no longer accepts ... so this value is currently ignored". This is a classic field preservation, semantic migration pattern: caller contracts aren't broken 0.x code still compiles, still passes values , but at runtime these values are silently dropped. Policy-type things permissions, MCP plugins, proxy are required to move to reasonix.toml . To put it another way, it's like your original light switch is still on the wall, but the renovation guy changed the wiring. Now the switch is just decoration, the real lighting control moved to the smart home panel. The switch looks unchanged, pressing it doesn't error out, but the light just doesn't turn on. So the core action for integrating DeepSeek V4 is actually just one sentence: pass the model id through the -model selector, configure credentials/endpoint in reasonix.toml . In HagiCode's tests and README, the DeepSeek series uses the standard pattern through the Model field: js var reasonixOptions = new ReasonixOptions { WorkingDirectory = "/path/to/repo", Model = "deepseek-flash", SessionId = "reasonix-session-123" }; Tests repeatedly show Model = "deepseek-v4-flash" , corresponding to the generated command line reasonix acp -model deepseek-v4-flash . The specific model id deepseek-v4-flash , deepseek-flash , etc. should follow the Reasonix 1.x version you installed and the provider aliases registered in reasonix.toml —after all, whether an alias is real or not, Reasonix knows best. This is the second semantic change in 1.x, easy to get confused about. In 0.x you used --dir to specify working directory, in 1.x it changed to using session/new / session/load within the ACP protocol: js var sessionHandle = await sessionClient.StartSessionAsync workingDirectory, options.SessionId, model: null, // Model selection completely determined by startup -model startupCts.Token ; Note that the model parameter in StartSessionAsync passes null —model selection is completely determined by -model at startup, session level no longer overrides the model. SessionId is still a provider-native continuity hint, used only to resume sessions. Putting the above analysis together into an executable path, let's walk through four steps. Reasonix is a locally installed, IsPubliclyInstallable: false provider, can't be installed via npm publicly. First put the reasonix executable in PATH. After installing, verify with HagiCode.Libs' built-in console: Run Ping scenario, execute reasonix acp handshake and report version dotnet run --project src/HagiCode.Libs.Reasonix.Console -- --test-provider reasonix If handshake fails, it's usually one of two cases: either PATH didn't find reasonix , or reasonix.toml isn't configured. There aren't really any other reasons. 1.x no longer accepts startup flags like --api-key , --base-url . Model provider endpoint, API key, proxy policies all need to be written to reasonix.toml . Configuration roughly includes: -model selector like deepseek-v4-flash Specific field names should follow the documentation of your installed Reasonix version. HagiCode's side only cares about passing through -model deepseek-v4-flash , how this alias resolves to the actual model is Reasonix's business—responsibility boundaries are clearly drawn, don't cross lines. The resolution priority in backend ReasonixCliProvider.ResolveModel is: request.Model takes priority, otherwise fall back to config.Model : js private string? ResolveModel AIRequest request { var model = string.IsNullOrWhiteSpace request.Model ? config.Model : request.Model; return string.IsNullOrWhiteSpace model ? null : model.Trim ; } So in appsettings or runtime config, set the provider's Model to DeepSeek V4's alias: { "AIProvider": { "Providers": { "ReasonixCli": { "Type": "ReasonixCli", "Model": "deepseek-v4-flash", "Settings": {} } } } } Here's a trap that's easy to step in: Settings can only hold keys within the whitelist: private static readonly IReadOnlyList<string SupportedSettingKeys = "effort", "budgetUsd", "transcriptPath", "enableYolo", "arguments", "startupTimeoutMs", "reasoning" ; ValidateConfigurationOverrides will directly reject keys outside the whitelist. And most of these keys are ignored in 1.x corresponding to those ignored fields in ReasonixOptions , so never stuff DeepSeek credentials into Settings , that's not where they belong, credentials go to reasonix.toml . After configuration, run the full suite with Reasonix's dedicated console, explicitly specifying the model as DeepSeek V4: Default suite: four scenarios - Ping / Simple Prompt / Complex Prompt / Session Resume dotnet run --project src/HagiCode.Libs.Reasonix.Console -- \ --test-provider-full --model deepseek-v4-flash --repo . If all four scenarios pass green, the model selector, ACP handshake, streaming notifications, session recovery—the entire chain is connected. Green means peace of mind. If you go through HagiCode's Hero career UI instead of directly modifying appsettings, after selecting Reasonix in HeroCliEquipmentForm , the form fields are: reasonix deepseek-v4-flash key field for switching to DeepSeek V4 Actually, only the model field affects DeepSeek V4 behavior, the rest are just decoration under 1.x. This is also HagiCode's "field preservation, semantic migration" design reflected in the UI—the form doesn't break old user habits, but the fields that actually take effect are converged. ReasonixCliProvider uses ConcurrentDictionary<string, string to maintain session bindings, binding key is calculated from sessionId, working directory, executable path, and model: js var bindingKey = NormalizedAcpCliAdapter.BuildBindingKey effectiveRequest.CessionId, options.WorkingDirectory, options.ExecutablePath, options.Model ; This means if you switch models mid-session in the same session, the binding key changes and it's treated as a new session. So after integrating DeepSeek V4, keep the model alias stable throughout the session lifecycle , otherwise resume will break. I learned this the hard way through actual testing—blood and tears lesson, still remember the taste. Reasonix uses the Provider strategy not Grain strategy in AgentCliMonitoringRegistry , since it might not be installed: new AgentCliMonitoringDescriptor { CliId = "reasonix", DisplayName = "Reasonix", ProviderType = AIProviderType.ReasonixCli, Strategy = Provider, // ping-based, via PATH discovery ExecutableCandidates = "reasonix" } Frontend health checks show whether Reasonix is available. If reasonix isn't in PATH, the UI gracefully degrades to "unavailable"—this logic is built in, no need to worry about it yourself. deepseek-v4-flash must be a real alias registered in reasonix.toml , otherwise ACP handshake passes but sending prompts still fails. Verify with console first before going to Hero, don't cut corners. arguments to Pass Legacy Flags NormalizeExtraArguments filters out --effort , --budget , etc., passing them is futile, wasted effort. reasonix.toml , HagiCode's side Settings whitelist doesn't have these fields at all. startupTimeoutMs from default 15000, this field is recognized in 1.x. resolveEconomicSystemByExecutorType maps Reasonix to the 'claude' bucket, purely for display, doesn't affect billing.If you just want to confirm DeepSeek V4 works quickly without touching Hero UI: reasonix.toml DeepSeek endpoint + key + alias ReasonixCli.Model = "deepseek-v4-flash" in appsettings dotnet run --project src/HagiCode.Libs.Reasonix.Console -- --test-provider-full --model deepseek-v4-flash Returning to the original question—"how to integrate Reasonix 1.x to use DeepSeek v4". The answer is actually just one sentence: pass the model alias through the -model selector, configure credentials and policies in reasonix.toml, don't count on CLI flags . Behind that one sentence is a pretty clean semantic convergence by Reasonix 1.x: startup parameters cut to just -model , working directory and session recovery moved into ACP protocol, policies all sunk into toml. HagiCode's adaptation layer didn't fight this change head-on, but chose the gentle "field preservation, semantic migration" route—old code still compiles, still passes values, silently ignored at runtime, converging effective switches to just -model . The benefit of this trade-off is smooth migration, the cost is documentation needs to be clear—which is why this article exists. Just remember three things: -model -model deepseek-v4-flash HagiCode chose to design the Reasonix adaptation layer this way essentially because it needs to accommodate multiple providers, multiple model versions, multiple deployment forms. This complexity of multiple languages, multiple platforms is exactly why we repeatedly polish the provider adaptation strategy in HagiCode. repos/Hagicode.Libs/src/HagiCode.Libs.Providers/Reasonix/ReasonixProvider.cs repos/Hagicode.Libs/src/HagiCode.Libs.Providers/Reasonix/ReasonixOptions.cs repos/hagicode-core/src/PCode.ClaudeHelper/AI/Providers/ReasonixCliProvider.cs openspec/changes/archive/2026-06-06-integrate-reasonix-agent-provider openspec/specs/reasonix-backend-integration/spec.md repos/Hagicode.Libs/tests/HagiCode.Libs.Providers.Tests/ReasonixProviderTests.cs Around "Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice," a more solid approach is to first gradually get key configurations, dependency boundaries, and implementation paths working, then fill in optimization details. When goals, steps, and acceptance criteria are clear, this type of solution usually flows more smoothly into actual delivery. Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it. This article was created with AI assistance and reviewed by the author before publication.