langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/prompt/compact.py

@@ -0,0 +1,408 @@
+"""上下文压缩提示词（Compact Prompt）。
+
+对齐 Claude Code `services/compact/prompt.ts`，提供：
+- 压缩提示词模板（全量 / 部分 / up_to 三种变体）
+- 工具调用抑制机制（NO_TOOLS_PREAMBLE / TRAILER）
+- 摘要格式化（format_compact_summary）
+- 用户续写消息包装（get_compact_user_summary_message）
+
+设计要点：
+- 多段提示的用途：NO_TOOLS_PREAMBLE + 主体模板（BASE / PARTIAL / PARTIAL_UP_TO）
+  + 可选 Additional Instructions + NO_TOOLS_TRAILER 拼成一次 compact 调用的 system 侧全文
+- partial 方向：direction="from" 对应「只总结近期片段」；"up_to" 对应「总结置于续写会话开头、
+  之后还有未展示的新消息」的措辞与第 8/9 节标题差异
+- 后处理：format_compact_summary 去掉 <analysis>，把 <summary> 展平为 Summary:\\n...，
+  再交给 get_compact_user_summary_message 包一层用户可见续写说明
+
+注意：
+- 本模块无 I/O；与 CompactionSettings 解耦，供 settings 默认值与 AutocompactStage 后处理引用
+- 从 loop/context/prompt.py 迁移到此处，统一提示词管理
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+PartialCompactDirection = Literal["from", "up_to"]
+
+# Autocompact LLM 调用选哪套「主体模板」（对齐 compact.ts 全量 vs partial / up_to）
+AutocompactLlmPromptKind = Literal["full", "partial_from", "partial_up_to"]
+
+# Aggressive no-tools preamble (see TS 注释：maxTurns:1 时避免无效 tool 调用浪费轮次)
+NO_TOOLS_PREAMBLE = """CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
+
+- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
+- You already have all the context you need in the conversation above.
+- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
+- Your entire response must be plain text: an <analysis> block followed by a <summary> block.
+
+"""
+
+DETAILED_ANALYSIS_INSTRUCTION_BASE = """Before providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts and ensure you've covered all necessary points. In your analysis process:
+
+1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify:
+   - The user's explicit requests and intents
+   - Your approach to addressing the user's requests
+   - Key decisions, technical concepts and code patterns
+   - Specific details like:
+     - file names
+     - full code snippets
+     - function signatures
+     - file edits
+   - Errors that you ran into and how you fixed them
+   - Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+2. Double-check for technical accuracy and completeness, addressing each required element thoroughly."""
+
+DETAILED_ANALYSIS_INSTRUCTION_PARTIAL = """Before providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts and ensure you've covered all necessary points. In your analysis process:
+
+1. Analyze the recent messages chronologically. For each section thoroughly identify:
+   - The user's explicit requests and intents
+   - Your approach to addressing the user's requests
+   - Key decisions, technical concepts and code patterns
+   - Specific details like:
+     - file names
+     - full code snippets
+     - function signatures
+     - file edits
+   - Errors that you ran into and how you fixed them
+   - Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+2. Double-check for technical accuracy and completeness, addressing each required element thoroughly."""
+
+BASE_COMPACT_PROMPT = f"""Your task is to create a detailed summary of the conversation so far, paying close attention to the user's explicit requests and your previous actions.
+This summary should be thorough in capturing technical details, code patterns, and architectural decisions that would be essential for continuing development work without losing context.
+
+{DETAILED_ANALYSIS_INSTRUCTION_BASE}
+
+Your summary should include the following sections:
+
+1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
+2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
+3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Pay special attention to the most recent messages and include full code snippets where applicable and include a summary of why this file read or edit is important.
+4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
+6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users' feedback and changing intent.
+7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
+8. Current Work: Describe in detail precisely what was being worked on immediately before this summary request, paying special attention to the most recent messages from both user and assistant. Include file names and code snippets where applicable.
+9. Optional Next Step: List the next step that you will take that is related to the most recent work you were doing. IMPORTANT: ensure that this step is DIRECTLY in line with the user's most recent explicit requests, and the task you were working on immediately before this summary request. If your last task was concluded, then only list next steps if they are explicitly in line with the users request. Do not start on tangential requests or really old requests that were already completed without confirming with the user first.
+                       If there is a next step, include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off. This should be verbatim to ensure there's no drift in task interpretation.
+
+Here's an example of how your output should be structured:
+
+<example>
+<analysis>
+[Your thought process, ensuring all points are covered thoroughly and accurately]
+</analysis>
+
+<summary>
+1. Primary Request and Intent:
+   [Detailed description]
+
+2. Key Technical Concepts:
+   - [Concept 1]
+   - [Concept 2]
+   - [...]
+
+3. Files and Code Sections:
+   - [File Name 1]
+      - [Summary of why this file is important]
+      - [Summary of the changes made to this file, if any]
+      - [Important Code Snippet]
+   - [File Name 2]
+      - [Important Code Snippet]
+   - [...]
+
+4. Errors and fixes:
+    - [Detailed description of error 1]:
+      - [How you fixed the error]
+      - [User feedback on the error if any]
+    - [...]
+
+5. Problem Solving:
+   [Description of solved problems and ongoing troubleshooting]
+
+6. All user messages:
+    - [Detailed non tool use user message]
+    - [...]
+
+7. Pending Tasks:
+   - [Task 1]
+   - [Task 2]
+   - [...]
+
+8. Current Work:
+   [Precise description of current work]
+
+9. Optional Next Step:
+   [Optional Next step to take]
+
+</summary>
+</example>
+
+Please provide your summary based on the conversation so far, following this structure and ensuring precision and thoroughness in your response.
+
+There may be additional summarization instructions provided in the included context. If so, remember to follow these instructions when creating the above summary. Examples of instructions include:
+<example>
+## Compact Instructions
+When summarizing the conversation focus on typescript code changes and also remember the mistakes you made and how you fixed them.
+</example>
+
+<example>
+# Summary instructions
+When you are using compact - please focus on test output and code changes. Include file reads verbatim.
+</example>
+"""
+
+PARTIAL_COMPACT_PROMPT = f"""Your task is to create a detailed summary of the RECENT portion of the conversation — the messages that follow earlier retained context. The earlier messages are being kept intact and do NOT need to be summarized. Focus your summary on what was discussed, learned, and accomplished in the recent messages only.
+
+{DETAILED_ANALYSIS_INSTRUCTION_PARTIAL}
+
+Your summary should include the following sections:
+
+1. Primary Request and Intent: Capture the user's explicit requests and intents from the recent messages
+2. Key Technical Concepts: List important technical concepts, technologies, and frameworks discussed recently.
+3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Include full code snippets where applicable and include a summary of why this file read or edit is important.
+4. Errors and fixes: List errors encountered and how they were fixed.
+5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
+6. All user messages: List ALL user messages from the recent portion that are not tool results.
+7. Pending Tasks: Outline any pending tasks from the recent messages.
+8. Current Work: Describe precisely what was being worked on immediately before this summary request.
+9. Optional Next Step: List the next step related to the most recent work. Include direct quotes from the most recent conversation.
+
+Here's an example of how your output should be structured:
+
+<example>
+<analysis>
+[Your thought process, ensuring all points are covered thoroughly and accurately]
+</analysis>
+
+<summary>
+1. Primary Request and Intent:
+   [Detailed description]
+
+2. Key Technical Concepts:
+   - [Concept 1]
+   - [Concept 2]
+
+3. Files and Code Sections:
+   - [File Name 1]
+      - [Summary of why this file is important]
+      - [Important Code Snippet]
+
+4. Errors and fixes:
+    - [Error description]:
+      - [How you fixed it]
+
+5. Problem Solving:
+   [Description]
+
+6. All user messages:
+    - [Detailed non tool use user message]
+
+7. Pending Tasks:
+   - [Task 1]
+
+8. Current Work:
+   [Precise description of current work]
+
+9. Optional Next Step:
+   [Optional Next step to take]
+
+</summary>
+</example>
+
+Please provide your summary based on the RECENT messages only (after the retained earlier context), following this structure and ensuring precision and thoroughness in your response.
+"""
+
+PARTIAL_COMPACT_UP_TO_PROMPT = f"""Your task is to create a detailed summary of this conversation. This summary will be placed at the start of a continuing session; newer messages that build on this context will follow after your summary (you do not see them here). Summarize thoroughly so that someone reading only your summary and then the newer messages can fully understand what happened and continue the work.
+
+{DETAILED_ANALYSIS_INSTRUCTION_BASE}
+
+Your summary should include the following sections:
+
+1. Primary Request and Intent: Capture the user's explicit requests and intents in detail
+2. Key Technical Concepts: List important technical concepts, technologies, and frameworks discussed.
+3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Include full code snippets where applicable and include a summary of why this file read or edit is important.
+4. Errors and fixes: List errors encountered and how they were fixed.
+5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
+6. All user messages: List ALL user messages that are not tool results.
+7. Pending Tasks: Outline any pending tasks.
+8. Work Completed: Describe what was accomplished by the end of this portion.
+9. Context for Continuing Work: Summarize any context, decisions, or state that would be needed to understand and continue the work in subsequent messages.
+
+Here's an example of how your output should be structured:
+
+<example>
+<analysis>
+[Your thought process, ensuring all points are covered thoroughly and accurately]
+</analysis>
+
+<summary>
+1. Primary Request and Intent:
+   [Detailed description]
+
+2. Key Technical Concepts:
+   - [Concept 1]
+   - [Concept 2]
+
+3. Files and Code Sections:
+   - [File Name 1]
+      - [Summary of why this file is important]
+      - [Important Code Snippet]
+
+4. Errors and fixes:
+    - [Error description]:
+      - [How you fixed it]
+
+5. Problem Solving:
+   [Description]
+
+6. All user messages:
+    - [Detailed non tool use user message]
+
+7. Pending Tasks:
+   - [Task 1]
+
+8. Work Completed:
+   [Description of what was accomplished]
+
+9. Context for Continuing Work:
+   [Key context, decisions, or state needed to continue the work]
+
+</summary>
+</example>
+
+Please provide your summary following this structure, ensuring precision and thoroughness in your response.
+"""
+
+NO_TOOLS_TRAILER = (
+    "\n\nREMINDER: Do NOT call any tools. Respond with plain text only — "
+    "an <analysis> block followed by a <summary> block. "
+    "Tool calls will be rejected and you will fail the task."
+)
+
+
+def get_partial_compact_prompt(
+    custom_instructions: str | None = None,
+    direction: PartialCompactDirection = "from",
+) -> str:
+    """部分压缩提示词（对齐 getPartialCompactPrompt）。
+
+    Args:
+        custom_instructions: 用户自定义压缩指令（可选）
+        direction: "from" 只总结近期片段，"up_to" 摘要置于续写开头
+    """
+    template = PARTIAL_COMPACT_UP_TO_PROMPT if direction == "up_to" else PARTIAL_COMPACT_PROMPT
+    prompt = NO_TOOLS_PREAMBLE + template
+    if custom_instructions and custom_instructions.strip() != "":
+        prompt += f"\n\nAdditional Instructions:\n{custom_instructions}"
+    prompt += NO_TOOLS_TRAILER
+    return prompt
+
+
+def get_compact_prompt(custom_instructions: str | None = None) -> str:
+    """全量会话紧凑化用的系统侧提示（对齐 getCompactPrompt）。
+
+    Args:
+        custom_instructions: 用户自定义压缩指令（可选）
+    """
+    prompt = NO_TOOLS_PREAMBLE + BASE_COMPACT_PROMPT
+    if custom_instructions and custom_instructions.strip() != "":
+        prompt += f"\n\nAdditional Instructions:\n{custom_instructions}"
+    prompt += NO_TOOLS_TRAILER
+    return prompt
+
+
+def build_autocompact_llm_instruction_prompt(
+    kind: AutocompactLlmPromptKind,
+    custom_instructions: str | None = None,
+) -> str:
+    """按 CC compact.ts 分支选择 getCompactPrompt 或 getPartialCompactPrompt 的完整指令串。
+
+    Args:
+        kind: 压缩类型
+            - "full": 全量 compact，对齐 getCompactPrompt(customInstructions)
+            - "partial_from": 只总结「保留前缀之后的近期」，对齐 getPartialCompactPrompt(..., 'from')
+            - "partial_up_to": 摘要置于续写开头、其后还有未展示消息，对齐 getPartialCompactPrompt(..., 'up_to')
+        custom_instructions: 用户自定义压缩指令（可选）
+    """
+    if kind == "full":
+        return get_compact_prompt(custom_instructions)
+    if kind == "partial_from":
+        return get_partial_compact_prompt(custom_instructions, "from")
+    return get_partial_compact_prompt(custom_instructions, "up_to")
+
+
+def format_compact_summary(summary: str) -> str:
+    """去掉 <analysis>，将 <summary> 展平为 Summary: 前缀（对齐 formatCompactSummary）。
+
+    Args:
+        summary: 模型原始输出（包含 <analysis> 和 <summary> 标签）
+
+    Returns:
+        格式化后的摘要文本
+    """
+    formatted = re.sub(r"<analysis>[\s\S]*?</analysis>", "", summary)
+    m = re.search(r"<summary>([\s\S]*?)</summary>", formatted)
+    if m:
+        content = m.group(1) or ""
+        formatted = re.sub(
+            r"<summary>[\s\S]*?</summary>",
+            f"Summary:\n{content.strip()}",
+            formatted,
+            count=1,
+        )
+    formatted = re.sub(r"\n\n+", "\n\n", formatted)
+    return formatted.strip()
+
+
+def get_compact_user_summary_message(
+    summary: str,
+    suppress_follow_up_questions: bool = False,
+    transcript_path: str | None = None,
+    recent_messages_preserved: bool = False,
+) -> str:
+    """将模型原始输出格式化为「续写会话」用户可见说明（对齐 getCompactUserSummaryMessage）。
+
+    Args:
+        summary: 模型原始输出
+        suppress_follow_up_questions: 是否抑制追问（非交互续写模式）
+        transcript_path: 完整 transcript 文件路径（可选）
+        recent_messages_preserved: 是否保留了最近消息（partial 模式）
+
+    Returns:
+        用户可见的续写说明文本
+    """
+    formatted_summary = format_compact_summary(summary)
+    base_summary = f"""This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.
+
+{formatted_summary}"""
+    if transcript_path:
+        base_summary += (
+            "\n\nIf you need specific details from before compaction (like exact code snippets, "
+            f"error messages, or content you generated), read the full transcript at: {transcript_path}"
+        )
+    if recent_messages_preserved:
+        base_summary += "\n\nRecent messages are preserved verbatim."
+    if suppress_follow_up_questions:
+        return f"""{base_summary}
+Continue the conversation from where it left off without asking the user any further questions. Resume directly — do not acknowledge the summary, do not recap what was happening, do not preface with "I'll continue" or similar. Pick up the last task as if the break never happened."""
+    return base_summary
+
+
+__all__ = [
+    "AutocompactLlmPromptKind",
+    "BASE_COMPACT_PROMPT",
+    "DETAILED_ANALYSIS_INSTRUCTION_BASE",
+    "DETAILED_ANALYSIS_INSTRUCTION_PARTIAL",
+    "NO_TOOLS_PREAMBLE",
+    "NO_TOOLS_TRAILER",
+    "PARTIAL_COMPACT_PROMPT",
+    "PARTIAL_COMPACT_UP_TO_PROMPT",
+    "PartialCompactDirection",
+    "build_autocompact_llm_instruction_prompt",
+    "format_compact_summary",
+    "get_compact_prompt",
+    "get_compact_user_summary_message",
+    "get_partial_compact_prompt",
+]

langchain_agentx/loop/prompt/sections.py

@@ -0,0 +1,120 @@
+"""SystemPromptSection — session 级提示词段注册表。
+
+对标 Claude  Code：
+  - systemPromptSection()           → section()
+  - DANGEROUS_uncachedSystemPromptSection() → volatile_section()
+  - resolveSystemPromptSections()   → resolve_sections()
+
+和 CC 的核心差异：
+  - 不包含任何 cache_control / cacheScope 逻辑（本工程使用 OpenAI 兼容接口，
+    Anthropic 服务端 Prompt Cache 对本工程无效，详见
+    docs/experience/prompt-system-and-cache-experience-2026-04-13.md）
+  - 缓存存于调用方传入的 dict（来自 AgentState.section_cache），
+    生命周期与 session 绑定，session 结束时随 state 销毁。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass
+class SystemPromptSection:
+    """可组合的系统提示词段。
+
+    Attributes:
+        name:     段的唯一标识名（同一 session 内作为 cache key）。
+        compute:  计算段内容的函数，返回 str 时输出该段，返回 None 时跳过该段。
+        volatile: False（默认）= session 内只计算一次，结果存入 section_cache 复用；
+                  True = 每轮都重新调用 compute()，不读也不写 cache。
+    """
+
+    name: str
+    compute: Callable[[], str | None]
+    volatile: bool = False
+
+
+def section(
+    name: str,
+    compute: Callable[[], str | None],
+) -> SystemPromptSection:
+    """创建 session 级缓存的提示词段。
+
+    第一次调用 compute() 后，结果存入调用方传入的 section_cache dict；
+    同一 session 的后续轮次直接读缓存，不再重新计算。
+
+    适用场景：
+    - 读取环境变量、系统信息（平台、Python 版本等）
+    - 加载配置文件、用户偏好
+    - 语言偏好、固定的工具使用说明
+
+    Args:
+        name:    段的唯一标识名，用作 section_cache 的 key。
+        compute: 计算段内容的函数，返回 str 或 None（None 表示不输出该段）。
+
+    Returns:
+        volatile=False 的 SystemPromptSection。
+    """
+    return SystemPromptSection(name=name, compute=compute, volatile=False)
+
+
+def volatile_section(
+    name: str,
+    compute: Callable[[], str | None],
+    reason: str,
+) -> SystemPromptSection:
+    """创建每轮重算的提示词段。
+
+    每次进入 model 节点前都重新调用 compute()，不读也不写 section_cache。
+    ``reason`` 参数不影响运行逻辑，仅作代码意图标注，
+    便于审查时快速定位"为什么这里不能缓存"。
+
+    适用场景：
+    - 当前时间戳
+    - 会话中途动态加入/移除的工具列表
+    - 任何每轮都可能变化的外部状态
+
+    Args:
+        name:    段的唯一标识名（volatile 段不使用 cache，但 name 仍用于调试日志）。
+        compute: 计算段内容的函数，返回 str 或 None。
+        reason:  必须说明为何不能缓存（审查用，不影响运行）。
+
+    Returns:
+        volatile=True 的 SystemPromptSection。
+    """
+    return SystemPromptSection(name=name, compute=compute, volatile=True)
+
+
+def resolve_sections(
+    sections: list[SystemPromptSection],
+    cache: dict[str, str | None],
+) -> list[str]:
+    """按顺序解析 sections，返回所有非 None 的文本列表。
+
+    缓存策略：
+    - volatile=False：优先读 cache；miss 时调用 compute() 并写入 cache。
+    - volatile=True ：每次都调用 compute()，不读也不写 cache。
+
+    Args:
+        sections: 要解析的段列表，按列表顺序输出。
+        cache:    来自 AgentState.section_cache 的字典，session 生命周期。
+                  函数会原地修改 cache（写入非 volatile 段的计算结果）。
+
+    Returns:
+        所有 compute() 返回非 None 值的文本列表，顺序与 sections 一致。
+    """
+    results: list[str] = []
+    for s in sections:
+        if s.volatile:
+            val = s.compute()
+        elif s.name not in cache:
+            cache[s.name] = s.compute()
+            val = cache[s.name]
+        else:
+            val = cache[s.name]
+
+        if val is not None:
+            results.append(val)
+
+    return results

