langchain-agentx-python 2.4.0__py3-none-any.whl → 2.4.4__py3-none-any.whl

langchain_agentx/__init__.py

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

langchain_agentx/loop/config/interaction_profile.py

@@ -25,7 +25,10 @@ if TYPE_CHECKING:
 _WORKER_CONTAINER_TYPES = frozenset(
     {"background_task", "background", "batch", "worker", "sdk"}
 )
-_INTERACTIVE_HEADLESS_MODES = frozenset({"auto", "dontAsk", "bypassPermissions"})
+# acceptEdits：headless 子图继承父写快路径（与 auto 同属写链放行 mode）
+_INTERACTIVE_HEADLESS_MODES = frozenset(
+    {"auto", "dontAsk", "bypassPermissions", "acceptEdits"}
+)
 _HITL_PROFILE_IDS = frozenset({"code-interactive", "code-plan"})
 _HEADLESS_PROFILE_IDS = frozenset(
     {"qa-auto", "workflow-auto", "worker-deny", "interactive-headless"}
@@ -120,7 +123,8 @@ class InteractionProfileResolver:
                 if mode in ("default", "plan"):
                     raise ValueError(
                         f"interactive + headless=True cannot use permission_mode={mode!r}; "
-                        "use auto, dontAsk, or bypassPermissions (print/script entry)"
+                        "use auto, dontAsk, bypassPermissions, or acceptEdits "
+                        "(interactive-headless / print/script entry)"
                     )
                 if mode not in _INTERACTIVE_HEADLESS_MODES:
                     raise ValueError(

langchain_agentx/loop/config/loop_config.py

@@ -136,6 +136,8 @@ class SubagentLinkage:
     subagent_type: str | None = None
     agent_depth: int = 0
     parent_agent_id: str | None = None
+    fork_from_parent: bool = False
+    """True = 当前子 loop 为 ForkA worker（会话继承 fork）；供 ToolExecutionContext / L1。"""
 
 
 @dataclass(frozen=True, init=False)

langchain_agentx/loop/graph/factory.py

@@ -312,7 +312,12 @@ def _flatten_config_for_runtime(config: AgentLoopConfig) -> _FlatLoopConfig:
         conversation_session_id=config.conversation_session_id,
         agent_id=config.agent_id,
         parent_agent_id=config.subagent.parent_agent_id,
-        agent_depth=config.agent_depth,
+        agent_depth=(
+            config.subagent.agent_depth
+            if config.subagent.is_subagent
+            else config.agent_depth
+        ),
+        fork_from_parent=bool(config.subagent.fork_from_parent),
         subagent_type=config.subagent.subagent_type,
         trace_enabled=config.trace.enabled,
         trace_persist=config.trace.persist,
@@ -980,6 +985,7 @@ class LoopGraphBuilder:
             system_prompt=self._base_prompt,
             capabilities=self._services.capabilities,
             cwd=runtime_cwd,
+            permission_mode=self._config.permission_mode,
             boundary_snapshot=BoundarySnapshotPropagator.from_workspace_boundary(
                 boundary=self._workspace_boundary,
                 runtime_cwd=runtime_cwd,
@@ -1043,6 +1049,7 @@ class LoopGraphBuilder:
             system_prompt=base_prompt,
             capabilities=self._services.capabilities,
             cwd=runtime_cwd,
+            permission_mode=self._config.permission_mode,
             boundary_snapshot=BoundarySnapshotPropagator.from_workspace_boundary(
                 boundary=self._workspace_boundary,
                 runtime_cwd=runtime_cwd,

langchain_agentx/loop/run_context.py

@@ -112,6 +112,36 @@ async def run_under_owner_run_context(
         _current_run_context.reset(token)
 
 
+@dataclass
+class SubagentConcurrencyGate:
+    """会话级并发子 Agent 计数（挂在 RunContext.cancel_authority 根上）。
+
+    Doc-37 C9 / Phase 2：独立于深度；无「总 spawn」帽。
+    """
+
+    _running: int = field(default=0, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def try_acquire(self, *, limit: int) -> bool:
+        if limit < 1:
+            return False
+        with self._lock:
+            if self._running >= limit:
+                return False
+            self._running += 1
+            return True
+
+    def release(self) -> None:
+        with self._lock:
+            if self._running > 0:
+                self._running -= 1
+
+    @property
+    def running(self) -> int:
+        with self._lock:
+            return self._running
+
+
 @dataclass
 class RunContext:
     """运行上下文（Graph/Workflow/Agent 共享）。"""
@@ -127,6 +157,10 @@ class RunContext:
     # D-EVT-6：宿主在 cancel_tree / killAll 时写入；finish 投影读取；缺省 unknown。
     # 取值：escape | workflow_stop | kill_agents | unknown；禁止从「是否有后台」猜测。
     cancel_source: str | None = None
+    # Phase 2：并发子 Agent 槽位；acquire/release 始终走 cancel_authority 根上的 gate。
+    subagent_concurrency: SubagentConcurrencyGate = field(
+        default_factory=SubagentConcurrencyGate, repr=False
+    )
     # install 时若成功 register_agent_loop，记下以便 reset 精确 unregister（勿误弹外层）。
     _registered_agent_loop: asyncio.AbstractEventLoop | None = field(
         default=None, repr=False, compare=False
@@ -134,6 +168,18 @@ class RunContext:
     # install 时是否 push 进进程级 RunContext 栈（供 worker 解析 owner）。
     _registered_on_ctx_stack: bool = field(default=False, repr=False, compare=False)
 
+    def try_acquire_subagent_slot(self, *, limit: int) -> bool:
+        """在 outermost RunContext 上占用一个并发槽；满则 False。"""
+        return self.cancel_authority().subagent_concurrency.try_acquire(limit=limit)
+
+    def release_subagent_slot(self) -> None:
+        """释放 outermost 上的一个并发槽（幂等下限 0）。"""
+        self.cancel_authority().subagent_concurrency.release()
+
+    @property
+    def running_subagent_count(self) -> int:
+        return self.cancel_authority().subagent_concurrency.running
+
     def register_child(self, task: asyncio.Task) -> None:
         self.child_tasks.add(task)
 
@@ -412,6 +458,7 @@ def register_spawned_thread(
 
 __all__ = [
     "RunContext",
+    "SubagentConcurrencyGate",
     "create_task_with_copied_context",
     "drive_async_iterator_in_current_task",
     "get_run_context",
@@ -420,5 +467,6 @@ __all__ = [
     "register_spawned_thread",
     "reset_run_context",
     "resolve_cancel_authority",
+    "resolve_owner_run_context",
     "run_context_scope",
 ]

langchain_agentx/loop/runtime/context_factory.py

@@ -5,8 +5,17 @@ loop/runtime/context_factory.py — RuntimeContextFactory 继承规则单点
       继承优先级（单点定义）：显式 override > SubagentConfig 默认 > 父 ctx 字段。
 在整体链路中的位置：SubagentOrchestrator.invoke_subagent() 调用。
 CC 对照：src/utils/forkedAgent.ts createSubagentContext() 中的字段合并逻辑。
-当前裁剪范围：v1 model / max_steps / available_tools / agent_depth 继承；permission_mode 直通；
+当前裁剪范围：v1 model / max_steps / available_tools / agent_depth 继承；
+      permission_mode 经 read_parent_permission_mode 写入 AgentLoopConfig（derive 侧）；
+      orchestrator 再经 resolve_definition_permission_mode 合并 definition/overrides 后
+      注入 SubagentContext.permission_mode（构图 SSOT；见 dual-track / parent-wins bug 单）；
       ``subagent_effective_cwd`` 由 ``SubagentExecutionPaths.prepare`` 注入（不在此 mkdir）。
+
+编排消费说明（防双轨幻觉）：
+      ``derive`` 返回完整 ``AgentLoopConfig``，但 ``create_subagent_graph`` **不直接吃**该对象；
+      orchestrator 当前只抽出并注入子 ctx 的字段：``model`` / ``max_steps`` /
+      ``agent_depth`` / ``permission_mode``（及 path/workspace 旁路）。子图权限权威在
+      ``SubagentContext.permission_mode``，勿在 graph 再读父 runnable。
 """
 
 from __future__ import annotations
@@ -83,16 +92,22 @@ class RuntimeContextFactory:
             else list(parent_ctx.available_tools or [])
         )
 
-        # 权限：override > 父 ctx.tool_flags["permission_mode"] > "default"
-        parent_permission = (
-            getattr(parent_ctx, "permission_mode", None)
-            or getattr(getattr(parent_ctx, "tool_flags", None), "get", lambda x: None)("permission_mode")
-            or "default"
+        # 权限：override > read_parent_permission_mode > "default"（AgentLoopConfig 侧）。
+        # 子图有效 mode（含 definition 父优先）由 orchestrator._resolve_effective_permission_mode
+        # 写入 SubagentContext.permission_mode；勿把本字段当作 definition merge 结果。
+        from langchain_agentx.tool_runtime.prompt.session_mode import (
+            read_parent_permission_mode,
         )
-        resolved_permission = (
+
+        parent_permission = (
             overrides.permission_mode
             if overrides.permission_mode is not None
-            else parent_permission
+            else read_parent_permission_mode(parent_ctx)
+        )
+        resolved_permission = (
+            parent_permission.strip()
+            if isinstance(parent_permission, str) and parent_permission.strip()
+            else "default"
         )
         workspace_root = getattr(parent_ctx, "workspace_root", None)
         parent_agent_home = getattr(parent_ctx, "agent_home_segment", None)
@@ -146,12 +161,17 @@ class RuntimeContextFactory:
         subagent_query_source = (
             f"agent:{subagent_type}" if subagent_type else "agent:default"
         )
+        # 子 depth 与顶层 agent_depth 必须一致：factory flatten 在 is_subagent 时
+        # 优先读 subagent.agent_depth（嵌套 L1→L2 若只写顶层会误成 0）。
+        child_depth = int(getattr(parent_ctx, "agent_depth", 0) or 0) + 1
 
+        # 完整 AgentLoopConfig 供编排/后台路径复用；构图 SSOT 仍经 SubagentContext
+        # （orchestrator 仅透传 model/max_steps/agent_depth/permission_mode 等）。
         return AgentLoopConfig(
             model=resolved_model,
             session_id=getattr(parent_ctx, "session_id", "") or "",
             agent_id=agent_id,
-            agent_depth=(parent_ctx.agent_depth or 0) + 1,
+            agent_depth=child_depth,
             max_steps=resolved_max_steps,
             permission_mode=resolved_permission,
             model_retry=ModelRetrySettings(query_source=subagent_query_source),
@@ -171,6 +191,9 @@ class RuntimeContextFactory:
             ),
             subagent=SubagentLinkage(
                 is_subagent=True,
+                subagent_type=str(subagent_type) if subagent_type else None,
                 parent_agent_id=parent_agent_id,
+                agent_depth=child_depth,
+                # fork_from_parent 由 orchestrator mode 决定，derive 不知 mode → False
             ),
         )

langchain_agentx/loop/subagent/async_runner.py

@@ -175,8 +175,12 @@ async def _execute_background_lifecycle(
     task_id: str,
     task_runtime: Any | None,
     allowed_tool_names: set[str] | None = None,
+    slot_owner: RunContext | None = None,
 ) -> None:
-    """共享后台生命周期：run_subagent → 写 output → task_runtime 终态。"""
+    """共享后台生命周期：run_subagent → 写 output → task_runtime 终态。
+
+    ``slot_owner``：Phase 2 并发槽从 orchestrator 移交至此；终态时 release。
+    """
     execution_ctx = ctx
     execution_ctx.is_async = False
     agent_id = getattr(ctx, "agent_id", None)
@@ -252,6 +256,9 @@ async def _execute_background_lifecycle(
             agent_id=agent_id,
             terminal_reason=TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
         )
+    finally:
+        if slot_owner is not None:
+            slot_owner.release_subagent_slot()
 
 
 def register_background_agent(
@@ -264,6 +271,7 @@ def register_background_agent(
     parent_ctx: Any | None = None,
     owner_run_ctx: RunContext | None = None,
     allowed_tool_names: set[str] | None = None,
+    slot_owner: RunContext | None = None,
 ) -> BackgroundAgentHandle:
     """注册并启动后台子 Agent（仅同 loop C3；无/异 loop 拒绝，D-BG-1）。"""
     task_runtime = _resolve_task_runtime(parent_ctx)
@@ -307,6 +315,7 @@ def register_background_agent(
         task_runtime=task_runtime,
         owner_run_ctx=owner_run_ctx,
         allowed_tool_names=allowed_tool_names,
+        slot_owner=slot_owner,
     )
 
 
@@ -321,6 +330,7 @@ def _register_background_agent_task(
     task_runtime: Any | None,
     owner_run_ctx: RunContext | None,
     allowed_tool_names: set[str] | None = None,
+    slot_owner: RunContext | None = None,
 ) -> BackgroundAgentHandle:
     async def _task_body() -> None:
         await _execute_background_lifecycle(
@@ -331,6 +341,7 @@ def _register_background_agent_task(
             task_id=task_id,
             task_runtime=task_runtime,
             allowed_tool_names=allowed_tool_names,
+            slot_owner=slot_owner,
         )
 
     task = loop.create_task(_task_body(), name=f"agentx-subagent-{task_id}")

langchain_agentx/loop/subagent/context.py

@@ -54,6 +54,7 @@ from langchain_agentx.loop.subagent.fork_worktree_notice import build_worktree_n
 from langchain_agentx.loop.message_contract import to_record
 from langchain_agentx.tool_runtime.prompt.session_mode import (
     read_parent_loop_config,
+    read_parent_permission_mode,
     resolve_subagent_headless,
 )
 from langchain_agentx.tool_runtime.session_store import AgentSessionStore
@@ -82,6 +83,8 @@ class SubagentContext:
     fork_from_parent: bool = False  # True = fork 模式，initial_messages 含父会话历史
     is_async: bool = False         # True = 走异步路径（coordinate/fork-async）
     headless: bool = True          # CC 对齐：async 强制 True；sync 继承父 loop headless
+    permission_mode: str | None = None
+    """子图 permission_mode SSOT（derive/ctx 工厂写入；create_subagent_graph 只读本字段）。"""
 
     # 共享字段（从父会话继承）
     session_store: Any = None  # SessionStore
@@ -177,6 +180,7 @@ def create_subagent_context(
     is_builtin_subagent: bool = False,
     recovery: RecoveryPolicy | RecoveryPolicyMode | None = None,
     inherit_hooks: bool | frozenset[HookEvent] | None = True,
+    permission_mode: str | None = None,
 ) -> SubagentContext:
     """工厂函数：从父上下文创建子 Agent 上下文
 
@@ -199,6 +203,7 @@ def create_subagent_context(
         fork_worktree_parent_cwd: 父 Agent 工作目录（须在 ``run_with_cwd_override`` 子 cwd 生效前由编排层捕获）。
         fork_worktree_path: 子 Agent 的 worktree 根路径（通常即 ``path_prep.worktree_dir``）。
         thinking_generation_enabled: 是否启用 request-side thinking（由 SubagentOrchestrator 根据 mode 决定）
+        permission_mode: 显式子 mode（orchestrator 传 derive 结果）；None 时从父 runnable/tool_flags 读一次
 
     Returns:
         SubagentContext 实例
@@ -301,6 +306,12 @@ def create_subagent_context(
         is_async=is_async,
     )
 
+    # permission_mode SSOT：显式（derive）> 父 runnable/tool_flags 读一次；构图不再重读父
+    if isinstance(permission_mode, str) and permission_mode.strip():
+        resolved_permission_mode: str | None = permission_mode.strip()
+    else:
+        resolved_permission_mode = read_parent_permission_mode(parent_ctx)
+
     resolved_query_source = (
         query_source
         if isinstance(query_source, str) and query_source.strip()
@@ -331,6 +342,7 @@ def create_subagent_context(
         fork_from_parent=fork_from_parent,
         is_async=is_async,
         headless=resolved_headless,
+        permission_mode=resolved_permission_mode,
         session_store=session_store,
         tool_registry=getattr(parent_ctx, "tool_registry", None),
         tool_loader=getattr(parent_ctx, "tool_loader", None),
@@ -403,6 +415,8 @@ class ForkedParentRuntime:
     cwd: str | None = None
     thinking_generation_enabled: bool | None = None
     boundary_snapshot: BoundarySnapshot | None = None
+    permission_mode: str | None = None
+    """父 loop permission_mode；后台 fork 写入 SubagentContext SSOT。"""
 
 
 def _clone_parent_session_store(parent_store: Any) -> Any:
@@ -510,6 +524,12 @@ class SubagentContextFactory:
             fork_from_parent=True,
             is_async=False,
             headless=True,
+            permission_mode=(
+                parent_runtime.permission_mode.strip()
+                if isinstance(parent_runtime.permission_mode, str)
+                and parent_runtime.permission_mode.strip()
+                else None
+            ),
             session_store=session_store,
             tool_registry=parent_runtime.tool_registry,
             tool_loader=parent_runtime.tool_loader,

langchain_agentx/loop/subagent/definition_permission.py

@@ -0,0 +1,73 @@
+"""loop/subagent/definition_permission.py — 子 Agent 定义 permissionMode 父优先合并
+
+职责：官网 Permission modes 规则核（纯函数）；不读 AppState、不写 ctx。
+链路：SubagentConfig / overrides.declared + 父 mode → orchestrator → SubagentContext SSOT。
+裁剪：auto_available 本期恒 True（LOCK-10）；无 plugin 忽略面；非法枚举由 loader 告警后置 None。
+
+规范化枚举见 ``tool_runtime.prompt.session_mode.normalize_definition_permission_mode``
+（避免 tools.loader → loop 反向依赖）。
+"""
+
+from __future__ import annotations
+
+from langchain_agentx.tool_runtime.prompt.session_mode import (
+    normalize_definition_permission_mode,
+)
+
+_ELEVATED_PARENT_MODES = frozenset(
+    {
+        "bypassPermissions",
+        "acceptEdits",
+        "auto",
+    }
+)
+
+
+def _normalize_parent_mode(parent_mode: str | None) -> str | None:
+    """父 mode：blank→None；manual→default；其余保留（含合法枚举）。"""
+    if parent_mode is None:
+        return None
+    if not isinstance(parent_mode, str):
+        return None
+    stripped = parent_mode.strip()
+    if not stripped:
+        return None
+    if stripped == "manual":
+        return "default"
+    return stripped
+
+
+def resolve_definition_permission_mode(
+    *,
+    parent_mode: str | None,
+    declared: str | None,
+    auto_available: bool = True,
+) -> str | None:
+    """合并父会话 mode 与子定义声明（官网 Permission modes / Nested 链式）。
+
+    LOCK-2：父 ∈ elevated → 忽略子声明。
+    LOCK-3：子 bypass 且父非 bypass → 保持父。
+    LOCK-10：本期 auto_available 默认 True。
+    """
+    parent = _normalize_parent_mode(parent_mode)
+    declared_n = normalize_definition_permission_mode(declared)
+
+    if declared_n is None:
+        return parent
+
+    if parent in _ELEVATED_PARENT_MODES:
+        return parent
+
+    if declared_n == "bypassPermissions" and parent != "bypassPermissions":
+        return parent
+
+    if declared_n == "auto" and not auto_available:
+        return parent
+
+    return declared_n
+
+
+__all__ = [
+    "normalize_definition_permission_mode",
+    "resolve_definition_permission_mode",
+]

langchain_agentx/loop/subagent/graph.py

@@ -24,6 +24,41 @@ if TYPE_CHECKING:
     from .context import SubagentContext
 
 
+def resolve_subagent_permission_mode(
+    *,
+    headless: bool,
+    inherited: str | None,
+) -> str:
+    """解析子图 permission_mode。
+
+    headless 时继承父 mode（父 ``auto`` → 子 ``auto``，写快路径才可通）；
+    无父 mode 时回落 ``dontAsk``（无交互面）。非 headless 无父 mode 回落 ``default``。
+
+    对照：docs/bug/headless-subagent-dontask-blocks-write-roots-2026-10-22.md
+    """
+    if isinstance(inherited, str) and inherited.strip():
+        return inherited.strip()
+    return "dontAsk" if headless else "default"
+
+
+def resolve_subagent_container_type(
+    *,
+    headless: bool,
+    permission_mode: str,
+) -> str:
+    """解析子图 container_type，与 ``InteractionProfileResolver`` 合法三元组对齐。
+
+    ``sdk`` 剖面强制 ``permission_mode=dontAsk``；若子图继承了 ``auto`` /
+    ``acceptEdits`` / ``bypassPermissions``，须改走 ``interactive`` + headless
+    （interactive-headless），否则 normalize 会拒掉。
+    """
+    if not headless:
+        return "interactive"
+    if permission_mode == "dontAsk":
+        return "sdk"
+    return "interactive"
+
+
 def create_subagent_graph(
     ctx: SubagentContext,
     loader: Any,
@@ -58,9 +93,10 @@ def create_subagent_graph(
         sync_tool_policy_roots_from_workspace,
     )
     from langchain_agentx.tool_runtime.loader import ToolRuntimeLoader
-    from langchain_agentx.tool_runtime.prompt.session_mode import read_parent_permission_mode
 
-    inherited_permission_mode = read_parent_permission_mode(ctx)
+    # permission_mode SSOT：只读 SubagentContext（derive/create_subagent_context 写入）
+    # 勿再 read_parent_permission_mode — docs/bug/subagent-permission-mode-dual-track-ssot-2026-10-22.md
+    inherited_permission_mode = ctx.permission_mode
 
     if ctx.boundary_snapshot is not None and isinstance(loader, ToolRuntimeLoader):
         sync_tool_policy_roots_from_workspace(
@@ -89,6 +125,18 @@ def create_subagent_graph(
     else:
         session_id = f"subagent:{ctx.subagent_type}:{ctx.agent_id}"
 
+    # 勿无条件 headless→dontAsk / 一律 sdk：会盖掉父 auto，且与 sdk 剖面冲突
+    # （docs/bug/headless-subagent-dontask-blocks-write-roots-2026-10-22.md）
+    sub_headless = bool(ctx.headless)
+    sub_permission_mode = resolve_subagent_permission_mode(
+        headless=sub_headless,
+        inherited=inherited_permission_mode,
+    )
+    sub_container_type = resolve_subagent_container_type(
+        headless=sub_headless,
+        permission_mode=sub_permission_mode,
+    )
+
     # Phase 3: config-first 模式
     config = AgentLoopConfig(
         session_id=session_id,
@@ -119,20 +167,18 @@ def create_subagent_graph(
             parent_tool_call_id=ctx.parent_tool_call_id,
             parent_conversation_session_id=ctx.parent_conversation_session_id,
         ),
+        agent_depth=ctx.agent_depth,
         subagent=SubagentLinkage(
             is_subagent=True,
             subagent_type=ctx.subagent_type,
             parent_agent_id=ctx.parent_agent_id,
             agent_depth=ctx.agent_depth,
+            fork_from_parent=bool(ctx.fork_from_parent),
         ),
         max_steps=ctx.max_steps,
-        headless=bool(ctx.headless),
-        container_type="sdk" if ctx.headless else "interactive",
-        permission_mode=(
-            "dontAsk"
-            if ctx.headless
-            else (inherited_permission_mode or "default")
-        ),
+        headless=sub_headless,
+        permission_mode=sub_permission_mode,
+        container_type=sub_container_type,
         name=f"subagent:{ctx.subagent_type}:{ctx.agent_id[:8]}",
     )
     services = LoopServices(