langchain-agentx-python 2.4.7__tar.gz → 2.4.8__tar.gz

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 2.4.7
+Version: 2.4.8
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "2.4.7"
+__version__ = "2.4.8"
 
 from .mcp.call import McpToolCaller
 from .mcp.client_manager import McpClientManager, McpConnectedClient

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/loop/graph/factory.py

@@ -1593,13 +1593,25 @@ class LoopGraphBuilder:
             patch["compaction_pipeline_meta"] = meta
         meta["compact_progress"] = progress_events
 
+    def _clear_file_reads_after_message_compaction(self, patch: dict[str, Any]) -> None:
+        """消息被 compaction 改写后清空 last_read（对齐 CC ``readFileState.clear()``）。
+
+        防止 Read dedup 返回 file_unchanged 却断言「内容仍在本会话」（A2）。
+        """
+        if "messages" not in patch:
+            return
+        store = getattr(self, "_session_store", None)
+        clearer = getattr(store, "clear_file_read_state", None)
+        if callable(clearer):
+            clearer()
+
     def _apply_prune_and_compress(self, state: dict[str, Any]) -> dict[str, Any]:
         if self._session_memory_compact_bridge is not None:
             compacted_messages = self._session_memory_compact_bridge.try_compact(
                 list(state.get("messages") or [])
             )
             if compacted_messages is not None:
-                return {
+                patch = {
                     "messages": compacted_messages,
                     "collapse_retry_available": True,
                     "compaction_pipeline_meta": {
@@ -1607,10 +1619,13 @@ class LoopGraphBuilder:
                         "session_memory_compaction": "applied",
                     },
                 }
+                self._clear_file_reads_after_message_compaction(patch)
+                return patch
         patch = self._loop_context_compaction.run(state, model=self._model)
         compaction_meta = patch.get("compaction_pipeline_meta")
         if isinstance(compaction_meta, dict):
             patch["collapse_retry_available"] = bool(compaction_meta.get("tokens_freed_sum", 0))
+        self._clear_file_reads_after_message_compaction(patch)
         return patch
 
     async def _apply_prune_and_compress_async(self, state: dict[str, Any]) -> dict[str, Any]:
@@ -1619,7 +1634,7 @@ class LoopGraphBuilder:
                 list(state.get("messages") or [])
             )
             if compacted_messages is not None:
