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

langchain_agentx/tools/bash/tool.py

@@ -0,0 +1,939 @@
+"""
+tools/bash/tool.py — BashRuntimeTool 主类
+
+职责：
+    实现 RuntimeTool 的所有生命周期 hook，编排命令执行完整流程。
+    核心 I/O 委托给 BashBackend，安全检查来自 security.py，
+    语义解析来自 semantics.py，配置来自 limits.py。
+
+对应 CC BashTool.tsx 主体逻辑（call() + validateInput() + checkPermissions()）。
+present() 对应 CC UI.tsx 的 renderToolResultMessage()。
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+import hashlib
+import os
+import tempfile
+from typing import Any
+
+from langchain_agentx.tool_runtime.base import RuntimeTool
+from langchain_agentx.tool_runtime.models import (
+    AuthorizationDecision,
+    ToolExecutionContext,
+    ToolResultEnvelope,
+    ValidationResult,
+)
+
+from .ast_security import (
+    BashAstAnalyzer,
+)
+from .bash_hardening import BashSecurityHardener
+from .backend import BashBackend, ExecuteResult, strip_empty_lines
+from .limits import get_bash_limits
+from .mode_validation import BashPermissionModeValidator
+from .models import BashToolInput, BashToolOutput
+from .observability import (
+    BashEventBuffer,
+    TraceContext,
+    build_decision_observability,
+    finalize_observability_payload,
+)
+from .path_security import BashPathSecurityAnalyzer
+from .prompt import DESCRIPTION, SILENT_COMMANDS, TOOL_NAME
+from .read_only_validation import BashReadOnlyClassifier
+from .result_presenter import BashResultPresenter
+from .sandbox_decision import BashSandboxDecisionEngine
+from .sed_edit_parser import BashSedEditParser
+from .sed_validation import BashSedCommandValidator
+from .security import (
+    detect_destructive_patterns,
+    detect_infinite_output,
+    detect_interactive_command,
+    detect_sleep_block,
+)
+from .semantics import interpret_command_result
+
+
+def _as_bash_input_dict(data: dict[str, Any] | BashToolInput) -> dict[str, Any]:
+    """兼容层：统一将工具入参归一化为 dict。"""
+    if isinstance(data, dict):
+        return data
+    if isinstance(data, BashToolInput):
+        return data.model_dump()
+    msg = f"Unsupported bash tool input type: {type(data)!r}"
+    raise TypeError(msg)
+
+
+class BashRuntimeTool(RuntimeTool):
+    """
+    Shell 命令执行工具。
+
+    对应 CC BashTool（BashTool.tsx）。
+
+    特性：
+        is_destructive=True       具有写副作用，通过 PolicyEngine 权限检查
+        is_read_only=False        保守默认；动态判断只读命令
+        is_concurrency_safe=False 同一 shell 有 cwd 状态，不允许并发
+        never_truncate=False      走 ToolOutputManager 截断（max 30KB）
+        max_result_size_chars     对应 CC maxResultSizeChars=30_000
+    """
+
+    name: str = TOOL_NAME
+    description: str = DESCRIPTION
+    input_model = BashToolInput
+    is_destructive: bool = True
+    is_concurrency_safe: bool = False
+    never_truncate: bool = False
+    max_result_size_chars: int = 30_000
+
+    def __init__(
+        self,
+        *,
+        policy: Any | None = None,
+        state_bridge: Any | None = None,
+        backend: BashBackend | None = None,
+        ast_analyzer: BashAstAnalyzer | None = None,
+        path_security: BashPathSecurityAnalyzer | None = None,
+        read_only_classifier: BashReadOnlyClassifier | None = None,
+        mode_validator: BashPermissionModeValidator | None = None,
+        sed_validator: BashSedCommandValidator | None = None,
+        sed_parser: BashSedEditParser | None = None,
+        security_hardener: BashSecurityHardener | None = None,
+        sandbox_decider: BashSandboxDecisionEngine | None = None,
+        result_presenter: BashResultPresenter | None = None,
+    ) -> None:
+        super().__init__(policy=policy, state_bridge=state_bridge)
+        self._backend = backend or BashBackend()
+        self._ast_analyzer = ast_analyzer or BashAstAnalyzer()
+        self._path_security = path_security or BashPathSecurityAnalyzer()
+        self._read_only_classifier = read_only_classifier or BashReadOnlyClassifier()
+        self._mode_validator = mode_validator or BashPermissionModeValidator()
+        self._sed_parser = sed_parser or BashSedEditParser()
+        self._sed_validator = sed_validator or BashSedCommandValidator(self._sed_parser)
+        self._security_hardener = security_hardener or BashSecurityHardener()
+        self._sandbox_decider = sandbox_decider or BashSandboxDecisionEngine()
+        self._result_presenter = result_presenter or BashResultPresenter()
+
+    # ------------------------------------------------------------------
+    # Hook 1: normalize_input
+    # ------------------------------------------------------------------
+
+    def normalize_input(
+        self, raw: dict[str, Any], ctx: ToolExecutionContext
+    ) -> dict[str, Any]:
+        """
+        输入预处理：
+        - timeout 值 clamp 到最大值
+        - command 首尾空白清理
+
+        对应 CC backfillObservableInput() 的 timeout 处理。
+        """
+        raw = dict(raw)
+        limits = get_bash_limits()
+
+        # timeout clamp
+        if raw.get("timeout") is not None:
+            raw["timeout"] = min(int(raw["timeout"]), limits["max_timeout_sec"])
+
+        # 清理命令首尾空白（模型有时会多加换行）
+        if raw.get("command"):
+            raw["command"] = raw["command"].strip()
+
+        if "dangerouslyDisableSandbox" in raw and "dangerously_disable_sandbox" not in raw:
+            raw["dangerously_disable_sandbox"] = bool(raw["dangerouslyDisableSandbox"])
+
+        return raw
+
+    # ------------------------------------------------------------------
+    # Hook 3: validate_input
+    # ------------------------------------------------------------------
+
+    def validate_input(
+        self, data: dict[str, Any], ctx: ToolExecutionContext
+    ) -> ValidationResult:
+        """
+        语义校验（对应 CC validateInput() + checkPermissionMode() 前置检查）。
+
+        检查顺序（快速失败原则）：
+            [1] 空命令检查
+            [2] sleep 大值检测（提示使用后台）
+            [3] 交互式命令检测（需要 TTY）
+            [4] 无限输出命令检测
+        """
+        input_data = _as_bash_input_dict(data)
+        command = str(input_data.get("command", ""))
+        limits = get_bash_limits()
+
+        # [1] 空命令
+        if not command.strip():
+            return ValidationResult(ok=False, message="Command cannot be empty.")
+
+        # [2] sleep 大值检测
+        sleep_sec = detect_sleep_block(command, limits["sleep_block_threshold_sec"])
+        if sleep_sec is not None:
+            threshold = limits["sleep_block_threshold_sec"]
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"Blocked: sleep {sleep_sec}s would block for too long "
+                    f"(threshold: {threshold}s). "
+                    "Use run_in_background=true for long-running commands, "
+                    f"or keep sleep under {threshold} seconds."
+                ),
+            )
+
+        # [3] 交互式命令检测
+        interactive = detect_interactive_command(command)
+        if interactive:
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"Cannot run interactive command '{interactive}': "
+                    "it requires a TTY which is not available in this environment. "
+                    "Use non-interactive alternatives instead."
+                ),
+            )
+
+        # [4] 无限输出检测
+        if detect_infinite_output(command):
+            return ValidationResult(
+                ok=False,
+                message=(
+                    "This command would produce infinite output. "
+                    "If you need to capture output, add a size limit (e.g. head -n 100) "
+                    "or use run_in_background=true with a timeout."
+                ),
+            )
+
+        return ValidationResult(ok=True)
+
+    # ------------------------------------------------------------------
+    # Hook 4: check_permissions
+    # ------------------------------------------------------------------
+
+    def check_permissions(
+        self, data: dict[str, Any], ctx: ToolExecutionContext
+    ) -> AuthorizationDecision:
+        """
+        Bash 权限检查。
+
+        v2 对照 CC `checkCommandOperatorPermissions()`：
+        - 先用 AST 识别高风险 shell 结构（subshell / command substitution / nested shell）
+        - 再把顶层 pipeline / list 拆成 segment，逐段做权限决策
+        - 每个 segment 动态计算 `is_read_only` / `is_destructive`，让 read_only_mode 生效
+
+        对应 CC bashToolHasPermission() 的规则匹配层（[8] 规则匹配）。
+        """
+        trace: list[dict[str, Any]] = []
+        input_data = _as_bash_input_dict(data)
+        command = str(input_data.get("command", ""))
+
+        preflight_mode_decision = self._mode_validator.check_preflight(command, ctx)
+        trace.append(
+            {
+                "layer": "mode_preflight",
+                "command": command,
+                "behavior": preflight_mode_decision.behavior,
+                "policy_id": preflight_mode_decision.policy_id,
+                "message": preflight_mode_decision.message,
+            }
+        )
+        if preflight_mode_decision.behavior == "allow":
+            return self._with_observability(
+                AuthorizationDecision(
+                behavior="allow",
+                message=preflight_mode_decision.message,
+                policy_id=preflight_mode_decision.policy_id,
+                ),
+                trace=trace,
+                trace_context=TraceContext.from_ctx(ctx),
+            )
+        if preflight_mode_decision.behavior == "deny":
+            return self._with_observability(
+                AuthorizationDecision(
+                behavior="deny",
+                message=preflight_mode_decision.message,
+                policy_id=preflight_mode_decision.policy_id,
+                ),
+                trace=trace,
+                trace_context=TraceContext.from_ctx(ctx),
+            )
+
+        current_cwd = self._get_current_cwd()
+        analysis = self._ast_analyzer.analyze(command)
+        hardening_decision = self._security_hardener.check_command(
+            command=command,
+            analysis=analysis,
+            cwd=current_cwd,
+        )
+        trace.append(
+            {
+                "layer": "hardening_command",
+                "command": command,
+                "behavior": hardening_decision.behavior if hardening_decision else "allow",
+                "policy_id": hardening_decision.policy_id if hardening_decision else None,
+            }
+        )
+        if hardening_decision is not None:
+            decision = self._mode_validator.finalize_decision(
+                command=command,
+                ctx=ctx,
+                decision=hardening_decision,
+            )
+            trace.append(
+                {
+                    "layer": "mode_finalize",
+                    "command": command,
+                    "behavior": decision.behavior,
+                    "policy_id": decision.policy_id,
+                }
+            )
+            return self._with_observability(
+                decision,
+                trace=trace,
+                trace_context=TraceContext.from_ctx(ctx),
+            )
+        approval_reason = self._ast_analyzer.get_approval_reason(analysis)
+        if approval_reason:
+            decision = self._mode_validator.finalize_decision(
+                command=command,
+                ctx=ctx,
+                decision=AuthorizationDecision(
+                    behavior="ask",
+                    message=approval_reason,
+                    policy_id="bash_ast_v2",
+                    ask_prompt=approval_reason,
+                ),
+            )
+            trace.append(
+                {
+                    "layer": "ast_guard",
+                    "command": command,
+                    "behavior": "ask",
+                    "policy_id": "bash_ast_v2",
+                }
+            )
+            trace.append(
+                {
+                    "layer": "mode_finalize",
+                    "command": command,
+                    "behavior": decision.behavior,
+                    "policy_id": decision.policy_id,
+                }
+            )
+            return self._with_observability(
+                decision,
+                trace=trace,
+                trace_context=TraceContext.from_ctx(ctx),
+            )
+
+        segments = [
+            segment.strip()
+            for segment in analysis.permission_segments
+            if segment and segment.strip()
+        ]
+        if not segments:
+            decision = self._mode_validator.finalize_decision(
+                command=command,
+                ctx=ctx,
+                decision=self._authorize_command_segment(
+                    command,
+                    analysis,
+                    ctx,
+                    current_cwd,
+                    compound_has_cd=False,
+                ),
+            )
+            trace.append(
+                {
+                    "layer": "segment_single",
+                    "command": command,
+                    "behavior": decision.behavior,
+                    "policy_id": decision.policy_id,
+                }
+            )
+            return self._with_observability(
+                decision,
+                trace=trace,
+                trace_context=TraceContext.from_ctx(ctx),
+            )
+
+        compound_has_cd = "cd" in analysis.normalized_base_commands and len(segments) > 1
+
+        decisions: list[tuple[str, AuthorizationDecision]] = []
+        for segment in segments:
+            segment_analysis = self._ast_analyzer.analyze(segment)
+            seg_decision = self._mode_validator.finalize_decision(
+                command=segment,
+                ctx=ctx,
+                decision=self._authorize_command_segment(
+                    segment,
+                    segment_analysis,
+                    ctx,
+                    current_cwd,
+                    compound_has_cd=compound_has_cd,
+                ),
+            )
+            trace.append(
+                {
+                    "layer": "segment",
+                    "command": segment,
+                    "behavior": seg_decision.behavior,
+                    "policy_id": seg_decision.policy_id,
+                }
+            )
+            decisions.append(
+                (
+                    segment,
+                    seg_decision,
+                )
+            )
+
+        denied = next((item for item in decisions if item[1].behavior == "deny"), None)
+        if denied is not None:
+            segment, decision = denied
+            return self._with_observability(
+                AuthorizationDecision(
+                behavior="deny",
+                message=decision.message or f"Permission denied for segment: {segment}",
+                policy_id=decision.policy_id or "bash_segment_deny",
+                ),
+                trace=trace,
+                trace_context=TraceContext.from_ctx(ctx),
+            )
+
+        asked = next((item for item in decisions if item[1].behavior == "ask"), None)
+        if asked is not None:
+            segment, decision = asked
+            message = decision.message or f"This command segment requires approval: {segment}"
+            return self._with_observability(
+                AuthorizationDecision(
+                behavior="ask",
+                message=message,
+                policy_id=decision.policy_id or "bash_segment_ask",
+                ask_prompt=decision.ask_prompt or message,
+                updated_input=decision.updated_input,
+                ),
+                trace=trace,
+                trace_context=TraceContext.from_ctx(ctx),
+            )
+
+        updated_input = next(
+            (item[1].updated_input for item in decisions if item[1].updated_input),
+            None,
+        )
+        return self._with_observability(
+            AuthorizationDecision(behavior="allow", updated_input=updated_input),
+            trace=trace,
+            trace_context=TraceContext.from_ctx(ctx),
+        )
+
+    # ------------------------------------------------------------------
+    # Core: invoke
+    # ------------------------------------------------------------------
+
+    def invoke(
+        self, data: dict[str, Any], ctx: ToolExecutionContext
+    ) -> BashToolOutput:
+        """
+        核心执行：后台任务路径 or 同步执行路径。
+        对应 CC BashTool.tsx::call()。
+        """
+        input_data = _as_bash_input_dict(data)
+        command = str(input_data.get("command", ""))
+        timeout_raw = input_data.get("timeout")
+        timeout_opt = int(timeout_raw) if timeout_raw is not None else None
+        run_in_background_flag = bool(input_data.get("run_in_background", False))
+        disable_sandbox_flag = bool(input_data.get("dangerously_disable_sandbox", False))
+
+        limits = get_bash_limits()
+        timeout_sec = timeout_opt if timeout_opt is not None else limits["default_timeout_sec"]
+
+        # 从 state_bridge 取上次 cwd（跨调用持久化）
+        cwd: str | None = None
+        if self._state_bridge is not None:
+            cwd = self._state_bridge.get_cwd() if hasattr(self._state_bridge, "get_cwd") else None
+
+        sandbox_decision = self._sandbox_decider.decide(
+            command=command,
+            dangerously_disable_sandbox=disable_sandbox_flag,
+            ctx=ctx,
+        )
+        auto_backgrounded = False
+        auto_bg_reason = "none"
+        run_in_background = run_in_background_flag
+        if (
+            not run_in_background
+            and limits["auto_background_enabled"]
+            and timeout_sec >= limits["auto_background_timeout_sec"]
+        ):
+            run_in_background = True
+            auto_backgrounded = True
+            auto_bg_reason = "long_timeout_policy"
+        elif run_in_background:
+            auto_bg_reason = "explicit_request"
+
+        # ------------------------------------------------------------------
+        # 后台执行路径
+        # ------------------------------------------------------------------
+        if run_in_background:
+            task = self._backend.submit_background(
+                command=command,
+                cwd=cwd,
+                output_dir=limits["background_task_output_dir"],
+                sandbox_decision=sandbox_decision,
+            )
+            snapshot = self._backend.build_background_snapshot(task)
+            ev = BashEventBuffer(trace_context=TraceContext.from_ctx(ctx), scenario="background")
+            ev.add(
+                "sandbox_decided",
+                sandboxed=task.sandboxed,
+                reason=sandbox_decision.reason,
+            )
+            ev.add(
+                "auto_background_decision",
+                chosen=run_in_background,
+                auto_backgrounded=auto_backgrounded,
+                reason_code=auto_bg_reason,
+                timeout_sec=timeout_sec,
+                threshold_sec=limits["auto_background_timeout_sec"],
+            )
+            ev.add(
+                "task_submitted",
+                mode="background",
+                auto_backgrounded=auto_backgrounded,
+                timeout_sec=timeout_sec,
+            )
+            ev.add("task_state_changed", from_state="created", to_state="running")
+            ev.add("task_state_snapshot", task_status=snapshot.task_status, task_mode=snapshot.task_mode)
+            return BashToolOutput(
+                stdout="",
+                interrupted=False,
+                exit_code=0,
+                background_task_id=task.task_id,
+                background_output_path=task.output_path,
+                task_mode=snapshot.task_mode,
+                task_status=snapshot.task_status,
+                task_exit_code=snapshot.exit_code,
+                auto_backgrounded=auto_backgrounded,
+                sandboxed=task.sandboxed,
+                sandbox_temp_dir=task.sandbox_temp_dir,
+                sandbox_bypass_reason=(
+                    None if task.sandboxed else sandbox_decision.reason
+                ),
+                observability=finalize_observability_payload(ev.to_observability()),
+            )
+
+        simulated_edit = self._consume_pending_sed_edit(command, ctx)
+        if simulated_edit is not None:
+            path = Path(simulated_edit["absolute_path"])
+            path.write_text(simulated_edit["new_content"], encoding="utf-8")
+            ev = BashEventBuffer(trace_context=TraceContext.from_ctx(ctx), scenario="sed_preview")
+            ev.add("sed_preview_apply", mode="foreground")
+            return BashToolOutput(
+                stdout="",
+                interrupted=False,
+                exit_code=0,
+                no_output_expected=True,
+                observability=finalize_observability_payload(ev.to_observability()),
+            )
+
+        # ------------------------------------------------------------------
+        # 同步执行路径
+        # ------------------------------------------------------------------
+        if sandbox_decision.use_sandbox:
+            result = self._backend.execute(
+                command=command,
+                cwd=cwd,
+                timeout_sec=timeout_sec,
+                sandbox_decision=sandbox_decision,
+                session_key=ctx.thread_id,
+            )
+        else:
+            stream_chunks: list[str] = []
+            final_exit_code = 0
+            final_interrupted = False
+            final_cwd_after: str | None = None
+            for event in self._backend.stream_execute_iter(
+                command=command,
+                cwd=cwd,
+                timeout_sec=timeout_sec,
+                sandbox_decision=sandbox_decision,
+                session_key=ctx.thread_id,
+            ):
+                if event.kind == "chunk" and event.chunk:
+                    stream_chunks.append(event.chunk)
+                elif event.kind == "final":
+                    final_exit_code = event.exit_code or 0
+                    final_interrupted = bool(event.interrupted)
+                    final_cwd_after = event.cwd_after
+            merged_stdout, parsed_cwd_after = _strip_stream_cwd_marker("".join(stream_chunks))
+            result = ExecuteResult(
+                stdout=merged_stdout,
+                exit_code=final_exit_code,
+                interrupted=final_interrupted,
+                cwd_after=parsed_cwd_after or final_cwd_after,
+                sandboxed=False,
+                sandbox_bypass_reason=sandbox_decision.reason,
+            )
+
+        # 更新 cwd（如果 cd 命令改变了目录）
+        if (
+            self._state_bridge is not None
+            and result.cwd_after is not None
+            and result.cwd_after != cwd
+            and hasattr(self._state_bridge, "set_cwd")
+        ):
+            self._state_bridge.set_cwd(result.cwd_after)
+
+        # 危险命令警告（非阻断）
+        destructive_warning = detect_destructive_patterns(command)
+        snapshot = self._backend.build_foreground_snapshot(result)
+
+        # 退出码语义解析
+        cmd_result = interpret_command_result(
+            command, result.exit_code, result.stdout
+        )
+
+        # 真正错误时抛异常（pipeline 捕获 → error envelope）
+        if cmd_result.is_error and result.exit_code != 0 and not result.sandbox_violation_message:
+            raise RuntimeError(
+                f"Command failed with exit code {result.exit_code}:\n"
+                f"{strip_empty_lines(result.stdout)}"
+            )
+
+        stdout_text = strip_empty_lines(result.stdout)
+        overflow_file: str | None = None
+        output_truncated = False
+        max_chars = limits["max_output_chars"]
+        if len(stdout_text) > max_chars:
+            spill_root = os.path.join(
+                os.path.expanduser("~/.cache/langchain_agentx/bash_spill"),
+            )
+            os.makedirs(spill_root, exist_ok=True)
+            fd, overflow_file = tempfile.mkstemp(
+                suffix=".txt", prefix="bash_out_", dir=spill_root, text=True
+            )
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(stdout_text)
+            stdout_text = stdout_text[:max_chars]
+            output_truncated = True
+
+        ev = BashEventBuffer(trace_context=TraceContext.from_ctx(ctx), scenario="foreground")
+        ev.add("task_state_changed", from_state="created", to_state="running")
+        ev.add(
+            "sandbox_decided",
+            sandboxed=result.sandboxed,
+            reason=sandbox_decision.reason,
+        )
+        ev.add(
+            "command_started",
+            mode="foreground",
+            timeout_sec=timeout_sec,
+        )
+        if not sandbox_decision.use_sandbox:
+            # 为流式路径补充 chunk 粒度观测（安全起见仅预览+长度）
+            for idx, c in enumerate(stream_chunks if 'stream_chunks' in locals() else []):
+                ev.add(
+                    "stdout_chunk",
+                    chunk_index=idx + 1,
+                    chunk_size=len(c),
+                    chunk_preview=c[:120],
+                )
+        ev.add(
+            "command_completed",
+            mode="foreground",
+            exit_code=result.exit_code,
+            interrupted=result.interrupted,
+            output_truncated=output_truncated,
+            auto_backgrounded=False,
+        )
+        ev.add("task_state_changed", from_state="running", to_state=snapshot.task_status)
+        return BashToolOutput(
+            stdout=stdout_text,
+            interrupted=result.interrupted,
+            exit_code=result.exit_code,
+            task_mode=snapshot.task_mode,
+            task_status=snapshot.task_status,
+            task_exit_code=snapshot.exit_code,
+            return_code_interpretation=cmd_result.message,
+            no_output_expected=_is_silent_command(command),
+            destructive_warning=destructive_warning,
+            sandboxed=result.sandboxed,
+            sandbox_bypass_reason=result.sandbox_bypass_reason,
+            sandbox_temp_dir=result.sandbox_temp_dir,
+            sandbox_violation_message=result.sandbox_violation_message,
+            overflow_file=overflow_file,
+            output_truncated=output_truncated,
+            observability=finalize_observability_payload(ev.to_observability()),
+        )
+
+    # ------------------------------------------------------------------
+    # Hook 9: present
+    # ------------------------------------------------------------------
+
+    def present(
+        self, data: dict[str, Any], result: BashToolOutput, ctx: ToolExecutionContext
+    ) -> ToolResultEnvelope:
+        """
+        将执行结果映射为 ToolResultEnvelope。
+        对应 CC UI.tsx 的 renderToolResultMessage()。
+        """
+        return self._result_presenter.present(
+            tool_name=self.name,
+            data=_as_bash_input_dict(data),
+            result=result,
+        )
+
+    def __repr__(self) -> str:
+        return f"<BashRuntimeTool name={self.name!r} [destructive]>"
+
+    @staticmethod
+    def _with_observability(
+        decision: AuthorizationDecision,
+        *,
+        trace: list[dict[str, Any]],
+        trace_context: TraceContext,
+    ) -> AuthorizationDecision:
+        metadata = dict(decision.metadata or {})
+        metadata.update(
+            build_decision_observability(
+                trace=trace,
+                trace_context=trace_context,
+            )
+        )
+        return AuthorizationDecision(
+            behavior=decision.behavior,
+            message=decision.message,
+            policy_id=decision.policy_id,
+            updated_input=decision.updated_input,
+            ask_prompt=decision.ask_prompt,
+            metadata=metadata,
+        )
+
+    def _authorize_command_segment(
+        self,
+        command: str,
+        analysis: Any,
+        ctx: ToolExecutionContext,
+        cwd: str,
+        compound_has_cd: bool,
+    ) -> AuthorizationDecision:
+        """
+        对单个 command segment 做权限决策。
+
+        这里动态修正 tool_flags，让 PolicyEngine 的 read_only_mode /
+        deny_globs / ask_globs 能基于 segment 语义工作。
+        """
+        path_decision = self._path_security.authorize_segment(
+            command=command,
+            analysis=analysis,
+            cwd=cwd,
+            policy=self._policy,
+            compound_has_cd=compound_has_cd,
+        )
+        if path_decision.behavior != "allow":
+            return path_decision
+
+        hardening_decision = self._security_hardener.check_segment(
+            command=command,
+            analysis=analysis,
+            cwd=cwd,
+        )
+        if hardening_decision is not None:
+            return hardening_decision
+
+        if self._policy is None:
+            return self._authorize_sed_segment(command=command, ctx=ctx, cwd=cwd) or AuthorizationDecision(behavior="allow")
+
+        needs_write = self._ast_analyzer.requires_write_permissions(analysis)
+        classification = self._read_only_classifier.classify(command)
+        read_only = classification.is_read_only and not needs_write
+
+        seg_ctx = replace(
+            ctx,
+            tool_flags={
+                **(ctx.tool_flags or {}),
+                "is_read_only": read_only,
+                "is_destructive": not read_only,
+            },
+        )
+        decision = self._policy.authorize(
+            tool_name=self.name,
+            input_data={
+                "command": self._security_hardener.canonicalize_for_policy(command),
+            },
+            ctx=seg_ctx,
+        )
+        sed_check = self._sed_validator.evaluate(command)
+        if (
+            decision.behavior == "ask"
+            and self._mode_validator.should_auto_allow_after_policy(command, ctx)
+            and not sed_check.is_sed
+        ):
+            return AuthorizationDecision(
+                behavior="allow",
+                message="Command auto-approved in acceptEdits mode.",
+                policy_id="permission_mode",
+            )
+        if decision.behavior != "allow":
+            return decision
+
+        return self._authorize_sed_segment(command=command, ctx=ctx, cwd=cwd) or decision
+
+    def _authorize_sed_segment(
+        self,
+        *,
+        command: str,
+        ctx: ToolExecutionContext,
+        cwd: str,
+    ) -> AuthorizationDecision | None:
+        pending = self._get_pending_sed_edit(command, ctx)
+        if pending is not None:
+            return AuthorizationDecision(
+                behavior="allow",
+                message="Applying previously previewed sed edit.",
+                policy_id="bash_sed_preview",
+            )
+
+        check = self._sed_validator.evaluate(command)
+        if not check.is_sed:
+            return None
+        if check.requires_manual_approval:
+            return AuthorizationDecision(
+                behavior="ask",
+                message=check.reason,
+                policy_id="bash_sed_validation",
+                ask_prompt=check.reason,
+            )
+        if not check.is_in_place or check.edit_info is None:
+            return None
+
+        absolute_path = os.path.abspath(os.path.join(cwd, check.edit_info.file_path))
+        try:
+            original = Path(absolute_path).read_text(encoding="utf-8")
+        except OSError:
+            return None
+
+        updated = self._sed_parser.apply_substitution(original, check.edit_info)
+        preview = self._sed_parser.build_preview(
+            original=original,
+            updated=updated,
+            file_path=check.edit_info.file_path,
+        )
+        self._store_pending_sed_edit(
+            command=command,
+            ctx=ctx,
+            absolute_path=absolute_path,
+            new_content=updated,
+        )
+
+        if self._mode_validator.get_mode(ctx) == "acceptEdits":
+            return AuthorizationDecision(
+                behavior="allow",
+                message="sed edit auto-approved in acceptEdits mode.",
+                policy_id="bash_sed_preview",
+            )
+
+        prompt = (
+            "sed in-place edit requires approval. The command will be applied using the "
+            "previewed content shown below.\n\n"
+            f"{preview}"
+        )
+        return AuthorizationDecision(
+            behavior="ask",
+            message="sed in-place edit requires approval.",
+            policy_id="bash_sed_preview",
+            ask_prompt=prompt,
+        )
+
+    def _get_current_cwd(self) -> str:
+        if self._state_bridge is not None and hasattr(self._state_bridge, "get_cwd"):
+            cwd = self._state_bridge.get_cwd()
+            if isinstance(cwd, str) and cwd:
+                return cwd
+        return os.getcwd()
+
+    @staticmethod
+    def _pending_sed_state(ctx: ToolExecutionContext) -> dict[str, dict[str, str]]:
+        if ctx.state is None:
+            ctx.state = {}
+        return ctx.state.setdefault("__bash_sed_pending__", {})
+
+    def _pending_sed_key(self, command: str, ctx: ToolExecutionContext) -> str:
+        if ctx.tool_call_id:
+            return ctx.tool_call_id
+        return hashlib.sha256(command.encode("utf-8")).hexdigest()
+
+    def _store_pending_sed_edit(
+        self,
+        *,
+        command: str,
+        ctx: ToolExecutionContext,
+        absolute_path: str,
+        new_content: str,
+    ) -> None:
+        key = self._pending_sed_key(command, ctx)
+        self._pending_sed_state(ctx)[key] = {
+            "command": command,
+            "absolute_path": absolute_path,
+            "new_content": new_content,
+        }
+
+    def _get_pending_sed_edit(
+        self,
+        command: str,
+        ctx: ToolExecutionContext,
+    ) -> dict[str, str] | None:
+        key = self._pending_sed_key(command, ctx)
+        pending = self._pending_sed_state(ctx).get(key)
+        if pending is None or pending.get("command") != command:
+            return None
+        return pending
+
+    def _consume_pending_sed_edit(
+        self,
+        command: str,
+        ctx: ToolExecutionContext,
+    ) -> dict[str, str] | None:
+        key = self._pending_sed_key(command, ctx)
+        pending = self._pending_sed_state(ctx).get(key)
+        if pending is None or pending.get("command") != command:
+            return None
+        return self._pending_sed_state(ctx).pop(key)
+
+
+# ---------------------------------------------------------------------------
+# 内部辅助
+# ---------------------------------------------------------------------------
+
+
+def _is_silent_command(command: str) -> bool:
+    """
+    检测命令是否预期不产生 stdout（mv/cp/rm 等）。
+    对应 CC BASH_SILENT_COMMANDS。
+    """
+    stripped = command.strip()
+    if not stripped:
+        return False
+
+    # 提取第一个 token
+    parts = stripped.split()
+    if not parts:
+        return False
+
+    base = parts[0].rsplit("/", 1)[-1]
+    return base in SILENT_COMMANDS
+
+
+def _strip_stream_cwd_marker(stdout: str) -> tuple[str, str | None]:
+    marker = "__AGENTX_STREAM_CWD__"
+    if marker not in stdout:
+        return stdout, None
+    before, _, after = stdout.rpartition(marker)
+    cwd = after.strip().splitlines()[0] if after.strip() else None
+    cleaned = before.rstrip("\n")
+    return cleaned, cwd