langchain-agentx-python 0.2.7__py3-none-any.whl → 0.2.8__py3-none-any.whl

langchain_agentx/loop/config/agent_loop_config.py

@@ -47,6 +47,8 @@ class AgentLoopConfig:
 
     # 工具与权限
     available_tools: list[Any] = field(default_factory=list)
+    # 为 False 时禁止需要外网的工具（如 WebSearch）；只读/离线模式由宿主设置。
+    network_access_allowed: bool = True
     permission_mode: str = "default"
     permission_resolver: Any | None = None
     workspace_root: str | None = None  # 工具层 workspace 根路径，权限检查边界

langchain_agentx/loop/subagent/context.py

@@ -5,17 +5,19 @@
 CC 对照：src/agent/subagent/context.ts SubagentContext 接口
 当前裁剪范围：v1 全量；system_prompt / is_async 字段驱动执行路径选择；
       ``path_prep`` 与遗留 ``cwd``/worktree 自建二选一（编排层须传 ``path_prep``）；
-      fork + worktree 时可选注入 CC 等价 ``buildWorktreeNotice`` user 消息（见 ``fork_worktree_notice``）。
+      fork + worktree 时可选注入 CC 等价 ``buildWorktreeNotice`` user 消息（见 ``fork_worktree_notice``）；
+      ``fork_from_parent=True`` 且父持有 ``AgentSessionStore`` 时子上下文使用 ``clone(file_state_only=True)``。
 """
 
 import os
 import shutil
 import uuid
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Any
 
 from langchain_agentx.loop.runtime.subagent_execution_paths import PreparedSubagentPaths
 from langchain_agentx.loop.subagent.fork_worktree_notice import build_worktree_notice
+from langchain_agentx.tool_runtime.session_store import AgentSessionStore
 from langchain_agentx.workspace import resolve_agent_workspace_config
 
 
@@ -57,7 +59,6 @@ class SubagentContext:
     workspace_root: str = ""
     agent_home: str = ".langchain_agentx"
     cwd: str | None = None
-    _file_read_state: dict[str, Any] = field(default_factory=dict)
     capabilities: Any = None  # RuntimeCapabilities，从父会话继承
 
 
@@ -178,6 +179,11 @@ def create_subagent_context(
             os.makedirs(worktree_dir, exist_ok=False)
             effective_cwd = (cwd.strip() if isinstance(cwd, str) and cwd.strip() else None) or worktree_dir
 
+    parent_store = getattr(parent_ctx, "session_store", None)
+    session_store: Any = parent_store
+    if fork_from_parent and isinstance(parent_store, AgentSessionStore):
+        session_store = parent_store.clone(file_state_only=True)
+
     return SubagentContext(
         agent_id=agent_id,
         initial_messages=initial_messages,
@@ -188,7 +194,7 @@ def create_subagent_context(
         system_prompt=system_prompt,
         fork_from_parent=fork_from_parent,
         is_async=is_async,
-        session_store=getattr(parent_ctx, "session_store", None),
+        session_store=session_store,
         tool_registry=getattr(parent_ctx, "tool_registry", None),
         tool_loader=getattr(parent_ctx, "tool_loader", None),
         parent_agent_id=getattr(parent_ctx, "agent_id", None),

langchain_agentx/tool_runtime/adapter.py

@@ -94,18 +94,20 @@ class LangChainAdapter:
         conversation_session_id = getattr(loop_config, "conversation_session_id", None) or session_id
         workspace_root = getattr(loop_config, "workspace_root", None)
         agent_home = getattr(loop_config, "agent_home", ".langchain_agentx")
-        # cwd 优先级（v0.2.0）：loop_config.cwd > state_bridge cwd > workspace_root > get_cwd()
-        # state_bridge cwd 由 BashRuntimeTool.set_cwd() 维护，支持 bash cd 后其他工具自动感知
+        # cwd：loop_config.cwd → session_store.cwd_override → workspace_root → get_cwd()
         from langchain_agentx.utils.cwd import get_cwd as _utils_get_cwd
-        from langchain_agentx.tool_runtime.state_bridge import ToolStateBridge
 
         cwd = getattr(loop_config, "cwd", None)
-        if not cwd and isinstance(state, dict):
-            # 尝试从 state_bridge 读取存储的 cwd（bash cd 设置的）
-            bridge_cwd_key = ToolStateBridge.CWD_KEY
-            bridge_cwd = state.get(bridge_cwd_key)
-            if isinstance(bridge_cwd, str) and bridge_cwd:
-                cwd = bridge_cwd
+        if not cwd:
+            sess = configurable.get("session_store")
+            from langchain_agentx.tool_runtime.session_store import (
+                AgentSessionStore as _AgentSessionStore,
+            )
+
+            if isinstance(sess, _AgentSessionStore):
+                sess_cwd = sess.cwd_override
+                if isinstance(sess_cwd, str) and sess_cwd:
+                    cwd = sess_cwd
         if not cwd:
             cwd = workspace_root or _utils_get_cwd()
         trace_enabled = bool(getattr(loop_config, "trace_enabled", True))
@@ -185,6 +187,14 @@ class LangChainAdapter:
             if low in ("markdown", "html"):
                 question_preview_format = low
 
+        network_access_allowed = bool(getattr(loop_config, "network_access_allowed", True))
+        if "network_access_allowed" in configurable:
+            network_access_allowed = bool(configurable.get("network_access_allowed"))
+
+        tool_progress_callback: Any | None = configurable.get("tool_progress_callback")
+        if tool_progress_callback is None and loop_config is not None:
+            tool_progress_callback = getattr(loop_config, "tool_progress_callback", None)
+
         return ToolExecutionContext(
             tool_name=tool_name,
             # 回退顺序：显式 tool_call_id -> config.tool_call_id -> input.tool_call_id -> input.id -> run_id
@@ -217,6 +227,8 @@ class LangChainAdapter:
             trace_emit_session_id=trace_emit_session_id,
             question_preview_format=question_preview_format,
             capabilities=capabilities,
+            network_access_allowed=network_access_allowed,
+            tool_progress_callback=tool_progress_callback,
         )
 
     def build_structured_tool(

langchain_agentx/tool_runtime/loader.py

@@ -117,6 +117,8 @@ class ToolRuntimeLoader:
         from langchain_agentx.tools.ripgrep_plugin_exclusions import PluginCacheGlobExclusions
         from langchain_agentx.tools.task_list.tool import TaskListRuntimeTool
         from langchain_agentx.tools.user_message import UserMessageTool
+        from langchain_agentx.tools.webfetch import loader as webfetch_loader
+        from langchain_agentx.tools.websearch import loader as websearch_loader
         from langchain_agentx.tools.write import WriteRuntimeTool
         from langchain_agentx.tool_runtime.state_bridge import ToolStateBridge
         from langchain_agentx.workspace.config import AgentWorkspaceConfig
@@ -153,6 +155,9 @@ class ToolRuntimeLoader:
         self.register(AskUserQuestionTool())
         self.register(TaskListRuntimeTool(config=cfg))
 
+        websearch_loader.register(self)
+        webfetch_loader.register(self)
+
         if include_agent:
             from langchain_agentx.tools.agent import AgentRuntimeTool
 

langchain_agentx/tool_runtime/models.py

@@ -14,6 +14,7 @@ runtime/models.py — 工具运行时框架核心数据模型
     readFileState、getAppState、messages 等大量 UI/应用层字段。
     本框架的 ToolExecutionContext 只保留框架稳定依赖的最小字段集，
     UI/应用层依赖由 LangChainAdapter 在边界处消费，不透传到工具内部。
+    ``session_store``（AgentSessionStore）为会话级工具态后端，供 ToolStateBridge 等读写。
     协作取消：``cancel_event`` 对应 CC ``AbortSignal``（由上层 ``set()`` 终止 ripgrep 等子进程）。
 
     CC 的 ValidationResult / PermissionResult 是 TypeScript union type。
@@ -114,6 +115,13 @@ class ToolExecutionContext:
     """
     capabilities: Any | None = None
     """可选；RuntimeCapabilities 实例，供子 Agent 继承全局 model_profile_registry。"""
