langchain-agentx-python 0.6.0__tar.gz → 0.6.1__tar.gz

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/PKG-INFO

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

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/__init__.py

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

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/loop/config/agent_loop_config.py

@@ -67,6 +67,7 @@ class AgentLoopConfig:
     subagent_type: str | None = None
     # 观测控制面：主 Agent 打开则子 Agent 默认继承打开
     trace_enabled: bool = True
+    headless: bool = False
     # 模型能力配置：显式 profile > registry 匹配 > model metadata > 代码兜底
     model_profile: ModelProfile | None = None
     model_profile_registry: ModelProfileRegistry | None = None

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/loop/graph/factory.py

@@ -101,6 +101,7 @@ from ..config import AgentLoopConfig, ModelContextResolver
 from ..config.runtime_settings import compute_recursion_limit
 from ...provider.model_profile import ModelProfileRegistry  # re-exported for legacy tests
 from ...workspace import resolve_agent_workspace_config
+from ...tool_runtime.prompt.session_mode import infer_session_headless
 
 logger = logging.getLogger(__name__)
 SKILL_TOOL_NAME = "skill"
@@ -195,6 +196,7 @@ class LoopGraphBuilder:
         enable_git_snapshot: bool | None = None,
         include_default_session_context: bool = True,
         enable_dynamic_root_grant: bool = False,
+        headless: bool | None = None,
     ) -> None:
         self._raw_model = model
         self._raw_system_prompt = system_prompt
@@ -240,6 +242,7 @@ class LoopGraphBuilder:
         self._raw_enable_git_snapshot = enable_git_snapshot
         self._raw_include_default_session_context = include_default_session_context
         self._raw_enable_dynamic_root_grant = enable_dynamic_root_grant
+        self._raw_headless = headless
 
         self._prepared = False
 
@@ -368,6 +371,7 @@ class LoopGraphBuilder:
             subagent_type=self._raw_subagent_type,
             trace_enabled=self._raw_enable_trace,
             model_profile_registry=self._model_profile_registry,
+            headless=self._resolve_session_headless(),
         )
         self._compaction_settings = self._build_compaction_settings()
         self._loop_context_compaction = default_loop_context_compaction().with_default_pipeline(
@@ -477,6 +481,12 @@ class LoopGraphBuilder:
             )
         self._prepared = True
 
+    def _resolve_session_headless(self) -> bool:
+        return infer_session_headless(
+            headless=self._raw_headless,
+            container_type=self._raw_container_type,
+        )
+
     def _resolve_model_session_and_logger(
         self,
     ) -> tuple[BaseChatModel, str, ObservabilityLoggerAdapter]:
@@ -1443,6 +1453,7 @@ def create_loop_agent(
     enable_git_snapshot: bool | None = None,
     include_default_session_context: bool = True,
     enable_dynamic_root_grant: bool = False,
+    headless: bool | None = None,
 ) -> CompiledStateGraph[
     AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]
 ]:
@@ -1493,6 +1504,7 @@ def create_loop_agent(
         enable_git_snapshot=enable_git_snapshot,
         include_default_session_context=include_default_session_context,
         enable_dynamic_root_grant=enable_dynamic_root_grant,
+        headless=headless,
     )
     tool_node = builder._build_tool_node()
     model_node = builder._build_model_nodes(tool_node)

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/session/factory.py

@@ -24,6 +24,7 @@ from langchain_core.language_models.chat_models import BaseChatModel
 from ..loop.graph.factory import create_loop_agent
 from ..loop.hook import HookEngine, HooksConfigSnapshot, HookRegistry, WorkspaceTrustChecker
 from ..loop.subagent.transcript import SubagentTranscriptStore
+from ..tool_runtime.prompt.session_mode import infer_session_headless
 from ..workspace import resolve_agent_workspace_config
 from .agent_session import AgentSession
 
@@ -40,6 +41,7 @@ def create_agent_session(
     transcript_writer: SubagentTranscriptStore | None = None,
     container_type: str = "interactive",
     enable_trace: bool = True,
+    headless: bool | None = None,
     **loop_kwargs: Any,
 ) -> AgentSession:
     """创建默认走 graph_factory 注入路径的 AgentSession。
@@ -48,6 +50,10 @@ def create_agent_session(
     （环境变量 ``LANGCHAIN_AGENTX_*`` 与产品默认 ``.langchain_agentx``）。
     """
     resolved_session_id = session_id or f"session-{uuid4().hex}"
