langchain-agentx-python 1.2.8__tar.gz → 1.2.9__tar.gz

{langchain-agentx-python-1.2.8 → langchain-agentx-python-1.2.9}/PKG-INFO

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

{langchain-agentx-python-1.2.8 → langchain-agentx-python-1.2.9}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "1.2.8"
+__version__ = "1.2.9"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-1.2.8 → langchain-agentx-python-1.2.9}/langchain_agentx/loop/graph/factory.py

@@ -363,6 +363,7 @@ class LoopGraphBuilder:
         self._context_schema = context_schema
         self._prepared = False
         self._memory_prefetch_coordinator: Any | None = None
+        self._plan_mode_attachment_coordinator: Any | None = None
 
     def _prepare_compile_context(self) -> None:
         if self._prepared:
@@ -620,6 +621,9 @@ class LoopGraphBuilder:
             model=model,
             session_store=session_store,
         )
+        self._plan_mode_attachment_coordinator = self._build_plan_mode_attachment_coordinator(
+            session_id=session_id or "",
+        )
         self._hook_graph_wiring = HookGraphWiring(
             hook_engine,
             trace_lifecycle_collector=trace_lifecycle_collector,
@@ -947,20 +951,66 @@ class LoopGraphBuilder:
         iteration = int(state.get("turn_count", 0) or 0)
         return coordinator.consume_attachment_messages(state, iteration=iteration)
 
-    def _patch_messages_with_memory_prefetch(
+    def _build_plan_mode_attachment_coordinator(self, *, session_id: str) -> Any | None:
+        if self._is_subagent:
+            return None
+        from ...session.plan_mode_attachments import PlanModeAttachmentCoordinator
+
+        return PlanModeAttachmentCoordinator(
+            workspace_cfg=self._workspace_cfg,
+            session_id=session_id,
+        )
+
+    def _consume_plan_mode_attachment_messages(
+        self,
+        state: dict[str, Any],
+        *,
+        configurable: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        coordinator = self._plan_mode_attachment_coordinator
+        if coordinator is None:
+            return []
+        iteration = int(state.get("turn_count", 0) or 0)
+        return coordinator.consume_attachment_messages(
+            state,
+            iteration=iteration,
+            configurable=configurable,
+        )
+
+    def _patch_messages_with_loop_attachments(
         self,
         state: dict[str, Any],
         patch: dict[str, Any],
+        *,
+        configurable: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         memory_attachments = self._consume_memory_prefetch_attachment_messages(state)
-        if not memory_attachments:
+        plan_mode_attachments = self._consume_plan_mode_attachment_messages(
+            state,
+            configurable=configurable,
+        )
+        extra = memory_attachments + plan_mode_attachments
+        if not extra:
             return patch
         messages = list(patch.get("messages") or state.get("messages") or [])
-        messages.extend(to_record(m) for m in memory_attachments)
+        messages.extend(to_record(m) for m in extra)
         patch = dict(patch)
         patch["messages"] = messages
         return patch
 
+    def _patch_messages_with_memory_prefetch(
+        self,
+        state: dict[str, Any],
+        patch: dict[str, Any],
+        *,
+        configurable: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._patch_messages_with_loop_attachments(
+            state,
+            patch,
+            configurable=configurable,
+        )
+
     def _resolve_workspace_config(self) -> None:
         raw_workspace_root = self._config.workspace.workspace_root
         if raw_workspace_root is None:
@@ -1464,6 +1514,12 @@ class LoopGraphBuilder:
             agent_id = state.get("agent_id")
             scope = TaskScope(agent_id=agent_id if isinstance(agent_id, str) else None)
             task_events: list[dict[str, Any]] = []
+            try:
+                from langgraph.config import get_config
+
+                runnable_config = get_config()
+            except Exception:
+                runnable_config = None
 
             provider_index = -1
             batch = None
@@ -1541,6 +1597,7 @@ class LoopGraphBuilder:
                             "pending_task_command_ids": [],
                             "task_events": task_events,
                         },
+                        configurable=runnable_config,
                     )
                 messages = list(state.get("messages") or [])
                 # 冻结契约：task 通知附件仅经本节点注入；按 command_id 与已有 messages 去重
@@ -1615,6 +1672,7 @@ class LoopGraphBuilder:
                         "pending_task_command_ids": list(batch.command_ids),
                         "task_events": task_events,
                     },
+                    configurable=runnable_config,
                 )
             except Exception:
                 if batch is not None and batch.batch_id:

{langchain-agentx-python-1.2.8 → langchain-agentx-python-1.2.9}/langchain_agentx/session/plan_mode.py

@@ -18,6 +18,8 @@ logger = logging.getLogger(__name__)
 
 PRE_PLAN_MODE_KEY = "prePlanMode"
 PERMISSION_MODE_KEY = "permission_mode"
+NEEDS_PLAN_MODE_EXIT_ATTACHMENT_KEY = "needsPlanModeExitAttachment"
+HAS_EXITED_PLAN_MODE_KEY = "hasExitedPlanModeInSession"
 PLAN_MODE = "plan"
 DEFAULT_MODE = "default"
 
@@ -37,6 +39,18 @@ def _mutable_configurable(target: MutableMapping[str, Any]) -> MutableMapping[st
 class PlanModeTransition:
     """IF-G9：configurable 上 plan 模式 enter/exit（OOP 单职责）。"""
 
+    @staticmethod
+    def handle_transition(
+        configurable: MutableMapping[str, Any],
+        from_mode: str,
+        to_mode: str,
+    ) -> None:
+        """对齐 CC ``handlePlanModeTransition``：exit attachment 与快速切换互斥。"""
+        if to_mode == PLAN_MODE and from_mode != PLAN_MODE:
+            configurable[NEEDS_PLAN_MODE_EXIT_ATTACHMENT_KEY] = False
+        if from_mode == PLAN_MODE and to_mode != PLAN_MODE:
+            configurable[NEEDS_PLAN_MODE_EXIT_ATTACHMENT_KEY] = True
+
     @staticmethod
     def enter(config_or_configurable: MutableMapping[str, Any]) -> str:
         """进入 plan；返回进入前的 permission_mode（并写入 prePlanMode）。"""
@@ -44,6 +58,7 @@ class PlanModeTransition:
         previous = str(configurable.get(PERMISSION_MODE_KEY, DEFAULT_MODE))
         configurable[PRE_PLAN_MODE_KEY] = previous
         configurable[PERMISSION_MODE_KEY] = PLAN_MODE
+        PlanModeTransition.handle_transition(configurable, previous, PLAN_MODE)
         return previous
 
     @staticmethod
@@ -56,6 +71,8 @@ class PlanModeTransition:
                 DEFAULT_MODE,
             )
         restore = str(configurable.get(PRE_PLAN_MODE_KEY, DEFAULT_MODE))
+        PlanModeTransition.handle_transition(configurable, PLAN_MODE, restore)
+        configurable[HAS_EXITED_PLAN_MODE_KEY] = True
         configurable[PERMISSION_MODE_KEY] = restore
         configurable.pop(PRE_PLAN_MODE_KEY, None)
         return restore
@@ -102,6 +119,8 @@ __all__ = [
     "PLAN_MODE",
     "PRE_PLAN_MODE_KEY",
     "PERMISSION_MODE_KEY",
+    "NEEDS_PLAN_MODE_EXIT_ATTACHMENT_KEY",
+    "HAS_EXITED_PLAN_MODE_KEY",
     "PlanModeAction",
     "PlanModeTransition",
     "build_plan_mode_transition_event",

langchain-agentx-python-1.2.9/langchain_agentx/session/plan_mode_attachments.py

@@ -0,0 +1,400 @@
+"""
+plan_mode_attachments.py — plan_mode / plan_mode_exit loop 附件（P-S6）
+
+职责：
+    对齐 CC ``utils/attachments.ts``：plan 模式下按 turn 节流注入 plan_mode；
+    退出时一次性 plan_mode_exit；re-entry 时 plan_mode_reentry。
+
+链路位置：
+    LoopGraphBuilder.task_event_reserve → PlanModeAttachmentCoordinator.consume_attachment_messages。
+
+当前裁剪范围：
+    不含 ultraplan / interview phase 变体；full 指令为 SDK 精简版。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Mapping, MutableMapping
+
+from langchain_agentx.loop.message_contract import normalize_role
+from langchain_agentx.session.plan_mode import (
+    HAS_EXITED_PLAN_MODE_KEY,
+    NEEDS_PLAN_MODE_EXIT_ATTACHMENT_KEY,
+    PERMISSION_MODE_KEY,
+    PLAN_MODE,
+)
+from langchain_agentx.tools.plan_mode.constants import EXIT_PLAN_MODE_TOOL_NAME
+from langchain_agentx.workspace import ResolvedAgentStateConfig
+from langchain_agentx.workspace.plans import get_plan_content, get_plan_file_path
+
+PLAN_MODE_ATTACHMENT_CONFIG = {
+    "TURNS_BETWEEN_ATTACHMENTS": 5,
+    "FULL_REMINDER_EVERY_N_ATTACHMENTS": 5,
+}
+
+PlanModeReminderType = Literal["full", "sparse"]
+PlanModeAttachmentType = Literal[
+    "plan_mode",
+    "plan_mode_reentry",
+    "plan_mode_exit",
+]
+
+
+@dataclass(frozen=True)
+class PlanModeAttachment:
+    type: PlanModeAttachmentType
+    plan_file_path: str
+    plan_exists: bool = False
+    reminder_type: PlanModeReminderType | None = None
+    is_sub_agent: bool = False
+
+
+def _configurable_from_mapping(
+    config_or_configurable: Mapping[str, Any] | None,
+) -> Mapping[str, Any]:
+    if config_or_configurable is None:
+        return {}
+    nested = config_or_configurable.get("configurable")
+    if isinstance(nested, Mapping):
+        return nested
+    return config_or_configurable
+
+
+def _is_human_turn(msg: Any) -> bool:
+    if isinstance(msg, dict):
+        role = normalize_role(str(msg.get("role") or msg.get("type") or ""))
+        if role != "user":
+            return False
+        if msg.get("is_meta") or msg.get("metadata", {}).get("is_meta"):
+            return False
+        return True
+    role = getattr(msg, "type", None) or getattr(msg, "role", None)
+    if normalize_role(str(role or "")) != "user":
+        return False
+    meta = getattr(msg, "additional_kwargs", None) or {}
+    if isinstance(meta, dict) and meta.get("is_meta"):
+        return False
+    return True
+
+
+def _attachment_type_from_message(msg: Any) -> str | None:
+    if isinstance(msg, dict):
+        meta = msg.get("metadata")
+        if isinstance(meta, dict):
+            attachment = meta.get("attachment")
+            if isinstance(attachment, dict):
+                raw = attachment.get("type")
+                return str(raw) if raw is not None else None
+        return None
+    kwargs = getattr(msg, "additional_kwargs", None)
+    if isinstance(kwargs, dict):
+        meta = kwargs.get("metadata")
+        if isinstance(meta, dict):
+            attachment = meta.get("attachment")
+            if isinstance(attachment, dict):
+                raw = attachment.get("type")
+                return str(raw) if raw is not None else None
+    return None
+
+
+def _plan_mode_attachment_turn_count(messages: list[Any]) -> tuple[int, bool]:
+    turns_since_last = 0
+    found_plan_mode = False
+    for msg in reversed(messages):
+        if _is_human_turn(msg):
+            turns_since_last += 1
+            continue
+        attachment_type = _attachment_type_from_message(msg)
+        if attachment_type in ("plan_mode", "plan_mode_reentry"):
+            found_plan_mode = True
+            break
+    return turns_since_last, found_plan_mode
+
+
+def _count_plan_mode_attachments_since_last_exit(messages: list[Any]) -> int:
+    count = 0
+    for msg in reversed(messages):
+        attachment_type = _attachment_type_from_message(msg)
+        if attachment_type == "plan_mode_exit":
+            break
+        if attachment_type == "plan_mode":
+            count += 1
+    return count
+
+
+def _format_plan_file_info(plan_file_path: str, plan_exists: bool) -> str:
+    if plan_exists:
+        return (
+            f"A plan file already exists at {plan_file_path}. "
+            "You can read it and make incremental edits using the Edit tool."
+        )
+    return (
+        f"No plan file exists yet. You should create your plan at {plan_file_path} "
+        "using the Write tool."
+    )
+
+
+def _format_plan_mode_full_text(
+    plan_file_path: str,
+    plan_exists: bool,
+    *,
+    is_sub_agent: bool,
+) -> str:
+    plan_info = _format_plan_file_info(plan_file_path, plan_exists)
+    sub_agent_note = (
+        " You are a subagent: do not edit files except the plan file when needed."
+        if is_sub_agent
+        else ""
+    )
+    return (
+        "Plan mode is active. The user indicated that they do not want you to execute yet — "
+        "you MUST NOT make any edits (except the plan file below), run non-readonly tools, "
+        "or otherwise change the system. This supersedes other instructions."
+        f"{sub_agent_note}\n\n"
+        "## Plan File Info:\n"
+        f"{plan_info}\n"
+        "Build your plan incrementally in this file only; other actions must be read-only.\n\n"
+        "## Plan Workflow (summary)\n"
+        "1. Explore the codebase and understand the request.\n"
+        "2. Design an implementation approach and note files to change.\n"
+        "3. Write the final plan to the plan file (concise, with verification steps).\n"
+        f"4. When ready, call {EXIT_PLAN_MODE_TOOL_NAME} for approval — not plain text."
+    )
+
+
+def _format_plan_mode_sparse_text(plan_file_path: str) -> str:
+    return (
+        f"Plan mode still active (see full instructions earlier). "
+        f"Read-only except plan file ({plan_file_path}). "
+        f"End turns with {EXIT_PLAN_MODE_TOOL_NAME} when the plan is ready for approval."
+    )
+
+
+def _format_plan_mode_reentry_text(plan_file_path: str) -> str:
+    return (
+        "## Re-entering Plan Mode\n\n"
+        f"You are returning to plan mode. A plan file exists at {plan_file_path} "
+        "from your previous session.\n\n"
+        "Read the existing plan, evaluate the user's current request, and update or "
+        f"overwrite the plan file before calling {EXIT_PLAN_MODE_TOOL_NAME}."
+    )
+
+
+def _format_plan_mode_exit_text(plan_file_path: str, plan_exists: bool) -> str:
+    plan_reference = (
+        f" The plan file is at {plan_file_path} if you need to reference it."
+        if plan_exists
+        else ""
+    )
+    return (
+        "## Exited Plan Mode\n\n"
+        f"You have exited plan mode. You can now make edits, run tools, and take actions."
+        f"{plan_reference}"
+    )
+
+
+def _wrap_system_reminder(text: str) -> str:
+    return f"<system-reminder>\n{text}\n</system-reminder>"
+
+
+def format_plan_mode_attachment_text(attachment: PlanModeAttachment) -> str:
+    if attachment.type == "plan_mode_exit":
+        return _wrap_system_reminder(
+            _format_plan_mode_exit_text(
+                attachment.plan_file_path,
+                attachment.plan_exists,
+            )
+        )
+    if attachment.type == "plan_mode_reentry":
+        return _wrap_system_reminder(
+            _format_plan_mode_reentry_text(attachment.plan_file_path)
+        )
+    reminder = attachment.reminder_type or "full"
+    if reminder == "sparse":
+        body = _format_plan_mode_sparse_text(attachment.plan_file_path)
+    else:
+        body = _format_plan_mode_full_text(
+            attachment.plan_file_path,
+            attachment.plan_exists,
+            is_sub_agent=attachment.is_sub_agent,
+        )
+    return _wrap_system_reminder(body)
+
+
+def plan_mode_attachment_to_dict(attachment: PlanModeAttachment) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "type": attachment.type,
+        "planFilePath": attachment.plan_file_path,
+        "planExists": attachment.plan_exists,
+    }
+    if attachment.reminder_type is not None:
+        payload["reminderType"] = attachment.reminder_type
+    if attachment.is_sub_agent:
+        payload["isSubAgent"] = True
+    return payload
+
+
+def build_plan_mode_attachment_message(
+    attachment: PlanModeAttachment,
+    *,
+    command_id: str,
+) -> dict[str, Any]:
+    text = format_plan_mode_attachment_text(attachment)
+    return {
+        "role": "user",
+        "content": [{"type": "text", "text": text}],
+        "metadata": {
+            "attachment": plan_mode_attachment_to_dict(attachment),
+            "task_notification": {"command_id": command_id},
+            "plan_mode_attachment": {"type": attachment.type},
+            "is_meta": True,
+        },
+    }
+
+
+def build_plan_mode_attachments_for_turn(
+    *,
+    messages: list[Any],
+    configurable: Mapping[str, Any] | None,
+    session_id: str,
+    cfg: ResolvedAgentStateConfig,
+    agent_id: str | None = None,
+) -> list[PlanModeAttachment]:
+    """对齐 CC ``getPlanModeAttachments`` + ``getPlanModeExitAttachment``。"""
+    flat = _configurable_from_mapping(configurable)
+    permission_mode = str(flat.get(PERMISSION_MODE_KEY, "default"))
+    plan_path = get_plan_file_path(session_id, cfg, agent_id=agent_id)
+    plan_path_str = str(plan_path)
+    plan_exists = get_plan_content(session_id, cfg) is not None
+    is_sub_agent = bool(agent_id)
+
+    exit_attachments: list[PlanModeAttachment] = []
+    if flat.get(NEEDS_PLAN_MODE_EXIT_ATTACHMENT_KEY) and permission_mode != PLAN_MODE:
+        exit_attachments.append(
+            PlanModeAttachment(
+                type="plan_mode_exit",
+                plan_file_path=plan_path_str,
+                plan_exists=plan_exists,
+            )
+        )
+
+    if permission_mode != PLAN_MODE:
+        return exit_attachments
+
+    if messages:
+        turn_count, found_plan_mode = _plan_mode_attachment_turn_count(messages)
+        if (
+            found_plan_mode
+            and turn_count < PLAN_MODE_ATTACHMENT_CONFIG["TURNS_BETWEEN_ATTACHMENTS"]
+        ):
+            return exit_attachments
+
+    attachments: list[PlanModeAttachment] = list(exit_attachments)
+
+    if flat.get(HAS_EXITED_PLAN_MODE_KEY) and plan_exists:
+        attachments.append(
+            PlanModeAttachment(
+                type="plan_mode_reentry",
+                plan_file_path=plan_path_str,
+                plan_exists=True,
+            )
+        )
+
+    attachment_count = _count_plan_mode_attachments_since_last_exit(messages) + 1
+    reminder_type: PlanModeReminderType = (
+        "full"
+        if attachment_count % PLAN_MODE_ATTACHMENT_CONFIG["FULL_REMINDER_EVERY_N_ATTACHMENTS"]
+        == 1
+        else "sparse"
+    )
+    attachments.append(
+        PlanModeAttachment(
+            type="plan_mode",
+            plan_file_path=plan_path_str,
+            plan_exists=plan_exists,
+            reminder_type=reminder_type,
+            is_sub_agent=is_sub_agent,
+        )
+    )
+    return attachments
+
+
+def clear_plan_mode_exit_attachment_flag(
+    configurable: MutableMapping[str, Any] | Mapping[str, Any] | None,
+) -> None:
+    """消费 plan_mode_exit 后清除 one-shot 标志（对齐 CC ``setNeedsPlanModeExitAttachment``）。"""
+    if not isinstance(configurable, MutableMapping):
+        return
+    nested = configurable.get("configurable")
+    target: MutableMapping[str, Any]
+    if isinstance(nested, MutableMapping):
+        target = nested
+    else:
+        target = configurable
+    target[NEEDS_PLAN_MODE_EXIT_ATTACHMENT_KEY] = False
+
+
+class PlanModeAttachmentCoordinator:
+    """每 turn 在 task_event_reserve 消费 plan_mode 附件。"""
+
+    def __init__(
+        self,
+        *,
+        workspace_cfg: ResolvedAgentStateConfig,
+        session_id: str,
+    ) -> None:
+        self._workspace_cfg = workspace_cfg
+        self._session_id = session_id
+
+    def consume_attachment_messages(
+        self,
+        state: dict[str, Any],
+        *,
+        iteration: int,
+        configurable: Mapping[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        if state.get("agent_id") is not None:
+            return []
+        attachments = build_plan_mode_attachments_for_turn(
+            messages=list(state.get("messages") or []),
+            configurable=configurable,
+            session_id=self._session_id,
+            cfg=self._workspace_cfg,
+            agent_id=None,
+        )
+        if not attachments:
+            return []
+        messages: list[dict[str, Any]] = []
+        for idx, attachment in enumerate(attachments):
+            command_id = f"plan_mode:{attachment.type}:{iteration}:{idx}"
+            messages.append(
+                build_plan_mode_attachment_message(attachment, command_id=command_id)
+            )
+        if any(a.type == "plan_mode_exit" for a in attachments):
+            if isinstance(configurable, MutableMapping):
+                clear_plan_mode_exit_attachment_flag(configurable)
+            elif configurable is not None:
+                nested = configurable.get("configurable")
+                if isinstance(nested, MutableMapping):
+                    clear_plan_mode_exit_attachment_flag(nested)
+        if any(a.type == "plan_mode_reentry" for a in attachments):
+            target: MutableMapping[str, Any] | None = None
+            if isinstance(configurable, MutableMapping):
+                nested = configurable.get("configurable")
+                target = nested if isinstance(nested, MutableMapping) else configurable
+            if target is not None:
+                target[HAS_EXITED_PLAN_MODE_KEY] = False
+        return messages
+
+
+__all__ = [
+    "PLAN_MODE_ATTACHMENT_CONFIG",
+    "PlanModeAttachment",
+    "PlanModeAttachmentCoordinator",
+    "build_plan_mode_attachment_message",
+    "build_plan_mode_attachments_for_turn",
+    "clear_plan_mode_exit_attachment_flag",
+    "format_plan_mode_attachment_text",
+    "plan_mode_attachment_to_dict",
+]

{langchain-agentx-python-1.2.8 → langchain-agentx-python-1.2.9}/langchain_agentx/tool_runtime/__init__.py

@@ -70,12 +70,13 @@ from .resolvers import (
 )
 from .auto_mode.config import AutoModeConfig
 from .auto_mode.events import AutoModeDecisionEvent
-from .override import DenyOverrideManager, DenyOverrideRecord, enrich_blocked_deny_envelope
+from .override import DenyOverrideManager, DenyOverrideRecord, enrich_blocked_deny_envelope, attach_permission_tool_input
 from .permission_decision import (
     ENVELOPE_META_KEY_CAN_OVERRIDE,
     ENVELOPE_META_KEY_DENY_OVERRIDE,
     ENVELOPE_META_KEY_POLICY_ID,
     ENVELOPE_META_KEY_TOOL_CALL_ID,
+    ENVELOPE_META_KEY_TOOL_INPUT,
     POLICY_ID_DENY_OVERRIDE_CONSUMED,
 )
 from .session_store import AgentSessionStore, FileReadRecord, FileWriteRecord
@@ -146,10 +147,12 @@ __all__ = [
     "DenyOverrideRecord",
     "DenyOverrideManager",
     "enrich_blocked_deny_envelope",
+    "attach_permission_tool_input",
     "ENVELOPE_META_KEY_CAN_OVERRIDE",
     "ENVELOPE_META_KEY_TOOL_CALL_ID",
     "ENVELOPE_META_KEY_POLICY_ID",
     "ENVELOPE_META_KEY_DENY_OVERRIDE",
+    "ENVELOPE_META_KEY_TOOL_INPUT",
     "POLICY_ID_DENY_OVERRIDE_CONSUMED",
     # pipeline
     "ToolOutputManager",

{langchain-agentx-python-1.2.8 → langchain-agentx-python-1.2.9}/langchain_agentx/tool_runtime/inner_permission_chain.py

@@ -103,7 +103,11 @@ class InnerPermissionChain:
         """DefaultPolicyEngine.authorize 直调路径（无工具 L1，等同 L1 continue）。"""
         tool_flags = ctx.tool_flags if hasattr(ctx, "tool_flags") else {}
 
-        read_only_deny = self._engine._read_only_mode_deny_if_mutates_state(tool_flags)
+        read_only_deny = self._engine._read_only_mode_deny_if_mutates_state(
+            tool_flags,
+            input_data=input_data,
+            ctx=ctx,
+        )
         if read_only_deny is not None:
             return read_only_deny
 
@@ -250,7 +254,11 @@ class InnerPermissionChain:
                 policy_id="permission_mode",
             )
 
-        read_only_deny = self._engine._read_only_mode_deny_if_mutates_state(tool_flags)
+        read_only_deny = self._engine._read_only_mode_deny_if_mutates_state(
+            tool_flags,
+            input_data=data,
+            ctx=ctx,
+        )
         if read_only_deny is not None:
             return read_only_deny
 
@@ -323,7 +331,6 @@ class InnerPermissionChain:
         ctx: ToolExecutionContext,
         tool_flags: dict[str, Any],
     ) -> AuthorizationDecision | None:
-        del data
         mode = str(tool_flags.get("permission_mode", "default"))
         if mode == "bypassPermissions":
             return AuthorizationDecision(
@@ -332,7 +339,11 @@ class InnerPermissionChain:
                 policy_id="permission_mode",
             )
 
-        read_only_deny = self._engine._read_only_mode_deny_if_mutates_state(tool_flags)
+        read_only_deny = self._engine._read_only_mode_deny_if_mutates_state(
+            tool_flags,
+            input_data=data,
+            ctx=ctx,
+        )
         if read_only_deny is not None:
             return read_only_deny
 
@@ -382,6 +393,14 @@ class InnerPermissionChain:
             )
             return PathPolicyResult(decision=decision)
 
+        if self._engine._plan_mode_session_plan_whitelisted(tool_flags, data, ctx):
+            return PathPolicyResult(
+                decision=AuthorizationDecision(
+                    behavior="allow",
+                    policy_id="session_plan_file",
+                ),
+            )
+
         return self._engine.evaluate_write_path_policy(real_path)
 
     @staticmethod