+    network_access_allowed: bool = True
+    """为 False 时 WebSearch 等外网工具应在 check_permissions 中 deny。"""
+    tool_progress_callback: Any | None = None
+    """
+    可选；``RunnableConfig.configurable["tool_progress_callback"]`` 或 AgentLoopConfig 注入。
+    签名为 ``(event: ProgressEvent) -> None``（具体类型由工具包定义，避免 runtime 循环依赖）。
+    """
 
 
 # ---------------------------------------------------------------------------

langchain_agentx/tool_runtime/session_store.py

@@ -6,14 +6,24 @@ runtime/session_store.py — 会话级状态存储
     它独立于 LangGraph graph state（turn 级）和 ToolExecutionContext（call 级），
     负责跨 turn 持久化的会话状态：
 
-        file_read_state   — 文件读取记录（为 read-before-write 约束服务）
+        file_read_state   — 文件读取记录（为 read-before-write / Edit staleness 服务）
         file_history      — 文件写入/编辑历史
-        audit_log         — 工具调用审计日志
+        audit_log         — 工具调用审计日志（含权限窗口事件与工具框架审计）
         permissions_cache — 权限决策缓存（避免重复询问）
+        cwd               — Bash cd 等工作目录（与 ToolStateBridge 对齐的会话后端字段）
+        last_glob_summary — 最近一次 Glob 摘要（hint，非授权依据）
+
+链路位置：
+    GraphFactory 注入 configurable["session_store"] → LangChainAdapter.build_tool_execution_context
+    → ToolExecutionContext.session_store；ToolStateBridge **仅**读写本对象。
+
+当前裁剪范围：
+    不做磁盘持久化；不实现设计文档中的 content LRU（仅保留字段，由 Read 侧截断占位）。
 """
 
 from __future__ import annotations
 
+import copy
 import time
 import uuid
 from dataclasses import dataclass
@@ -27,6 +37,50 @@ class FileReadRecord:
     ts: float
     line_start: int | None = None
     line_end: int | None = None
+    offset: int | None = None
+    limit: int | None = None
+    mtime_ms: int = 0
+    content: str | None = None
+
+    def to_bridge_dict(self) -> dict[str, Any]:
+        """转为 ToolStateBridge / StalenessChecker 消费的 dict 形态。"""
+        out: dict[str, Any] = {
+            "tool_call_id": self.tool_call_id,
+            "ts": self.ts,
+            "offset": self.offset,
+            "limit": self.limit,
+            "mtime_ms": self.mtime_ms,
+            "line_start": self.line_start,
+            "line_end": self.line_end,
+        }
+        if self.content is not None:
+            out["content"] = self.content
+        return out
+
+    @classmethod
+    def from_bridge_dict(cls, path: str, d: dict[str, Any]) -> FileReadRecord:
+        ts_raw = d.get("ts")
+        ts = float(ts_raw) if isinstance(ts_raw, (int, float)) else time.time()
+        mtime_raw = d.get("mtime_ms", 0)
+        try:
+            mtime_ms = int(mtime_raw) if mtime_raw is not None else 0
+        except (TypeError, ValueError):
+            mtime_ms = 0
+        raw_tid = d.get("tool_call_id")
+        tool_call_id = raw_tid if isinstance(raw_tid, str) or raw_tid is None else None
+        raw_content = d.get("content")
+        content = raw_content if isinstance(raw_content, str) or raw_content is None else None
+        return cls(
+            path=path,
+            tool_call_id=tool_call_id,
+            ts=ts,
+            line_start=d.get("line_start"),
+            line_end=d.get("line_end"),
+            offset=d.get("offset"),
+            limit=d.get("limit"),
+            mtime_ms=mtime_ms,
+            content=content,
+        )
 
 
 @dataclass
@@ -47,6 +101,8 @@ class AgentSessionStore:
         self._file_history: list[FileWriteRecord] = []
         self._audit_log: list[dict[str, Any]] = []
         self._permissions_cache: dict[str, Any] = {}
+        self._cwd: str | None = None
+        self._last_glob_summary: dict[str, Any] | None = None
 
     def record_file_read(
         self,
@@ -56,6 +112,10 @@ class AgentSessionStore:
         ts: float | None = None,
         line_start: int | None = None,
         line_end: int | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+        mtime_ms: int = 0,
+        content: str | None = None,
     ) -> None:
         self._file_read_state[path] = FileReadRecord(
             path=path,
@@ -63,8 +123,31 @@ class AgentSessionStore:
             ts=ts if ts is not None else time.time(),
             line_start=line_start,
             line_end=line_end,
+            offset=offset,
+            limit=limit,
+            mtime_ms=mtime_ms,
+            content=content,
         )
 
+    def upsert_last_read_from_bridge_entry(
+        self,
+        path: str,
+        entry: dict[str, Any],
+    ) -> None:
+        """用与 LangGraph state 中 last_read 条目同构的 dict 覆盖该路径。"""
+        self._file_read_state[path] = FileReadRecord.from_bridge_dict(path, entry)
+
+    def replace_all_file_reads_from_bridge_map(self, data: dict[str, Any]) -> None:
+        """整体替换文件读映射（对应 ToolStateBridge.set_last_read_map）。"""
+        self._file_read_state.clear()
+        for path, raw in data.items():
+            if isinstance(raw, dict):
+                self._file_read_state[path] = FileReadRecord.from_bridge_dict(str(path), raw)
+
+    def get_last_read_map_bridge_view(self) -> dict[str, dict[str, Any]]:
+        """返回 path → bridge dict，供 ToolStateBridge 与 StalenessChecker 使用。"""
+        return {p: rec.to_bridge_dict() for p, rec in self._file_read_state.items()}
+
     def has_been_read(self, path: str) -> bool:
         return path in self._file_read_state
 
@@ -110,6 +193,56 @@ class AgentSessionStore:
     def get_cached_permission(self, key: str) -> Any | None:
         return self._permissions_cache.get(key)
 
+    # ---- cwd（与 ToolStateBridge 会话后端对齐）----
+
+    def get_cwd(self, *, initial: str | None = None) -> str:
+        """已 set 的会话 cwd → initial → os.getcwd()。"""
+        if isinstance(self._cwd, str) and self._cwd:
+            return self._cwd
+        if isinstance(initial, str) and initial:
+            return initial
+        import os
+
+        return os.getcwd()
+
+    def set_cwd(self, cwd: str) -> None:
+        self._cwd = cwd
+
+    def clear_cwd(self) -> None:
+        self._cwd = None
+
+    @property
+    def cwd_override(self) -> str | None:
+        """Bash cd 等显式设置过的 cwd；未设置时为 None。"""
+        if isinstance(self._cwd, str) and self._cwd:
+            return self._cwd
+        return None
+
+    # ---- last_glob_summary ----
+
+    def set_last_glob_summary(self, payload: dict[str, Any]) -> None:
+        self._last_glob_summary = dict(payload)
+
+    def get_last_glob_summary(self) -> dict[str, Any] | None:
+        if self._last_glob_summary is None:
+            return None
+        return dict(self._last_glob_summary)
+
+    def clear_last_glob_summary(self) -> None:
+        self._last_glob_summary = None
+
+    # ---- fork：仅克隆文件读状态（权限 / cwd / glob 不共享）----
+
+    def clone(self, *, file_state_only: bool = True) -> AgentSessionStore:
+        new = AgentSessionStore(session_id=str(uuid.uuid4()))
+        new._file_read_state = {
+            k: copy.deepcopy(v) for k, v in self._file_read_state.items()
+        }
+        if not file_state_only:
+            new._audit_log = copy.deepcopy(self._audit_log)
+            new._file_history = copy.deepcopy(self._file_history)
+        return new
+
     @property
     def created_at(self) -> float:
         return self._created_at
@@ -122,6 +255,8 @@ class AgentSessionStore:
             "file_writes": len(self._file_history),
             "audit_entries": len(self._audit_log),
             "cached_permissions": len(self._permissions_cache),
+            "has_cwd_override": bool(self._cwd),
+            "has_glob_summary": self._last_glob_summary is not None,
         }
 
     def __repr__(self) -> str:

langchain_agentx/tool_runtime/smoke_test_runtime.py

@@ -52,7 +52,17 @@ def _load_module(sub: str) -> None:
     spec.loader.exec_module(mod)
 
 
-for _sub in ["models", "errors", "base", "policy", "state_bridge", "pipeline", "adapter", "registry"]:
+for _sub in [
+    "models",
+    "errors",
+    "base",
+    "policy",
+    "session_store",
+    "state_bridge",
+    "pipeline",
+    "adapter",
+    "registry",
+]:
     _load_module(_sub)
 
 # ---------------------------------------------------------------------------
@@ -65,6 +75,7 @@ from langchain_agentx.tool_runtime.pipeline     import ToolExecutorPipeline
 from langchain_agentx.tool_runtime.adapter      import LangChainAdapter           # noqa: E402
 from langchain_agentx.tool_runtime.registry     import RuntimeToolRegistry        # noqa: E402
 from langchain_agentx.tool_runtime.policy       import ToolPolicyConfig, DefaultPolicyEngine  # noqa: E402
+from langchain_agentx.tool_runtime.session_store import AgentSessionStore  # noqa: E402
 from langchain_agentx.tool_runtime.state_bridge import ToolStateBridge            # noqa: E402
 from pydantic import BaseModel                                                      # noqa: E402
 
@@ -104,6 +115,7 @@ def _make_ctx(state=None) -> ToolExecutionContext:
         tool_call_id="call_001",
         input_args={"message": "hello"},
         state=state if state is not None else {},
+        session_store=AgentSessionStore("smoke"),
     )
 
 
@@ -217,7 +229,11 @@ def test_state_bridge() -> None:
     bridge = ToolStateBridge()
     state = {}
     ctx = ToolExecutionContext(
-        tool_name="echo", tool_call_id="c1", input_args={}, state=state
+        tool_name="echo",
+        tool_call_id="c1",
+        input_args={},
+        state=state,
+        session_store=AgentSessionStore("smoke-bridge"),
     )
 
     _td = pathlib.Path(tempfile.gettempdir())

langchain_agentx/tool_runtime/state_bridge.py

@@ -2,23 +2,16 @@
 runtime/state_bridge.py — 工具级最小共享状态管理
 
 职责：
-    管理工具执行过程中的跨工具共享状态，维护：
-    - last_read_map：记录每个文件最近一次被读取的信息，
-      为 write/edit 工具的 read-before-write 约束提供基础
-    - tool_audit：工具调用审计日志，记录每次工具执行的关键信息
-    - last_glob_summary（v2-D）：最近一次 Glob 的摘要，供 Read/Grep 等读侧 **hint**（不替代授权）
-
-    状态存储在 ToolExecutionContext.state（LangGraph state）中，
-    通过固定 key 读写，不引入独立的状态存储。
-
-与 CC 对比：
-    CC 中通过 ToolUseContext.readFileState 维护文件读取状态，
-    通过 getAppState / setAppState 读写应用级状态。
-    本框架将这些能力收敛到 ToolStateBridge，通过 LangGraph state
-    作为底层存储，保持与 agent loop 的状态一致性。
-    v1：last_read_map（含 mtime_ms、可选 content，供 Edit staleness 方案 B）、tool_audit；
-    v2-D：last_glob_summary（可选写入，见 GlobRuntimeTool.after_invoke）。
-    不承担业务 workflow state。
+    管理工具执行过程中的跨工具共享状态（last_read_map、tool_audit、last_glob_summary、cwd），
+    为 write/edit 的 read-before-write、Edit staleness、Glob hint、Bash cd 等提供统一入口。
+
+链路位置：
+    ToolRuntimeLoader.register_default_tools 注入共享 ToolStateBridge；Read/Edit/Bash/Glob
+    after_invoke 或校验阶段调用本类。存储后端**仅**为 ``ToolExecutionContext.session_store``
+   （``AgentSessionStore``），由 GraphFactory 经 ``configurable`` 注入。
+
+当前裁剪范围：
+    不再读写 LangGraph ``ctx.state`` 中 ``_tool_*`` 键（迁移完成）；不在此模块内做 LRU。
 """
 
 from __future__ import annotations
