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 toreasonix.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:
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:
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:
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
:
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:
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:
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 FlagsNormalizeExtraArguments
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.