langchain-agentx-python 0.1.6__tar.gz → 0.1.8__tar.gz

{langchain-agentx-python-0.1.6/langchain_agentx_python.egg-info → langchain-agentx-python-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.1.6
+Version: 0.1.8
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License
@@ -471,7 +471,7 @@ pytest langchain_agentx/
 
 ### 代码规范
 
-所有代码遵循项目编码规范：`docs/guides/coding-style-guide.md`
+所有代码遵循项目编码规范：`docs/guides/coding-style-guide.html`
 
 ## 贡献
 

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/README.md

@@ -251,7 +251,7 @@ pytest langchain_agentx/
 
 ### 代码规范
 
-所有代码遵循项目编码规范：`docs/guides/coding-style-guide.md`
+所有代码遵循项目编码规范：`docs/guides/coding-style-guide.html`
 
 ## 贡献
 

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/loop/graph/factory.py

@@ -101,7 +101,7 @@ from ..prompt import SystemPromptSection, build_effective_system_prompt
 from ...tools.agent.prompt import build_explore_plan_guidance
 from ..config import AgentLoopConfig, ModelContextResolver
 from ..config.runtime_settings import compute_recursion_limit
-from ...provider.model_profile import ModelProfileRegistry
+from ...provider.model_profile import ModelProfileRegistry  # re-exported for legacy tests
 from ...workspace import resolve_agent_workspace_config
 
 logger = logging.getLogger(__name__)
@@ -140,6 +140,7 @@ if TYPE_CHECKING:
     from langgraph.runtime import Runtime
     from ...task_runtime.core.interfaces import TaskRuntime
     from ...tool_runtime import AgentSessionStore, ToolRuntimeLoader
+    from ...workspace import RuntimeCapabilities
 
 class LoopGraphBuilder:
     """create_loop_agent 内部图构建器，不对外暴露。
@@ -189,6 +190,7 @@ class LoopGraphBuilder:
         workspace_trust_accepted: bool | None = None,
         raw_hooks: "HookRegistry | None" = None,
         enable_session_memory: bool = False,
+        capabilities: "RuntimeCapabilities | None" = None,
     ) -> None:
         self._raw_model = model
         self._raw_system_prompt = system_prompt
@@ -227,6 +229,7 @@ class LoopGraphBuilder:
         self._raw_workspace_trust_accepted = workspace_trust_accepted
         self._raw_hooks = raw_hooks
         self._raw_enable_session_memory = enable_session_memory
+        self._raw_capabilities = capabilities
 
         self._prepared = False
 
@@ -246,9 +249,14 @@ class LoopGraphBuilder:
         append_system_prompt = self._raw_append_system_prompt
         self._setup_loader_tools()
         self._resolve_workspace_config()
-        self._model_profile_registry = ModelProfileRegistry.from_files(
-            agent_home_dir=self._workspace_cfg.agent_home_dir
-        )
+        if self._raw_capabilities is None:
+            from ...workspace import RuntimeCapabilities as _Caps
+
+            self._raw_capabilities = _Caps.build(
+                primary_workspace_root=self._workspace_cfg.workspace_root,
+                primary_agent_home=self._workspace_cfg.agent_home,
+            )
+        self._model_profile_registry = self._raw_capabilities.model_profile_registry
         self._model_context_resolver = ModelContextResolver()
         self._session_memory_manager: SessionMemoryManager | None = None
         self._session_memory_compact_bridge: SessionMemoryCompactBridge | None = None
@@ -280,6 +288,7 @@ class LoopGraphBuilder:
             MemoryPromptBootstrap(
                 workspace_root=Path(self._workspace_root),
                 agent_home=self._agent_home,
+                available_tools=self._loader_tools,
             ).build_sections()
         )
         self._dynamic_sections.extend(
@@ -287,6 +296,7 @@ class LoopGraphBuilder:
                 workspace_cfg=self._workspace_cfg,
                 is_subagent=self._raw_is_subagent,
                 subagent_type=self._raw_subagent_type,
+                available_tools=self._loader_tools,
             ).build_sections()
         )
         system_message = self._build_system_message(
@@ -350,6 +360,8 @@ class LoopGraphBuilder:
         self._context_schema = self._raw_context_schema
         self._is_subagent = self._raw_is_subagent
         self._task_runtime = self._raw_task_runtime
+        if self._task_runtime is None and self._raw_capabilities is not None:
+            self._task_runtime = self._raw_capabilities.task_runtime
         self._task_notification_max_priority = self._raw_task_notification_max_priority
         self._queued_command_providers = list(self._raw_queued_command_providers)
         self._enable_tool_call_degradation_fix = self._raw_enable_tool_call_degradation_fix
@@ -544,7 +556,11 @@ class LoopGraphBuilder:
     def _resolve_trace_collector(self) -> TraceCollector | None:
         if not self._raw_enable_trace:
             return None
-        return self._raw_trace_collector or TraceCollector(SqliteTraceStore.from_env())
+        if self._raw_trace_collector is not None:
+            return self._raw_trace_collector
+        if self._raw_capabilities is not None and self._raw_capabilities.trace_collector is not None:
+            return self._raw_capabilities.trace_collector
+        return TraceCollector(SqliteTraceStore.from_env())
 
     def _resolve_response_format_setup(
         self,
@@ -1349,6 +1365,7 @@ def create_loop_agent(
     workspace_trust_accepted: bool | None = None,
     hooks: "HookRegistry | None" = None,
     enable_session_memory: bool = False,
+    capabilities: "RuntimeCapabilities | None" = None,
 ) -> CompiledStateGraph[
     AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]
 ]:
@@ -1392,6 +1409,7 @@ def create_loop_agent(
         workspace_trust_accepted=workspace_trust_accepted,
         raw_hooks=hooks,
         enable_session_memory=enable_session_memory,
+        capabilities=capabilities,
     )
     tool_node = builder._build_tool_node()
     model_node = builder._build_model_nodes(tool_node)

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/memory/memdir/agent_memory.py

@@ -123,15 +123,21 @@ class AgentMemoryPromptBootstrap:
         is_subagent: bool,
         subagent_type: str | None,
         scope: str = "project",
+        available_tools: list[Any] | None = None,
     ) -> None:
         self._workspace_cfg = workspace_cfg
         self._is_subagent = is_subagent
         self._subagent_type = subagent_type
         self._scope = scope
+        self._available_tools = available_tools or []
 
     def build_sections(self) -> list["SystemPromptSection"]:
+        # 只有 Agent 工具存在且是 subagent 时才注入 agent_memory prompt
         if not self._is_subagent or not self._subagent_type:
             return []
+        if not any(t.name == "Agent" for t in self._available_tools):
+            return []
+
         from langchain_agentx.loop.prompt.sections import section
 
         service = AgentMemoryPromptService(self._workspace_cfg)

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/memory/memdir/runtime.py

@@ -25,13 +25,25 @@ if TYPE_CHECKING:
 
 
 class MemoryPromptBootstrap:
-    def __init__(self, *, workspace_root: str | Path, agent_home: str) -> None:
+    def __init__(
+        self,
+        *,
+        workspace_root: str | Path,
+        agent_home: str,
+        available_tools: list[Any] | None = None,
+    ) -> None:
         self._workspace_root = workspace_root
         self._agent_home = agent_home
+        self._available_tools = available_tools or []
 
     def build_sections(self) -> list["SystemPromptSection"]:
         from langchain_agentx.loop.prompt.sections import section
 
+        # 只有 Write 工具存在时才注入 auto_memory prompt
+        # 否则 agent 会尝试写文件但没有工具，导致 fallback 到 bash → 权限拒绝
+        if not any(t.name == "write" for t in self._available_tools):
+            return []
+
         workspace_cfg = resolve_agent_workspace_config(
             workspace_root=self._workspace_root,
             agent_home=self._agent_home,

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/session/agent_session.py

@@ -38,6 +38,7 @@ from ..plugin.loader import PluginLoader
 from ..plugin.registries import AgentRegistry, CommandRegistry as PluginCommandRegistry, SkillRegistry
 from ..plugin.types import PluginLoadResult
 from ..loop.subagent.transcript import SubagentTranscriptStore
+from ..workspace import RuntimeCapabilities
 from ..workspace.config import AgentWorkspaceConfig
 
 logger = logging.getLogger(__name__)
@@ -58,6 +59,7 @@ class AgentSession:
         transcript_writer: SubagentTranscriptStore | None = None,
         container_type: str = "interactive",
         enable_trace: bool = True,
+        capabilities: RuntimeCapabilities | None = None,
     ) -> None:
         self._graph = graph
         self._graph_factory = graph_factory
@@ -71,6 +73,10 @@ class AgentSession:
         self._transcript_writer = transcript_writer
         self._last_transcript_uuid: str | None = None
         self._session_memory_manager: Any | None = None
+        self._capabilities = capabilities or RuntimeCapabilities.build(
+            primary_workspace_root=workspace_cfg.workspace_root,
+            primary_agent_home=workspace_cfg.agent_home,
+        )
         self._skill_registry = SkillRegistry()
         self._command_registry = PluginCommandRegistry()
         self._agent_registry = AgentRegistry()
@@ -270,6 +276,7 @@ class AgentSession:
             active_files_getter=getter,
             container_type=self._container_type,
             enable_trace=self._enable_trace,
+            capabilities=self._capabilities,
         )
 
     def _append_transcript_message(self, message: Any) -> None:

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/session/factory.py

@@ -33,7 +33,7 @@ def create_agent_session(
     *,
     session_id: str | None = None,
     workspace_root: str | Path | None = None,
-    agent_home: str = ".langchain_agentx",
+    agent_home: str | None = None,
     hooks: HookRegistry | None = None,
     hook_engine: Any | None = None,
     workspace_trust_prompter: Any | None = None,
@@ -42,10 +42,14 @@ def create_agent_session(
     enable_trace: bool = True,
     **loop_kwargs: Any,
 ) -> AgentSession:
-    """创建默认走 graph_factory 注入路径的 AgentSession。"""
+    """创建默认走 graph_factory 注入路径的 AgentSession。
+
+    ``workspace_root`` / ``agent_home`` 为 ``None`` 时与 ``resolve_agent_workspace_config`` 默认链一致
+    （环境变量 ``LANGCHAIN_AGENTX_*`` 与产品默认 ``.langchain_agentx``）。
+    """
     resolved_session_id = session_id or f"session-{uuid4().hex}"
     workspace_cfg = resolve_agent_workspace_config(
-        workspace_root=workspace_root or Path.cwd(),
+        workspace_root=workspace_root,
         agent_home=agent_home,
     )
     workspace_trust_accepted = _resolve_workspace_trust_accepted(
@@ -69,6 +73,7 @@ def create_agent_session(
     def _graph_factory(
         active_files_getter: Any = None,
         container_type: str = container_type,
+        capabilities: Any = None,
         **_ignored: Any,
     ):
         return create_loop_agent(
@@ -81,6 +86,7 @@ def create_agent_session(
             active_files_getter=active_files_getter,
             container_type=container_type,
             enable_trace=enable_trace,
+            capabilities=capabilities,
             **loop_kwargs,
         )
 

langchain-agentx-python-0.1.8/langchain_agentx/task_runtime/tasks/ai_analysis/base.py

@@ -0,0 +1,77 @@
+"""
+task_runtime/tasks/ai_analysis/base.py — 后台 AI 分析任务基类。
+
+职责：
+    继承 BaseWorkflow，覆盖 container_type 为 background_task；
+    提供占位 ``build_graph`` 满足 ABC；``run(**kwargs)`` 直接委派 ``_execute`` 并静默降级。
+
+链路位置：
+    由后台任务调度器通过队列轮询触发。
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import abstractmethod
+from pathlib import Path
+from typing import Any
+
+from langgraph.graph import END, START, StateGraph
+
+from ....loop.hook.registry import HookRegistry
+from ....workflow.base import BaseWorkflow
+from ....workflow.state import WorkflowState
+
+logger = logging.getLogger(__name__)
+
+
+class BackgroundAiTask(BaseWorkflow):
+    """后台 AI 分析任务基类。失败必须静默降级。"""
+
+    container_type: str = "background_task"
+
+    def __init__(
+        self,
+        workflow_id: str | None = None,
+        hook_registry: HookRegistry | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # 历史调用方曾传 hook_engine；BaseWorkflow 使用 HookRegistry + HookEngine，此处丢弃兼容字段。
+        kwargs.pop("hook_engine", None)
+        wid = workflow_id or "background_task"
+        reg = hook_registry or HookRegistry()
+        if (
+            kwargs.get("capabilities") is None
+            and kwargs.get("workspace_root") is None
+            and kwargs.get("agent_home") is None
+        ):
+            kwargs.setdefault("workspace_root", Path.cwd())
+            kwargs.setdefault("agent_home", ".langchain_agentx")
+        super().__init__(workflow_id=wid, hook_registry=reg, **kwargs)
+
+    def build_graph(self) -> StateGraph:
+        """满足 BaseWorkflow ABC；后台任务实际入口为 ``run`` → ``_execute``，不编译执行本图。"""
+        graph = StateGraph(WorkflowState)
+
+        async def _placeholder(state: WorkflowState) -> WorkflowState:
+            return state
+
+        graph.add_node("_background_placeholder", _placeholder)
+        graph.add_edge(START, "_background_placeholder")
+        graph.add_edge("_background_placeholder", END)
+        return graph
+
+    async def run(self, **kwargs: Any) -> Any:
+        """执行后台逻辑；异常时静默降级为 ``None``（不调用 LangGraph ``super().run``）。"""
+        try:
+            return await self._execute(**kwargs)
+        except Exception:
+            logger.exception("%s 执行失败，静默降级", self.__class__.__name__)
+            return None
+
+    @abstractmethod
+    async def _execute(self, **kwargs: Any) -> Any:
+        """子类实现具体分析逻辑，结果写回外部存储。"""
+
+
+__all__ = ["BackgroundAiTask"]

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/task_runtime/tasks/trace_cleanup/bootstrap.py

@@ -57,6 +57,7 @@ def try_start_trace_cleanup_after_compile(
 
     import langchain_agentx.task_runtime.tasks.ai_analysis  # noqa: F401 — registry 侧载
 
+    from langchain_agentx.loop.hook.registry import HookRegistry
     from langchain_agentx.observability.evaluation.store import EvaluationStore
     from langchain_agentx.observability.trace.sqlite_store import SqliteTraceStore
     from langchain_agentx.task_runtime.tasks.ai_analysis.registry import registry
@@ -80,7 +81,7 @@ def try_start_trace_cleanup_after_compile(
         marker_cooldown_seconds=marker_cooldown_seconds,
         task_factory_kwargs={
             "graph_factory": _noop_graph_factory,
-            "hook_engine": wiring.hook_engine,
+            "hook_registry": HookRegistry(),
         },
     )
     loop.create_task(scheduler.start())

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/task_runtime/tasks/trace_cleanup/scheduler.py

@@ -60,7 +60,7 @@ class TraceCleanupScheduler(BackgroundAiTaskScheduler):
             enable_file_lock: 为 True 时用 ``portalocker`` 非阻塞独占锁，避免多进程同时跑 DELETE。
             lock_path / marker_path: 默认与 ``trace_store.db_path`` 同目录派生文件名。
             marker_cooldown_seconds: 非 None 时，marker 存在且距上次成功清理不足该秒数则跳过本轮（多进程节流）；**None** 表示不按 marker 跳过（§4.1 Q5 幂等每轮）。
-            task_factory_kwargs: 除 ``trace_store`` / ``evaluation_store`` 外传给 ``TraceCleanupTask`` 的 ``graph_factory`` / ``hook_engine`` 等。
+            task_factory_kwargs: 除 ``trace_store`` / ``evaluation_store`` 外传给 ``TraceCleanupTask`` 的 ``graph_factory`` / ``hook_registry`` 等。
         """
         db = Path(trace_store.db_path)
         self._trace_store = trace_store

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/tool_runtime/adapter.py

@@ -160,6 +160,19 @@ class LangChainAdapter:
             except Exception:
                 tool_config_path = None
 
+        channels: set[str] | None = None
+        raw_ch = configurable.get("channels") or configurable.get("active_channels")
+        if isinstance(raw_ch, (list, tuple, set)):
+            ch_set = {str(x).strip() for x in raw_ch if str(x).strip()}
+            channels = ch_set or None
+
+        question_preview_format: str | None = None
+        raw_pf = configurable.get("question_preview_format")
+        if isinstance(raw_pf, str) and raw_pf.strip():
+            low = raw_pf.strip().lower()
+            if low in ("markdown", "html"):
+                question_preview_format = low
+
         return ToolExecutionContext(
             tool_name=tool_name,
             # 回退顺序：显式 tool_call_id -> config.tool_call_id -> input.tool_call_id -> input.id -> run_id
@@ -187,8 +200,10 @@ class LangChainAdapter:
             trace_enabled=trace_enabled,
             cancel_event=cancel_ev,
             tool_config_path=tool_config_path,
+            channels=channels,
             trace_collector=trace_collector,
             trace_emit_session_id=trace_emit_session_id,
+            question_preview_format=question_preview_format,
         )
 
     def build_structured_tool(

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/tool_runtime/loader.py

@@ -106,6 +106,7 @@ class ToolRuntimeLoader:
         """
         from pathlib import Path
 
+        from langchain_agentx.tools.ask_user_question import AskUserQuestionTool
         from langchain_agentx.tools.bash import BashRuntimeTool
         from langchain_agentx.tools.glob import GlobRuntimeTool
         from langchain_agentx.tools.grep import GrepRuntimeTool
@@ -142,6 +143,7 @@ class ToolRuntimeLoader:
         )
         self.register(BashRuntimeTool())
         self.register(UserMessageTool())
+        self.register(AskUserQuestionTool())
 
         if include_agent:
             from langchain_agentx.tools.agent import AgentRuntimeTool

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/tool_runtime/models.py

@@ -101,10 +101,17 @@ class ToolExecutionContext:
     """可选；由 ``RunnableConfig.configurable[\"cancel_event\"]`` 注入。set 后 Grep/Glob 应中断 rg。"""
     tool_config_path: str | None = None
     """可选；`LangChainAdapter` 由 workspace 解析的 `tool_runtime_config.json` 绝对路径（UserMessage v2+）。"""
+    channels: set[str] | None = None
+    """可选；当前激活渠道（如 ``{"cli"}`` / ``{"discord"}``），供 AskUserQuestion 等工具禁用无 TUI 场景。"""
     trace_collector: Any | None = None
     """可选；来自 graph state / configurable 的 `TraceCollector`，供 pipeline 发 `user_message_send`。"""
     trace_emit_session_id: str | None = None
     """可选；`emit_event(session_id=...)` 用，与 Trace 会话键（常为 `_run_id`）对齐。"""
+    question_preview_format: Literal["markdown", "html"] | None = None
+    """
+    可选；宿主经 ``RunnableConfig.configurable["question_preview_format"]`` 注入，
+    取值为 ``markdown`` 或 ``html``，供 AskUserQuestion v3 对 ``preview`` 做 HTML 校验门控。
+    """
 
 
 # ---------------------------------------------------------------------------

{langchain-agentx-python-0.1.6 → langchain-agentx-python-0.1.8}/langchain_agentx/tool_runtime/pipeline.py

@@ -31,7 +31,8 @@ runtime/pipeline.py — 工具执行管道与输出大小管控
         作为“软提示防重复”策略的执行层硬约束替代。
 
     UserMessage v2：
-        `truncate_if_needed` 之后对 `user_message` 工具发 `user_message_send`（`_emit_user_message_analytics`）。
+        `truncate_if_needed` 之后对 `user_message` 发 `user_message_send`；
+        对 `AskUserQuestion` 发 `ask_user_question_completed`（`_emit_post_invoke_analytics`）。
 """
 
 from __future__ import annotations
@@ -135,6 +136,115 @@ def _emit_user_message_analytics(
         logger.debug("user_message_send emit skipped: %s", exc)
 
 
+_ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion"
+
+
+def _try_envelope_pending_user_questions_gather(
+    *,
+    tool: RuntimeTool,
+    auth: AuthorizationDecision,
+    headless: bool,
+) -> ToolResultEnvelope | None:
+    """
+    AskUserQuestion：check_permissions 以 behavior=ask + metadata.gather_tool 表达「待 UI 收集答案」。
+    在 sync/async pipeline 中于默认 ask→blocked 之前短路，返回 ok envelope（payload 含 questions）。
+    """
+    md = auth.metadata or {}
+    if md.get("gather_tool") != tool.name:
+        return None
+    if headless:
+        return blocked_envelope(
+            tool.name,
+            "AskUserQuestion requires interactive mode.",
+            policy_id="ask_user_question_headless",
+        )
+    return ToolResultEnvelope(
+        status="ok",
+        tool_name=tool.name,
+        summary=auth.ask_prompt or auth.message or "Answer questions?",
+        payload={
+            "pending_user_questions": True,
+            "questions": md.get("questions"),
+        },
+        meta={
+            "gather_tool": tool.name,
+            "permission": "pending_user_questions",
+            "policy_id": auth.policy_id,
+        },
+    )
+
+
+def _emit_ask_user_question_analytics(
+    *,
+    tool: RuntimeTool,
+    parsed_data: dict[str, Any],
+    envelope: ToolResultEnvelope,
+    ctx: ToolExecutionContext,
+) -> None:
+    """对齐设计 v2：成功完成后发分析事件（依赖 trace_collector）。"""
+    if tool.name != _ASK_USER_QUESTION_TOOL_NAME:
+        return
+    if envelope.status != "ok":
+        return
+    meta_out = envelope.meta or {}
+    if meta_out.get("permission") == "pending_user_questions":
+        return
+    collector = ctx.trace_collector
+    session_id = ctx.trace_emit_session_id
+    if collector is None or not isinstance(session_id, str) or not session_id.strip():
+        return
+    try:
+        has_fn = getattr(collector, "has_session", None)
+        if callable(has_fn) and not has_fn(session_id):
+            return
+    except Exception:
+        return
+
+    questions = parsed_data.get("questions")
+    question_count = len(questions) if isinstance(questions, list) else 0
+    answers = parsed_data.get("answers") or {}
+    answered_count = len(answers) if isinstance(answers, dict) else 0
+    has_multi = False
+    if isinstance(questions, list):
+        for q in questions:
+            if isinstance(q, dict) and q.get("multiSelect") is True:
+                has_multi = True
+                break
+
+    payload: dict[str, Any] = {
+        "question_count": question_count,
+        "answered_count": answered_count,
+        "has_multi_select": has_multi,
+    }
+
+    try:
+        emit_fn = getattr(collector, "emit_event", None)
+        if not callable(emit_fn):
+            return
+        emit_fn(
+            session_id=session_id,
+            event_type="ask_user_question_completed",
+            payload=payload,
+        )
+    except Exception as exc:
+        logger.debug("ask_user_question_completed emit skipped: %s", exc)
+
+
+def _emit_post_invoke_analytics(
+    *,
+    tool: RuntimeTool,
+    parsed_data: dict[str, Any],
+    envelope: ToolResultEnvelope,
+    ctx: ToolExecutionContext,
+) -> None:
+    _emit_user_message_analytics(
+        tool=tool, parsed_data=parsed_data, envelope=envelope, ctx=ctx
+    )
+    _emit_ask_user_question_analytics(
+        tool=tool, parsed_data=parsed_data, envelope=envelope, ctx=ctx
+    )
+
+
 # ---------------------------------------------------------------------------
 # PermissionAskInterrupt
 # ---------------------------------------------------------------------------
@@ -421,6 +531,26 @@ class ToolExecutorPipeline:
             )
             return env
         if auth.behavior == "ask":
+            gather = _try_envelope_pending_user_questions_gather(
+                tool=tool, auth=auth, headless=self._headless
+            )
+            if gather is not None:
+                self._attach_runtime_observability(
+                    gather,
+                    ctx=ctx,
+                    events=[
+                        {
+                            "event": "permission_checked",
+                            "behavior": "pending_user_questions",
+                            "policy_id": auth.policy_id,
+                        },
+                    ],
+                    decision_trace=(auth.metadata or {}).get("decision_trace"),
+                )
+                final_g = self._output_manager.truncate_if_needed(
+                    gather, tool, ctx.tool_call_id
+                )
+                return final_g
             logger.warning(
                 "tool permission requires ask tool=%s headless=%s policy_id=%s",
                 tool.name,
@@ -462,7 +592,7 @@ class ToolExecutorPipeline:
                 final_dedup = self._output_manager.truncate_if_needed(
                     out, tool, ctx.tool_call_id
                 )
-                _emit_user_message_analytics(
+                _emit_post_invoke_analytics(
                     tool=tool,
                     parsed_data=parsed_data,
                     envelope=final_dedup,
@@ -495,7 +625,7 @@ class ToolExecutorPipeline:
         final = self._output_manager.truncate_if_needed(
             envelope, tool, ctx.tool_call_id
         )
-        _emit_user_message_analytics(
+        _emit_post_invoke_analytics(
             tool=tool,
             parsed_data=parsed_data,
             envelope=final,
@@ -554,6 +684,26 @@ class ToolExecutorPipeline:
             )
             return env
         if auth.behavior == "ask":
+            gather = _try_envelope_pending_user_questions_gather(
+                tool=tool, auth=auth, headless=self._headless
+            )
+            if gather is not None:
+                self._attach_runtime_observability(
+                    gather,
+                    ctx=ctx,
+                    events=[
+                        {
+                            "event": "permission_checked",
+                            "behavior": "pending_user_questions",
+                            "policy_id": auth.policy_id,
+                        },
+                    ],
+                    decision_trace=(auth.metadata or {}).get("decision_trace"),
+                )
+                final_g = self._output_manager.truncate_if_needed(
+                    gather, tool, ctx.tool_call_id
+                )
+                return final_g
             logger.warning(
                 "tool permission requires ask tool=%s headless=%s policy_id=%s",
                 tool.name,
@@ -615,7 +765,7 @@ class ToolExecutorPipeline:
                 final_dedup = self._output_manager.truncate_if_needed(
                     out, tool, ctx.tool_call_id
                 )
-                _emit_user_message_analytics(
+                _emit_post_invoke_analytics(
                     tool=tool,
                     parsed_data=parsed_data,
                     envelope=final_dedup,
@@ -648,7 +798,7 @@ class ToolExecutorPipeline:
         final = self._output_manager.truncate_if_needed(
             envelope, tool, ctx.tool_call_id
         )
-        _emit_user_message_analytics(
+        _emit_post_invoke_analytics(
             tool=tool,
             parsed_data=parsed_data,
             envelope=final,