@@ -26,27 +19,17 @@ from __future__ import annotations
 from typing import Any
 
 from .models import ToolExecutionContext
+from .session_store import AgentSessionStore
 
 
 class ToolStateBridge:
     """
     工具级最小共享状态管理器。
 
-    通过 ToolExecutionContext.state（LangGraph state dict）读写状态，
-    使用固定 key 隔离工具框架状态与业务状态。
-
-    维护：
-        last_read_map      — 文件最近读取记录（为 read-before-write 规则服务）
-        tool_audit         — 工具调用审计日志
-        last_glob_summary  — 最近一次 Glob 摘要（仅路径样本，防 state 膨胀）
-        cwd                — 当前工作目录（跨工具共享，bash cd 后 read/grep 自动感知）
-
-    不承担：
-        业务 workflow state
-        UI 临时态
-        task state
+    要求 ``ctx.session_store`` 为 ``AgentSessionStore``；否则各方法抛出 ``ValueError``。
     """
 
+    # 历史 LangGraph ctx.state 键名；bridge 已不读写 state，常量保留供设计文档/外部对照与 rg。
     LAST_READ_MAP_KEY = "_tool_last_read_map"
     AUDIT_LOG_KEY = "_tool_audit_log"
     LAST_GLOB_SUMMARY_KEY = "_tool_last_glob_summary"