+    resolved_headless = infer_session_headless(
+        headless=headless,
+        container_type=container_type,
+    )
     workspace_cfg = resolve_agent_workspace_config(
         workspace_root=workspace_root,
         agent_home=agent_home,
@@ -65,7 +71,7 @@ def create_agent_session(
         hook_engine = HookEngine(
             snapshot,
             trust_checker=WorkspaceTrustChecker(
-                headless=_is_headless_container(container_type),
+                headless=resolved_headless,
                 workspace_trust_accepted=workspace_cfg.workspace_trust_accepted,
             ),
         )
@@ -88,6 +94,7 @@ def create_agent_session(
             enable_trace=enable_trace,
             enable_dynamic_root_grant=True,
             capabilities=capabilities,
+            headless=resolved_headless,
             **loop_kwargs,
         )
 

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/tool_runtime/pipeline.py

@@ -910,7 +910,8 @@ class ToolExecutorPipeline:
             ask_decision=auth,
             ask_prompt=auth.ask_prompt,
             suggestions=self._suggestions_from_auth(auth),
-            headless=self._headless,
+            headless=False,
+            session_headless=self._headless,
         )
 
     def _revalidate_after_l3(
@@ -1040,7 +1041,7 @@ class ToolExecutorPipeline:
         if resp.behavior == "deny":
             env = blocked_envelope(
                 tool.name,
-                resp.reason or auth.ask_prompt or "User rejected the operation.",
+                resp.message or resp.reason or auth.ask_prompt or "User rejected the operation.",
                 policy_id=auth.policy_id,
             )
             self._attach_runtime_observability(

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/tool_runtime/prompt/__init__.py

@@ -14,6 +14,8 @@ from .headless import HeadlessPromptHandler
 from .legacy_resolver_adapter import LegacyResolverPromptHandler
 from .race import HitlRaceCoordinator, PromptBranch, PromptClassifier
 from .types import (
+    DecisionReason,
+    DecisionReasonType,
     PermissionUpdate,
     PromptDecisionSource,
     PromptRequest,
@@ -22,6 +24,8 @@ from .types import (
 
 __all__ = [
     "PermissionPromptHandler",
+    "DecisionReason",
+    "DecisionReasonType",
     "PermissionUpdate",
     "PromptDecisionSource",
     "PromptRequest",

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/tool_runtime/prompt/cli_interactive.py

@@ -42,7 +42,7 @@ def permission_resolver_to_user_ui(
         return PromptResponse(
             behavior="allow" if allowed else "deny",
             decision_source=PromptDecisionSource.USER_UI,
-            reason=None if allowed else (prompt or "denied by user"),
+            message=None if allowed else (prompt or "denied by user"),
         )
 
     return _ui
@@ -67,9 +67,10 @@ class CliInteractivePromptHandler(HitlRaceCoordinator):
         user_ui: UserUiCallback,
         hooks: Sequence[PromptBranch] | None = None,
         classifier: PromptClassifier | None = None,
-        hard_timeout_seconds: float = 60.0,
+        hard_timeout_seconds: float | None = None,
         hook_timeout_seconds: float = 30.0,
         classifier_timeout_seconds: float = 15.0,
+        headless_session: bool = False,
     ) -> None:
         super().__init__(
             hooks=hooks,
@@ -78,6 +79,7 @@ class CliInteractivePromptHandler(HitlRaceCoordinator):
             hard_timeout_seconds=hard_timeout_seconds,
             hook_timeout_seconds=hook_timeout_seconds,
             classifier_timeout_seconds=classifier_timeout_seconds,
+            headless_session=headless_session,
         )
 
     @classmethod
@@ -107,6 +109,7 @@ class CliInteractivePolicyEngine(PolicyEngineDecorator):
         auto_mode_hook: Any | None = None,
         hooks: Sequence[PromptBranch] | None = None,
         classifier: PromptClassifier | None = None,
+        headless_session: bool = False,
     ) -> None:
         warnings.warn(
             "CliInteractivePolicyEngine is deprecated; use "
@@ -130,6 +133,7 @@ class CliInteractivePolicyEngine(PolicyEngineDecorator):
             user_ui=ui,
             hooks=hooks,
             classifier=classifier,
+            headless_session=headless_session,
         )
 
     @property

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/tool_runtime/prompt/headless.py

@@ -14,13 +14,19 @@ import logging
 from collections.abc import Sequence
 
 from .race import PromptBranch, _deny, _run_hook_chain
-from .types import PromptDecisionSource, PromptRequest, PromptResponse
+from .types import (
+    DecisionReason,
+    DecisionReasonType,
+    PromptDecisionSource,
+    PromptRequest,
+    PromptResponse,
+)
 
 logger = logging.getLogger(__name__)
 
 
 class HeadlessPromptHandler:
-    """非交互 L3：只跑 hook，无 hook 决议则 ``HEADLESS_FALLBACK`` deny。"""
+    """非交互 L3：只跑 hook，无 hook 决议则 ``PROMPTS_UNAVAILABLE`` deny。"""
 
     def __init__(
         self,
@@ -34,7 +40,11 @@ class HeadlessPromptHandler:
     async def handle(self, request: PromptRequest) -> PromptResponse:
         if not self._hooks:
             return _deny(
-                reason="prompts unavailable",
+                reason=DecisionReason(
+                    type=DecisionReasonType.PROMPTS_UNAVAILABLE,
+                    detail="prompts unavailable",
+                ),
+                tool_name=request.tool_name,
                 source=PromptDecisionSource.HEADLESS_FALLBACK,
             )
         try:
@@ -46,12 +56,20 @@ class HeadlessPromptHandler:
         except Exception as exc:
             logger.exception("headless hook chain failed for %s: %s", request.tool_name, exc)
             return _deny(
-                reason="headless hook failure",
+                reason=DecisionReason(
+                    type=DecisionReasonType.PROMPTS_UNAVAILABLE,
+                    detail=f"headless hook failure: {exc}",
+                ),
+                tool_name=request.tool_name,
                 source=PromptDecisionSource.HEADLESS_FALLBACK,
             )
         if resp is not None:
             return resp
         return _deny(
-            reason="prompts unavailable",
+            reason=DecisionReason(
+                type=DecisionReasonType.PROMPTS_UNAVAILABLE,
+                detail="prompts unavailable",
+            ),
+            tool_name=request.tool_name,
             source=PromptDecisionSource.HEADLESS_FALLBACK,
         )

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/tool_runtime/prompt/legacy_resolver_adapter.py

@@ -14,7 +14,13 @@ from __future__ import annotations
 import warnings
 
 from ..resolvers.base import PermissionResolver
-from .types import PromptDecisionSource, PromptRequest, PromptResponse
+from .types import (
+    DecisionReason,
+    DecisionReasonType,
+    PromptDecisionSource,
+    PromptRequest,
+    PromptResponse,
+)
 
 
 class LegacyResolverPromptHandler:
@@ -37,10 +43,14 @@ class LegacyResolverPromptHandler:
             return PromptResponse(
                 behavior="deny",
                 decision_source=PromptDecisionSource.LEGACY_RESOLVER,
-                reason=f"legacy resolver failed: {exc}",
+                decision_reason=DecisionReason(
+                    type=DecisionReasonType.USER_REJECT,
+                    detail=f"legacy resolver failed: {exc}",
+                ),
+                message=f"Permission denied: legacy resolver failed: {exc}",
             )
         return PromptResponse(
             behavior="allow" if allowed else "deny",
             decision_source=PromptDecisionSource.LEGACY_RESOLVER,
-            reason=None if allowed else (prompt or "denied by legacy resolver"),
+            message=None if allowed else (prompt or "denied by legacy resolver"),
         )

langchain-agentx-python-0.6.1/langchain_agentx/tool_runtime/prompt/messages.py

@@ -0,0 +1,44 @@
+"""
+prompt/messages.py — L3 deny 消息模板（对齐 CC AUTO_REJECT_MESSAGE）
+
+职责：
+    LLM-facing 拒因文案与 workaround 指引；内部诊断与展示层分离。
+"""
+
+from __future__ import annotations
+
+DENIAL_WORKAROUND_GUIDANCE = (
+    "You should only try to work around this restriction in reasonable ways "
+    "that do not attempt to bypass the intent behind this denial. "
+    "If you believe this capability is essential to complete the user's request, "
+    "STOP and explain to the user what you were trying to do and why you need this permission."
+)
+
+PROMPTS_UNAVAILABLE_TEMPLATE = (
+    "Permission to use {tool_name} has been denied because "
+    "this session is running in non-interactive mode. "
+    f"{DENIAL_WORKAROUND_GUIDANCE}"
+)
+
+UI_RESPONSE_TIMEOUT_TEMPLATE = (
+    "Permission to use {tool_name} has been denied because "
+    "no user response was received within the configured timeout. "
+    f"{DENIAL_WORKAROUND_GUIDANCE}"
+)
+
+USER_ABORT_TEMPLATE = (
+    "Permission to use {tool_name} has been denied because "
+    "the session was aborted before a user response was received. "
+    f"{DENIAL_WORKAROUND_GUIDANCE}"
+)
+
+NO_PARTICIPANTS_TEMPLATE = (
+    "Permission to use {tool_name} has been denied because "
+    "no permission prompt handler is configured for this session. "
+    f"{DENIAL_WORKAROUND_GUIDANCE}"
+)
+
+GENERIC_DENY_TEMPLATE = (
+    "Permission to use {tool_name} has been denied. "
+    f"{DENIAL_WORKAROUND_GUIDANCE}"
+)

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/tool_runtime/prompt/race.py

@@ -3,13 +3,14 @@ prompt/race.py — HitlRaceCoordinator（L3 默认交互 race）
 
 职责：
     三路并发（PermissionRequest hooks / classifier / user UI）+ FIRST_COMPLETED；
-    deny 优先于 allow；abort 与 hard_timeout；finally 取消余 task。
+    deny 优先于 allow；abort 与可选 hard_timeout；finally 取消余 task。
 
 链路位置：
     交互模式 pipeline 默认 prompt_handler（Phase 3 注入）。
 
 当前裁剪：
     hook 链为串行 awaitables 列表；classifier 单实例 Protocol。
+    UI 等待默认 unbounded（对齐 CC）；hard_timeout 仅显式配置时生效。
 """
 
 from __future__ import annotations
@@ -22,7 +23,13 @@ from typing import Protocol
 
 from ._abort import _resolve_abort_event, run_with_branch_timeout, wait_for_abort
 from .handler import PermissionPromptHandler
-from .types import PromptDecisionSource, PromptRequest, PromptResponse
+from .types import (
+    DecisionReason,
+    DecisionReasonType,
+    PromptDecisionSource,
+    PromptRequest,
+    PromptResponse,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -41,13 +48,15 @@ class PromptClassifier(Protocol):
 
 def _deny(
     *,
-    reason: str,
+    reason: DecisionReason,
+    tool_name: str,
     source: PromptDecisionSource = PromptDecisionSource.HEADLESS_FALLBACK,
 ) -> PromptResponse:
     return PromptResponse(
         behavior="deny",
         decision_source=source,
-        reason=reason,
+        decision_reason=reason,
+        message=reason.to_llm_message(tool_name),
     )
 
 
@@ -117,12 +126,15 @@ def _consume_completed(
     return deny, allow
 
 
+def _is_headless_request(request: PromptRequest, *, headless_session: bool) -> bool:
+    return request.headless or request.session_headless or headless_session
+
+
 class HitlRaceCoordinator:
     """
     默认 L3 交互 race：hooks ‖ classifier ‖ user_ui。
 
-    headless 请求应使用 :class:`HeadlessPromptHandler`；本类在 ``req.headless``
-    时仅跑 hook 链并 deny 兜底。
+    headless / 无 UI 会话应在入口走 ``_run_headless``，不在 race 内赌时钟。
     """
 
     def __init__(
@@ -131,9 +143,10 @@ class HitlRaceCoordinator:
         hooks: Sequence[PromptBranch] | None = None,
         classifier: PromptClassifier | None = None,
         user_ui: PromptBranch | None = None,
-        hard_timeout_seconds: float = 60.0,
+        hard_timeout_seconds: float | None = None,
         hook_timeout_seconds: float = 30.0,
         classifier_timeout_seconds: float = 15.0,
+        headless_session: bool = False,
     ) -> None:
         self._hooks = list(hooks or ())
         self._classifier = classifier
@@ -141,6 +154,14 @@ class HitlRaceCoordinator:
         self._hard_timeout = hard_timeout_seconds
         self._hook_timeout = hook_timeout_seconds
         self._classifier_timeout = classifier_timeout_seconds
+        self._headless_session = headless_session
+
+        if not headless_session and user_ui is None:
+            logger.warning(
+                "HitlRaceCoordinator created without user_ui in non-headless session — "
+                "interactive prompts will deny without participants. "
+                "Either set headless_session=True or provide user_ui."
+            )
 
     @classmethod
     def default(cls) -> HitlRaceCoordinator:
@@ -148,7 +169,7 @@ class HitlRaceCoordinator:
         return cls()
 
     async def handle(self, request: PromptRequest) -> PromptResponse:
-        if request.headless:
+        if _is_headless_request(request, headless_session=self._headless_session):
             return await self._run_headless(request)
 
         task_sources: dict[asyncio.Task, PromptDecisionSource] = {}
@@ -185,7 +206,13 @@ class HitlRaceCoordinator:
             ] = PromptDecisionSource.USER_UI
 
         if not task_sources:
-            return _deny(reason="no prompt participants configured")
+            return _deny(
+                reason=DecisionReason(
+                    type=DecisionReasonType.NO_PARTICIPANTS,
+                    detail="no prompt participants configured",
+                ),
+                tool_name=request.tool_name,
+            )
 
         abort_task: asyncio.Task[None] | None = None
         if _resolve_abort_event(request.ctx) is not None:
@@ -208,10 +235,26 @@ class HitlRaceCoordinator:
                     return_when=asyncio.FIRST_COMPLETED,
                 )
                 if not done:
-                    return _deny(reason="prompt_timeout")
+                    if self._hard_timeout is not None:
+                        return _deny(
+                            reason=DecisionReason(
+                                type=DecisionReasonType.UI_RESPONSE_TIMEOUT,
+                                detail="ui_response_timeout",
+                            ),
+                            tool_name=request.tool_name,
+                            source=PromptDecisionSource.USER_UI,
+                        )
+                    continue
 
                 if abort_task is not None and abort_task in done:
-                    raise asyncio.CancelledError("permission prompt aborted")
+                    return _deny(
+                        reason=DecisionReason(
+                            type=DecisionReasonType.USER_ABORT,
+                            detail="permission prompt aborted",
+                        ),
+                        tool_name=request.tool_name,
+                        source=PromptDecisionSource.USER_UI,
+                    )
 
                 deny_hit, allow_hit = _consume_completed(
                     done,
@@ -243,11 +286,23 @@ class HitlRaceCoordinator:
                 best_allow.decision_source,
             )
             return best_allow
-        return _deny(reason="no prompt decision")
+        return _deny(
+            reason=DecisionReason(
+                type=DecisionReasonType.NO_DECISION,
+                detail="no prompt decision",
+            ),
+            tool_name=request.tool_name,
+        )
 
     async def _run_headless(self, request: PromptRequest) -> PromptResponse:
         if not self._hooks:
-            return _deny(reason="prompts unavailable")
+            return _deny(
+                reason=DecisionReason(
+                    type=DecisionReasonType.PROMPTS_UNAVAILABLE,
+                    detail="prompts unavailable",
+                ),
+                tool_name=request.tool_name,
+            )
         resp = await _run_hook_chain(
             self._hooks,
             request,
@@ -255,4 +310,10 @@ class HitlRaceCoordinator:
         )
         if resp is not None:
             return resp
-        return _deny(reason="prompts unavailable")
+        return _deny(
+            reason=DecisionReason(
+                type=DecisionReasonType.PROMPTS_UNAVAILABLE,
+                detail="prompts unavailable",
+            ),
+            tool_name=request.tool_name,
+        )

langchain-agentx-python-0.6.1/langchain_agentx/tool_runtime/prompt/session_mode.py

@@ -0,0 +1,28 @@
+"""
+prompt/session_mode.py — 会话 headless 推断（对齐 CC shouldAvoidPermissionPrompts）
+
+职责：
+    在 session / loop 创建时推断是否应避免交互式 permission prompt。
+"""
+
+from __future__ import annotations
+
+import sys
+
+_HEADLESS_CONTAINER_TYPES = frozenset({"background", "batch", "worker", "sdk"})
+
+
+def infer_session_headless(
+    *,
+    headless: bool | None,
+    container_type: str | None = None,
+) -> bool:
+    """显式 ``headless`` 优先；否则 container_type 或无 TTY stdout 推断。"""
+    if headless is not None:
+        return headless
+    if container_type in _HEADLESS_CONTAINER_TYPES:
+        return True
+    try:
+        return not sys.stdout.isatty()
+    except Exception:
+        return False

{langchain-agentx-python-0.6.0 → langchain-agentx-python-0.6.1}/langchain_agentx/tool_runtime/prompt/types.py

@@ -19,6 +19,13 @@ from enum import StrEnum
 from typing import Any, Literal
 
 from ..models import AuthorizationDecision, ToolExecutionContext
+from .messages import (
+    GENERIC_DENY_TEMPLATE,
+    NO_PARTICIPANTS_TEMPLATE,
+    PROMPTS_UNAVAILABLE_TEMPLATE,
+    UI_RESPONSE_TIMEOUT_TEMPLATE,
+    USER_ABORT_TEMPLATE,
+)
 
 
 class PromptDecisionSource(StrEnum):
@@ -31,6 +38,38 @@ class PromptDecisionSource(StrEnum):
     LEGACY_RESOLVER = "legacy_resolver"
 
 
+class DecisionReasonType(StrEnum):
+    """结构化拒因类型（内部诊断 + LLM 模板路由）。"""
+
+    HOOK_DENY = "hook_deny"
+    CLASSIFIER_DENY = "classifier_deny"
+    USER_REJECT = "user_reject"
+    NO_PARTICIPANTS = "no_participants"
+    PROMPTS_UNAVAILABLE = "prompts_unavailable"
+    UI_RESPONSE_TIMEOUT = "ui_response_timeout"
+    USER_ABORT = "user_abort"
+    NO_DECISION = "no_decision"
+
+
+@dataclass(frozen=True)
+class DecisionReason:
+    type: DecisionReasonType
+    detail: str | None = None
+
+    def to_llm_message(self, tool_name: str) -> str:
+        if self.type == DecisionReasonType.PROMPTS_UNAVAILABLE:
+            return PROMPTS_UNAVAILABLE_TEMPLATE.format(tool_name=tool_name)
+        if self.type == DecisionReasonType.UI_RESPONSE_TIMEOUT:
+            return UI_RESPONSE_TIMEOUT_TEMPLATE.format(tool_name=tool_name)
+        if self.type == DecisionReasonType.USER_ABORT:
+            return USER_ABORT_TEMPLATE.format(tool_name=tool_name)
+        if self.type == DecisionReasonType.NO_PARTICIPANTS:
+            return NO_PARTICIPANTS_TEMPLATE.format(tool_name=tool_name)
+        if self.detail:
+            return f"Permission to use {tool_name} has been denied: {self.detail}"
+        return GENERIC_DENY_TEMPLATE.format(tool_name=tool_name)
+
+
 @dataclass(frozen=True)
 class PermissionUpdate:
     """
@@ -55,7 +94,10 @@ class PromptRequest:
     input_data: dict[str, Any]
     ctx: ToolExecutionContext
     ask_decision: AuthorizationDecision
-    headless: bool
+    headless: bool = False
+    """单次请求强制 headless（罕见 override；默认 False）。"""
+    session_headless: bool = False
+    """会话级 headless（对齐 CC shouldAvoidPermissionPrompts）。"""
     ask_prompt: str | None = None
     suggestions: tuple[PermissionUpdate, ...] = field(default_factory=tuple)
 
@@ -66,6 +108,16 @@ class PromptResponse:
 
     behavior: Literal["allow", "deny"]
     decision_source: PromptDecisionSource
-    reason: str | None = None
+    decision_reason: DecisionReason | None = None
+    message: str | None = None
     updated_input: dict[str, Any] | None = None
     permission_updates: tuple[PermissionUpdate, ...] = field(default_factory=tuple)
+
+    @property
+    def reason(self) -> str | None:
+        """Deprecated：请用 ``message`` 或 ``decision_reason.detail``。"""
+        if self.message is not None:
+            return self.message
+        if self.decision_reason is not None:
+            return self.decision_reason.detail
+        return None