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

langchain_agentx/tools/bash/bash_runtime_contract.py

@@ -0,0 +1,41 @@
+"""
+bash_runtime_contract.py — Bash 跨平台运行时冻结契约（只读常量）
+
+职责：
+    集中记录 Shell 环境变量解析顺序、cwd 双轨策略、Windows 持久会话默认值等
+    **与 CC/exec-plan 对齐的冻结项**，供 `shell_locator`、`BashBackend` 与 CR 对齐；
+    避免散落在多文件中的口头约定。
+
+链路位置：
+    不参与 BashBackend 热路径；`shell_locator` 导入 **SHELL_ENV_PRECEDENCE**；
+    `BashBackend.__init__` 的 win32 持久会话策略与本模块 **WIN32_DEFAULT_USE_PERSISTENT_SESSION**
+    注释一致。
+
+当前裁剪范围：
+    不包含 Shell 解析、Popen、cwd 文件或 fd3 实现；不包含对 CC 源码的导入。
+
+设计 SSOT：
+    docs/design-docs/tool-design/bash-tool-cross-platform.md（§1.1–§1.4、§3.0）
+
+CC 对照（实施前阅读，路径相对 CC 检出 src/）：
+    utils/Shell.ts — findSuitableShell、spawn 与 SHELL 环境
+    utils/shell/bashProvider.ts — shellCwdFilePath / cwdFilePath 双轨
+"""
+
+from __future__ import annotations
+
+#: 显式覆盖 POSIX shell 可执行文件时，环境变量尝试顺序（先声明者优先；逐项校验见 SSOT §1.2）。
+SHELL_ENV_PRECEDENCE: tuple[str, ...] = (
+    "LANGCHAIN_AGENTX_SHELL",
+    "CLAUDE_CODE_SHELL",
+    "SHELL",
+)
+
+#: Linux/Unix 上 cwd 回传冻结策略（须保持 fd3 + pass_fds，不得未经 RFC 改为仅文件）。
+CWD_STRATEGY_POSIX = "fd3_pass_fds"
+
+#: Windows 上 cwd 回传目标策略（临时文件 + pwd -P；见 `cwd_reporter.py` / exec-plan）。
+CWD_STRATEGY_WIN32 = "temp_file_pwd_p"
+
+#: Windows 上 **默认** 关闭真持久 bash 会话（exec-plan：直至持久会话冒烟通过后再评估默认值）。
+WIN32_DEFAULT_USE_PERSISTENT_SESSION = False

langchain_agentx/tools/bash/cwd_reporter.py