langchain_agentx/loop/runtime/__init__.py

@@ -0,0 +1,19 @@
+"""
+loop/runtime/__init__.py — loop.runtime 包公共接口
+"""
+
+from .context import AgentLoopConfig, SubagentContextOverrides
+from .context_factory import RuntimeContextFactory
+from .subagent_execution_paths import PreparedSubagentPaths, SubagentExecutionPaths
+
+# 向后兼容：历史类型名与 AgentLoopConfig 为同一实现
+LoopRuntimeContext = AgentLoopConfig
+
+__all__ = [
+    "AgentLoopConfig",
+    "LoopRuntimeContext",
+    "SubagentContextOverrides",
+    "RuntimeContextFactory",
+    "PreparedSubagentPaths",
+    "SubagentExecutionPaths",
+]

langchain_agentx/loop/runtime/context.py

@@ -0,0 +1,34 @@
+"""
+loop/runtime/context.py — 子代理运行态控制面数据结构
+
+职责：从 `loop.config` 再导出 `AgentLoopConfig`（已合并原 `LoopRuntimeContext` 全部字段）；
+      以及 `SubagentContextOverrides`（子代理显式覆盖参数）。
+在整体链路中的位置：RuntimeContextFactory.derive() 消费，SubagentOrchestrator 传递给 runner。
+CC 对照：src/query.ts State.toolUseContext / src/utils/forkedAgent.ts createSubagentContext。
+当前裁剪范围：不变配置强类型统一为 `AgentLoopConfig`；历史名 `LoopRuntimeContext` 由
+      `loop.runtime` 包以别名导出以保持向后兼容。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..config import AgentLoopConfig
+
+__all__ = ["AgentLoopConfig", "SubagentContextOverrides"]
+
+
+@dataclass
+class SubagentContextOverrides:
+    """子代理显式覆盖参数。
+
+    None 表示"不覆盖，继承父值"。
+    CC 对照：src/utils/forkedAgent.ts forkOptions 参数。
+    """
+    model: Any | None = None
+    max_steps: int | None = None
+    available_tools: list[Any] | None = None
+    permission_mode: str | None = None
+    isolation: str = "none"
+    cwd: str | None = None

langchain_agentx/loop/runtime/context_factory.py

@@ -0,0 +1,107 @@
+"""
+loop/runtime/context_factory.py — RuntimeContextFactory 继承规则单点
+
+职责：从父 ToolExecutionContext 派生 AgentLoopConfig，应用 SubagentContextOverrides。
+      继承优先级（单点定义）：显式 override > SubagentConfig 默认 > 父 ctx 字段。
+在整体链路中的位置：SubagentOrchestrator.invoke_subagent() 调用。
+CC 对照：src/utils/forkedAgent.ts createSubagentContext() 中的字段合并逻辑。
+当前裁剪范围：v1 model / max_steps / available_tools / agent_depth 继承；permission_mode 直通；
+      ``subagent_effective_cwd`` 由 ``SubagentExecutionPaths.prepare`` 注入（不在此 mkdir）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+from .context import AgentLoopConfig, SubagentContextOverrides
+
+if TYPE_CHECKING:
+    from langchain_agentx.tool_runtime.models import ToolExecutionContext
+
+
+class RuntimeContextFactory:
+    """子代理运行态上下文派生器。
+
+    继承优先级（所有字段统一在此定义，不允许在别处散落推断）：
+        显式 SubagentContextOverrides 字段
+          > SubagentConfig.default_xxx
+          > 父 ToolExecutionContext 字段
+          > 系统默认值
+
+    CC 对照：createSubagentContext() 的参数合并顺序。
+    """
+
+    @staticmethod
+    def derive(
+        parent_ctx: "ToolExecutionContext",
+        overrides: SubagentContextOverrides,
+        *,
+        subagent_config: Any | None = None,
+        agent_id: str | None = None,
+        subagent_effective_cwd: str | None = None,
+    ) -> AgentLoopConfig:
+        """从父 ctx 派生子代理 AgentLoopConfig。
+
+        Args:
+            parent_ctx: 父会话工具执行上下文（含 model / agent_depth 等控制面字段）。
+            overrides: 子代理显式覆盖（None 字段表示继承）。
+            subagent_config: SubagentConfig 实例，提供 default_model / default_max_steps。
+            agent_id: 子代理 ID（调用方生成）。
+            subagent_effective_cwd: 由 ``SubagentExecutionPaths.prepare`` 解析的最终 cwd；
+                非 ``None`` 时写入 ``AgentLoopConfig.cwd``；为 ``None`` 时维持历史行为
+                ``parent_ctx.cwd``（兼容未接 Agent 编排的调用方）。
+        """
+        # 模型继承：override > config.default_model > parent_ctx.model
+        config_model = getattr(subagent_config, "default_model", None)
+        resolved_model = overrides.model or config_model or parent_ctx.model
+
+        # max_steps 继承：override > config.default_max_steps > None
+        config_max_steps = getattr(subagent_config, "default_max_steps", None)
+        resolved_max_steps = (
+            overrides.max_steps if overrides.max_steps is not None
+            else config_max_steps
+        )
+
+        # 工具池继承：override > 父 ctx.available_tools
+        resolved_tools = (
+            overrides.available_tools
+            if overrides.available_tools is not None
+            else list(parent_ctx.available_tools or [])
+        )
+
+        # 权限：override > 父 ctx.permission_mode > "default"
+        resolved_permission = (
+            overrides.permission_mode
+            or getattr(parent_ctx, "permission_mode", "default")
+            or "default"
+        )
+        workspace_root = getattr(parent_ctx, "workspace_root", None)
+        parent_agent_home = getattr(parent_ctx, "agent_home", None)
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=workspace_root or Path.cwd(),
+            agent_home=parent_agent_home,
+        )
+
+        resolved_cwd = (
+            subagent_effective_cwd
+            if subagent_effective_cwd is not None
+            else getattr(parent_ctx, "cwd", None)
+        )
+
+        return AgentLoopConfig(
+            model=resolved_model,
+            session_id=getattr(parent_ctx, "session_id", "") or "",
+            agent_id=agent_id,
+            parent_agent_id=getattr(parent_ctx, "agent_id", None),
+            agent_depth=(parent_ctx.agent_depth or 0) + 1,
+            max_steps=resolved_max_steps,
+            available_tools=resolved_tools,
+            permission_mode=resolved_permission,
+            workspace_root=workspace_cfg.workspace_root,
+            agent_home=workspace_cfg.agent_home,
+            cwd=resolved_cwd,
+            trace_enabled=bool(getattr(parent_ctx, "trace_enabled", True)),
+        )