-                return {
+                patch = {
                     "messages": compacted_messages,
                     "collapse_retry_available": True,
                     "compaction_pipeline_meta": {
@@ -1627,6 +1642,8 @@ class LoopGraphBuilder:
                         "session_memory_compaction": "applied",
                     },
                 }
+                self._clear_file_reads_after_message_compaction(patch)
+                return patch
         progress_events: list[dict[str, Any]] = []
         seen_progress = False
 
@@ -1660,6 +1677,7 @@ class LoopGraphBuilder:
         compaction_meta = patch.get("compaction_pipeline_meta")
         if isinstance(compaction_meta, dict):
             patch["collapse_retry_available"] = bool(compaction_meta.get("tokens_freed_sum", 0))
+        self._clear_file_reads_after_message_compaction(patch)
         return patch
 
     def _run_prune_and_compress_with_trace(self, state: dict[str, Any]) -> dict[str, Any]:

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/loop/subagent/context.py

@@ -117,6 +117,8 @@ class SubagentContext:
     loop_compilation_context: LoopCompilationContext | None = None
     can_use_tool: Callable[[str, dict[str, Any]], bool] | None = None
     register_transcript: bool = True
+    transcript_store: Any | None = None
+    """可选落盘后端；None → runner 使用 InMemoryTranscriptStore。Workflow 注入 workflows/<runId>/。"""
 
     # Thinking 控制字段（request-side 生成意图，与 UI 展示意图分离）
     thinking_generation_enabled: bool = True  # 子代理 request-side thinking 生成开关

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/loop/subagent/runner.py

@@ -864,7 +864,7 @@ async def _run_subagent_body(
     resolved_model = _resolve_subagent_model(ctx, model)
 
     if ctx.register_transcript and ctx.agent_id:
-        store = InMemoryTranscriptStore()
+        store = getattr(ctx, "transcript_store", None) or InMemoryTranscriptStore()
         transcript: SubagentTranscriptManager | NoOpTranscriptManager = SubagentTranscriptManager(
             store=store,
             agent_id=ctx.agent_id,

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/tool_runtime/errors.py

@@ -20,7 +20,6 @@ from typing import Literal
 
 from .limits import ERROR_TRUNCATE_HALF, ERROR_TRUNCATE_THRESHOLD
 from .messages import (
-    DENIAL_WORKAROUND_GUIDANCE,
     INTERRUPT_MESSAGE_FOR_TOOL_USE,
     auto_reject_message,
 )
@@ -68,10 +67,6 @@ def truncate_error_text(text: str) -> str:
     return _DEFAULT_TRUNCATOR.truncate(text)
 
 
-def _llm_summary_already_formatted(message: str) -> bool:
-    return "STOP and explain" in message or DENIAL_WORKAROUND_GUIDANCE in message
-
-
 # ---------------------------------------------------------------------------
 # 框架级异常类型
 # ---------------------------------------------------------------------------
@@ -236,12 +231,13 @@ def blocked_envelope(
     """
     构造 status="blocked" 的 ToolResultEnvelope。
 
-    check_permissions() 返回 deny 时由 pipeline 调用。
-    模型可见 summary 默认使用 AUTO_REJECT_MESSAGE；L3 已格式化的拒因可经 llm_summary 透传。
+    对齐 CC ``permissionDecision.message → tool_result content``：
+    模型可见 summary 优先使用决策拒因（message / llm_summary）；
+    仅当拒因空时回退 AUTO_REJECT_MESSAGE（与 CC headless 无细文案时一致）。
     """
     if llm_summary is not None:
         summary_text = truncate_error_text(llm_summary)
-    elif _llm_summary_already_formatted(message):
+    elif isinstance(message, str) and message.strip():
         summary_text = truncate_error_text(message)
     else:
         summary_text = truncate_error_text(auto_reject_message(tool_name))

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/tool_runtime/loader.py

@@ -96,10 +96,11 @@ class ToolRuntimeLoader:
         agent_home_segment: str = ".langchain_agentx",
         include_agent: bool = True,
         include_skill: bool = False,
+        include_workflow: bool = False,
         agent_registry: Any | None = None,
     ) -> "ToolRuntimeLoader":
         """
-        注册默认工具集（Read/Grep/Glob/Bash + 可选 Agent/Skill）。
+        注册默认工具集（Read/Grep/Glob/Bash + 可选 Agent/Skill/Workflow）。
 
         向后兼容：在 loader 自身 registry 上注册（单 loop 模式）。
         create_loop_agent 应优先使用 ``spawn_loop_loader`` 获得 per-loop 隔离。
@@ -109,6 +110,7 @@ class ToolRuntimeLoader:
             agent_home_segment: agent home 子目录名（如 .claude、.cursor）
             include_agent: 是否包含 Agent 工具
             include_skill: 是否包含 Skill 工具
+            include_workflow: 是否包含 Workflow 工具（默认 False，结项前不进默认池）
             agent_registry: 可选的自定义 agent 注册表
         """
         loop = self.spawn_loop_loader(
@@ -118,6 +120,7 @@ class ToolRuntimeLoader:
         loop.register_default_tools(
             include_agent=include_agent,
             include_skill=include_skill,
+            include_workflow=include_workflow,
             agent_registry=agent_registry,
         )
         for tool in loop.registry.list():

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/tool_runtime/loop_loader.py

@@ -86,6 +86,7 @@ class LoopLoader:
         *,
         include_agent: bool = True,
         include_skill: bool = False,
+        include_workflow: bool = False,
         agent_registry: Any | None = None,
     ) -> "LoopLoader":
         from pathlib import Path
@@ -198,6 +199,11 @@ class LoopLoader:
                 )
             )
 
+        if include_workflow:
+            from langchain_agentx.tools.workflow import WorkflowRuntimeTool
+
+            self.register(WorkflowRuntimeTool(config=cfg))
+
         return self
 
     def attach_mcp(

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/tool_runtime/session_store.py

@@ -163,6 +163,14 @@ class AgentSessionStore:
         """用与 LangGraph state 中 last_read 条目同构的 dict 覆盖该路径。"""
         self._file_read_state[path] = FileReadRecord.from_bridge_dict(path, entry)
 
+    def clear_file_read_state(self) -> None:
+        """清空文件读缓存（对齐 CC ``readFileState.clear()`` on compact）。
+
+        compaction 蒸发消息后若不清理，Read dedup 会返回 ``file_unchanged`` stub
+        却断言「内容仍在本会话」（BUG-20261107-28 A2）。
+        """
+        self._file_read_state.clear()
+
     def replace_all_file_reads_from_bridge_map(self, data: dict[str, Any]) -> None:
         """整体替换文件读映射（对应 ToolStateBridge.set_last_read_map）。"""
         self._file_read_state.clear()

{langchain-agentx-python-2.4.7 → langchain-agentx-python-2.4.8}/langchain_agentx/tools/registry_names.py

@@ -44,6 +44,7 @@ TaskUpdate = "TaskUpdate"
 WebSearch = "WebSearch"
 WebFetch = "WebFetch"
 Agent = "Agent"
+Workflow = "Workflow"
 
 # CC SAFE_YOLO 中尚未在 register_default_tools 注册的工具（白名单可预留）
 CC_ALLOWLIST_UNREGISTERED: frozenset[str] = frozenset({
@@ -120,6 +121,7 @@ class ToolNameRegistry:
         *,
         include_agent: bool = True,
         include_skill: bool = False,
+        include_workflow: bool = False,
     ) -> frozenset[str]:
         """register_default_tools 目标注册名集（CC PascalCase）。"""
         names = {
@@ -143,6 +145,8 @@ class ToolNameRegistry:
             names.add(Agent)
         if include_skill:
             names.add(Skill)
+        if include_workflow:
+            names.add(Workflow)
         return frozenset(names)
 
     @staticmethod
@@ -162,11 +166,13 @@ class ToolNameRegistry:
         *,
         include_agent: bool = True,
         include_skill: bool = False,
+        include_workflow: bool = False,
     ) -> frozenset[str]:
         """白名单中已注册工具子集（排除 TodoWrite / TaskStop / TaskOutput）。"""
         registered = ToolNameRegistry.cc_default_registered_names(
             include_agent=include_agent,
             include_skill=include_skill,
+            include_workflow=include_workflow,
         )
         return ToolNameRegistry.cc_auto_mode_allowlist_full() & registered
 
@@ -221,5 +227,6 @@ __all__ = [
     "ToolNameRegistry",
     "WebFetch",
     "WebSearch",
+    "Workflow",
     "Write",
 ]

langchain-agentx-python-2.4.8/langchain_agentx/tools/workflow/__init__.py

@@ -0,0 +1,18 @@
+"""
+tools/workflow — CC 对齐 Workflow RuntimeTool 包根
+
+职责：Python 脚本编排 + 私有 hooks；工人经 kernel_bridge → run_subagent。
+链路位置：可选挂入默认工具集（include_workflow=False 直至结项）。
+当前裁剪：Phase 3 门面已导出；真内核工人在 Phase 4。
+"""
+
+from langchain_agentx.tools.workflow.constants import WORKFLOW_TOOL_NAME
+from langchain_agentx.tools.workflow.runtime import ScriptGate, TrustedWorkflowExecutor
+from langchain_agentx.tools.workflow.tool import WorkflowRuntimeTool
+
+__all__ = [
+    "WORKFLOW_TOOL_NAME",
+    "ScriptGate",
+    "TrustedWorkflowExecutor",
+    "WorkflowRuntimeTool",
+]

langchain-agentx-python-2.4.8/langchain_agentx/tools/workflow/agents/__init__.py

@@ -0,0 +1,14 @@
+"""tools/workflow/agents — 工人组装层（L4）。"""
+
+from langchain_agentx.tools.workflow.agents.definition import register_workflow_subagent
+from langchain_agentx.tools.workflow.agents.kernel_bridge import KernelBridge
+from langchain_agentx.tools.workflow.agents.ports import FakeWorkflowWorker, WorkflowWorkerPort
+from langchain_agentx.tools.workflow.agents.worker_runner import WorkflowWorkerRunner
+
+__all__ = [
+    "FakeWorkflowWorker",
+    "KernelBridge",
+    "WorkflowWorkerPort",
+    "WorkflowWorkerRunner",
+    "register_workflow_subagent",
+]

langchain-agentx-python-2.4.8/langchain_agentx/tools/workflow/agents/definition.py

@@ -0,0 +1,38 @@
+"""
+tools/workflow/agents/definition.py — 注册 workflow-subagent 到统一定义表
+
+职责：E1 — SubagentConfig 写入 get_global_registry()；默认 acceptEdits。
+链路位置：包加载或 Backend 启动时 register_workflow_subagent()。
+当前裁剪：不 import AgentRuntimeTool；仅注册侧依赖 registry。
+"""
+
+from __future__ import annotations
+
+from langchain_agentx.tools.agent.registry.config import SubagentConfig
+from langchain_agentx.tools.agent.registry.registry import SubagentRegistry, get_global_registry
+from langchain_agentx.tools.workflow.agents.prompt import workflow_subagent_system_prompt
+from langchain_agentx.tools.workflow.agents.toolset import filter_workflow_worker_tools
+from langchain_agentx.tools.workflow.constants import WORKFLOW_SUBAGENT_AGENT_TYPE
+
+
+def build_workflow_subagent_config() -> SubagentConfig:
+    return SubagentConfig(
+        name=WORKFLOW_SUBAGENT_AGENT_TYPE,
+        description="Internal subagent for workflow script orchestration.",
+        when_to_use="Internal subagent for workflow script orchestration.",
+        system_prompt_factory=lambda: workflow_subagent_system_prompt(has_schema=False),
+        tool_filter=filter_workflow_worker_tools,
+        tools_description="All tools except SendUserMessage/Agent/Workflow",
+        allow_async=False,
+        is_builtin=True,
+        permission_mode="acceptEdits",
+        tags={"workflow", "internal"},
+    )
+
+
+def register_workflow_subagent(registry: SubagentRegistry | None = None) -> SubagentConfig:
+    """幂等注册 workflow-subagent。"""
+    target = registry if registry is not None else get_global_registry()
+    cfg = build_workflow_subagent_config()
+    target.register(cfg)
+    return cfg

langchain-agentx-python-2.4.8/langchain_agentx/tools/workflow/agents/kernel_bridge.py

@@ -0,0 +1,162 @@
+"""
+tools/workflow/agents/kernel_bridge.py — 唯一触碰 run_subagent 的薄封装（E2）
+
+职责：填充 SubagentContext（acceptEdits / prompt / worktree）并调用 run_subagent；
+      工人工具池按父当前表派生（含会话 MCP concat）；transcript 落到 workflows/<runId>/；
+      R1-A：run 前走 hooks pipeline（全局/registered 继承；父 session 槽不复制）。
+链路位置：WorkflowWorkerRunner → KernelBridge → loop.subagent.runner.run_subagent。
+当前裁剪：禁 Orchestrator / AgentRuntimeTool；noop setAppState 语义由不写父 state 体现；
+      不传 allowedTools 替换（继承父权限规则）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Awaitable
+
+from langchain_agentx.loop.runtime.context import SubagentContextOverrides
+from langchain_agentx.loop.runtime.subagent_execution_paths import SubagentExecutionPaths
+from langchain_agentx.loop.subagent.context import create_subagent_context
+from langchain_agentx.loop.subagent.hooks_pipeline import apply_subagent_hooks_pipeline_async
+from langchain_agentx.loop.subagent.runner import run_subagent
+from langchain_agentx.tools.agent.registry.registry import get_global_registry
+from langchain_agentx.tools.workflow.agents.prompt import workflow_subagent_system_prompt
+from langchain_agentx.tools.workflow.agents.tool_pool import assemble_workflow_worker_tool_pool
+from langchain_agentx.tools.workflow.agents.transcript_store import WorkflowRunTranscriptStore
+from langchain_agentx.tools.workflow.constants import WORKFLOW_SUBAGENT_AGENT_TYPE
+from langchain_agentx.tools.workflow.engine.paths import RunPathFactory
+from langchain_agentx.tools.workflow.models import AgentRunResult, AgentSpec
+from langchain_agentx.workspace import resolve_agent_state_config
+
+
+RunSubagentFn = Callable[..., Awaitable[Any]]
+
+
+@dataclass
+class KernelBridgeRequest:
+    parent_ctx: Any
+    loader: Any
+    spec: AgentSpec
+    agent_index: int
+    run_id: str
+    workflow_name: str | None = None
+    model: Any | None = None
+    permission_mode: str = "acceptEdits"
+
+
+class KernelBridge:
+    """直调 run_subagent；可注入 run_fn 供单测 mock。"""
+
+    def __init__(self, *, run_fn: RunSubagentFn | None = None) -> None:
+        self._run_fn = run_fn or run_subagent
+
+    async def run(self, req: KernelBridgeRequest) -> AgentRunResult:
+        has_schema = req.spec.schema is not None
+        system_prompt = workflow_subagent_system_prompt(has_schema=has_schema)
+        agent_type = req.spec.agent_type or WORKFLOW_SUBAGENT_AGENT_TYPE
+        isolation = req.spec.isolation or "none"
+
+        pool = assemble_workflow_worker_tool_pool(
+            parent_ctx=req.parent_ctx,
+            loader=req.loader,
+            headless=True,
+        )
+
+        overrides = SubagentContextOverrides(
+            isolation=isolation,
+            cwd=None,
+        )
+        path_prep = SubagentExecutionPaths.prepare(
+            parent_ctx=req.parent_ctx,
+            overrides=overrides,
+        )
+        parent_depth = int(getattr(req.parent_ctx, "agent_depth", 0) or 0)
+        spawn_depth = parent_depth + 1
+        ctx = create_subagent_context(
+            parent_ctx=req.parent_ctx,
+            task=req.spec.prompt,
+            subagent_type=agent_type,
+            system_prompt=system_prompt,
+            isolation=isolation,
+            path_prep=path_prep,
+            permission_mode=req.permission_mode,
+            agent_depth=spawn_depth,
+            is_async=False,
+            model=req.model,
+            available_tools=pool.tools,
+            inherit_hooks=True,
+        )
+        # R1-A（bug1.md）：与普通 Agent/fork 共用 hooks 解析——全局 PreToolUse 仍跑；
+        # 父 session 槽不经 compose（不复制 hooks_snapshot）；自挂走 definition frontmatter。
+        await apply_subagent_hooks_pipeline_async(
+            ctx,
+            req.parent_ctx,
+            subagent_type=agent_type,
+            subagent_config=self._resolve_subagent_config(agent_type),
+        )
+        # 扩展字段 + 落盘 store（runner 消费 transcript_store / workflow_run_id）
+        setattr(ctx, "workflow_run_id", req.run_id)
+        if req.workflow_name:
+            setattr(ctx, "workflow_name", req.workflow_name)
+        store = self._build_transcript_store(
+            req=req,
+            agent_type=agent_type,
+            spawn_depth=spawn_depth,
+            agent_id=getattr(ctx, "agent_id", None),
+        )
+        if store is not None:
+            ctx.transcript_store = store
+
+        result = await self._run_fn(
+            ctx,
+            pool.loader,
+            model=req.model or getattr(ctx, "model", None),
+            allowed_tool_names=set(pool.allowed_tool_names),
+        )
+        content = getattr(result, "content", "") or ""
+        status = getattr(result, "status", "completed")
+        if status == "error":
+            raise RuntimeError(getattr(result, "error_message", None) or content or "subagent error")
+        tokens = 0
+        trace = getattr(result, "execution_trace", None)
+        if trace is not None:
+            tokens = int(getattr(trace, "total_tokens", 0) or 0)
+        tool_calls = int(getattr(result, "total_steps", 0) or 0)
+        return AgentRunResult(value=content, tokens=tokens, tool_calls=tool_calls)
+
+    @staticmethod
+    def _resolve_subagent_config(agent_type: str) -> Any | None:
+        """统一定义表项（含可选 frontmatter hooks）；缺省不影响继承 compose。"""
+        try:
+            return get_global_registry().get(agent_type)
+        except KeyError:
+            return None
+
+    @staticmethod
+    def _build_transcript_store(
+        *,
+        req: KernelBridgeRequest,
+        agent_type: str,
+        spawn_depth: int,
+        agent_id: str | None,
+    ) -> WorkflowRunTranscriptStore | None:
+        workspace_root = getattr(req.parent_ctx, "workspace_root", None) or ""
+        if not str(workspace_root).strip():
+            return None
+        agent_home = (
+            getattr(req.parent_ctx, "agent_home_segment", None) or ".langchain_agentx"
+        )
+        cfg = resolve_agent_state_config(
+            workspace_root=str(workspace_root),
+            agent_home_segment=str(agent_home),
+        )
+        paths = RunPathFactory(cfg).for_run(req.run_id)
+        store = WorkflowRunTranscriptStore(
+            paths.transcript_dir,
+            run_id=req.run_id,
+            agent_type=agent_type,
+            spawn_depth=spawn_depth,
+            workflow_name=req.workflow_name,
+        )
+        store.write_meta(agent_id=agent_id if isinstance(agent_id, str) else None)
+        return store

langchain-agentx-python-2.4.8/langchain_agentx/tools/workflow/agents/ports.py

@@ -0,0 +1,31 @@
+"""
+tools/workflow/agents/ports.py — WorkflowWorkerPort Protocol
+
+职责：hooks → 工人执行的唯一出口接口（Phase 1 仅接口 + 假实现）。
+链路位置：engine.hooks 依赖本 Protocol；真实现见 worker_runner（P4）。
+当前裁剪：不含 journal/cache。
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from langchain_agentx.tools.workflow.models import AgentRunResult, AgentSpec
+
+
+@runtime_checkable
+class WorkflowWorkerPort(Protocol):
+    async def run(self, spec: AgentSpec, agent_index: int) -> AgentRunResult:
+        """执行一个工人；抛出异常由 hooks 决定是否变 null 槽。"""
+
+
+class FakeWorkflowWorker:
+    """固定返回字符串的假工人（Phase 1/2）。"""
+
+    def __init__(self, reply: str = "fake-worker-ok") -> None:
+        self.reply = reply
+        self.calls: list[AgentSpec] = []
+
+    async def run(self, spec: AgentSpec, agent_index: int) -> AgentRunResult:
+        self.calls.append(spec)
+        return AgentRunResult(value=f"{self.reply}:{agent_index}:{spec.prompt[:32]}")

langchain-agentx-python-2.4.8/langchain_agentx/tools/workflow/agents/prompt.py

@@ -0,0 +1,35 @@
+"""
+tools/workflow/agents/prompt.py — workflow-subagent 系统提示（e9g / n9g）
+
+职责：无 schema / 有 schema 两套逐字提示。
+链路位置：definition / KernelBridge 组装。
+当前裁剪：不实现 wVr 后置注释器。
+"""
+
+from __future__ import annotations
+
+STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput"
+
+# EVIDENCE: hooks-impl.txt e9g — verbatim (CC workflowSubagent.ts).
+PLAIN_RETURN_SYSTEM_PROMPT = """\
+You are a subagent spawned by a workflow orchestration script. Use the tools available to complete the task.
+
+CRITICAL: Your final text response is returned **verbatim** as a string to the calling script — it is your return value, not a message to a human.
+- Output the literal result (data, JSON, text). Do NOT output confirmations like "Done." or "Sent."
+- If asked for JSON, return ONLY the raw JSON — no code fences, no prose, no markdown.
+- Do NOT use SendUserMessage to deliver your answer. Put your answer in your final text response.
+- Be concise. The script will parse your output."""
+
+# EVIDENCE: hooks-impl.txt n9g — verbatim.
+STRUCTURED_RETURN_SYSTEM_PROMPT = f"""\
+You are a subagent spawned by a workflow orchestration script. Use the tools available to complete the task.
+
+CRITICAL: You MUST call the {STRUCTURED_OUTPUT_TOOL_NAME} tool exactly once to return your final answer. The tool's input schema defines the required shape.
+- Do your work (Read files, run commands, etc.), then call {STRUCTURED_OUTPUT_TOOL_NAME} with your answer.
+- Do NOT put your answer in a text response. The script reads ONLY the {STRUCTURED_OUTPUT_TOOL_NAME} tool call.
+- If the schema validation fails, read the error and call {STRUCTURED_OUTPUT_TOOL_NAME} again with a corrected shape.
+- After calling {STRUCTURED_OUTPUT_TOOL_NAME} successfully, end your turn. No acknowledgment needed."""
+
+
+def workflow_subagent_system_prompt(*, has_schema: bool) -> str:
+    return STRUCTURED_RETURN_SYSTEM_PROMPT if has_schema else PLAIN_RETURN_SYSTEM_PROMPT