@@ -0,0 +1,95 @@
+"""
+cwd_reporter.py — Bash 执行后 cwd 回传（Unix fd3 / Windows 临时文件）
+
+职责：
+    为 `BashBackend._execute_raw` / `_aexecute_raw` 生成包装脚本：Unix 用 **fd3 + pass_fds**；
+    Windows 用 **临时文件 + `pwd -P`**（禁止 pass_fds），与 CC `bashProvider` 双轨语义对齐。
+
+链路位置：
+    仅被 `backend.py` 调用；不读工具入参、不碰权限链。
+
+当前裁剪范围：
+    不处理流式 `_stream_execute_raw_iter`；不处理沙箱 backend 内部；UNC 临时目录尽力而为
+   （`native_path_for_bash_redirect` 覆盖常见 `//server/share` 形态）。
+
+设计 SSOT：
+    docs/design-docs/tool-design/bash-tool-cross-platform.md（Phase 2）
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def bash_single_quoted(s: str) -> str:
+    """Bash 单引号字面量（可嵌入 `pwd -P >| ...` 等）。"""
+    return "'" + s.replace("'", "'\\''") + "'"
+
+
+def native_path_for_bash_redirect(win_native: str) -> str:
+    """
+    将 **本机绝对路径** 转为 Git Bash / MSYS 下用于重定向的 POSIX 形态。
+
+    - `C:\\Users\\x` → `/c/Users/x`
+    - `\\\\server\\share\\a` → `//server/share/a`
+    - 长路径前缀 `\\\\?\\` 会剥离后再转换（尽力而为）。
+    """
+    p = Path(win_native).resolve()
+    s = os.fspath(p)
+    norm = s.replace("/", "\\")
+    if norm.startswith("\\\\?\\"):
+        norm = norm[4:]
+        if norm.upper().startswith("UNC\\"):
+            norm = "\\" + norm[3:]
+    if norm.startswith("\\\\"):
+        body = norm[2:].replace("\\", "/").strip("/")
+        return "//" + body if body else "//"
+    if len(norm) >= 2 and norm[1] == ":":
+        letter = norm[0].lower()
+        tail = norm[2:].replace("\\", "/")
+        if not tail.startswith("/"):
+            tail = "/" + tail.lstrip("/")
+        return f"/{letter}{tail}"
+    return norm.replace("\\", "/")
+
+
+def read_cwd_file(native_path: str) -> str | None:
+    """读取 `pwd -P` 写入的临时文件，返回最后一行非空 cwd，失败为 None。"""
+    try:
+        raw = Path(native_path).read_text(encoding="utf-8", errors="replace").strip()
+    except OSError:
+        return None
+    if not raw:
+        return None
+    lines = [ln.strip() for ln in raw.splitlines() if ln.strip()]
+    return lines[-1] if lines else None
+
+
+class BashCwdReporter:
+    """构造「执行用户命令 + 回写 cwd」的包装脚本（双平台）。"""
+
+    __slots__ = ()
+
+    @staticmethod
+    def wrap_with_fd3(command: str, write_fd: int) -> str:
+        """Unix：通过 fd3 写 `$PWD`（与既有 `backend._execute_raw` 一致）。"""
+        return (
+            f"exec 3>&{write_fd}\n"
+            f"{command}\n"
+            f'__EC=$?; echo "$PWD" >&3; exit $__EC'
+        )
+
+    @staticmethod
+    def wrap_with_cwd_file(command: str, posix_target_single_quoted: str) -> str:
+        """
+        Windows：用户命令在同一 shell 内执行后 `pwd -P` 覆写到目标文件。
+
+        `posix_target_single_quoted` 须已用 `bash_single_quoted(...)` 包一层。
+        """
+        return (
+            f"{command}\n"
+            f"__EC=$?\n"
+            f"pwd -P >| {posix_target_single_quoted}\n"
+            f"exit $__EC\n"
+        )

langchain_agentx/tools/bash/limits.py

@@ -0,0 +1,71 @@
+"""
+tools/bash/limits.py — BashRuntimeTool 上限配置
+
+对应 CC prompt.ts 中的 getDefaultBashTimeoutMs() / getMaxBashTimeoutMs()
+以及 BashTool.tsx 中的 maxResultSizeChars=30_000。
+
+全部支持环境变量覆盖，便于测试 mock 和生产调优。
+"""
+
+from __future__ import annotations
+
+import os
+
+# ---------------------------------------------------------------------------
+# 超时配置
+# ---------------------------------------------------------------------------
+
+DEFAULT_TIMEOUT_SEC = int(os.getenv("BASH_TOOL_DEFAULT_TIMEOUT", "120"))
+"""默认超时秒数（对应 CC getDefaultBashTimeoutMs() = 120000ms）。"""
+
+MAX_TIMEOUT_SEC = int(os.getenv("BASH_TOOL_MAX_TIMEOUT", "600"))
+"""最大超时秒数（对应 CC getMaxBashTimeoutMs() = 600000ms / 10min）。"""
+
+# ---------------------------------------------------------------------------
+# 输出限制
+# ---------------------------------------------------------------------------
+
+MAX_OUTPUT_CHARS = int(os.getenv("BASH_TOOL_MAX_OUTPUT_CHARS", str(30_000)))
+"""单次输出字符上限（对应 CC maxResultSizeChars=30_000）。"""
+
+# ---------------------------------------------------------------------------
+# 安全阈值
+# ---------------------------------------------------------------------------
+
+SLEEP_BLOCK_THRESHOLD_SEC = int(os.getenv("BASH_TOOL_SLEEP_BLOCK_SEC", "30"))
+"""sleep 命令阻断阈值（秒）。超过此值提示使用 run_in_background（对应 CC detectBlockedSleepPattern）。"""
+
+# ---------------------------------------------------------------------------
+# 后台任务
+# ---------------------------------------------------------------------------
+
+BACKGROUND_TASK_OUTPUT_DIR = os.path.expanduser(
+    os.getenv(
+        "BASH_TOOL_BACKGROUND_OUTPUT_DIR",
+        "~/.cache/langchain_agentx/tasks",
+    )
+)
+"""后台任务输出目录。"""
+
+AUTO_BACKGROUND_ENABLED = os.getenv("BASH_TOOL_AUTO_BACKGROUND_ENABLED", "1") == "1"
+"""是否开启自动后台化策略。"""
+
+AUTO_BACKGROUND_TIMEOUT_SEC = int(
+    os.getenv("BASH_TOOL_AUTO_BACKGROUND_TIMEOUT_SEC", "180")
+)
+"""触发自动后台化的 timeout 阈值（秒）。"""
+
+
+def get_bash_limits() -> dict:
+    """
+    返回当前有效配置（动态读取，支持运行时环境变量覆盖）。
+    """
+    return {
+        "default_timeout_sec": DEFAULT_TIMEOUT_SEC,
+        "max_timeout_sec": MAX_TIMEOUT_SEC,
+        "max_output_chars": MAX_OUTPUT_CHARS,
+        "sleep_block_threshold_sec": SLEEP_BLOCK_THRESHOLD_SEC,
+        "background_task_output_dir": BACKGROUND_TASK_OUTPUT_DIR,
+        "auto_background_enabled": AUTO_BACKGROUND_ENABLED,
+        "auto_background_timeout_sec": AUTO_BACKGROUND_TIMEOUT_SEC,
+    }

langchain_agentx/tools/bash/mode_validation.py

@@ -0,0 +1,282 @@
+"""
+tools/bash/mode_validation.py — BashRuntimeTool：mode-aware 权限分流（P2 细粒度版）
+
+职责：
+    与 CC `modeValidation.ts` 对齐方向，在命令级基础上增加：
+    - 子模式 / 参数语义（acceptEdits 何时可自动放行）
+    - 可解释结论（reason_code + message，便于归因与降误判）
+
+当前实现：
+    - `acceptEdits`：按命令 + flag + 参数形态分流；显式拒绝高危 rm/chmod/chown 递归等
+    - `dontAsk`：将 ask 降级为 deny
+    - `bypassPermissions`：直接 allow（仅跳过权限层，不影响 validate_input）
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+from typing import Literal
+
+from langchain_agentx.tool_runtime.models import AuthorizationDecision, ToolExecutionContext
+
+
+BashPermissionMode = Literal["default", "acceptEdits", "dontAsk", "bypassPermissions"]
+
+
+@dataclass(frozen=True)
+class BashModeDecision:
+    behavior: Literal["passthrough", "allow", "deny"]
+    message: str | None = None
+    policy_id: str | None = None
+
+
+@dataclass(frozen=True)
+class AcceptEditsEvaluation:
+    """acceptEdits 细粒度评估结果（可对接日志 / 策略归因）。"""
+
+    allowed: bool
+    reason_code: str
+    message: str
+
+
+class BashPermissionModeValidator:
+    """模式级权限协作者（P2：参数语义 + 场景约束）。"""
+
+    _ACCEPT_EDITS_ALLOWED_COMMANDS = frozenset({
+        "mkdir", "touch", "rm", "rmdir", "mv", "cp", "sed", "ln", "install",
+        "chmod", "chown",
+    })
+
+    _CHMOD_DENY_RECURSIVE = frozenset({"-R", "-r", "--recursive"})
+    _CHOWN_DENY_RECURSIVE = frozenset({"-R", "-r", "--recursive"})
+    _CP_DENY_FLAGS = frozenset({
+        "--reflink=always", "--parents", "--link", "-l", "--symbolic-link", "-s",
+        "--backup", "--remove-destination",
+    })
+    _MV_DENY_FLAGS = frozenset({"-f", "--force"})
+    _MKDIR_DENY_FLAGS = frozenset({"-Z", "--context"})
+    _INSTALL_DENY_FLAGS = frozenset({"-D", "--strip", "-s", "-S", "--strip-program"})
+    _CHOWN_DENY_FLAGS = frozenset({"--reference", "--from"})
+
+    def get_mode(self, ctx: ToolExecutionContext) -> BashPermissionMode:
+        tool_flags = ctx.tool_flags or {}
+        raw_mode = tool_flags.get("permission_mode", "default")
+        if raw_mode in {"acceptEdits", "dontAsk", "bypassPermissions"}:
+            return raw_mode
+        return "default"
+
+    def check_preflight(
+        self,
+        command: str,
+        ctx: ToolExecutionContext,
+    ) -> BashModeDecision:
+        mode = self.get_mode(ctx)
+        if mode == "bypassPermissions":
+            return BashModeDecision(
+                behavior="allow",
+                message="Permission checks bypassed by current permission mode.",
+                policy_id="permission_mode",
+            )
+        return BashModeDecision(behavior="passthrough")
+
+    def evaluate_accept_edits(self, command: str) -> AcceptEditsEvaluation:
+        """显式评估 acceptEdits 是否允许自动放行（供调试与扩展）。"""
+        base = self._base_command(command)
+        if base not in self._ACCEPT_EDITS_ALLOWED_COMMANDS:
+            return AcceptEditsEvaluation(
+                allowed=False,
+                reason_code="command_not_in_accept_edits_set",
+                message=f"Command `{base}` is not eligible for acceptEdits auto-allow.",
+            )
+        ok, code, msg = self._accept_edits_semantics(command, base)
+        return AcceptEditsEvaluation(allowed=ok, reason_code=code, message=msg)
+
+    def should_auto_allow_after_policy(
+        self,
+        command: str,
+        ctx: ToolExecutionContext,
+    ) -> bool:
+        if self.get_mode(ctx) != "acceptEdits":
+            return False
+        return self.evaluate_accept_edits(command).allowed
+
+    def finalize_decision(
+        self,
+        *,
+        command: str,
+        decision: AuthorizationDecision,
+        ctx: ToolExecutionContext,
+    ) -> AuthorizationDecision:
+        mode = self.get_mode(ctx)
+        if mode == "dontAsk" and decision.behavior == "ask":
+            detail = self.evaluate_accept_edits(command)
+            suffix = f" [acceptEdits_context: {detail.reason_code}]" if detail.reason_code else ""
+            message = (decision.message or f"Command requires approval in dontAsk mode: {command}") + suffix
+            return AuthorizationDecision(
+                behavior="deny",
+                message=message,
+                policy_id=decision.policy_id or "permission_mode",
+            )
+        return decision
+
+    def _accept_edits_semantics(self, command: str, base: str) -> tuple[bool, str, str]:
+        """返回 (allowed, reason_code, message)。"""
+        try:
+            tokens = shlex.split(command)
+        except ValueError:
+            tokens = command.split()
+        args = tokens[1:] if len(tokens) > 1 else []
+
+        if base == "rm":
+            risky = {"-r", "-R", "-rf", "-fr", "--recursive", "--force"}
+            if any(a in risky for a in args):
+                return (False, "rm_recursive_or_force", "Recursive or force rm is not auto-allowed under acceptEdits.")
+            return (True, "rm_safe", "Single-file or small-arg rm eligible for acceptEdits.")
+
+        if base == "sed":
+            if any(arg.startswith("-i") or arg == "--in-place" for arg in args):
+                if self._sed_inplace_shell_chain(command):
+                    return (False, "sed_inplace_shell_chain", "sed -i in compound shell chain not auto-allowed.")
+                return (True, "sed_inplace", "In-place sed eligible for acceptEdits.")
+            return (False, "sed_not_inplace", "Only in-place sed is auto-allowed under acceptEdits.")
+
+        if base == "cp":
+            if self._args_contain_token_or_flag(args, self._CP_DENY_FLAGS):
+                return (False, "cp_submode_denied", "cp with link/backup/parents/reflink semantics not auto-allowed.")
+            if self._cp_short_bundle_risky(args):
+                return (False, "cp_short_link_or_symlink", "cp -l/-s (含合并短选项) not auto-allowed.")
+            if self._cp_sparse_or_preserve_root(args):
+                return (False, "cp_sparse_or_preserve_root", "cp --sparse=always or --preserve=root not auto-allowed.")
+            return (True, "cp_default", "cp eligible for acceptEdits.")
+
+        if base == "mv":
+            if self._args_contain_token_or_flag(args, self._MV_DENY_FLAGS):
+                return (False, "mv_force", "mv -f/--force not auto-allowed under acceptEdits.")
+            if "--strip-trailing-slashes" in args:
+                return (False, "mv_strip_slashes", "mv --strip-trailing-slashes not auto-allowed.")
+            return (True, "mv_default", "mv eligible for acceptEdits.")
+
+        if base == "mkdir":
+            if self._args_contain_token_or_flag(args, self._MKDIR_DENY_FLAGS):
+                return (False, "mkdir_selinux_context", "mkdir -Z/--context not auto-allowed.")
+            if "-m" in args or "--mode" in args:
+                return (True, "mkdir_with_mode", "mkdir with explicit mode still eligible.")
+            return (True, "mkdir_default", "mkdir eligible for acceptEdits.")
+
+        if base == "touch":
+            return (True, "touch_default", "touch eligible for acceptEdits.")
+
+        if base == "rmdir":
+            if "--ignore-fail-on-non-empty" in args:
+                return (False, "rmdir_ignore_nonempty", "rmdir --ignore-fail-on-non-empty not auto-allowed.")
+            return (True, "rmdir_default", "rmdir eligible for acceptEdits.")
+
+        if base == "ln":
+            if "-r" in args or "--relative" in args:
+                return (False, "ln_relative", "ln --relative not auto-allowed.")
+            return (True, "ln_default", "ln eligible for acceptEdits.")
+
+        if base == "install":
+            if self._args_contain_token_or_flag(args, self._INSTALL_DENY_FLAGS):
+                return (False, "install_submode_denied", "install -D/strip or similar not auto-allowed.")
+            if "-d" in args or "--directory" in args:
+                return (True, "install_dirs", "install -d eligible.")
+            return (True, "install_default", "install file copy eligible for acceptEdits.")
+
+        if base == "chmod":
+            if any(a in self._CHMOD_DENY_RECURSIVE for a in args):
+                return (False, "chmod_recursive", "Recursive chmod not auto-allowed under acceptEdits.")
+            mode, paths = self._chmod_mode_and_paths(args)
+            if mode and self._chmod_mode_caps_setuid(mode):
+                return (False, "chmod_setuid_or_special", "chmod with setuid/setgid/sticky not auto-allowed.")
+            return (True, "chmod_non_recursive", "Non-recursive chmod eligible for acceptEdits.")
+
+        if base == "chown":
+            if any(a in self._CHOWN_DENY_RECURSIVE for a in args):
+                return (False, "chown_recursive", "Recursive chown not auto-allowed under acceptEdits.")
+            if self._args_contain_token_or_flag(args, self._CHOWN_DENY_FLAGS):
+                return (False, "chown_reference_or_from", "chown --reference/--from not auto-allowed.")
+            return (True, "chown_non_recursive", "Non-recursive chown eligible for acceptEdits.")
+
+        return (True, "generic_ok", f"{base} eligible for acceptEdits.")
+
+    @staticmethod
+    def _sed_inplace_shell_chain(command: str) -> bool:
+        """与 `&&`、`|` 组合的 in-place sed 不自动放行（子模式边界）。"""
+        return "&&" in command or "|" in command
+
+    @staticmethod
+    def _args_contain_token_or_flag(args: list[str], needles: frozenset[str]) -> bool:
+        for a in args:
+            if a in needles:
+                return True
+            if a.startswith("--") and "=" in a:
+                opt = a.split("=", 1)[0]
+                if opt in needles or a in needles:
+                    return True
+        return False
+
+    @staticmethod
+    def _cp_sparse_or_preserve_root(args: list[str]) -> bool:
+        for a in args:
+            if a.startswith("--sparse=") and a != "--sparse=never":
+                return True
+            if a == "--preserve=root":
+                return True
+        return False
+
+    @staticmethod
+    def _cp_short_bundle_risky(args: list[str]) -> bool:
+        for a in args:
+            if not a.startswith("-") or a.startswith("--") or len(a) < 2:
+                continue
+            body = a.lstrip("-")
+            if "l" in body or "s" in body:
+                return True
+        return False
+
+    @staticmethod
+    def _chmod_mode_and_paths(args: list[str]) -> tuple[str | None, list[str]]:
+        """从 chmod 参数中取出 mode 字串（若存在）与路径候选（启发式）。"""
+        mode: str | None = None
+        paths: list[str] = []
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a in ("-f", "--silent", "--quiet", "-v", "--verbose", "-c", "--changes", "-R", "-r", "--recursive"):
+                i += 1
+                continue
+            if a.startswith("-"):
+                i += 1
+                continue
+            if mode is None and re.match(r"^[ugoa]*[-+=]?[rwxXst,0-7]+$", a):
+                mode = a
+                i += 1
+                continue
+            paths.append(a)
+            i += 1
+        return mode, paths
+
+    @staticmethod
+    def _chmod_mode_caps_setuid(mode: str) -> bool:
+        if re.fullmatch(r"[0-7]{3,4}", mode):
+            try:
+                val = int(mode, 8)
+            except ValueError:
+                return False
+            return (val & 0o6000) != 0
+        if any(x in mode for x in ("s", "t", "T")) and ("+" in mode or "-" in mode or "=" in mode):
+            return True
+        return False
+
+    @staticmethod
+    def _base_command(command: str) -> str:
+        try:
+            tokens = shlex.split(command)
+        except ValueError:
+            tokens = command.split()
+        if not tokens:
+            return ""
+        return tokens[0].rsplit("/", 1)[-1]

