Skip to content

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

Python

fix: hand off screenshot requests without completing work

yxlyxcc99baf0c36e
diff --git a/docs/adr/0015-ask-user-images-are-a-follow-up-user-message.md b/docs/adr/0015-ask-user-images-are-a-follow-up-user-message.md
index 0a628d22..f21b396d 100644
--- a/docs/adr/0015-ask-user-images-are-a-follow-up-user-message.md
+++ b/docs/adr/0015-ask-user-images-are-a-follow-up-user-message.md
@@ -26,6 +26,22 @@ Responses 16k output cap (#95's sibling) and the per-output handle contract.
result names path / paste-text / next-prompt fallbacks instead of
implying the pixels arrived.
+## Question-interface capability
+
+The image transport above is not a promise that every question dialog can
+accept an attachment. `ask_user` defaults to text and option selections;
+request images there only when the active interface explicitly supports
+attachments in question replies. Unknown support is not support. When an
+image is essential on a text-only or unknown interface, explain the handoff
+with `yield_turn` so the user can attach it to the next prompt. This explicit
+root-only boundary runs alone, requires no confirmation, and stops completion
+nudges and autonomous continuation without passing a verifier or completing
+a goal. Keep the conversation and unfinished work available; do not claim
+completion. Idle job, worker, schedule and peer notices remain queued rather
+than reopening the handoff on REPL or ACP. The next human prompt clears the
+idle handoff latch and starts a fresh turn; goals and verification stay intact.
+Existing image-capable reply paths keep the transport described above.
+
## Consequences
The next model request sees the text result and the pixels. Compaction
diff --git a/docs/adr/README.md b/docs/adr/README.md
index ac864fdf..ae92a3b7 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -25,7 +25,7 @@ record only when you need the evidence or the edge cases.
| [0012](0012-overflow-handles-named-limits-extra-roots.md) | Fat tool results become `tr_N` handles; named `--context-limit` caps prefix bytes; `--add-dir` extra roots are PathConfine allow-lists, not cwd/skill/session sources. |
| [0013](0013-list-dir-lives-in-codedb.md) | Directory listing is `codedb list_dir` (in-process BFS, gitignore, 10k cap), not a new always-on catalog tool. |
| [0014](0014-session-resume-carries-the-room-cursor.md) | `/resume` restores the peer-channel byte cursor and inbox; it does not replay the room into history. |
-| [0015](0015-ask-user-images-are-a-follow-up-user-message.md) | `ask_user` images ride a follow-up user message after the text tool result; Responses/OpenAI tool output stays text-only. |
+| [0015](0015-ask-user-images-are-a-follow-up-user-message.md) | Reply images require explicit UI support and ride a follow-up user message; otherwise `yield_turn` stops for the next prompt without completing work. |
| [0016](0016-line-repl-is-a-working-block.md) | Line REPL chrome is a `WORKING` block plus a bare `›`; tool fan-out is a tree, never `✓ bash`. |
| [0017](0017-model-election-ranks-signed-in-plans-first.md) | `/model` and `/models` on both frontends rank signed-in plan seats above credits and metered keys (`src/models_rank.zig`). |
| [0018](0018-standing-chrome-shows-last-turn-cache-hit.md) | Last-turn cache hit % rides with `ctx` on the line-REPL meter and the TUI footer; `/cache` stays the posture HUD. |
diff --git a/evals/harness_behavior.jsonl b/evals/harness_behavior.jsonl
index 3272e75f..73188640 100644
--- a/evals/harness_behavior.jsonl
+++ b/evals/harness_behavior.jsonl
@@ -133,3 +133,4 @@
{"id": "headless-heartbeat-checks-stuck-job", "why": "Run until idle: a waiting run wakes the model with a heartbeat after silence, naming the running job, so it can stop work that will not finish.", "env": {"GRAFF_NO_CODEDB_GUARD": "1", "GRAFF_HEARTBEAT_SECS": "1"}, "prompt": "Start the background watcher and handle it.", "script": [{"tool": "bash", "arguments": {"command": "sleep 30; echo NEVER_PRINTED", "run_in_background": true}}, {"text": "The watcher is running."}, {"tool": "bash_kill", "arguments": {"id": 4294967296}}, {"text": "Stopped the watcher; it was not going to finish."}], "assert": [{"request_count": 4}, {"request_contains": {"index": 2, "text": "[heartbeat: no news from background work"}}, {"request_contains": {"index": 2, "text": "sleep 30"}}, {"final_text_contains": "Stopped the watcher"}], "workspace_seed": {".codegraff/shell-id.lock": "shell-ids-v1\n", ".codegraff/shell-id.counter": "4294967295\n"}}
{"id": "headless-server-does-not-hold", "why": "Run until idle: a server never reports, so a turn that leaves one running in the background ends instead of waiting on it.", "env": {"GRAFF_NO_CODEDB_GUARD": "1", "GRAFF_HEARTBEAT_SECS": "1"}, "prompt": "Start the dev server in the background and confirm it launched.", "script": [{"tool": "bash", "arguments": {"command": "python3 -m http.server 0 --bind 127.0.0.1", "run_in_background": true}}, {"text": "The dev server is running."}], "assert": [{"request_count": 2}, {"final_text_contains": "The dev server is running."}]}
{"id": "claude-conversation-import-resume", "why": "Imported history uses the configured graff route without Claude credentials, retaining dialogue and historical tool results.", "env": {"ANTHROPIC_API_KEY": ""}, "args": ["--resume", "claude-import-fixture"], "claude_transcripts": {"import-fixture.jsonl": "{\"type\": \"user\", \"uuid\": \"u1\", \"message\": {\"content\": \"import-retained-question-1495\"}}\n{\"type\": \"assistant\", \"uuid\": \"a1\", \"message\": {\"model\": \"claude-sonnet-4-5\", \"content\": [{\"type\": \"thinking\", \"thinking\": \"import-private-thinking-1495\", \"signature\": \"signed\"}, {\"type\": \"text\", \"text\": \"import-retained-answer-1495\"}, {\"type\": \"tool_use\", \"id\": \"tool-import-1495\", \"name\": \"Bash\", \"input\": {\"command\": \"echo imported\"}}]}}\n{\"type\": \"user\", \"message\": {\"content\": [{\"type\": \"tool_result\", \"tool_use_id\": \"tool-import-1495\", \"content\": \"import-retained-result-1495\"}]}}\n{\"type\": \"assistant\", \"isSidechain\": true, \"message\": {\"content\": [{\"type\": \"text\", \"text\": \"import-sidechain-1495\"}]}}\n{\"type\": \"assistant\", \"message\": {\"content\": [{\"type\": \"text\", \"text\": \"import-finished-1495\"}]}}\n"}, "controls_before_prompt": [{"type": "set_model", "provider": "lmstudio", "model": "mock"}], "prompt": "Continue the imported task.", "script": [{"text": "Imported history is available."}], "assert": [{"request_contains": {"index": 0, "text": "import-retained-question-1495"}}, {"request_contains": {"index": 0, "text": "import-retained-answer-1495"}}, {"request_contains": {"index": 0, "text": "import-retained-result-1495"}}, {"request_contains": {"index": 0, "text": "import-finished-1495"}}, {"request_lacks": {"index": 0, "text": "import-private-thinking-1495"}}, {"request_lacks": {"index": 0, "text": "import-sidechain-1495"}}, {"final_text_contains": "Imported history is available."}]}
+{"id": "screenshot-handoff-preserves-open-work-1531", "why": "#1531: a screenshot needed on the next prompt must end the current turn without a pause question, completion claim, verifier approval, or open-work retry, and resume with the unfinished checklist intact.", "args": ["--no-lean", "--goal", "fix the control after visual identification", "--eval", "printf \"0\\n\""], "prompt": "The question interface accepts text only. A screenshot is essential to identify the control. Stop this turn so I can attach it to my next prompt.", "second_prompt": "Continue with the new input. Read back the unfinished checklist before proceeding.", "script": [{"tool": "todo_write", "arguments": {"todos": [{"content": "identify the control from the screenshot", "status": "in_progress"}]}}, {"tool": "eval", "arguments": {}}, {"tool": "yield_turn", "arguments": {"message": "Stopping this turn so you can attach the screenshot to your next prompt. The task remains unfinished."}}, {"tool": "todo_read", "arguments": {}}, {"tool": "yield_turn", "arguments": {"message": "The checklist still has the unfinished visual identification item; this turn is stopping until the missing input arrives."}}], "assert": [{"request_contains": {"index": 0, "text": "explicitly supports attachments in question replies"}}, {"request_contains": {"index": 0, "text": "Do not ask for permission to pause"}}, {"request_lacks": {"index": 0, "text": "typed text and/or pasted images"}}, {"event": {"type": "turn", "api_calls": 3, "complete": true, "text": "Stopping this turn so you can attach the screenshot to your next prompt. The task remains unfinished."}}, {"events_at_least": {"match": {"type": "turn"}, "count": 2}}, {"events_at_most": {"match": {"type": "turn"}, "count": 2}}, {"no_event": {"type": "ask_user"}}, {"no_event": {"type": "tool_call", "name": "attempt_completion"}}, {"request_contains": {"index": 4, "text": "identify the control from the screenshot"}}, {"request_contains": {"index": 4, "text": "in_progress"}}, {"request_lacks": {"index": 4, "text": "Open-work reconciliation"}}, {"final_text_contains": "checklist still has the unfinished"}]}
diff --git a/examples/edge-worker/src/remote.ts b/examples/edge-worker/src/remote.ts
index 386abd0f..e91ee92e 100644
--- a/examples/edge-worker/src/remote.ts
+++ b/examples/edge-worker/src/remote.ts
@@ -10,7 +10,7 @@
export const HARNESS_VERSION = "0.13";
export type ModelName = "MiniMax-M2.5" | "MiniMax-M2.7" | "MiniMax-M3" | "accounts/fireworks/models/deepseek-v4-flash" | "accounts/fireworks/models/deepseek-v4-pro" | "accounts/fireworks/models/glm-5p2" | "accounts/fireworks/models/gpt-oss-120b" | "accounts/fireworks/models/kimi-k2p6" | "accounts/fireworks/models/kimi-k2p7-code" | "accounts/fireworks/models/minimax-m3" | "accounts/fireworks/models/qwen3p7-plus" | "alibaba/qwen3.8-27b" | "anthropic/claude-sonnet-4.6" | "claude-fable-5" | "claude-fable-5-1" | "claude-haiku-4-5" | "claude-opus-4-5" | "claude-opus-4-6" | "claude-opus-4-7" | "claude-opus-4-8" | "claude-opus-4.8" | "claude-opus-5" | "claude-opus-5-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-4.6" | "claude-sonnet-5" | "claude-sonnet-5-5" | "deepseek-chat" | "deepseek-reasoner" | "deepseek-v4-flash" | "deepseek-v4-pro" | "fugu" | "fugu-ultra" | "fugu-ultra-20260615" | "gemini-3-flash-preview" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-3.6-flash" | "gemini-3.7-flash" | "gemini-3.8-flash" | "gemma-4-26b-a4b-it" | "gemma-4-31b" | "gemma-4-31b-it" | "glm-4.5" | "glm-4.7" | "glm-5" | "glm-5-turbo" | "glm-5.2" | "glm-5.3" | "glm-5.3-flash" | "glm-5v-turbo" | "gpt-5-codex" | "gpt-5.2" | "gpt-5.3-codex-spark" | "gpt-5.4" | "gpt-5.4-mini" | "gpt-5.4-pro" | "gpt-5.5" | "gpt-5.6" | "gpt-5.6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-6-astra" | "gpt-6-luna" | "gpt-6-sol" | "gpt-6.1-sol" | "gpt-oss-120b" | "grok-4.3" | "grok-4.6" | "grok-4.7" | "grok-build" | "k3" | "kilo-auto/small" | "kimi-for-coding" | "kimi-for-coding-highspeed" | "kimi-k2.6" | "kimi-k2.7-code" | "kimi-k3" | "kimi-latest" | "lmstudio" | "mimo-v2-flash" | "mimo-v2.5" | "mimo-v2.5-pro" | "mimo-v2.5-pro-ultraspeed" | "mimo-v2.6-flash" | "mimo-v2.6-pro" | "mimo-v2.6-pro-ultraspeed" | "minimax-m3" | "mistral-medium-latest" | "mlx-community/Qwen3.6-27B-OptiQ-4bit" | "muse-spark-1.2" | "muse-spark-1.2-contributor" | "openai/gpt-oss-120b" | (string & {});
-export type ToolName = "shell" | "read_file" | "edit_file" | "write_file" | "webfetch" | "skill" | "codedb" | "read_tool_result" | "render_html" | "todo_write" | "todo_read" | "eval" | "note_constraint" | "ask_user" | "attempt_completion" | "load_tool_schemas" | "mcp_search_tools" | "mcp_select_tool" | "clock_sleep" | "subagent" | "workflow" | "agent_output" | "agent_message" | "subagent_resume" | "learn_candidate" | "peer_message" | "workspace" | "imagegen" | "rlm";
+export type ToolName = "shell" | "read_file" | "edit_file" | "write_file" | "webfetch" | "skill" | "codedb" | "read_tool_result" | "render_html" | "todo_write" | "todo_read" | "eval" | "note_constraint" | "ask_user" | "attempt_completion" | "load_tool_schemas" | "mcp_search_tools" | "mcp_select_tool" | "clock_sleep" | "subagent" | "workflow" | "agent_output" | "agent_message" | "subagent_resume" | "learn_candidate" | "peer_message" | "workspace" | "yield_turn" | "imagegen" | "rlm";
export type ProviderId = "anthropic" | "codegraff" | "deepseek" | "openai" | "google" | "minimax" | "xiaomi" | "kilo" | "groq" | "cerebras" | "mistral" | "kimi" | "moonshot" | "xai" | "zai" | "meta" | "vercel" | "openrouter" | "fugu" | "fireworks" | "mlx" | "lmstudio" | "chatgpt-new" | "codex";
/** Events streamed by the bridge (same `--json` contract as the stdio SDK).
@@ -529,4 +529,4 @@ export async function* runAgentRemote(opts: RunAgentRemoteOptions): AsyncGenerat
}
export const MODELS: ModelName[] = ["MiniMax-M2.5", "MiniMax-M2.7", "MiniMax-M3", "accounts/fireworks/models/deepseek-v4-flash", "accounts/fireworks/models/deepseek-v4-pro", "accounts/fireworks/models/glm-5p2", "accounts/fireworks/models/gpt-oss-120b", "accounts/fireworks/models/kimi-k2p6", "accounts/fireworks/models/kimi-k2p7-code", "accounts/fireworks/models/minimax-m3", "accounts/fireworks/models/qwen3p7-plus", "alibaba/qwen3.8-27b", "anthropic/claude-sonnet-4.6", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5", "claude-opus-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-opus-4.8", "claude-opus-5", "claude-opus-5-5", "claude-sonnet-4-5", "claude-sonnet-4-6", "claude-sonnet-4.6", "claude-sonnet-5", "claude-sonnet-5-5", "deepseek-chat", "deepseek-reasoner", "deepseek-v4-flash", "deepseek-v4-pro", "fugu", "fugu-ultra", "fugu-ultra-20260615", "gemini-3-flash-preview", "gemini-3.1-flash-lite", "gemini-3.1-pro-preview", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.7-flash", "gemini-3.8-flash", "gemma-4-26b-a4b-it", "gemma-4-31b", "gemma-4-31b-it", "glm-4.5", "glm-4.7", "glm-5", "glm-5-turbo", "glm-5.2", "glm-5.3", "glm-5.3-flash", "glm-5v-turbo", "gpt-5-codex", "gpt-5.2", "gpt-5.3-codex-spark", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro", "gpt-5.5", "gpt-5.6", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-6-luna", "gpt-6-sol", "gpt-6.1-sol", "gpt-oss-120b", "grok-4.3", "grok-4.6", "grok-4.7", "grok-build", "k3", "kilo-auto/small", "kimi-for-coding", "kimi-for-coding-highspeed", "kimi-k2.6", "kimi-k2.7-code", "kimi-k3", "kimi-latest", "lmstudio", "mimo-v2-flash", "mimo-v2.5", "mimo-v2.5-pro", "mimo-v2.5-pro-ultraspeed", "mimo-v2.6-flash", "mimo-v2.6-pro", "mimo-v2.6-pro-ultraspeed", "minimax-m3", "mistral-medium-latest", "mlx-community/Qwen3.6-27B-OptiQ-4bit", "muse-spark-1.2", "muse-spark-1.2-contributor", "openai/gpt-oss-120b"];
-export const TOOLS: ToolName[] = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "imagegen", "rlm"];
+export const TOOLS: ToolName[] = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "yield_turn", "imagegen", "rlm"];
diff --git a/lean-proofs/Graff/ToolCatalog.lean b/lean-proofs/Graff/ToolCatalog.lean
index 963ef491..be893984 100644
--- a/lean-proofs/Graff/ToolCatalog.lean
+++ b/lean-proofs/Graff/ToolCatalog.lean
@@ -27,7 +27,7 @@ def localTools : List String :=
def leanTools : List String :=
["shell", "read_file", "edit_file", "write_file", "codedb",
- "subagent", "attempt_completion", "load_tool_schemas"]
+ "subagent", "attempt_completion", "yield_turn", "load_tool_schemas"]
def optionalTools : List String :=
["imagegen"]
@@ -44,7 +44,7 @@ def metaTools : List String :=
def rootExtras : List String :=
["subagent", "workflow", "agent_output", "agent_message", "learn_candidate", "peer_message",
- "workspace"]
+ "workspace", "yield_turn"]
def filterKeep (keep : String → Bool) : List String → List String
| [] => []
@@ -140,7 +140,7 @@ example : catalog {} =
["todo_write", "todo_read", "eval", "note_constraint", "ask_user",
"attempt_completion", "load_tool_schemas", "mcp_search_tools",
"mcp_select_tool"] ++
- ["subagent", "workflow", "agent_output", "agent_message", "peer_message", "workspace"]) := by native_decide
+ ["subagent", "workflow", "agent_output", "agent_message", "peer_message", "workspace", "yield_turn"]) := by native_decide
example : catalog { imagegen := true } =
catalog {} ++ ["imagegen"] := by native_decide
diff --git a/sdk/py/harness_sdk.py b/sdk/py/harness_sdk.py
index 08cb949c..26ab2fce 100644
--- a/sdk/py/harness_sdk.py
+++ b/sdk/py/harness_sdk.py
@@ -14,7 +14,7 @@ import urllib.request
from typing import Iterator, List, Literal, Optional, TypedDict, Union
MODELS = ["MiniMax-M2.5", "MiniMax-M2.7", "MiniMax-M3", "accounts/fireworks/models/deepseek-v4-flash", "accounts/fireworks/models/deepseek-v4-pro", "accounts/fireworks/models/glm-5p2", "accounts/fireworks/models/gpt-oss-120b", "accounts/fireworks/models/kimi-k2p6", "accounts/fireworks/models/kimi-k2p7-code", "accounts/fireworks/models/minimax-m3", "accounts/fireworks/models/qwen3p7-plus", "alibaba/qwen3.8-27b", "anthropic/claude-sonnet-4.6", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5", "claude-opus-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-opus-4.8", "claude-opus-5", "claude-opus-5-5", "claude-sonnet-4-5", "claude-sonnet-4-6", "claude-sonnet-4.6", "claude-sonnet-5", "claude-sonnet-5-5", "deepseek-chat", "deepseek-reasoner", "deepseek-v4-flash", "deepseek-v4-pro", "fugu", "fugu-ultra", "fugu-ultra-20260615", "gemini-3-flash-preview", "gemini-3.1-flash-lite", "gemini-3.1-pro-preview", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.7-flash", "gemini-3.8-flash", "gemma-4-26b-a4b-it", "gemma-4-31b", "gemma-4-31b-it", "glm-4.5", "glm-4.7", "glm-5", "glm-5-turbo", "glm-5.2", "glm-5.3", "glm-5.3-flash", "glm-5v-turbo", "gpt-5-codex", "gpt-5.2", "gpt-5.3-codex-spark", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro", "gpt-5.5", "gpt-5.6", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-6-luna", "gpt-6-sol", "gpt-6.1-sol", "gpt-oss-120b", "grok-4.3", "grok-4.6", "grok-4.7", "grok-build", "k3", "kilo-auto/small", "kimi-for-coding", "kimi-for-coding-highspeed", "kimi-k2.6", "kimi-k2.7-code", "kimi-k3", "kimi-latest", "lmstudio", "mimo-v2-flash", "mimo-v2.5", "mimo-v2.5-pro", "mimo-v2.5-pro-ultraspeed", "mimo-v2.6-flash", "mimo-v2.6-pro", "mimo-v2.6-pro-ultraspeed", "minimax-m3", "mistral-medium-latest", "mlx-community/Qwen3.6-27B-OptiQ-4bit", "muse-spark-1.2", "muse-spark-1.2-contributor", "openai/gpt-oss-120b"]
-TOOLS = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "imagegen", "rlm"]
+TOOLS = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "yield_turn", "imagegen", "rlm"]
PROVIDERS = ["anthropic", "codegraff", "deepseek", "openai", "google", "minimax", "xiaomi", "kilo", "groq", "cerebras", "mistral", "kimi", "moonshot", "xai", "zai", "meta", "vercel", "openrouter", "fugu", "fireworks", "mlx", "lmstudio", "chatgpt-new", "codex"]
diff --git a/sdk/ts/harness.ts b/sdk/ts/harness.ts
index d89928dd..d15cfd5a 100644
--- a/sdk/ts/harness.ts
+++ b/sdk/ts/harness.ts
@@ -12,7 +12,7 @@ import type { Readable, Writable } from "node:stream";
export const HARNESS_VERSION = "0.13";
export type ModelName = "MiniMax-M2.5" | "MiniMax-M2.7" | "MiniMax-M3" | "accounts/fireworks/models/deepseek-v4-flash" | "accounts/fireworks/models/deepseek-v4-pro" | "accounts/fireworks/models/glm-5p2" | "accounts/fireworks/models/gpt-oss-120b" | "accounts/fireworks/models/kimi-k2p6" | "accounts/fireworks/models/kimi-k2p7-code" | "accounts/fireworks/models/minimax-m3" | "accounts/fireworks/models/qwen3p7-plus" | "alibaba/qwen3.8-27b" | "anthropic/claude-sonnet-4.6" | "claude-fable-5" | "claude-fable-5-1" | "claude-haiku-4-5" | "claude-opus-4-5" | "claude-opus-4-6" | "claude-opus-4-7" | "claude-opus-4-8" | "claude-opus-4.8" | "claude-opus-5" | "claude-opus-5-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-4.6" | "claude-sonnet-5" | "claude-sonnet-5-5" | "deepseek-chat" | "deepseek-reasoner" | "deepseek-v4-flash" | "deepseek-v4-pro" | "fugu" | "fugu-ultra" | "fugu-ultra-20260615" | "gemini-3-flash-preview" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-3.6-flash" | "gemini-3.7-flash" | "gemini-3.8-flash" | "gemma-4-26b-a4b-it" | "gemma-4-31b" | "gemma-4-31b-it" | "glm-4.5" | "glm-4.7" | "glm-5" | "glm-5-turbo" | "glm-5.2" | "glm-5.3" | "glm-5.3-flash" | "glm-5v-turbo" | "gpt-5-codex" | "gpt-5.2" | "gpt-5.3-codex-spark" | "gpt-5.4" | "gpt-5.4-mini" | "gpt-5.4-pro" | "gpt-5.5" | "gpt-5.6" | "gpt-5.6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-6-astra" | "gpt-6-luna" | "gpt-6-sol" | "gpt-6.1-sol" | "gpt-oss-120b" | "grok-4.3" | "grok-4.6" | "grok-4.7" | "grok-build" | "k3" | "kilo-auto/small" | "kimi-for-coding" | "kimi-for-coding-highspeed" | "kimi-k2.6" | "kimi-k2.7-code" | "kimi-k3" | "kimi-latest" | "lmstudio" | "mimo-v2-flash" | "mimo-v2.5" | "mimo-v2.5-pro" | "mimo-v2.5-pro-ultraspeed" | "mimo-v2.6-flash" | "mimo-v2.6-pro" | "mimo-v2.6-pro-ultraspeed" | "minimax-m3" | "mistral-medium-latest" | "mlx-community/Qwen3.6-27B-OptiQ-4bit" | "muse-spark-1.2" | "muse-spark-1.2-contributor" | "openai/gpt-oss-120b" | (string & {});
-export type ToolName = "shell" | "read_file" | "edit_file" | "write_file" | "webfetch" | "skill" | "codedb" | "read_tool_result" | "render_html" | "todo_write" | "todo_read" | "eval" | "note_constraint" | "ask_user" | "attempt_completion" | "load_tool_schemas" | "mcp_search_tools" | "mcp_select_tool" | "clock_sleep" | "subagent" | "workflow" | "agent_output" | "agent_message" | "subagent_resume" | "learn_candidate" | "peer_message" | "workspace" | "imagegen" | "rlm";
+export type ToolName = "shell" | "read_file" | "edit_file" | "write_file" | "webfetch" | "skill" | "codedb" | "read_tool_result" | "render_html" | "todo_write" | "todo_read" | "eval" | "note_constraint" | "ask_user" | "attempt_completion" | "load_tool_schemas" | "mcp_search_tools" | "mcp_select_tool" | "clock_sleep" | "subagent" | "workflow" | "agent_output" | "agent_message" | "subagent_resume" | "learn_candidate" | "peer_message" | "workspace" | "yield_turn" | "imagegen" | "rlm";
export type ProviderId = "anthropic" | "codegraff" | "deepseek" | "openai" | "google" | "minimax" | "xiaomi" | "kilo" | "groq" | "cerebras" | "mistral" | "kimi" | "moonshot" | "xai" | "zai" | "meta" | "vercel" | "openrouter" | "fugu" | "fireworks" | "mlx" | "lmstudio" | "chatgpt-new" | "codex";
/** Events streamed by `harness --json` (one JSON object per stdout line), each
@@ -682,4 +682,4 @@ export async function* runAgent(opts: RunAgentOptions): AsyncGenerator<Event> {
}
export const MODELS: ModelName[] = ["MiniMax-M2.5", "MiniMax-M2.7", "MiniMax-M3", "accounts/fireworks/models/deepseek-v4-flash", "accounts/fireworks/models/deepseek-v4-pro", "accounts/fireworks/models/glm-5p2", "accounts/fireworks/models/gpt-oss-120b", "accounts/fireworks/models/kimi-k2p6", "accounts/fireworks/models/kimi-k2p7-code", "accounts/fireworks/models/minimax-m3", "accounts/fireworks/models/qwen3p7-plus", "alibaba/qwen3.8-27b", "anthropic/claude-sonnet-4.6", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5", "claude-opus-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-opus-4.8", "claude-opus-5", "claude-opus-5-5", "claude-sonnet-4-5", "claude-sonnet-4-6", "claude-sonnet-4.6", "claude-sonnet-5", "claude-sonnet-5-5", "deepseek-chat", "deepseek-reasoner", "deepseek-v4-flash", "deepseek-v4-pro", "fugu", "fugu-ultra", "fugu-ultra-20260615", "gemini-3-flash-preview", "gemini-3.1-flash-lite", "gemini-3.1-pro-preview", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.7-flash", "gemini-3.8-flash", "gemma-4-26b-a4b-it", "gemma-4-31b", "gemma-4-31b-it", "glm-4.5", "glm-4.7", "glm-5", "glm-5-turbo", "glm-5.2", "glm-5.3", "glm-5.3-flash", "glm-5v-turbo", "gpt-5-codex", "gpt-5.2", "gpt-5.3-codex-spark", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro", "gpt-5.5", "gpt-5.6", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-6-luna", "gpt-6-sol", "gpt-6.1-sol", "gpt-oss-120b", "grok-4.3", "grok-4.6", "grok-4.7", "grok-build", "k3", "kilo-auto/small", "kimi-for-coding", "kimi-for-coding-highspeed", "kimi-k2.6", "kimi-k2.7-code", "kimi-k3", "kimi-latest", "lmstudio", "mimo-v2-flash", "mimo-v2.5", "mimo-v2.5-pro", "mimo-v2.5-pro-ultraspeed", "mimo-v2.6-flash", "mimo-v2.6-pro", "mimo-v2.6-pro-ultraspeed", "minimax-m3", "mistral-medium-latest", "mlx-community/Qwen3.6-27B-OptiQ-4bit", "muse-spark-1.2", "muse-spark-1.2-contributor", "openai/gpt-oss-120b"];
-export const TOOLS: ToolName[] = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "imagegen", "rlm"];
+export const TOOLS: ToolName[] = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "yield_turn", "imagegen", "rlm"];
diff --git a/sdk/ts/remote.ts b/sdk/ts/remote.ts
index 386abd0f..e91ee92e 100644
--- a/sdk/ts/remote.ts
+++ b/sdk/ts/remote.ts
@@ -10,7 +10,7 @@
export const HARNESS_VERSION = "0.13";
export type ModelName = "MiniMax-M2.5" | "MiniMax-M2.7" | "MiniMax-M3" | "accounts/fireworks/models/deepseek-v4-flash" | "accounts/fireworks/models/deepseek-v4-pro" | "accounts/fireworks/models/glm-5p2" | "accounts/fireworks/models/gpt-oss-120b" | "accounts/fireworks/models/kimi-k2p6" | "accounts/fireworks/models/kimi-k2p7-code" | "accounts/fireworks/models/minimax-m3" | "accounts/fireworks/models/qwen3p7-plus" | "alibaba/qwen3.8-27b" | "anthropic/claude-sonnet-4.6" | "claude-fable-5" | "claude-fable-5-1" | "claude-haiku-4-5" | "claude-opus-4-5" | "claude-opus-4-6" | "claude-opus-4-7" | "claude-opus-4-8" | "claude-opus-4.8" | "claude-opus-5" | "claude-opus-5-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-4.6" | "claude-sonnet-5" | "claude-sonnet-5-5" | "deepseek-chat" | "deepseek-reasoner" | "deepseek-v4-flash" | "deepseek-v4-pro" | "fugu" | "fugu-ultra" | "fugu-ultra-20260615" | "gemini-3-flash-preview" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-3.6-flash" | "gemini-3.7-flash" | "gemini-3.8-flash" | "gemma-4-26b-a4b-it" | "gemma-4-31b" | "gemma-4-31b-it" | "glm-4.5" | "glm-4.7" | "glm-5" | "glm-5-turbo" | "glm-5.2" | "glm-5.3" | "glm-5.3-flash" | "glm-5v-turbo" | "gpt-5-codex" | "gpt-5.2" | "gpt-5.3-codex-spark" | "gpt-5.4" | "gpt-5.4-mini" | "gpt-5.4-pro" | "gpt-5.5" | "gpt-5.6" | "gpt-5.6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-6-astra" | "gpt-6-luna" | "gpt-6-sol" | "gpt-6.1-sol" | "gpt-oss-120b" | "grok-4.3" | "grok-4.6" | "grok-4.7" | "grok-build" | "k3" | "kilo-auto/small" | "kimi-for-coding" | "kimi-for-coding-highspeed" | "kimi-k2.6" | "kimi-k2.7-code" | "kimi-k3" | "kimi-latest" | "lmstudio" | "mimo-v2-flash" | "mimo-v2.5" | "mimo-v2.5-pro" | "mimo-v2.5-pro-ultraspeed" | "mimo-v2.6-flash" | "mimo-v2.6-pro" | "mimo-v2.6-pro-ultraspeed" | "minimax-m3" | "mistral-medium-latest" | "mlx-community/Qwen3.6-27B-OptiQ-4bit" | "muse-spark-1.2" | "muse-spark-1.2-contributor" | "openai/gpt-oss-120b" | (string & {});
-export type ToolName = "shell" | "read_file" | "edit_file" | "write_file" | "webfetch" | "skill" | "codedb" | "read_tool_result" | "render_html" | "todo_write" | "todo_read" | "eval" | "note_constraint" | "ask_user" | "attempt_completion" | "load_tool_schemas" | "mcp_search_tools" | "mcp_select_tool" | "clock_sleep" | "subagent" | "workflow" | "agent_output" | "agent_message" | "subagent_resume" | "learn_candidate" | "peer_message" | "workspace" | "imagegen" | "rlm";
+export type ToolName = "shell" | "read_file" | "edit_file" | "write_file" | "webfetch" | "skill" | "codedb" | "read_tool_result" | "render_html" | "todo_write" | "todo_read" | "eval" | "note_constraint" | "ask_user" | "attempt_completion" | "load_tool_schemas" | "mcp_search_tools" | "mcp_select_tool" | "clock_sleep" | "subagent" | "workflow" | "agent_output" | "agent_message" | "subagent_resume" | "learn_candidate" | "peer_message" | "workspace" | "yield_turn" | "imagegen" | "rlm";
export type ProviderId = "anthropic" | "codegraff" | "deepseek" | "openai" | "google" | "minimax" | "xiaomi" | "kilo" | "groq" | "cerebras" | "mistral" | "kimi" | "moonshot" | "xai" | "zai" | "meta" | "vercel" | "openrouter" | "fugu" | "fireworks" | "mlx" | "lmstudio" | "chatgpt-new" | "codex";
/** Events streamed by the bridge (same `--json` contract as the stdio SDK).
@@ -529,4 +529,4 @@ export async function* runAgentRemote(opts: RunAgentRemoteOptions): AsyncGenerat
}
export const MODELS: ModelName[] = ["MiniMax-M2.5", "MiniMax-M2.7", "MiniMax-M3", "accounts/fireworks/models/deepseek-v4-flash", "accounts/fireworks/models/deepseek-v4-pro", "accounts/fireworks/models/glm-5p2", "accounts/fireworks/models/gpt-oss-120b", "accounts/fireworks/models/kimi-k2p6", "accounts/fireworks/models/kimi-k2p7-code", "accounts/fireworks/models/minimax-m3", "accounts/fireworks/models/qwen3p7-plus", "alibaba/qwen3.8-27b", "anthropic/claude-sonnet-4.6", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5", "claude-opus-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-opus-4.8", "claude-opus-5", "claude-opus-5-5", "claude-sonnet-4-5", "claude-sonnet-4-6", "claude-sonnet-4.6", "claude-sonnet-5", "claude-sonnet-5-5", "deepseek-chat", "deepseek-reasoner", "deepseek-v4-flash", "deepseek-v4-pro", "fugu", "fugu-ultra", "fugu-ultra-20260615", "gemini-3-flash-preview", "gemini-3.1-flash-lite", "gemini-3.1-pro-preview", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.7-flash", "gemini-3.8-flash", "gemma-4-26b-a4b-it", "gemma-4-31b", "gemma-4-31b-it", "glm-4.5", "glm-4.7", "glm-5", "glm-5-turbo", "glm-5.2", "glm-5.3", "glm-5.3-flash", "glm-5v-turbo", "gpt-5-codex", "gpt-5.2", "gpt-5.3-codex-spark", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro", "gpt-5.5", "gpt-5.6", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-6-luna", "gpt-6-sol", "gpt-6.1-sol", "gpt-oss-120b", "grok-4.3", "grok-4.6", "grok-4.7", "grok-build", "k3", "kilo-auto/small", "kimi-for-coding", "kimi-for-coding-highspeed", "kimi-k2.6", "kimi-k2.7-code", "kimi-k3", "kimi-latest", "lmstudio", "mimo-v2-flash", "mimo-v2.5", "mimo-v2.5-pro", "mimo-v2.5-pro-ultraspeed", "mimo-v2.6-flash", "mimo-v2.6-pro", "mimo-v2.6-pro-ultraspeed", "minimax-m3", "mistral-medium-latest", "mlx-community/Qwen3.6-27B-OptiQ-4bit", "muse-spark-1.2", "muse-spark-1.2-contributor", "openai/gpt-oss-120b"];
-export const TOOLS: ToolName[] = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "imagegen", "rlm"];
+export const TOOLS: ToolName[] = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "yield_turn", "imagegen", "rlm"];
diff --git a/spec/kernels/tool_catalog.json b/spec/kernels/tool_catalog.json
index c45b641a..aaaaa560 100644
--- a/spec/kernels/tool_catalog.json
+++ b/spec/kernels/tool_catalog.json
@@ -33,7 +33,8 @@
"subagent_resume",
"learn_candidate",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"optional": [
"imagegen"
@@ -56,6 +57,7 @@
"codedb",
"subagent",
"attempt_completion",
+ "yield_turn",
"load_tool_schemas"
]
},
@@ -95,7 +97,8 @@
"agent_message",
"subagent_resume",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"imagegen"
@@ -162,7 +165,8 @@
"subagent_resume",
"learn_candidate",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"imagegen"
@@ -229,7 +233,8 @@
"agent_message",
"subagent_resume",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"imagegen"
@@ -297,7 +302,8 @@
"subagent_resume",
"learn_candidate",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"imagegen"
@@ -364,6 +370,7 @@
"subagent_resume",
"peer_message",
"workspace",
+ "yield_turn",
"imagegen"
],
"blocked": []
@@ -429,6 +436,7 @@
"learn_candidate",
"peer_message",
"workspace",
+ "yield_turn",
"imagegen"
],
"blocked": []
@@ -494,6 +502,7 @@
"subagent_resume",
"peer_message",
"workspace",
+ "yield_turn",
"imagegen"
],
"blocked": []
@@ -560,6 +569,7 @@
"learn_candidate",
"peer_message",
"workspace",
+ "yield_turn",
"imagegen"
],
"blocked": []
@@ -606,7 +616,8 @@
"codedb",
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"imagegen"
@@ -655,7 +666,8 @@
"codedb",
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"imagegen"
@@ -704,7 +716,8 @@
"codedb",
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"imagegen"
@@ -753,7 +766,8 @@
"codedb",
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"imagegen"
@@ -802,7 +816,8 @@
"codedb",
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": []
},
@@ -848,7 +863,8 @@
"codedb",
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": []
},
@@ -894,7 +910,8 @@
"codedb",
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": []
},
@@ -940,7 +957,8 @@
"codedb",
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": []
},
@@ -996,7 +1014,8 @@
"agent_message",
"subagent_resume",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1063,7 +1082,8 @@
"subagent_resume",
"learn_candidate",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1130,7 +1150,8 @@
"agent_message",
"subagent_resume",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1198,7 +1219,8 @@
"subagent_resume",
"learn_candidate",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1264,7 +1286,8 @@
"agent_message",
"subagent_resume",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1331,7 +1354,8 @@
"subagent_resume",
"learn_candidate",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1398,7 +1422,8 @@
"agent_message",
"subagent_resume",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1466,7 +1491,8 @@
"subagent_resume",
"learn_candidate",
"peer_message",
- "workspace"
+ "workspace",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1517,7 +1543,8 @@
"advertised": [
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1568,7 +1595,8 @@
"advertised": [
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1619,7 +1647,8 @@
"advertised": [
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1670,7 +1699,8 @@
"advertised": [
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1721,7 +1751,8 @@
"advertised": [
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1772,7 +1803,8 @@
"advertised": [
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1823,7 +1855,8 @@
"advertised": [
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"codedb",
@@ -1874,7 +1907,8 @@
"advertised": [
"attempt_completion",
"load_tool_schemas",
- "subagent"
+ "subagent",
+ "yield_turn"
],
"blocked": [
"codedb",
diff --git a/spec/ref/tool_catalog.py b/spec/ref/tool_catalog.py
index fc936f36..43052db8 100644
--- a/spec/ref/tool_catalog.py
+++ b/spec/ref/tool_catalog.py
@@ -28,6 +28,7 @@ LEAN_TOOLS = (
"codedb",
"subagent",
"attempt_completion",
+ "yield_turn",
"load_tool_schemas",
)
OPTIONAL_TOOLS = ("imagegen",)
@@ -63,6 +64,7 @@ ROOT_EXTRAS = (
"learn_candidate",
"peer_message",
"workspace",
+ "yield_turn",
)
ROOT_UNIVERSE = BASE_TOOLS + META_TOOLS + ROOT_EXTRAS
diff --git a/src/agent.zig b/src/agent.zig
index caa3cc69..ff8ffa9f 100644
--- a/src/agent.zig
+++ b/src/agent.zig
@@ -27,9 +27,7 @@ const run_budget_mod = @import("run_budget.zig");
// agent_prompt.zig owns the width-budgeted status line (#209); aliased below.
const prompt_ui = @import("agent_prompt.zig");
const agent_tests = @import("agent_tests.zig");
-const empty_completion = @import("agent_empty_completion.zig");
const goal_state = @import("goal_state.zig");
-const turn_inbox = @import("turn_inbox.zig");
pub const TodoItem = struct {
content: []const u8,
status: []const u8,
@@ -196,6 +194,7 @@ pub const Agent = struct {
eval_fp: ?[32]u8 = null, // #412: worktree fingerprint at the last RED eval (verify_fingerprint.Digest); an identical tree skips the re-verify instead of paying for it
strict: bool = false,
completed: ?[]const u8 = null,
+ yielded: ?[]const u8 = null, // turn-local handoff, never a completed goal
last_context_tokens: u64 = 0,
context_local_tokens: u64 = 0, // local request estimate paired with last_context_tokens
last_usage_includes_output: bool = false, // fresh usage covers response items step* is about to append
@@ -324,88 +323,7 @@ pub const Agent = struct {
}
pub fn runTurn(self: *Agent) anyerror![]const u8 {
- defer @import("jev_effort_state.zig").finishTurn(self);
- errdefer self.jev_effort_pending.invalidate(self.io);
- @import("jev_auto.zig").beginTurn(self); // ADR 0246: Jev picks this turn's effort; finishTurn puts it back
- self.async_tools_armed = !self.sub and self.eval_cmd == null;
- defer self.async_tools_armed = false;
- defer @import("agent_async_tools.zig").reset(self);
- if (!self.sub) @import("peer_idle.zig").noteTurnStart();
- defer if (!self.sub) @import("peer_idle.zig").noteTurnEnd();
- var pending_work: empty_completion.PendingWork = .{};
- var bounced_answer: empty_completion.BounceAnswer = .{};
- self.completed = null;
- self.read_miss.reset();
- self.mcp_context.begin(self.io);
- @import("named_work.zig").beginTurn(self);
- try self.ensureRootTools(self.provider.kind);
- var task_scope = @import("task_intent.zig").State.begin(self);
- if (!self.sub and !root_turn_prepared.swap(false, .acq_rel)) @import("cancel_source.zig").clear();
- var review_deadline = try @import("review_deadline.zig").start(self);
- defer review_deadline.stop();
- while (true) {
- try task_scope.beforeRequest(self);
- if (try @import("turn_chrome.zig").beforeRequest(self)) |paused| return review_deadline.finish(paused);
- // Esc during a tool join lands here; root consumes, subagents bail.
- if (esc_cancel.load(.acquire)) {
- if (!self.sub) esc_cancel.store(false, .release);
- return error.Interrupted;
- }
- // Peer mail, job/schedule wakes, and REPL steer land here so a
- // follow-up typed during tools is the next user message in this
- // turn rather than the next prompt after runTurn returns.
- try turn_inbox.deliver(self);
- // #193: pre-send overflow gate. A single turn's tool-output burst can
- // push the input past the model's wall before the between-turns 80%
- // meter (last_context_tokens, server-reported) catches up. Estimate the
- // full input locally and compact BEFORE sending so we never ship an
- // over-cap request (codex run_pre_sampling_compact / opencode isOverflow).
- if (self.inputOverCompactThreshold()) {
- // Bracket the compaction with codex-WS resets, mirroring how every
- // other compactOrRecover call site is bookended by runTurn's
- // closeCodexWs (299 + defer 300). Mid-turn the WS can be live with a
- // prev_id / codex_sent_upto watermark keyed to the pre-trim history:
- // (1) the first reset lets compact()'s own summary request (it calls
- // request() at agent_compact.zig:267, after shrinking history at
- // 259-260) run against a clean session — a stale prev_id makes the
- // server re-prepend the full pre-trim context, defeating or
- // overflowing the summary itself; (2) the second re-anchors so the
- // next in-turn request() re-sends the trimmed full input, not a delta
- // keyed to dropped messages (same closeCodexWs-after-trim reason as
- // the in-turn recovery at agent_request.zig:273).
- self.closeCodexWs();
- // Match the between-turn policy: at the ordinary compactAt
- // threshold, a transient/empty summary must not immediately drop
- // real history. Destructive recovery is reserved for >=95%.
- const recovery_meter = self.effectiveContextTokens();
- self.autocompact(recovery_meter);
- self.closeCodexWs();
- }
- // ADR 0030: showcase rlm once the existing compact meter is
- // actually large. Schema rides the tail; head bytes stay put.
- if (!self.sub) {
- const fold = @import("native_fold.zig");
- if (fold.noticeContext(self.effectiveContextTokens(), self.provider.compactAt())) {
- self.invalidateRootTools();
- try self.ensureRootTools(self.provider.kind);
- }
- }
- const hist_len = self.messages.items.len;
- const root = self.request(if (self.text_only) null else self.toolsJson()) catch |err| return review_deadline.finish(try @import("agent_model_loop.zig").finishError(self, err));
- const done = try @import("agent_steps.zig").stepForWire(self, root);
- if (done) |final_text| {
- if (@import("tool_call_repair.zig").endsTurn(self, final_text)) return review_deadline.finish(final_text); // final: no retry/nudge
- // Retry empty replies; reconcile plain finals with live work (#745).
- if (try bounced_answer.retry(self, final_text, hist_len)) continue;
- if (try @import("named_work.zig").handle(self, final_text)) continue;
- if (try pending_work.finish(self, bounced_answer.finish(self, final_text))) |text| {
- if (self.feedback) |inbox| if (!inbox.tryFinish(self.io)) continue;
- return review_deadline.finish(text);
- }
- continue;
- }
- self.empty_completion_retries = 0;
- }
+ return @import("agent_turn.zig").run(self, &root_turn_prepared);
}
// The provider round trip (request/buildBody + usage/cost recording +
diff --git a/src/agent_eval_control_tests.zig b/src/agent_eval_control_tests.zig
index 81ba6466..d17f2221 100644
--- a/src/agent_eval_control_tests.zig
+++ b/src/agent_eval_control_tests.zig
@@ -174,3 +174,98 @@ test "read-only MCP never hides a later mutation from completion policy" {
try std.testing.expect(eval_control.shouldDeferCompletion(&batch));
}
}
+
+fn handoffFixture(arena: std.mem.Allocator) Agent {
+ return .{
+ .gpa = std.testing.allocator,
+ .arena = arena,
+ .io = std.testing.io,
+ .client = undefined,
+ .provider = .{ .id = "test", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "test", .context = 128000 },
+ .messages = .init(arena),
+ .sub = false,
+ .label = "test",
+ .out = null,
+ .eval_cmd = "verify",
+ .eval_repair_pending = true,
+ .goal = .{ .objective = "fix the control", .standing = true, .epoch = 1 },
+ };
+}
+
+test "yield_turn (#1531): stops without verifier, completion, or pause approval and preserves work" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ var agent = handoffFixture(arena);
+ try agent.todos.append(arena, .{ .content = "fix the control", .status = "in_progress", .epoch = 1 });
+ const handoff = try call(arena, "yield_turn", "{\"message\":\"Stopping this turn; attach the screenshot to your next prompt.\"}");
+ const saved_max = @import("main.zig").max_tool_calls;
+ defer @import("main.zig").max_tool_calls = saved_max;
+ const idle = @import("peer_idle.zig");
+ const was_suppressed = idle.idleWakeSuppressed();
+ const was_waiting = idle.waitingForInput();
+ defer {
+ idle.noteHumanPrompt();
+ if (was_suppressed) idle.noteCompletion();
+ if (was_waiting) idle.noteHandoff();
+ }
+ const saved_json = @import("main.zig").json_mode;
+ @import("main.zig").json_mode = false;
+ defer @import("main.zig").json_mode = saved_json;
+ var output: std.Io.Writer.Allocating = .init(arena);
+ agent.out = &output.writer;
+ agent.streamed_text = true; // a preamble must not hide the handoff explanation
+
+ @import("main.zig").max_tool_calls = 0;
+ try std.testing.expect((try agent_tools.rejectToolCall(&agent, handoff)) == null);
+ const result = try agent.handleMeta(handoff);
+ try std.testing.expect(!result.is_error);
+ try std.testing.expect(std.mem.indexOf(u8, output.writer.buffered(), "attach the screenshot") != null);
+ try std.testing.expect(idle.idleWakeSuppressed());
+ const notify = @import("job_notify.zig");
+ var wake_buf: [512]u8 = undefined;
+ while (notify.takeIdleWake(agent.io, &wake_buf)) |_| {}
+ notify.record(agent.io, 1531, 0, false, "handoff-fixture", false);
+ try std.testing.expect(@import("idle_wake_sources.zig").takeIdleWake(agent.io, "handoff-fixture", &wake_buf) == null);
+ try std.testing.expect(notify.pending(agent.io));
+ idle.noteHumanPrompt();
+ try std.testing.expect(!idle.idleWakeSuppressed() and !idle.waitingForInput());
+ try std.testing.expect(notify.takeIdleWake(agent.io, &wake_buf) != null);
+ try std.testing.expectEqualStrings("Stopping this turn; attach the screenshot to your next prompt.", agent.yielded.?);
+ try std.testing.expect(agent.completed == null);
+ try std.testing.expect(!agent.completion_refused);
+ try std.testing.expect(!agent.completion_gate_armed);
+ try std.testing.expect(agent.eval_repair_pending and !agent.eval_verified);
+ try std.testing.expectEqual(@import("agent.zig").GoalStatus.active, agent.goal.?.status);
+ try std.testing.expectEqualStrings("in_progress", agent.todos.items[0].status);
+ try std.testing.expectEqual(repl_glue.ContinuationOutcome.blocked, @import("goal_flow.zig").loopTurnDecision(&agent, 25, 0).stop);
+}
+
+test "yield_turn (#1531): malformed or child handoffs do not end execution" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ var agent = handoffFixture(arena);
+ for ([_][]const u8{ "{}", "{\"message\":1}", "{\"message\":\" \\n\"}" }) |input| {
+ try std.testing.expect((try agent.handleMeta(try call(arena, "yield_turn", input))).is_error);
+ try std.testing.expect(agent.yielded == null);
+ }
+ agent.sub = true;
+ try std.testing.expect((try agent.handleMeta(try call(arena, "yield_turn", "{\"message\":\"wait\"}"))).is_error);
+ try std.testing.expect(agent.yielded == null);
+}
+
+test "yield_turn (#1531): mixed batches execute nothing instead of racing the handoff" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ var agent = handoffFixture(arena);
+ const batch = [_]ToolCall{
+ try call(arena, "yield_turn", "{\"message\":\"wait\"}"),
+ try call(arena, "todo_write", "{\"todos\":[{\"content\":\"should not run\",\"status\":\"completed\"}]}"),
+ };
+ const results = try agent.runTools(&batch);
+ for (results) |result| try std.testing.expect(result.is_error);
+ try std.testing.expect(agent.yielded == null);
+ try std.testing.expectEqual(@as(usize, 0), agent.todos.items.len);
+}
diff --git a/src/agent_steps.zig b/src/agent_steps.zig
index 58320a6c..46c45d17 100644
--- a/src/agent_steps.zig
+++ b/src/agent_steps.zig
@@ -151,6 +151,7 @@ pub fn stepResponses(self: *Agent, response: std.json.ObjectMap) !?[]const u8 {
if (try grantRepairTurn(self)) return null;
return eval_control.verifier_hard_stop;
}
+ if (self.yielded) |handoff| return handoff;
if (self.completed) |result| return result;
return null;
}
@@ -223,6 +224,7 @@ pub fn stepAnthropic(self: *Agent, root: std.json.ObjectMap) !?[]const u8 {
if (try grantRepairTurn(self)) return null;
return eval_control.verifier_hard_stop;
}
+ if (self.yielded) |handoff| return handoff;
if (self.completed) |result| return result;
return null; // loop again
}
@@ -325,6 +327,7 @@ pub fn stepOpenAI(self: *Agent, root: std.json.ObjectMap) !?[]const u8 {
if (try grantRepairTurn(self)) return null;
return eval_control.verifier_hard_stop;
}
+ if (self.yielded) |handoff| return handoff;
if (self.completed) |result| return result;
return null;
}
diff --git a/src/agent_steps_tests.zig b/src/agent_steps_tests.zig
index 6f31d747..6ebbd67e 100644
--- a/src/agent_steps_tests.zig
+++ b/src/agent_steps_tests.zig
@@ -185,3 +185,42 @@ test "#748: error-only OpenAI SSE is an error envelope, not a missing stream" {
try std.testing.expectEqualStrings("invalid_request_error", root.get("error").?.object.get("type").?.string);
try std.testing.expectEqualStrings("only auto is supported", root.get("error").?.object.get("message").?.string);
}
+
+test "yield_turn (#1531): every wire returns the handoff after recording the tool result" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ const idle = @import("peer_idle.zig");
+ const was_suppressed = idle.idleWakeSuppressed();
+ const was_waiting = idle.waitingForInput();
+ defer {
+ idle.noteHumanPrompt();
+ if (was_suppressed) idle.noteCompletion();
+ if (was_waiting) idle.noteHandoff();
+ }
+ const cases = .{
+ .{ .openai, "{\"choices\":[{\"message\":{\"role\":\"assistant\",\"tool_calls\":[{\"id\":\"y\",\"function\":{\"name\":\"yield_turn\",\"arguments\":\"{\\\"message\\\":\\\"Attach the screenshot on the next prompt.\\\"}\"}}]}}]}" },
+ .{ .anthropic, "{\"content\":[{\"type\":\"tool_use\",\"id\":\"y\",\"name\":\"yield_turn\",\"input\":{\"message\":\"Attach the screenshot on the next prompt.\"}}]}" },
+ .{ .responses, "{\"output\":[{\"type\":\"function_call\",\"call_id\":\"y\",\"name\":\"yield_turn\",\"arguments\":\"{\\\"message\\\":\\\"Attach the screenshot on the next prompt.\\\"}\"}]}" },
+ .{ .interactions, "{\"steps\":[{\"type\":\"function_call\",\"id\":\"y\",\"name\":\"yield_turn\",\"arguments\":{\"message\":\"Attach the screenshot on the next prompt.\"}}]}" },
+ };
+ inline for (cases) |case| {
+ var agent: Agent = .{
+ .gpa = std.testing.allocator,
+ .arena = arena,
+ .io = std.testing.io,
+ .client = undefined,
+ .provider = .{ .id = "test", .kind = case[0], .auth = .bearer, .url = "", .api_key = "", .model = "test", .context = 128000 },
+ .messages = .init(arena),
+ .sub = false,
+ .label = "test",
+ .out = null,
+ };
+ defer agent.tools_used.deinit(std.testing.allocator);
+ const root = try std.json.parseFromSliceLeaky(std.json.Value, arena, case[1], .{});
+ const result = (try @import("agent_steps.zig").stepForWire(&agent, root.object)).?;
+ try std.testing.expectEqualStrings("Attach the screenshot on the next prompt.", result);
+ try std.testing.expect(agent.completed == null);
+ try std.testing.expectEqual(@as(usize, 2), agent.messages.items.len);
+ }
+}
diff --git a/src/agent_tools.zig b/src/agent_tools.zig
index 8c0ec2e1..3b097bf1 100644
--- a/src/agent_tools.zig
+++ b/src/agent_tools.zig
@@ -72,6 +72,7 @@ pub fn runTools(self: *Agent, calls: []const ToolCall) ![]ExecResult {
}
}
const results = try self.arena.alloc(ExecResult, calls.len);
+ if (try @import("turn_handoff.zig").rejectMixedBatch(self, calls, results)) return results;
const eval_index = eval_control.evalCallIndex(calls);
const blocks_completion = eval_control.batchBlocksCompletion(calls);
const defer_completion = eval_control.shouldDeferCompletion(calls);
@@ -196,6 +197,7 @@ pub fn rejectToolCall(self: *Agent, call: ToolCall) !?ExecResult {
if (self.read_miss.shouldRefuse(path)) return try refuseRead(self, call);
}
}
+ if (!self.sub and std.mem.eql(u8, call.name, "yield_turn")) return null;
if (isMetaName(call.name) or local_tools.isInstall(call.name) or schedule.isName(call.name) or std.mem.eql(u8, call.name, "structured_output")) {
if (self.run_budget) |budget| if (budget.toolRefusal(self.arena, self.tracer)) |denied| {
self.emitToolRejected(call, "exhausted", denied.text);
@@ -304,6 +306,7 @@ pub fn handleMeta(self: *Agent, call: ToolCall) !ExecResult {
if (main_mod.plan_mode) return .{ .text = "plan mode is on — schedule_task writes .graff/schedule; switch to act first.", .is_error = true };
return schedule.handleTool(self, call);
}
+ if (std.mem.eql(u8, call.name, "yield_turn")) return @import("turn_handoff.zig").handle(self, call);
if (std.mem.eql(u8, call.name, "attempt_completion")) {
if (!self.review_mode and self.eval_cmd != null and (!self.eval_verified or self.eval_repair_pending)) {
const message = if (self.eval_repair_pending)
diff --git a/src/agent_turn.zig b/src/agent_turn.zig
new file mode 100644
index 00000000..96bb41c6
--- /dev/null
+++ b/src/agent_turn.zig
@@ -0,0 +1,93 @@
+//! The shared agent turn loop, including explicit non-completing handoffs.
+
+const std = @import("std");
+const Agent = @import("agent.zig").Agent;
+const empty_completion = @import("agent_empty_completion.zig");
+const turn_inbox = @import("turn_inbox.zig");
+
+pub fn run(self: *Agent, root_turn_prepared: *std.atomic.Value(bool)) anyerror![]const u8 {
+ defer @import("jev_effort_state.zig").finishTurn(self);
+ errdefer self.jev_effort_pending.invalidate(self.io);
+ @import("jev_auto.zig").beginTurn(self); // ADR 0246: Jev picks this turn's effort; finishTurn puts it back
+ self.async_tools_armed = !self.sub and self.eval_cmd == null;
+ defer self.async_tools_armed = false;
+ defer @import("agent_async_tools.zig").reset(self);
+ if (!self.sub) @import("peer_idle.zig").noteTurnStart();
+ defer if (!self.sub) @import("peer_idle.zig").noteTurnEnd();
+ var pending_work: empty_completion.PendingWork = .{};
+ var bounced_answer: empty_completion.BounceAnswer = .{};
+ self.completed = null;
+ self.yielded = null;
+ self.read_miss.reset();
+ self.mcp_context.begin(self.io);
+ @import("named_work.zig").beginTurn(self);
+ try self.ensureRootTools(self.provider.kind);
+ var task_scope = @import("task_intent.zig").State.begin(self);
+ if (!self.sub and !root_turn_prepared.swap(false, .acq_rel)) @import("cancel_source.zig").clear();
+ var review_deadline = try @import("review_deadline.zig").start(self);
+ defer review_deadline.stop();
+ while (true) {
+ try task_scope.beforeRequest(self);
+ if (try @import("turn_chrome.zig").beforeRequest(self)) |paused| return review_deadline.finish(paused);
+ // Esc during a tool join lands here; root consumes, subagents bail.
+ if (Agent.esc_cancel.load(.acquire)) {
+ if (!self.sub) Agent.esc_cancel.store(false, .release);
+ return error.Interrupted;
+ }
+ // Peer mail, job/schedule wakes, and REPL steer land here so a
+ // follow-up typed during tools is the next user message in this
+ // turn rather than the next prompt after runTurn returns.
+ try turn_inbox.deliver(self);
+ // #193: pre-send overflow gate. A single turn's tool-output burst can
+ // push the input past the model's wall before the between-turns 80%
+ // meter (last_context_tokens, server-reported) catches up. Estimate the
+ // full input locally and compact BEFORE sending so we never ship an
+ // over-cap request (codex run_pre_sampling_compact / opencode isOverflow).
+ if (self.inputOverCompactThreshold()) {
+ // Bracket the compaction with codex-WS resets, mirroring how every
+ // other compactOrRecover call site is bookended by runTurn's
+ // closeCodexWs (299 + defer 300). Mid-turn the WS can be live with a
+ // prev_id / codex_sent_upto watermark keyed to the pre-trim history:
+ // (1) the first reset lets compact()'s own summary request (it calls
+ // request() at agent_compact.zig:267, after shrinking history at
+ // 259-260) run against a clean session — a stale prev_id makes the
+ // server re-prepend the full pre-trim context, defeating or
+ // overflowing the summary itself; (2) the second re-anchors so the
+ // next in-turn request() re-sends the trimmed full input, not a delta
+ // keyed to dropped messages (same closeCodexWs-after-trim reason as
+ // the in-turn recovery at agent_request.zig:273).
+ self.closeCodexWs();
+ // Match the between-turn policy: at the ordinary compactAt
+ // threshold, a transient/empty summary must not immediately drop
+ // real history. Destructive recovery is reserved for >=95%.
+ const recovery_meter = self.effectiveContextTokens();
+ self.autocompact(recovery_meter);
+ self.closeCodexWs();
+ }
+ // ADR 0030: showcase rlm once the existing compact meter is
+ // actually large. Schema rides the tail; head bytes stay put.
+ if (!self.sub) {
+ const fold = @import("native_fold.zig");
+ if (fold.noticeContext(self.effectiveContextTokens(), self.provider.compactAt())) {
+ self.invalidateRootTools();
+ try self.ensureRootTools(self.provider.kind);
+ }
+ }
+ const hist_len = self.messages.items.len;
+ const root = self.request(if (self.text_only) null else self.toolsJson()) catch |err| return review_deadline.finish(try @import("agent_model_loop.zig").finishError(self, err));
+ const done = try @import("agent_steps.zig").stepForWire(self, root);
+ if (done) |final_text| {
+ if (self.yielded != null) return review_deadline.finish(final_text);
+ if (@import("tool_call_repair.zig").endsTurn(self, final_text)) return review_deadline.finish(final_text); // final: no retry/nudge
+ // Retry empty replies; reconcile plain finals with live work (#745).
+ if (try bounced_answer.retry(self, final_text, hist_len)) continue;
+ if (try @import("named_work.zig").handle(self, final_text)) continue;
+ if (try pending_work.finish(self, bounced_answer.finish(self, final_text))) |text| {
+ if (self.feedback) |inbox| if (!inbox.tryFinish(self.io)) continue;
+ return review_deadline.finish(text);
+ }
+ continue;
+ }
+ self.empty_completion_retries = 0;
+ }
+}
diff --git a/src/goal_flow.zig b/src/goal_flow.zig
index 895909cf..980107b3 100644
--- a/src/goal_flow.zig
+++ b/src/goal_flow.zig
@@ -177,6 +177,7 @@ pub fn applyGoalSet(root: *Agent, objective: []const u8, now_ms: i64) GoalSetRes
/// work, not silence. A session with no goal reads as .active, so a goal-less run
/// is governed by its work and its iteration bound alone.
pub fn loopTurnDecision(root: *Agent, iters_left: u32, now_ms: i64) repl_glue.ContinuationDecision {
+ if (root.yielded != null) return .{ .stop = .blocked }; // wait for the next user prompt, not completion
if (@import("subagent_interactive.zig").enabled.load(.acquire) and @import("subagent_interactive.zig").yielded) return .{ .stop = .idle };
const work_done = root.completed != null or goal_state.checklistFinished(root);
const model_stopped = repl_glue.turnStopped(root.tool_calls_this_turn, root.completion_refused);
@@ -275,6 +276,7 @@ fn flowRoot(arena: Allocator) Agent {
root.completion_gate_armed = false;
root.completion_refused = false;
root.completed = null;
+ root.yielded = null;
root.goal_note_fp = 0;
root.pending_goal_note = null;
root.history_rewrites = 0;
diff --git a/src/goal_persist_tests.zig b/src/goal_persist_tests.zig
index 0b3aba5d..dca11bf2 100644
--- a/src/goal_persist_tests.zig
+++ b/src/goal_persist_tests.zig
@@ -79,6 +79,7 @@ fn blankRoot(arena: Allocator) Agent {
root.completion_gate_armed = false;
root.completion_refused = false;
root.completed = null;
+ root.yielded = null;
root.tool_calls_this_turn = 0;
root.goal_note_fp = 0;
root.pending_goal_note = null;
diff --git a/src/idle_wake_sources.zig b/src/idle_wake_sources.zig
index eaca55c5..7cf18a59 100644
--- a/src/idle_wake_sources.zig
+++ b/src/idle_wake_sources.zig
@@ -21,6 +21,7 @@ const subagent_interactive = @import("subagent_interactive.zig");
/// latches stay inside `peer_idle.takeIdleWake` (#1137 / #1138); this helper
/// only unifies which sources run and in which order.
pub fn takeIdleWake(io: Io, session_name: []const u8, buf: []u8) ?[]const u8 {
+ if (peer_idle.waitingForInput()) return null; // retain notices for the next human prompt
if (subagent_interactive.takeWake(io, session_name, buf)) |t| return t;
if (job_notify.takeIdleWake(io, buf)) |t| return t; // idle-stop waits for a real step boundary (#199)
if (schedule.takeWake(io, buf)) |t| return t;
diff --git a/src/interactions_steps.zig b/src/interactions_steps.zig
index d9ea0196..55a08d94 100644
--- a/src/interactions_steps.zig
+++ b/src/interactions_steps.zig
@@ -145,6 +145,7 @@ pub fn step(self: *@import("agent.zig").Agent, root: std.json.ObjectMap) !?[]con
if (try agent_steps.grantRepairTurn(self)) return null;
return eval_control.verifier_hard_stop;
}
+ if (self.yielded) |message| return message;
if (self.completed) |result| return result;
return null;
}
diff --git a/src/mainloop.zig b/src/mainloop.zig
index a2790ca4..3daadc97 100644
--- a/src/mainloop.zig
+++ b/src/mainloop.zig
@@ -539,7 +539,7 @@ pub fn run(ctx: *Ctx) !void {
.session_arena_kb = if (main_mod.g_session_arena) |a| a.queryCapacity() / 1024 else 0,
.scratch_arena_kb = if (ctx.root.scratch_arena) |a| a.queryCapacity() / 1024 else 0,
});
- ctx.root.emit(turn_event.fromTally(&pricing.g_cost, ctx.io, emitted_text, session_context_tokens, isolated_review or !ctx.root.eval_repair_pending));
+ ctx.root.emit(turn_event.fromTally(&pricing.g_cost, ctx.io, emitted_text, session_context_tokens, isolated_review or ctx.root.yielded != null or !ctx.root.eval_repair_pending));
}
// Apply only if already complete; poll never waits for title generation.
title_jobs.poll(ctx);
diff --git a/src/no_local_tools.zig b/src/no_local_tools.zig
index 0cca97ee..1ba224ea 100644
--- a/src/no_local_tools.zig
+++ b/src/no_local_tools.zig
@@ -101,6 +101,7 @@ pub const lean_tools = [_][]const u8{
"codedb",
"subagent",
"attempt_completion",
+ "yield_turn",
"load_tool_schemas",
};
@@ -237,7 +238,7 @@ test "#330: GRAFF_NO_LOCAL_TOOLS is affirmative-only" {
for ([_][]const u8{ "", "0", "false", "off", "no", "2", "enabled" }) |v| try std.testing.expect(!envEnables(v));
}
-test "lean: the filter keeps exactly the seven one-shot tools, and allocates nothing when off" {
+test "lean: the filter keeps the one-shot tools and handoff, and allocates nothing when off" {
const Spec = struct { name: []const u8, desc: []const u8 = "" };
const specs = [_]Spec{
.{ .name = "shell" },
@@ -246,6 +247,7 @@ test "lean: the filter keeps exactly the seven one-shot tools, and allocates not
.{ .name = "todo_write" },
.{ .name = "subagent" },
.{ .name = "attempt_completion" },
+ .{ .name = "yield_turn" },
};
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
@@ -260,12 +262,13 @@ test "lean: the filter keeps exactly the seven one-shot tools, and allocates not
lean = true;
const kept = try filterLeanSpecs(Spec, arena, &specs);
- try std.testing.expectEqual(@as(usize, 4), kept.len);
+ try std.testing.expectEqual(@as(usize, 5), kept.len);
try std.testing.expectEqualStrings("shell", kept[0].name);
try std.testing.expectEqualStrings("read_file", kept[1].name);
try std.testing.expectEqualStrings("subagent", kept[2].name);
try std.testing.expectEqualStrings("attempt_completion", kept[3].name);
- try std.testing.expectEqual(@as(usize, 8), lean_tools.len);
+ try std.testing.expectEqualStrings("yield_turn", kept[4].name);
+ try std.testing.expectEqual(@as(usize, 9), lean_tools.len);
try std.testing.expect(leanKeeps("read_file") and leanKeeps("edit_file") and leanKeeps("write_file"));
try std.testing.expect(!leanKeeps("read_tool_result"));
for (lean_tools) |tool| try std.testing.expect(leanKeeps(tool));
diff --git a/src/peer_idle.zig b/src/peer_idle.zig
index 321e4f00..c21cfc4d 100644
--- a/src/peer_idle.zig
+++ b/src/peer_idle.zig
@@ -15,12 +15,14 @@ const presence_chan = @import("presence_chan.zig");
var last_woken_unread: usize = 0;
var last_placed_gen: u64 = 0;
var suppress_idle_wake: bool = false;
+var waiting_for_input: bool = false;
var turn_busy: std.atomic.Value(bool) = .init(false);
pub fn resetForTest() void {
last_woken_unread = 0;
last_placed_gen = 0;
suppress_idle_wake = false;
+ waiting_for_input = false;
turn_busy.store(false, .release);
}
@@ -44,9 +46,21 @@ pub fn noteCompletion() void {
suppress_idle_wake = true;
}
+/// A handoff waits for human input without completing a goal. Peer mail
+/// stays readable, but cannot immediately reopen the yielded turn.
+pub fn noteHandoff() void {
+ suppress_idle_wake = true;
+ waiting_for_input = true;
+}
+
+pub fn waitingForInput() bool {
+ return waiting_for_input;
+}
+
/// A later human prompt re-opens idle auto-turn.
pub fn noteHumanPrompt() void {
suppress_idle_wake = false;
+ waiting_for_input = false;
}
pub fn idleWakeSuppressed() bool {
diff --git a/src/prompt_golden.zig b/src/prompt_golden.zig
index 1cdf92f8..1a5ef49a 100644
--- a/src/prompt_golden.zig
+++ b/src/prompt_golden.zig
@@ -143,7 +143,17 @@ pub const full_prompt =
\\blocks you, ask with ask_user (the choices in options); otherwise decide
\\and go. Never end a turn with a menu of options written in prose: the
\\harness renders ask_user options as a numbered picker and blocks for the
- \\answer, and a menu in prose does neither. When a task names files or
+ \\answer, and a menu in prose does neither. This applies to text questions,
+ \\not image requests: do not ask for screenshots or images through ask_user
+ \\unless the active interface explicitly supports attachments in question
+ \\replies. Backend vision support does not establish that UI capability.
+ \\If support is absent or unknown and an image is essential, use yield_turn
+ \\to explain that this turn is stopping so the user can attach it to the
+ \\next prompt. No ask_user or permission to pause: yield_turn stops even
+ \\with open work or an unmet verifier. It preserves the conversation and
+ \\unfinished checklist without claiming completion. Finish independent
+ \\authorized work first; do not ask the user to stop the harness for you.
+ \\When a task names files or
\\failing tests, use the named target directly instead of probing unrelated
\\indexes first; that dice roll makes every run of the same task different.
\\Match the verification to the
diff --git a/src/prompt_text.zig b/src/prompt_text.zig
index 75db78e9..bdd8fb80 100644
--- a/src/prompt_text.zig
+++ b/src/prompt_text.zig
@@ -208,7 +208,17 @@ pub const work_note =
\\blocks you, ask with ask_user (the choices in options); otherwise decide
\\and go. Never end a turn with a menu of options written in prose: the
\\harness renders ask_user options as a numbered picker and blocks for the
- \\answer, and a menu in prose does neither. When a task names files or
+ \\answer, and a menu in prose does neither. This applies to text questions,
+ \\not image requests: do not ask for screenshots or images through ask_user
+ \\unless the active interface explicitly supports attachments in question
+ \\replies. Backend vision support does not establish that UI capability.
+ \\If support is absent or unknown and an image is essential, use yield_turn
+ \\to explain that this turn is stopping so the user can attach it to the
+ \\next prompt. No ask_user or permission to pause: yield_turn stops even
+ \\with open work or an unmet verifier. It preserves the conversation and
+ \\unfinished checklist without claiming completion. Finish independent
+ \\authorized work first; do not ask the user to stop the harness for you.
+ \\When a task names files or
\\failing tests, use the named target directly instead of probing unrelated
\\indexes first; that dice roll makes every run of the same task different.
\\Match the verification to the
diff --git a/src/schema.zig b/src/schema.zig
index e4936f11..2abafcb7 100644
--- a/src/schema.zig
+++ b/src/schema.zig
@@ -124,14 +124,14 @@ const meta_specs = [_]ToolSpec{
.{ .name = "note_constraint", .desc = "Record an explicit project-wide user rule in this project's playbook (.graff/playbook.jsonl). Do not call for temporary, task/session-limited, or ambiguous steering; follow that locally or ask before persisting. Durable intent must be clear. Pass scope=project and copy text verbatim from the current user message without widening qualifiers. The visible result includes scope, origin, and text plus /never removal guidance. Project records survive compaction and future sessions. Append-only: only the user can retire one with /never rm <id-or-text> (REPL, TUI, or ACP) or an explicit override. Duplicates are harmless.", .schema = "{\"type\": \"object\", \"properties\": {\"text\": {\"type\": \"string\", \"description\": \"Exact verbatim project-wide constraint from the current user message\"}, \"scope\": {\"type\": \"string\", \"enum\": [\"project\"], \"description\": \"Durable scope; local steering must not be recorded\"}}, \"required\": [\"text\", \"scope\"]}" },
.{
.name = "ask_user",
- .desc = "Ask the human a question and wait for their reply (typed text and/or pasted images). Images reach you as vision blocks on the next request, same as a normal prompt. Call it whenever the next step depends on the user's choice — a decision between approaches, a clarification, or missing information — and put the choices in options: the harness renders them as a numbered picker and blocks for the answer. Ending the turn with a menu written in prose does neither.",
+ .desc = "Ask the human a question and wait for typed text or an option selection. Do not request screenshots or images here unless the active interface explicitly supports attachments in question replies; backend vision support alone is not enough. If that support is absent or unknown and an image is essential, use yield_turn to explain the next-prompt attachment handoff and stop without calling ask_user. Do not ask for permission to pause. Keep the conversation open and do not claim the task is complete. For text questions, put choices in options: the harness renders a numbered picker and blocks for the answer. Ending the turn with a menu written in prose does neither.",
.schema =
\\{"type": "object", "properties": {"question": {"type": "string", "description": "The question to ask the user"}, "options": {"type": "array", "items": {"type": "string"}, "description": "Optional suggested answers, shown numbered"}}, "required": ["question"]}
,
},
.{
.name = "attempt_completion",
- .desc = "Signal that the task is complete. Put the complete final answer to the user only in the result field; do not repeat it in accompanying prose. In strict mode this is the only way to end a turn. Completing also closes the standing /goal; if its checklist still has open items you will be asked once to finish or confirm.",
+ .desc = "Signal that the task is complete. Put your final answer to the user in the result field. In strict mode use this for completed tasks; use yield_turn instead to stop for missing user input without claiming completion. Completing also closes the standing /goal; if its checklist still has open items you will be asked once to finish or confirm.",
.schema =
\\{"type": "object", "properties": {"result": {"type": "string", "description": "Final answer to present to the user"}}, "required": ["result"]}
,
@@ -167,7 +167,7 @@ const learn_candidate_spec = ToolSpec{
const peer_spec = ToolSpec{ .name = peer_channel.tool_name, .desc = peer_channel.tool_desc, .schema = peer_channel.tool_schema };
const workspace_spec = ToolSpec{ .name = workspace_switch.tool_name, .desc = workspace_switch.tool_desc, .schema = workspace_switch.tool_schema };
-pub const root_specs = base_specs ++ meta_specs ++ [_]ToolSpec{ subagent_spec, workflow_spec, agent_output_spec, agent_message_spec, @import("schema_agents.zig").subagent_resume_spec, learn_candidate_spec, peer_spec, workspace_spec };
+pub const root_specs = base_specs ++ meta_specs ++ [_]ToolSpec{ subagent_spec, workflow_spec, agent_output_spec, agent_message_spec, @import("schema_agents.zig").subagent_resume_spec, learn_candidate_spec, peer_spec, workspace_spec, @import("turn_handoff.zig").spec };
/// The root catalog minus the named optional entries, built once at compile
/// time. The length check is the guard: each name must match EXACTLY one
/// spec, so a rename or a duplicated entry is a compile error rather than a
@@ -188,7 +188,7 @@ const root_specs_without_clock = rootSpecsWithout(&.{"clock_sleep"});
const root_specs_without_learning = rootSpecsWithout(&.{"learn_candidate"});
const root_specs_without_optional = rootSpecsWithout(&.{ "clock_sleep", "learn_candidate" });
-pub const meta_names = [_][]const u8{ "todo_write", "todo_read", "ask_user", "eval", "attempt_completion", "clock_sleep", "note_constraint", mcp_schema_gate.tool_name, mcp_select.search_name, mcp_select.select_name, peer_channel.tool_name, workspace_switch.tool_name };
+pub const meta_names = [_][]const u8{ "todo_write", "todo_read", "ask_user", "eval", "attempt_completion", "yield_turn", "clock_sleep", "note_constraint", mcp_schema_gate.tool_name, mcp_select.search_name, mcp_select.select_name, peer_channel.tool_name, workspace_switch.tool_name };
pub fn isMetaName(name: []const u8) bool {
for (meta_names) |m| if (std.mem.eql(u8, name, m)) return true;
diff --git a/src/tool_schema_tests.zig b/src/tool_schema_tests.zig
index 634ef2ff..8eb606b2 100644
--- a/src/tool_schema_tests.zig
+++ b/src/tool_schema_tests.zig
@@ -464,6 +464,36 @@ test "subagent desc: Codex sidecar rules, no routing essay on the catalog prefix
try std.testing.expect(found);
}
+test "ask_user (#1531): catalogs require reply attachment capability and explain next-prompt handoff" {
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ for ([_]Provider.Kind{ .anthropic, .openai, .responses, .interactions }) |kind| {
+ const catalog = try schema.renderRootTools(arena, kind, &schema.root_specs, &.{});
+ const parsed = try std.json.parseFromSliceLeaky(Value, arena, catalog, .{});
+ var found = false;
+ for (parsed.array.items) |tool| {
+ const obj = if (tool.object.get("function")) |f| f.object else tool.object;
+ if (!std.mem.eql(u8, obj.get("name").?.string, "ask_user")) continue;
+ found = true;
+ const desc = obj.get("description").?.string;
+ try testing.expect(std.mem.indexOf(u8, desc, "explicitly supports attachments in question replies") != null);
+ try testing.expect(std.mem.indexOf(u8, desc, "absent or unknown") != null);
+ try testing.expect(std.mem.indexOf(u8, desc, "next-prompt attachment handoff") != null);
+ try testing.expect(std.mem.indexOf(u8, desc, "use yield_turn") != null);
+ try testing.expect(std.mem.indexOf(u8, desc, "without calling ask_user") != null);
+ try testing.expect(std.mem.indexOf(u8, desc, "do not claim the task is complete") != null);
+ try testing.expect(std.mem.indexOf(u8, desc, "typed text and/or pasted images") == null);
+ }
+ try testing.expect(found);
+ }
+ try testing.expect(schema.isMetaName("yield_turn"));
+ try testing.expect(std.mem.indexOf(u8, schema.tools_openai_sub, "yield_turn") == null);
+ for (schema.root_specs) |t| if (std.mem.eql(u8, t.name, "attempt_completion")) {
+ try testing.expect(std.mem.indexOf(u8, t.desc, "use yield_turn instead") != null);
+ };
+}
+
test "codedb schema exposes per-call local_only (#765)" {
var found = false;
for (schema.root_specs) |t| if (std.mem.eql(u8, t.name, "codedb")) {
diff --git a/src/turn_handoff.zig b/src/turn_handoff.zig
new file mode 100644
index 00000000..ced79228
--- /dev/null
+++ b/src/turn_handoff.zig
@@ -0,0 +1,46 @@
+//! Explicit non-completing turn boundary for missing user input (#1531).
+//! No question/confirmation, verifier bypass claim, or durable goal transition.
+
+const std = @import("std");
+const Agent = @import("agent.zig").Agent;
+const tools = @import("tools.zig");
+
+pub const tool_name = "yield_turn";
+pub const spec: @import("schema.zig").ToolSpec = .{
+ .name = tool_name,
+ .desc = "End the current turn without completing the task or closing the conversation. Call alone after finishing independent authorized work when you need input on the user's next prompt, especially a screenshot that a question dialog cannot accept, or when the user asks to stop. Put the explanation and needed next-prompt input in message. No permission to pause is required. Stops open-work retries and autonomous continuation even with unfinished todos or an unmet verifier; preserves goals, checklist statuses, and verification state. Never use attempt_completion or mark unfinished work done for this handoff.",
+ .schema =
+ \\{"type": "object", "properties": {"message": {"type": "string", "description": "Explain why this turn is stopping and what input is needed on the next prompt"}}, "required": ["message"]}
+ ,
+};
+
+pub fn rejectMixedBatch(self: *Agent, calls: []const tools.ToolCall, results: []tools.ExecResult) !bool {
+ if (calls.len <= 1) return false;
+ for (calls) |call| if (std.mem.eql(u8, call.name, tool_name)) {
+ const text = "yield_turn must run alone; this batch was rejected";
+ for (calls, results) |c, *r| {
+ self.emitToolRejected(c, "handoff_boundary", text);
+ r.* = .{ .text = text, .is_error = true };
+ }
+ return true;
+ };
+ return false;
+}
+
+pub fn handle(self: *Agent, call: tools.ToolCall) !tools.ExecResult {
+ if (self.sub) return .{ .text = "yield_turn is root-only; return your blocker to the parent", .is_error = true };
+ const obj = tools.json_args.object(call.input) orelse return invalid();
+ const raw = tools.json_args.str(obj, "message") orelse return invalid();
+ if (std.mem.trim(u8, raw, " \t\r\n").len == 0) return invalid();
+ const message = try @import("cite_markup.zig").dupe(self.arena, raw);
+ if (@import("main.zig").json_mode) {
+ self.emit(.{ .type = "text", .text = message });
+ } else try self.say("{s}\n", .{message});
+ self.yielded = message;
+ @import("peer_idle.zig").noteHandoff();
+ return .{ .text = "turn yielded; task remains unfinished and conversation stays open", .is_error = false };
+}
+
+fn invalid() tools.ExecResult {
+ return .{ .text = "yield_turn requires a nonempty message explaining the handoff", .is_error = true };
+}