langchain-agentx-python 2.3.8__tar.gz → 2.4.0__tar.gz

{langchain-agentx-python-2.3.8/langchain_agentx_python.egg-info → langchain-agentx-python-2.4.0}/PKG-INFO

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

{langchain-agentx-python-2.3.8 → langchain-agentx-python-2.4.0}/langchain_agentx/__init__.py

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

{langchain-agentx-python-2.3.8 → langchain-agentx-python-2.4.0}/langchain_agentx/loop/loop_abort.py

@@ -45,11 +45,23 @@ class LoopAbortSignal(Exception):
 
 
 def is_cancel_requested() -> bool:
-    """当前 RunContext 是否已请求取消（无 context 则为 False）。"""
+    """当前或祖先 RunContext 是否已请求取消（无 context 则为 False）。
+
+    祖先链：nested Parallelization ctx 下 leaf 可读到 L0 ``cancel_requested``。
+    """
     from .run_context import get_run_context
 
     ctx = get_run_context()
-    return ctx is not None and bool(ctx.cancel_requested)
+    seen: set[int] = set()
+    while ctx is not None:
+        ident = id(ctx)
+        if ident in seen:
+            break
+        seen.add(ident)
+        if bool(ctx.cancel_requested):
+            return True
+        ctx = ctx.parent
+    return False
 
 
 def abort_signal_for_phase(

langchain-agentx-python-2.4.0/langchain_agentx/loop/run_context.py

@@ -0,0 +1,424 @@
+"""
+run_context.py — Workflow/Agent 结构化并发上下文（parent → child cancel 传播）。
+
+职责：
+    持有 root asyncio task、child asyncio tasks 与 detached background threads；
+    通过 contextvars 隐式传递。
+
+链路位置：
+    BaseWorkflow.run() / astream_events() 入口 install；Agent spawn 时 register_child / register_child_thread。
+
+当前裁剪范围：
+    asyncio 为主；thread 仅 bounded join（无法强制中断 LLM）；anyio/trio 不保证 context 传播。
+    P1：reset 失败时在仍可见 owner 的 derived logical context 内 force-clear；
+    宿主 detached ingest 用 create_task_with_copied_context / run_context_scope。
+    nested Parallelization：child_contexts + 递归 cancel_tree；W4 可用 use_cancel_authority。
+    agent loop 登记：供 skill fork 同步桥 ``run_coroutine_threadsafe`` 解析父 loop
+    （ContextVar 在 ThreadPoolExecutor 上常丢失，故用进程级 stack）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+import time
+from contextlib import asynccontextmanager
+from contextvars import ContextVar, Token, copy_context
+from dataclasses import dataclass, field
+from typing import AsyncIterator, Awaitable, Optional, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+_current_run_context: ContextVar[Optional["RunContext"]] = ContextVar(
+    "run_ctx", default=None
+)
+
+# 进程级父 agent loop / RunContext 栈：ThreadPoolExecutor worker 看不见 ContextVar，
+# 须 threadsafe 回父 loop（bug4）并恢复 owner 供 cancel 登记（skill-fork cancel orphan）。
+_agent_loop_lock = threading.Lock()
+_agent_loop_stack: list[asyncio.AbstractEventLoop] = []
+_agent_run_ctx_stack: list["RunContext"] = []
+
+
+def register_agent_loop(loop: asyncio.AbstractEventLoop) -> None:
+    """登记当前存活的 agent/session event loop（可嵌套；同 loop 可重复 push）。"""
+    with _agent_loop_lock:
+        _agent_loop_stack.append(loop)
+
+
+def unregister_agent_loop(loop: asyncio.AbstractEventLoop) -> None:
+    """弹出最近一次与 ``loop`` 相同的登记（LIFO；未见则 no-op）。"""
+    with _agent_loop_lock:
+        for index in range(len(_agent_loop_stack) - 1, -1, -1):
+            if _agent_loop_stack[index] is loop:
+                del _agent_loop_stack[index]
+                return
+
+
+def resolve_agent_loop(
+    *,
+    owner: RunContext | None = None,
+) -> asyncio.AbstractEventLoop | None:
+    """解析仍在跑的父 agent loop；优先 ``owner.root_task``，否则栈顶存活项。"""
+    if owner is not None:
+        try:
+            loop = owner.root_task.get_loop()
+            if not loop.is_closed() and loop.is_running():
+                return loop
+        except Exception:
+            pass
+    with _agent_loop_lock:
+        for loop in reversed(_agent_loop_stack):
+            try:
+                if not loop.is_closed() and loop.is_running():
+                    return loop
+            except Exception:
+                continue
+    return None
+
+
+def resolve_owner_run_context(
+    owner: RunContext | None = None,
+) -> RunContext | None:
+    """解析取消挂接用的 owner：显式参数 → ContextVar → 进程级 install 栈顶。"""
+    if owner is not None:
+        return owner
+    current = get_run_context()
+    if current is not None:
+        return current
+    with _agent_loop_lock:
+        if _agent_run_ctx_stack:
+            return _agent_run_ctx_stack[-1]
+    return None
+
+
+async def run_under_owner_run_context(
+    coro: Awaitable[T],
+    *,
+    owner: RunContext | None,
+) -> T:
+    """在指定 owner 的 ContextVar 下 await（threadsafe 桥恢复父 RunContext）。"""
+    if owner is None:
+        return await coro
+    if get_run_context() is owner:
+        return await coro
+    token = _current_run_context.set(owner)
+    try:
+        return await coro
+    finally:
+        _current_run_context.reset(token)
+
+
+@dataclass
+class RunContext:
+    """运行上下文（Graph/Workflow/Agent 共享）。"""
+
+    root_task: asyncio.Task
+    child_tasks: set[asyncio.Task] = field(default_factory=set)
+    child_threads: set[threading.Thread] = field(default_factory=set)
+    # nested Parallelization/Chaining 再 install 时登记；cancel_tree 先深取消其 child_tasks。
+    # 用 list：RunContext 含 set/Task 不可哈希，不能放 set。
+    child_contexts: list["RunContext"] = field(default_factory=list, repr=False)
+    parent: Optional["RunContext"] = field(default=None, repr=False, compare=False)
+    cancel_requested: bool = False
+    # D-EVT-6：宿主在 cancel_tree / killAll 时写入；finish 投影读取；缺省 unknown。
+    # 取值：escape | workflow_stop | kill_agents | unknown；禁止从「是否有后台」猜测。
+    cancel_source: str | None = None
+    # install 时若成功 register_agent_loop，记下以便 reset 精确 unregister（勿误弹外层）。
+    _registered_agent_loop: asyncio.AbstractEventLoop | None = field(
+        default=None, repr=False, compare=False
+    )
+    # install 时是否 push 进进程级 RunContext 栈（供 worker 解析 owner）。
+    _registered_on_ctx_stack: bool = field(default=False, repr=False, compare=False)
+
+    def register_child(self, task: asyncio.Task) -> None:
+        self.child_tasks.add(task)
+
+    def register_child_thread(self, thread: threading.Thread) -> None:
+        self.child_threads.add(thread)
+
+    def register_child_context(self, child: "RunContext") -> None:
+        """登记 nested RunContext（install_run_context(parent=…)）。"""
+        if all(existing is not child for existing in self.child_contexts):
+            self.child_contexts.append(child)
+        child.parent = self
+
+    def cancel_authority(self) -> "RunContext":
+        """取消权威：最外层 RunContext（宿主 Stop / cancel_tree 目标）。"""
+        node: RunContext = self
+        seen: set[int] = set()
+        while node.parent is not None:
+            ident = id(node)
+            if ident in seen:
+                break
+            seen.add(ident)
+            node = node.parent
+        return node
+
+    def _mark_cancel_requested(self, *, source: str | None) -> None:
+        """本层 + 全部 nested 写入 cancel_requested（协作闸可立即看到）。"""
+        self.cancel_requested = True
+        if source is not None and self.cancel_source is None:
+            self.cancel_source = source
+        for nested in list(self.child_contexts):
+            nested._mark_cancel_requested(source=source or self.cancel_source)
+
+    async def cancel_tree(self, timeout: float = 10.0) -> None:
+        """取消本层 child_tasks，并递归 nested child_contexts（W4 / leaf producer）。"""
+        self._mark_cancel_requested(source=self.cancel_source)
+        deadline = time.monotonic() + timeout
+
+        # 深取消：先砍 nested 内 W4 producer，再 cancel 本层（含 nested.root_task）。
+        for nested in list(self.child_contexts):
+            remaining = max(0.0, deadline - time.monotonic())
+            await nested.cancel_tree(timeout=remaining)
+
+        for child in list(self.child_tasks):
+            child.cancel()
+        if self.child_tasks:
+            remaining = max(0.0, deadline - time.monotonic())
+            try:
+                await asyncio.wait_for(
+                    asyncio.gather(*self.child_tasks, return_exceptions=True),
+                    timeout=remaining,
+                )
+            except TimeoutError:
+                logger.warning(
+                    "RunContext.cancel_tree asyncio children timed out after %ss",
+                    timeout,
+                )
+            finally:
+                self.child_tasks.clear()
+
+        if self.child_threads:
+            remaining = max(0.0, deadline - time.monotonic())
+            _join_child_threads_bounded(self.child_threads, timeout=remaining)
+            self.child_threads.clear()
+
+
+def _join_child_threads_bounded(
+    threads: set[threading.Thread],
+    *,
+    timeout: float,
+) -> None:
+    """Phase 4.1：detached thread 无法 cancel，仅 bounded join + 告警。"""
+    if timeout <= 0:
+        for thread in threads:
+            if thread.is_alive():
+                logger.warning(
+                    "Background thread still alive after cancel_tree (no join budget): %s",
+                    thread.name,
+                )
+        return
+    deadline = time.monotonic() + timeout
+    for thread in list(threads):
+        remaining = max(0.0, deadline - time.monotonic())
+        thread.join(timeout=remaining)
+        if thread.is_alive():
+            logger.warning(
+                "Background thread join timed out after cancel_tree: %s",
+                thread.name,
+            )
+
+
+def get_run_context() -> RunContext | None:
+    return _current_run_context.get()
+
+
+def install_run_context(
+    ctx: RunContext | None = None,
+    *,
+    parent: RunContext | None = None,
+) -> tuple[RunContext, Token]:
+    """安装 RunContext；若已有 parent 则把当前 root task 注册为 child。"""
+    if ctx is None:
+        try:
+            current = asyncio.current_task()
+        except RuntimeError as exc:
+            raise RuntimeError(
+                "install_run_context requires a running asyncio task"
+            ) from exc
+        if current is None:
+            raise RuntimeError(
+                "install_run_context requires a running asyncio task"
+            )
+        ctx = RunContext(root_task=current)
+    if parent is not None:
+        parent.register_child(ctx.root_task)
+        parent.register_child_context(ctx)
+    token = _current_run_context.set(ctx)
+    try:
+        loop = ctx.root_task.get_loop()
+        register_agent_loop(loop)
+        ctx._registered_agent_loop = loop
+    except Exception:
+        logger.debug(
+            "register_agent_loop skipped at install_run_context",
+            exc_info=True,
+        )
+    with _agent_loop_lock:
+        _agent_run_ctx_stack.append(ctx)
+        ctx._registered_on_ctx_stack = True
+    return ctx, token
+
+
+def reset_run_context(token: Token, *, owner: RunContext | None = None) -> None:
+    """恢复 RunContext ContextVar；跨 logical context 时 force-clear 或降级 warn。
+
+    P0：token.reset 失败不抛未捕获异常。
+    P1：若当前 logical context 仍可见 ``owner``（derived context 继承值但 token 无效），
+    显式 ``set(None)`` 清理本层，避免 workflow finally 后 run_ctx 悬挂。
+    """
+    source = owner if owner is not None else get_run_context()
+    loop_to_unreg: asyncio.AbstractEventLoop | None = None
+    ctx_to_unreg: RunContext | None = None
+    if source is not None and source._registered_agent_loop is not None:
+        loop_to_unreg = source._registered_agent_loop
+        source._registered_agent_loop = None
+    if source is not None and source._registered_on_ctx_stack:
+        ctx_to_unreg = source
+        source._registered_on_ctx_stack = False
+
+    try:
+        try:
+            _current_run_context.reset(token)
+            return
+        except ValueError:
+            pass
+
+        current = get_run_context()
+        if owner is not None and current is owner:
+            _current_run_context.set(None)
+            logger.warning(
+                "run_ctx force-cleared: token reset failed in derived logical context "
+                "(task=%r)",
+                owner.root_task.get_name(),
+            )
+            return
+
+        if owner is not None and owner.root_task.done():
+            logger.debug(
+                "run_ctx reset skipped: owner task %r already done; context discarded",
+                owner.root_task.get_name(),
+            )
+            return
+
+        logger.warning(
+            "run_ctx reset skipped: token created in a different context",
+            exc_info=True,
+        )
+    finally:
+        if loop_to_unreg is not None:
+            unregister_agent_loop(loop_to_unreg)
+        if ctx_to_unreg is not None:
+            with _agent_loop_lock:
+                for index in range(len(_agent_run_ctx_stack) - 1, -1, -1):
+                    if _agent_run_ctx_stack[index] is ctx_to_unreg:
+                        del _agent_run_ctx_stack[index]
+                        break
+
+
+@asynccontextmanager
+async def run_context_scope(*, parent: RunContext | None = None):
+    """显式 bracket RunContext install/reset（宿主非 generator 路径）。"""
+    ctx, token = install_run_context(parent=parent)
+    try:
+        yield ctx
+    finally:
+        reset_run_context(token, owner=ctx)
+
+
+def create_task_with_copied_context(
+    coro: Awaitable[T],
+    *,
+    context=None,
+    name: str | None = None,
+) -> asyncio.Task[T]:
+    """在显式 context 快照中 spawn task（宿主 POST → 后台 ingest 正模式）。
+
+    默认 ``copy_context()``，保证 detached task 与创建点 contextvars 一致。
+    仍需在同一 task 内完整消费 workflow 流，避免跨 task aclose generator。
+    """
+    if context is None:
+        context = copy_context()
+    return asyncio.create_task(coro, context=context, name=name)
+
+
+async def drive_async_iterator_in_current_task(
+    iterator: AsyncIterator[T],
+) -> AsyncIterator[T]:
+    """在当前 asyncio task 内驱动 async iterator（禁止把 aclose 交给子 task）。
+
+    用于宿主 ingest 需额外并发但仍须保证 generator finally 与 install 同 task 的场景。
+    """
+    async for item in iterator:
+        yield item
+
+
+def resolve_cancel_authority(
+    ctx: RunContext | None = None,
+) -> RunContext | None:
+    """解析取消权威 ctx；缺省取当前 ContextVar 的 outermost。"""
+    current = ctx if ctx is not None else get_run_context()
+    if current is None:
+        return None
+    return current.cancel_authority()
+
+
+def register_spawned_task(
+    task: asyncio.Task,
+    *,
+    owner: RunContext | None = None,
+    use_cancel_authority: bool = False,
+) -> None:
+    """将 spawn 出的 asyncio task 注册到 RunContext（无 context 时 no-op）。
+
+    ``use_cancel_authority=True``：挂到 outermost（Workflow W4），避免仅挂在
+    nested Parallelization ctx 上导致 L0 ``cancel_tree`` 砍不到 producer。
+    """
+    ctx = owner if owner is not None else get_run_context()
+    if ctx is None:
+        return
+    if use_cancel_authority:
+        ctx = ctx.cancel_authority()
+    try:
+        owner_loop = ctx.root_task.get_loop()
+        task_loop = task.get_loop()
+    except RuntimeError:
+        logger.warning("register_spawned_task: cannot resolve event loop; skipping registration")
+        return
+    if owner_loop is not task_loop:
+        logger.warning(
+            "register_spawned_task: skipping foreign-loop task %r",
+            task.get_name(),
+        )
+        return
+    ctx.register_child(task)
+
+
+def register_spawned_thread(
+    thread: threading.Thread,
+    *,
+    owner: RunContext | None = None,
+) -> None:
+    """Phase 4.1：detached thread spawn 注册到 owner RunContext（bounded join）。"""
+    ctx = owner if owner is not None else get_run_context()
+    if ctx is not None:
+        ctx.register_child_thread(thread)
+
+
+__all__ = [
+    "RunContext",
+    "create_task_with_copied_context",
+    "drive_async_iterator_in_current_task",
+    "get_run_context",
+    "install_run_context",
+    "register_spawned_task",
+    "register_spawned_thread",
+    "reset_run_context",
+    "resolve_cancel_authority",
+    "run_context_scope",
+]

{langchain-agentx-python-2.3.8 → langchain-agentx-python-2.4.0}/langchain_agentx/loop/stream/loop_driver.py

@@ -11,6 +11,7 @@ loop_driver.py — Loop-aware shared stream driver.
     root closeout 捕获、synthetic error/finish、orphan tool_result repair（stream surface）。
     正常结束但缺 root on_chain_end(LangGraph) 时打 anomaly WARNING（不伪造 synthetic finish）。
     R1 反应恢复：单次 drain 内 budgeted continue 重入（S2，对齐 CC queryLoop continue）。
+    进入/退出时登记 agent loop，供 Ask 路径无 Workflow RunContext 时 fork 同步桥解析。
 """
 
 from __future__ import annotations
@@ -22,6 +23,7 @@ from typing import Any, AsyncIterator, Literal
 from langgraph.errors import GraphRecursionError
 
 from langchain_agentx.loop.loop_abort import LoopAbortSignal, is_cancel_requested
+from langchain_agentx.loop.run_context import register_agent_loop, unregister_agent_loop
 from ..exit.reason_codes import (
     TERMINAL_REASON_ABORTED_STREAMING,
     TERMINAL_REASON_ABORTED_TOOLS,
@@ -84,6 +86,8 @@ class LoopStreamDriver:
         self.result.reactive_continue_drains = 0
         current_input = dict(graph_input)
         reactive_continues = 0
+        agent_loop = asyncio.get_running_loop()
+        register_agent_loop(agent_loop)
         try:
             while True:
                 async for event in self._stream_single_drain(
@@ -113,6 +117,7 @@ class LoopStreamDriver:
                     (self.result.graph_output or {}).get("transition", {}).get("reason"),
                 )
         finally:
+            unregister_agent_loop(agent_loop)
             self._log_stream_closeout_summary()
 
     async def _stream_single_drain(

{langchain-agentx-python-2.3.8 → langchain-agentx-python-2.4.0}/langchain_agentx/loop/subagent/orchestrator.py

@@ -666,6 +666,7 @@ class SubagentOrchestrator:
                     loader=child_loader,
                     model=runtime_ctx.model,
                     allowed_tool_names=allowed_tool_names,
+                    owner_run_ctx=get_run_context(),
                 )
 
         return AgentToolOutput(
@@ -1015,13 +1016,17 @@ class SubagentOrchestrator:
         model: Any,
         allowed_tool_names: set[str],
     ) -> Any:
-        owner_run_ctx = get_run_context()
+        from langchain_agentx.loop.run_context import resolve_owner_run_context
+
+        # worker 上 ContextVar 常空；进程级 install 栈仍可解析父 RunContext（cancel 挂接）。
+        owner_run_ctx = resolve_owner_run_context()
         return _run_coroutine_sync(
             run_subagent(
                 ctx=subagent_ctx,
                 loader=loader,
                 model=model,
                 allowed_tool_names=allowed_tool_names,
+                owner_run_ctx=owner_run_ctx,
             ),
             owner_run_ctx=owner_run_ctx,
         )

{langchain-agentx-python-2.3.8 → langchain-agentx-python-2.4.0}/langchain_agentx/loop/subagent/runner.py

@@ -119,23 +119,43 @@ def _is_abort_like_terminal_reason(reason: str | None) -> bool:
 
 
 def _run_coroutine_sync(coro: Any, *, owner_run_ctx: Any | None = None) -> Any:
-    """在无 running loop 的同步上下文用 asyncio.run 跑协程。
-
-    P0（Doc-35）：已有 running loop 时禁止 Thread+asyncio.run（C2）；须改走
-    ``await`` / ``ainvoke_subagent``。``owner_run_ctx`` 保留签名兼容，有 loop 时不再使用。
+    """同步桥：无当前线程 running loop 时跑协程。
+
+    - 当前线程已有 running loop：禁止阻塞桥接（会死锁）→ 须 ``await`` /
+      ``ainvoke_subagent``（Doc-35 / C2）。
+    - 进程内已有存活的父 agent loop（``resolve_agent_loop``）：
+      ``run_coroutine_threadsafe`` 提交回父 loop（skill fork 对齐 CC 同 loop；
+      避免 worker ``asyncio.run`` 新 loop + 共享 httpx 池毒化，bug4）；
+      并 ``run_under_owner_run_context`` 恢复父 RunContext（cancel 登记，bug cancel-orphan）。
+    - 否则：``asyncio.run``（纯同步脚本、无父会话）。
     """
-    del owner_run_ctx  # C2 删除后同步路径不再登记 worker thread
     try:
         asyncio.get_running_loop()
     except RuntimeError:
-        return asyncio.run(coro)
+        pass
+    else:
+        raise RuntimeError(
+            "cannot run subagent coroutine via thread while an asyncio event loop "
+            "is running (C2 removed, Doc-35 P0). Use await run_subagent / "
+            "ainvoke_subagent on the same loop instead of sync invoke."
+        )
 
-    raise RuntimeError(
-        "cannot run subagent coroutine via thread while an asyncio event loop "
-        "is running (C2 removed, Doc-35 P0). Use await run_subagent / "
-        "ainvoke_subagent on the same loop instead of sync invoke."
+    from langchain_agentx.loop.run_context import (
+        resolve_agent_loop,
+        resolve_owner_run_context,
+        run_under_owner_run_context,
     )
 
+    owner = resolve_owner_run_context(owner_run_ctx)
+    target = resolve_agent_loop(owner=owner)
+    if target is not None and target.is_running():
+        return asyncio.run_coroutine_threadsafe(
+            run_under_owner_run_context(coro, owner=owner),
+            target,
+        ).result()
+
+    return asyncio.run(coro)
+
 
 @dataclass
 class BackgroundLaunchedResult:
@@ -815,7 +835,12 @@ async def run_subagent(
             ),
             name=f"agentx-subagent-fg-{ctx.agent_id or 'anon'}",
         )
-        register_spawned_task(task, owner=owner_run_ctx)
+        # Skill fork / nested Parallelization：挂 cancel authority（L0），对齐 D-REG-1。
+        register_spawned_task(
+            task,
+            owner=owner_run_ctx,
+            use_cancel_authority=True,
+        )
         return await task
     return await _run_subagent_body(
         ctx=ctx,

{langchain-agentx-python-2.3.8 → langchain-agentx-python-2.4.0}/langchain_agentx/tools/bash/ast_security.py

@@ -219,6 +219,18 @@ class BashPermissionSegmenter:
     def __init__(self, node_helper: BashAstNodeHelper) -> None:
         self._node_helper = node_helper
 
+    # 控制结构整段保留：避免 for/while 的变量名与 in-list 词被拆成伪 command 段
+    # （否则 ``for i in 1 2; do echo; done`` → segments ``i``/``1``/``2``…，
+    #  触发 bash_passthrough ask 误阻只读循环）。
+    _ATOMIC_CONTROL_TYPES = frozenset({
+        "for_statement",
+        "while_statement",
+        "until_statement",
+        "if_statement",
+        "case_statement",
+        "function_definition",
+    })
+
     def collect_segments(self, node: Node) -> list[str]:
         if node.type == "program":
             return self._collect_from_container(node)
@@ -226,7 +238,13 @@ class BashPermissionSegmenter:
         if node.type in {"pipeline", "list"}:
             return self._collect_from_container(node)
 
-        if node.type in {"command", "redirected_statement", "subshell", "compound_statement"}:
+        if node.type in {
+            "command",
+            "redirected_statement",
+            "subshell",
+            "compound_statement",
+            *self._ATOMIC_CONTROL_TYPES,
+        }:
             text = self._node_helper.text(node).strip()
             return [text] if text else []
 

{langchain-agentx-python-2.3.8 → langchain-agentx-python-2.4.0}/langchain_agentx/tools/bash/command_allow_rules.py

@@ -10,6 +10,8 @@ tools/bash/command_allow_rules.py — Bash 内容级 allow 匹配（slash comman
 
 from __future__ import annotations
 
+import re
+import shlex
 from typing import TYPE_CHECKING
 
 from langchain_agentx.tools.bash.shell_rule_matching import match_shell_permission_rule
@@ -29,6 +31,8 @@ from langchain_agentx.tool_runtime.policy import PolicyEngine, resolve_default_p
 if TYPE_CHECKING:
     from langchain_agentx.tool_runtime.policy import DefaultPolicyEngine
 
+_ENV_ASSIGNMENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=.*$")
+
 
 def bash_command_matches_allow_rule(command: str, rule_content: str) -> bool:
     """CC shellRuleMatching（prefix / wildcard / exact）。"""
@@ -105,6 +109,27 @@ def registry_has_cliarg_bash_allow(registry: PermissionRuleRegistry) -> bool:
     return False
 
 
+def _is_pure_cd_segment(command: str) -> bool:
+    """``cd`` / ``cd <path>``（可带前导 ``VAR=``）不 promote。
+
+    G4：``cd`` 本身非只读，但段级静默 allow 是 cwd 语义的必要通路；
+    若 promote 为 ask，会抢在 ``compound_cd_write`` / 后续只读段之前，
+    导致 ``cd && touch`` / ``cd && pwd`` / session cwd 合并用例被 headless 误阻。
+    """
+    try:
+        tokens = shlex.split(command.strip())
+    except ValueError:
+        tokens = command.strip().split()
+    index = 0
+    while index < len(tokens) and _ENV_ASSIGNMENT_RE.match(tokens[index]):
+        index += 1
+    rest = tokens[index:]
+    if not rest or rest[0].rsplit("/", 1)[-1] != "cd":
+        return False
+    # 段级调用不应含 list/pipe；若整串被误传，拒绝当作 pure cd
+    return not any(tok in {"&&", "||", "|", ";"} for tok in rest)
+
+
 def promote_unscoped_bash_passthrough_to_ask(
     decision: AuthorizationDecision,
     *,
@@ -126,6 +151,8 @@ def promote_unscoped_bash_passthrough_to_ask(
         shell_ops_already_resolved=True,
     ).is_read_only:
         return decision
+    if _is_pure_cd_segment(command):
+        return decision
     # 显式规则 / mode / safety 等已标 policy_id 的 allow 不降级
     if decision.policy_id not in (None, "", "write_roots"):
         return decision