langchain_agentx/tools/bash/models.py

@@ -0,0 +1,131 @@
+"""
+tools/bash/models.py — BashRuntimeTool 输入输出数据模型
+
+对应 CC BashTool.tsx 的 inputSchema / outputSchema。
+纯 Pydantic 数据模型，无 I/O，无框架依赖。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BashToolInput(BaseModel):
+    """
+    BashRuntimeTool 输入参数。
+
+    对应 CC inputSchema。
+    """
+
+    command: str = Field(
+        ...,
+        description="The bash command to execute",
+    )
+    timeout: int | None = Field(
+        None,
+        gt=0,
+        description=(
+            "Optional timeout in seconds (max 600). "
+            "Defaults to 120 seconds if not specified."
+        ),
+    )
+    description: str | None = Field(
+        None,
+        description=(
+            "Clear, concise description of what this command does in active voice. "
+            "For simple commands keep it brief (5-10 words). "
+            "For complex or piped commands add enough context to clarify intent."
+        ),
+    )
+    run_in_background: bool = Field(
+        False,
+        description=(
+            "Set to true to run this command in the background. "
+            "Use this when you don't need the result immediately. "
+            "A task_id is returned; output is written to a file you can read later."
+        ),
+    )
+    dangerously_disable_sandbox: bool = Field(
+        False,
+        description=(
+            "Request to bypass sandbox execution for this command. "
+            "This only takes effect when the runtime explicitly allows unsandboxed execution."
+        ),
+    )
+
+
+class BashToolOutput(BaseModel):
+    """
+    BashRuntimeTool 内部执行结果（对应 CC outputSchema）。
+
+    由 invoke() 返回，传递给 after_invoke() 和 present()。
+    """
+
+    stdout: str
+    """命令输出（stderr 已合并进 stdout）。"""
+
+    interrupted: bool
+    """是否因超时或外部中断而提前终止。"""
+
+    exit_code: int
+    """命令退出码。"""
+
+    background_task_id: str | None = None
+    """后台任务 ID（仅 run_in_background=True 时有值）。"""
+
+    background_output_path: str | None = None
+    """后台任务输出文件路径（模型可用 Read 工具读取）。"""
+
+    task_mode: str = "foreground"
+    """任务模式：foreground / background。"""
+
+    task_status: str = "completed"
+    """任务状态：running / completed / failed / interrupted。"""
+
+    task_exit_code: int | None = None
+    """统一任务协议退出码（前后台共用）。"""
+
+    auto_backgrounded: bool = False
+    """是否由自动后台化策略触发。"""
+
+    return_code_interpretation: str | None = None
+    """
+    特殊退出码的语义解释。
+    例如 grep 返回 1 = 无匹配（非错误），会在此字段给出说明。
+    对应 CC returnCodeInterpretation。
+    """
+
+    no_output_expected: bool = False
+    """
+    命令预期不产生输出（mv/cp/rm 等），成功时 present() 显示 "Done"。
+    对应 CC noOutputExpected。
+    """
+
+    destructive_warning: str | None = None
+    """
+    危险命令警告文本（非阻断）。
+    detect_destructive_patterns() 检测到危险模式时设置，在 present() 中注入到 hints。
+    """
+
+    sandboxed: bool = False
+    """本次命令是否在沙箱模式下执行。"""
+
+    sandbox_bypass_reason: str | None = None
+    """未走沙箱时的原因说明（如 excluded command / explicit override）。"""
+
+    sandbox_temp_dir: str | None = None
+    """沙箱注入的 TMPDIR 路径（基础版沙箱使用独立临时目录）。"""
+
+    sandbox_violation_message: str | None = None
+    """沙箱执行返回的结构化 violation 信息。"""
+
+    overflow_file: str | None = None
+    """超大 stdout 落盘路径（完整内容），与 output_truncated 配合使用。"""
+
+    output_truncated: bool = False
+    """stdout 是否已截断，完整内容见 overflow_file。"""
+
+    observability: dict[str, Any] | None = None
+    """结构化可观测数据（事件摘要/决策归因），供 UI/CLI/日志多端消费。"""