Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

DeepSeek: default effort thinks at the low level (ADR 0237)

justrach1d2cb892a353
diff --git a/docs/adr/0237-deepseek-thinks-at-its-low-level-by-default.md b/docs/adr/0237-deepseek-thinks-at-its-low-level-by-default.md
new file mode 100644
index 00000000..8f051fe7
--- /dev/null
+++ b/docs/adr/0237-deepseek-thinks-at-its-low-level-by-default.md
@@ -0,0 +1,44 @@
+# 0237. DeepSeek thinks at its low level by default
+
+Status: accepted 2026-10-02
+
+## Context
+
+ADR 0054 turned DeepSeek's thinking off when the wire effort is `low`, the
+flash models' default. Every other effort sent thinking enabled with the
+effort as chosen, so on DeepSeek V4 Pro graff's default (`medium`) thought at
+length. DeepSeek documents `low`, `high` and `max`.
+
+On tasks that read an MCP server, the first request of a turn reasoned for
+thousands of characters and planned the whole job before its first tool call.
+Another harness that sends DeepSeek's own default reasoned for a fraction of
+that on the same tasks.
+
+Sending `low` with thinking still enabled roughly halved graff's mean task
+time on the core and MCP suites, and every task still passed. Turning thinking
+off was faster again but lost a task there and missed a quarter of the
+sub-agent runs.
+
+On the sub-agent suites `low` was markedly faster too, most of all when
+children did the work. Across two rounds it missed two runs that the default
+passed: one child added up correct per-file counts wrongly, and one run
+misread a route's method. The default missed as many in an earlier round.
+
+## Decision
+
+On the DeepSeek family (native `deepseek`, or a `deepseek*` model on another
+provider), graff's default effort (`medium`) sends `reasoning_effort: low`
+with `thinking.type=enabled`. `/effort low` still sends thinking disabled
+(ADR 0054). `high` and above are sent as before, and the flash models' default
+stays thinking off. The picker, status line and ACP still call the default
+Medium.
+
+## Consequences
+
+A default DeepSeek turn reaches its first tool call sooner and spends less of
+each request thinking. Work that needs care with exact figures, such as adding
+up the counts a tool reported, gets less checking unless someone picks
+`/effort high`.
+
+Revisit if traces show default-effort DeepSeek runs failing where `high`
+would have passed, or if DeepSeek documents a `medium` level.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 41b01456..a9b948c3 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -263,6 +263,7 @@ record only when you need the evidence or the edge cases.
| [0234](0234-the-model-knows-the-os-and-the-codedb-guard-only-redirects-searches.md) | The `shell` tool names the OS its commands run on (macOS: BSD tools, `sed -i ''`). The codedb guard lets an in-place `sed -i` edit and a pipe-free whole-file read of files up to 16 KiB through; searches and bigger reads still go to codedb. |
| [0235](0235-mimo-thinks-only-at-high-effort.md) | MiMo thinks only at `high` and above: `minimal`/`low`/`medium` (graff's default) send thinking Off on the Chat and Responses wires; On, a worker pin, or Jev's `high` turn it on. Replaces ADR 0192's "positive values mean On" below high. |
| [0236](0236-rlm-takes-json-literals-and-each-maps-plain-values.md) | `rlm` takes JSON array/object literals as arguments and binds (`name = [...]`, bound names allowed inside); its splitters nest `[]`/`{}`; `each(arr, tool[, field])` passes plain items as is, picks `field` from objects (default: an MCP tool's first parameter) and names the fields it found; an unsupported statement lists the forms that work. |
+| [0237](0237-deepseek-thinks-at-its-low-level-by-default.md) | DeepSeek's default effort (`medium`) sends `reasoning_effort: low` with thinking enabled; `/effort low` still turns thinking off (ADR 0054), and `high` and above are unchanged. |
## When to write one
diff --git a/src/provider_codegraff_tests.zig b/src/provider_codegraff_tests.zig
index 3fbf05a0..72fcffcd 100644
--- a/src/provider_codegraff_tests.zig
+++ b/src/provider_codegraff_tests.zig
@@ -126,7 +126,8 @@ test "Codegraff Gemini sends low for default effort; /effort high still sends" {
try std.testing.expect(deepseek.sendReasoningEffort());
const ds = try deepseek.buildBody(null, false, true, true);
defer std.testing.allocator.free(ds);
- try std.testing.expect(std.mem.indexOf(u8, ds, "\"reasoning_effort\":\"medium\"") != null);
+ // ADR 0237: graff's default keeps thinking on at DeepSeek's low level.
+ try std.testing.expect(std.mem.indexOf(u8, ds, "\"reasoning_effort\":\"low\"") != null);
try std.testing.expect(std.mem.indexOf(u8, ds, "\"thinking\":{\"type\":\"enabled\"}") != null);
}
diff --git a/src/zai_wire.zig b/src/zai_wire.zig
index 2e453156..33384b56 100644
--- a/src/zai_wire.zig
+++ b/src/zai_wire.zig
@@ -41,6 +41,14 @@ pub fn isDeepseekFamily(provider_id: []const u8, model: []const u8) bool {
return std.mem.indexOf(u8, model, "deepseek") != null;
}
+/// ADR 0237: DeepSeek documents `low`, `high` and `max`. At graff's default
+/// (`medium`) the first request of an MCP task planned the whole job before
+/// its first call. The default keeps thinking on at `low`; `/effort low`
+/// still turns it off (writeChatExtras).
+pub fn deepseekEffort(requested: []const u8) []const u8 {
+ return if (std.mem.eql(u8, requested, "medium")) "low" else requested;
+}
+
/// OpenAI-chat extras after `prompt_cache_key`: Z.AI thinking, Vercel
/// `reasoning.effort`, DeepSeek thinking on/off, then `reasoning_effort`.
pub fn writeChatExtras(s: *std.json.Stringify, provider_id: []const u8, model: []const u8, send_effort: bool, requested: []const u8) !void {
@@ -75,7 +83,8 @@ pub fn writeChatExtras(s: *std.json.Stringify, provider_id: []const u8, model: [
}
if (!std.mem.eql(u8, provider_id, "kimi") and send_effort) {
try s.objectField("reasoning_effort");
- try s.write(if (is_zai) reasoningEffort(requested) else @import("meta_wire.zig").chatEffort(requested, provider_id, model));
+ const effort = @import("meta_wire.zig").chatEffort(requested, provider_id, model);
+ try s.write(if (is_zai) reasoningEffort(requested) else if (isDeepseekFamily(provider_id, model)) deepseekEffort(effort) else effort);
}
}
@@ -87,6 +96,48 @@ test "DeepSeek family is native id or a deepseek model name" {
try std.testing.expect(!isDeepseekFamily("zai", "glm-5.3"));
}
+test "ADR 0237: DeepSeek thinks at its low level by default; /effort low turns thinking off" {
+ const Agent = @import("agent.zig").Agent;
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ var messages = std.json.Array.init(arena);
+ var user: std.json.ObjectMap = .empty;
+ try user.put(arena, "role", .{ .string = "user" });
+ try user.put(arena, "content", .{ .string = "hello" });
+ try messages.append(.{ .object = user });
+ var agent: Agent = .{
+ .gpa = std.testing.allocator,
+ .arena = arena,
+ .io = std.testing.io,
+ .client = undefined,
+ .provider = .{ .id = "deepseek", .kind = .openai, .auth = .bearer, .url = "https://api.deepseek.com/chat/completions", .api_key = "k", .model = "deepseek-v4-pro", .context = 1_000_000 },
+ .messages = messages,
+ .sub = false,
+ .label = "",
+ .out = null,
+ .sys_normal = "system",
+ .reasoning = .medium,
+ };
+ const cases = [_]struct { effort: @TypeOf(agent.reasoning), thinking: []const u8, wire: []const u8 }{
+ .{ .effort = .medium, .thinking = "enabled", .wire = "low" }, // graff's default
+ .{ .effort = .low, .thinking = "disabled", .wire = "low" },
+ .{ .effort = .high, .thinking = "enabled", .wire = "high" },
+ .{ .effort = .ultra, .thinking = "enabled", .wire = "max" },
+ };
+ for (cases) |c| {
+ agent.reasoning = c.effort;
+ const body = try agent.buildBody(null, false, true, true);
+ defer std.testing.allocator.free(body);
+ const thinking = try std.fmt.allocPrint(arena, "\"thinking\":{{\"type\":\"{s}\"}}", .{c.thinking});
+ const wire = try std.fmt.allocPrint(arena, "\"reasoning_effort\":\"{s}\"", .{c.wire});
+ try std.testing.expect(std.mem.indexOf(u8, body, thinking) != null);
+ try std.testing.expect(std.mem.indexOf(u8, body, wire) != null);
+ }
+ try std.testing.expectEqualStrings("low", deepseekEffort("medium"));
+ try std.testing.expectEqualStrings("high", deepseekEffort("high"));
+}
+
test "Z.AI maps graff efforts onto low|high|max" {
try std.testing.expectEqualStrings("low", reasoningEffort("low"));
try std.testing.expectEqualStrings("high", reasoningEffort("medium"));