Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: keep the local Claude agent from stopping on a small context window (#13477)

Nilay9cf63a2fd155
diff --git a/unsloth_cli/claude_subagent_mcp.py b/unsloth_cli/claude_subagent_mcp.py
index b618fc93f00..ff3a3577b9e 100644
--- a/unsloth_cli/claude_subagent_mcp.py
+++ b/unsloth_cli/claude_subagent_mcp.py
@@ -63,10 +63,9 @@ def _bounded(text: str) -> str:
return text[:_MAX_RESULT_CHARACTERS] + "\n\n[Local agent output truncated]"
-def _result_text(stdout: str) -> str:
+def _result_payload(stdout: str) -> dict:
lines = [line for line in stdout.splitlines() if line.strip()]
- candidates = [stdout.strip(), *reversed(lines)]
- for candidate in candidates:
+ for candidate in [stdout.strip(), *reversed(lines)]:
try:
payload = json.loads(candidate)
except ValueError:
@@ -74,10 +73,18 @@ def _result_text(stdout: str) -> str:
if not isinstance(payload, dict):
continue
result = payload.get("result")
- if payload.get("is_error"):
- raise RuntimeError(str(result or "The local Claude agent failed."))
- if isinstance(result, str) and result.strip():
- return _bounded(result.strip())
+ if payload.get("is_error") or (isinstance(result, str) and result.strip()):
+ return payload
+ return {}
+
+
+def _result_text(stdout: str) -> str:
+ payload = _result_payload(stdout)
+ result = payload.get("result")
+ if payload.get("is_error"):
+ raise RuntimeError(str(result or "The local Claude agent failed."))
+ if isinstance(result, str) and result.strip():
+ return _bounded(result.strip())
raise RuntimeError("The local Claude agent returned no readable result.")
@@ -172,14 +179,11 @@ def run_local_agent(
"--output-format",
"json",
"--no-session-persistence",
- # Strip human-blocking tools so the child runs unattended; plan/prompt tools are listed
- # pre-emptively, and Bash is denied read-only side because plan mode is not a write barrier.
- "--disallowedTools",
- (
- "AskUserQuestion,EnterPlanMode,Edit,Write,NotebookEdit,Bash"
- if read_only
- else "AskUserQuestion,EnterPlanMode,ExitPlanMode"
- ),
+ # The full tool set (~16k tokens) fills a small window; plan mode is no write barrier, so read-only gets no writer.
+ "--tools",
+ "Read,Grep,Glob,ExitPlanMode"
+ if read_only
+ else "Bash,Read,Edit,Write,Grep,Glob,NotebookEdit",
"--append-system-prompt",
_SUBAGENT_PLAN_INSTRUCTIONS if read_only else _SUBAGENT_INSTRUCTIONS,
f"Task: {task}",
@@ -238,7 +242,9 @@ def run_local_agent(
_stop_child(process)
raise
if process.returncode != 0:
- detail = stderr.strip() or stdout.strip()
+ # stderr can hold only claude's own warnings; the result says why the run stopped.
+ reason = _result_payload(stdout).get("result")
+ detail = str(reason or "").strip() or stderr.strip() or stdout.strip()
raise RuntimeError(
_bounded(detail) or f"Local Claude exited with code {process.returncode}."
)
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index 04a2f2a10ae..6413841c08e 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -132,6 +132,7 @@ _PI_USER_RESOURCES_MANIFEST = ".unsloth-user-resources.json"
_OPENCODE_PROVIDER = "unsloth-studio"
# OpenCode sends min(limit.output, this) as max_tokens unless the env var below raises it.
_OPENCODE_OUTPUT_TOKEN_MAX = 32_000
+_CLAUDE_COMPACT_OUTPUT_RESERVE = 20_000
_OPENCODE_OUTPUT_TOKEN_MAX_ENV = "OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX"
_VIBE_PROVIDER = "unsloth-studio"
_VIBE_MODEL_ALIAS = "unsloth"
@@ -3064,6 +3065,10 @@ def _claude_local_env(
env["CLAUDE_CODE_MAX_CONTEXT_TOKENS"] = str(int(window))
env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] = str(int(window))
env["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"] = "90"
+ # claude reserves min(max output, 20k) + 13k before compacting, so its 32k default output leaves a 32k window nothing; above 20k the cap gains no room.
+ output = opencode_output_limit(int(window))
+ if output < _CLAUDE_COMPACT_OUTPUT_RESERVE:
+ env["CLAUDE_CODE_MAX_OUTPUT_TOKENS"] = str(output)
if extra_body:
env["CLAUDE_CODE_EXTRA_BODY"] = json.dumps(extra_body)
return env
diff --git a/unsloth_cli/tests/test_claude_subagent_mcp.py b/unsloth_cli/tests/test_claude_subagent_mcp.py
index 3bbb204dc36..c81fd65bd0b 100644
--- a/unsloth_cli/tests/test_claude_subagent_mcp.py
+++ b/unsloth_cli/tests/test_claude_subagent_mcp.py
@@ -246,8 +246,8 @@ def test_local_child_uses_unsloth_without_overwriting_parent_auth(
assert command[command.index("--settings") + 1] == str(settings_path)
assert command[command.index("--permission-mode") + 1] == permission
assert "--no-session-persistence" in command
- disallowed = command[command.index("--disallowedTools") + 1]
- assert disallowed == "AskUserQuestion,EnterPlanMode,ExitPlanMode"
+ assert command[command.index("--tools") + 1] == "Bash,Read,Edit,Write,Grep,Glob,NotebookEdit"
+ assert "--disallowedTools" not in command
assert captured["cwd"] == str(tmp_path)
assert captured["stdin"] is bridge.subprocess.DEVNULL
assert captured["stdout"] is bridge.subprocess.PIPE
@@ -263,6 +263,7 @@ def test_local_child_uses_unsloth_without_overwriting_parent_auth(
assert child_env["CLAUDE_CODE_MAX_CONTEXT_TOKENS"] == "32768"
assert child_env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] == "32768"
assert child_env["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"] == "90"
+ assert child_env["CLAUDE_CODE_MAX_OUTPUT_TOKENS"] == "8192"
assert "ANTHROPIC_API_KEY" not in child_env
assert "CLAUDE_CODE_OAUTH_TOKEN" not in child_env
@@ -346,10 +347,9 @@ def test_read_only_local_child_uses_plan_mode(monkeypatch, tmp_path):
assert bridge.run_local_agent("plan this", read_only = True) == "PLAN_OK"
command = captured["command"]
assert command[command.index("--permission-mode") + 1] == "plan"
- disallowed = command[command.index("--disallowedTools") + 1]
- assert disallowed == "AskUserQuestion,EnterPlanMode,Edit,Write,NotebookEdit,Bash"
- # Bash matters: plan mode routes it through a classifier served by this same local model, so
- # without the deny a "read-only" child can still write files.
+ assert command[command.index("--tools") + 1] == "Read,Grep,Glob,ExitPlanMode"
+ # No Bash: plan mode routes it through a classifier served by this same local model, so a
+ # "read-only" child with Bash can still write files.
prompt = command[command.index("--append-system-prompt") + 1]
assert "read-only local coding subagent" in prompt
@@ -475,6 +475,32 @@ def test_stop_child_kills_survivors_after_leader_exit(monkeypatch, tmp_path):
assert not marker.exists()
+def test_failed_child_reports_why_it_stopped_not_its_warnings(monkeypatch, tmp_path):
+ _stub_env(monkeypatch, tmp_path)
+ reason = "Autocompact is thrashing: the context refilled to the limit within 3 turns."
+
+ class Process:
+ pid = 1234
+ returncode = 1
+
+ def communicate(self, timeout):
+ payload = {
+ "is_error": True,
+ "terminal_reason": "rapid_refill_breaker",
+ "result": reason,
+ }
+ warning = '[claude-code:unrecognized_model] {"model":"unsloth/model-GGUF:Q4_K_M"}\n'
+ return json.dumps(payload), warning
+
+ def poll(self):
+ return self.returncode
+
+ monkeypatch.setattr(bridge.subprocess, "Popen", lambda *a, **k: Process())
+ with pytest.raises(RuntimeError) as failure:
+ bridge.run_local_agent("hello")
+ assert str(failure.value) == reason
+
+
def test_result_parser_accepts_diagnostics_before_json():
output = "connector warning\n" + json.dumps({"is_error": False, "result": "OK"})
assert bridge._result_text(output) == "OK"
diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.py
index 7fb4824b7d4..3c8566d5fa1 100644
--- a/unsloth_cli/tests/test_start.py
+++ b/unsloth_cli/tests/test_start.py
@@ -168,6 +168,19 @@ def test_claude_settings_overlay_pins_local_routing_and_auth():
assert overlay["env"]["CLAUDE_CODE_SUBAGENT_MODEL"] == "inherit"
+ ("window", "output"), [(32768, "8192"), (65536, "16384"), (98304, None), (131072, None)]
+)
+def test_claude_local_env_leaves_room_to_compact_a_small_window(window, output):
+ local_env = start._claude_local_env(
+ BASE, "sk-unsloth-test", {**MODEL, "context_length": window}
+ )
+ assert local_env.get("CLAUDE_CODE_MAX_OUTPUT_TOKENS") == output
+ assert "CLAUDE_CODE_MAX_OUTPUT_TOKENS" not in start._claude_local_env(
+ BASE, "sk-unsloth-test", {"id": MODEL["id"]}
+ )
+
+
def test_claude_settings_files_preserve_concurrent_sessions(tmp_path):
first_env = start._claude_local_env("http://127.0.0.1:8001", "first-key", MODEL)
second_env = start._claude_local_env("http://127.0.0.1:8002", "second-key", MODEL)