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

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.

Background

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:

• HagiCode.Libs — ReasonixProvider, ReasonixOptions, wrapping reasonix acp process startup, ACP handshake, streaming notification mapping.
• hagicode-core — ReasonixCliProvider thin adapter, AIProviderType.ReasonixCli = 12, ReasonixGrain, Hero parameter mapping, health monitoring.
• web — OpenAPI types, visual mapping, Hero configuration forms, multilingual copy.

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.

About HagiCode

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.

Analysis

1.x Cut Startup Parameters to Just One

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"
]);

ReasonixOptions Fields Still There, But Semantics Changed

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.

How DeepSeek V4 Gets In

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.

Working Directory and Session Recovery Go Through ACP, Not CLI Flags

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.

Solution

Putting the above analysis together into an executable path, let's walk through four steps.

Step 1: Install Reasonix CLI

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.

Step 2: Configure DeepSeek V4 Credentials in reasonix.toml

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:

• DeepSeek V4 API endpoint
• DeepSeek API key
• Aliases you want to expose to the -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.

Step 3: Configure HagiCode's ProviderConfiguration

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.

Step 4: Use Console for End-to-End Verification

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.

Practice

How to Fill the Hero Configuration Form in Frontend

If you go through HagiCode's Hero career UI instead of directly modifying appsettings, after selecting Reasonix in HeroCliEquipmentForm, the form fields are:

• binary: default reasonix
• model: fill deepseek-v4-flash (key field for switching to DeepSeek V4)
• effort: none / low / medium / high (ignored in 1.x, but UI still keeps it)
• budgetUsd: number (ignored in 1.x)
• transcriptPath: text (ignored in 1.x)
• enableYolo: boolean (ignored in 1.x, permissions go to toml)
• arguments: extra parameters passed through to ACP
• startupTimeoutMs: default 15000

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.

Session Binding and Recovery

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.

Monitoring and Degradation

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.

Several Practical Points to Note

1. Authenticity of Model Aliases: 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.
2. Don't Use arguments to Pass Legacy Flags: NormalizeExtraArguments filters out --effort, --budget, etc., passing them is futile, wasted effort.
3. Credentials Only in toml: API key, endpoint, proxy, MCP plugins all go in reasonix.toml, HagiCode's side Settings whitelist doesn't have these fields at all.
4. startupTimeoutMs is Adjustable: If DeepSeek V4 cold start is slow, raise startupTimeoutMs from default 15000, this field is recognized in 1.x.
5. Economic System Maps to Claude Bucket: Frontend resolveEconomicSystemByExecutorType maps Reasonix to the 'claude' bucket, purely for display, doesn't affect billing.

A Minimal Verification Path

If you just want to confirm DeepSeek V4 works quickly without touching Hero UI:

1. Install reasonix, configure reasonix.toml (DeepSeek endpoint + key + alias)
2. Set ReasonixCli.Model = "deepseek-v4-flash" in appsettings
3. Run dotnet run --project src/HagiCode.Libs.Reasonix.Console -- --test-provider-full --model deepseek-v4-flash
4. All four scenarios green, integration complete

Summary

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:

1. Models go through -model, DeepSeek V4 is -model deepseek-v4-flash
2. Credentials go to toml, don't stuff them into Settings
3. Don't switch models mid-session, binding key changes, resume breaks

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.

References

• Reasonix Provider implementation: repos/Hagicode.Libs/src/HagiCode.Libs.Providers/Reasonix/ReasonixProvider.cs
• Reasonix Options field semantics: repos/Hagicode.Libs/src/HagiCode.Libs.Providers/Reasonix/ReasonixOptions.cs
• Backend thin adapter: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Providers/ReasonixCliProvider.cs
• Integration proposal archive: openspec/changes/archive/2026-06-06-integrate-reasonix-agent-provider
• Backend spec: openspec/specs/reasonix-backend-integration/spec.md
• Unit tests (including deepseek-v4-flash cases): repos/Hagicode.Libs/tests/HagiCode.Libs.Providers.Tests/ReasonixProviderTests.cs
• HagiCode official site: hagicode.com

Summary

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.

Original Article & License

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.

• Author: newbe36524
• Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-19-reasonix-1x-deepseek-v4-acp-integration%2F
• License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.