@@ -61,32 +44,30 @@ class ToolStateBridge:
         """
         self._initial_cwd = initial_cwd
 
+    def _require_store(self, ctx: ToolExecutionContext) -> AgentSessionStore:
+        raw = ctx.session_store
+        if not isinstance(raw, AgentSessionStore):
+            raise ValueError(
+                "ToolStateBridge requires ToolExecutionContext.session_store to be an "
+                "AgentSessionStore instance (LangGraph state _tool_* keys are no longer used)."
+            )
+        return raw
+
     # ---- last_read_map ----
 
     def get_last_read_map(self, ctx: ToolExecutionContext) -> dict[str, Any]:
-        """
-        获取 last_read_map。
-
-        结构（每条 file_path）：至少含 ``tool_call_id``、``ts``；Read 写入时还含
-        ``offset``、``limit``、``mtime_ms``；可选 ``content``（文本快照或占位符，
-        供 Edit staleness）、``line_start`` / ``line_end``（Read 元数据）。
-
-        不存在时返回空 dict（不修改 state）。
-        """
-        return ctx.state.get(self.LAST_READ_MAP_KEY) or {}
+        return self._require_store(ctx).get_last_read_map_bridge_view()
 
     def set_last_read_map(
         self,
         ctx: ToolExecutionContext,
         value: dict[str, Any],
     ) -> None:
-        """更新 last_read_map，整体替换。"""
-        ctx.state[self.LAST_READ_MAP_KEY] = value
+        self._require_store(ctx).replace_all_file_reads_from_bridge_map(value)
 
     def get_last_read(
         self, ctx: ToolExecutionContext, file_path: str
     ) -> dict[str, Any] | None:
-        """返回 ``file_path`` 对应的最近一次读取记录；无则 ``None``。"""
         raw = self.get_last_read_map(ctx).get(file_path)
         return raw if isinstance(raw, dict) else None
 
@@ -102,13 +83,6 @@ class ToolStateBridge:
         line_start: int | None = None,
         line_end: int | None = None,
     ) -> None:
-        """
-        写入/覆盖某路径的最近一次读取记录（Read ``after_invoke`` 主入口）。
-
-        ``content``：可选；UTF-8 文本快照或 ``<image:...>`` 等占位符，供 Edit
-        staleness 内容对比；过大文本由调用方截断为占位符。
-        """
-        last_read_map = self.get_last_read_map(ctx)
         entry: dict[str, Any] = {
             "tool_call_id": ctx.tool_call_id,
             "ts": ctx.now_ts,
@@ -120,8 +94,7 @@ class ToolStateBridge:
         }
         if content is not None:
             entry["content"] = content
-        last_read_map[file_path] = entry
-        self.set_last_read_map(ctx, last_read_map)
+        self._require_store(ctx).upsert_last_read_from_bridge_entry(file_path, entry)
 
     def record_read(
         self,
@@ -131,10 +104,6 @@ class ToolStateBridge:
         line_start: int | None = None,
         line_end: int | None = None,
     ) -> None:
-        """
-        记录一次文件读取（兼容旧 API / 单测），等价于 ``offset=0``、``mtime_ms=0``
-        的 ``set_last_read``。
-        """
         self.set_last_read(
             ctx,
             file_path,
@@ -146,9 +115,6 @@ class ToolStateBridge:
         )
 
     def has_been_read(self, ctx: ToolExecutionContext, file_path: str) -> bool:
-        """
-        检查文件是否已被读取过（用于 read-before-write 约束）。
-        """
         return file_path in self.get_last_read_map(ctx)
 
     # ---- tool_audit ----
@@ -158,24 +124,12 @@ class ToolStateBridge:
         ctx: ToolExecutionContext,
         record: dict[str, Any],
     ) -> None:
-        """
-        追加一条审计记录到 tool_audit 列表。
-
-        record 建议包含：
-            tool        — 工具名
-            tool_call_id — 调用 ID
-            ts          — 时间戳
-            以及工具特定的关键字段（如 file_path、lines_read 等）
-        """
-        audit_log: list = ctx.state.get(self.AUDIT_LOG_KEY) or []
-        audit_log.append(record)
-        ctx.state[self.AUDIT_LOG_KEY] = audit_log
+        self._require_store(ctx).append_audit(record)
 
     def get_audit_log(self, ctx: ToolExecutionContext) -> list[dict[str, Any]]:
-        """获取完整审计日志，不存在时返回空列表。"""
-        return ctx.state.get(self.AUDIT_LOG_KEY) or []
+        return self._require_store(ctx).get_audit_log()
 
-    # ---- last_glob_summary（v2-D，本工程专有；CC 无对等）----
+    # ---- last_glob_summary ----
 
     def record_last_glob(
         self,
@@ -189,13 +143,8 @@ class ToolStateBridge:
         truncated: bool,
         offset: int,
     ) -> None:
-        """
-        覆盖写入最近一次 Glob 摘要（**不**用于 PolicyEngine，仅供 hint）。
-
-        ``filenames`` 为当前页相对路径列表；仅持久化前 ``MAX_GLOB_SAMPLE_PATHS`` 条。
-        """
         sample = list(filenames[: self.MAX_GLOB_SAMPLE_PATHS])
-        ctx.state[self.LAST_GLOB_SUMMARY_KEY] = {
+        payload = {
             "pattern": pattern,
             "search_root": search_root,
             "sample_paths": sample,
@@ -206,35 +155,18 @@ class ToolStateBridge:
             "tool_call_id": ctx.tool_call_id,
             "ts": ctx.now_ts,
         }
+        self._require_store(ctx).set_last_glob_summary(payload)
 
     def get_last_glob_summary(self, ctx: ToolExecutionContext) -> dict[str, Any] | None:
-        """读取最近一次 Glob 摘要；不存在或类型不对时返回 ``None``。"""
-        raw = ctx.state.get(self.LAST_GLOB_SUMMARY_KEY)
-        return raw if isinstance(raw, dict) else None
+        return self._require_store(ctx).get_last_glob_summary()
 
     def clear_last_glob_summary(self, ctx: ToolExecutionContext) -> None:
-        """清除摘要（测试或显式重置会话工具态时使用）。"""
-        ctx.state.pop(self.LAST_GLOB_SUMMARY_KEY, None)
+        self._require_store(ctx).clear_last_glob_summary()
 
-    # ---- cwd（跨工具共享工作目录，v0.2.0 新增）----
+    # ---- cwd ----
 
     def get_cwd(self, ctx: ToolExecutionContext) -> str:
-        """获取当前工作目录。
-
-        优先级：
-            1. state 中已存储的 cwd（之前 cd 命令设置的）
-            2. initial_cwd（构造时传入）
-            3. os.getcwd()（进程当前目录）
-        """
-        stored = ctx.state.get(self.CWD_KEY)
-        if isinstance(stored, str) and stored:
-            return stored
-        if self._initial_cwd:
-            return self._initial_cwd
-        import os
-
-        return os.getcwd()
+        return self._require_store(ctx).get_cwd(initial=self._initial_cwd)
 
     def set_cwd(self, ctx: ToolExecutionContext, cwd: str) -> None:
-        """设置当前工作目录（bash cd 命令后调用）。"""
-        ctx.state[self.CWD_KEY] = cwd
+        self._require_store(ctx).set_cwd(cwd)

langchain_agentx/tools/bash/tool.py

@@ -266,7 +266,7 @@ class BashRuntimeTool(RuntimeTool):
                 trace_context=TraceContext.from_ctx(ctx),
             )
 
-        current_cwd = self._get_current_cwd()
+        current_cwd = self._get_current_cwd(ctx)
         analysis = self._ast_analyzer.analyze(command)
         hardening_decision = self._security_hardener.check_command(
             command=command,
@@ -855,12 +855,18 @@ class BashRuntimeTool(RuntimeTool):
             ask_prompt=prompt,
         )
 
-    def _get_current_cwd(self) -> str:
+    def _get_current_cwd(self, ctx: ToolExecutionContext | None = None) -> str:
         """获取当前工作目录（用于 check_permissions 阶段）。
 
-        注意：此时 ctx 不可用，因此使用初始 cwd 或 os.getcwd()。
-        实际执行时 invoke() 会用 ctx 获取最新的 cwd。
+        与 ``invoke()`` 一致：优先 ``state_bridge.get_cwd(ctx)``；否则
+        ``_initial_cwd``（构造时从 bridge 属性读取）；最后 ``os.getcwd()``。
         """
+        if self._state_bridge is not None and ctx is not None:
+            getter = getattr(self._state_bridge, "get_cwd", None)
+            if callable(getter):
+                cwd = getter(ctx)
+                if cwd:
+                    return str(cwd)
         if self._initial_cwd:
             return self._initial_cwd
         return os.getcwd()