langchain-agentx-python 2.3.6__py3-none-any.whl → 2.3.8__py3-none-any.whl

langchain_agentx/__init__.py

@@ -1,75 +1,75 @@
-"""
-LangChain-based agent utilities for CodeBaseX.
-
-This package provides:
-- LangChain-AgentX LangGraph agent factory (`loop`)
-
-Typical usage:
-
-```python
-from langchain_agentx import create_loop_agent
-```
-"""
-
-__version__ = "2.3.6"
-
-from .mcp.call import McpToolCaller
-from .mcp.client_manager import McpClientManager, McpConnectedClient
-from .mcp.controller import McpRuntimeController
-from .mcp.config.resolver import McpConfigResolver
-from .mcp.events import CollectingEventSink
-from .loop import (  # noqa: F401
-    create_loop_agent,
-)
-
-from .loop.hook import (  # noqa: F401
-    ATTACHMENT_HOOK_BLOCKING_ERROR,
-    ATTACHMENT_HOOK_CANCELLED,
-    ATTACHMENT_HOOK_NON_BLOCKING_ERROR,
-    ATTACHMENT_HOOK_STOPPED_CONTINUATION,
-    ATTACHMENT_HOOK_SUCCESS,
-)
-from .observability import (  # noqa: F401
-    EventAdapterState,
-    LangchainAgentEvent,
-    LangchainAgentEventType,
-    LangGraphToLangchainAgentEventAdapter,
-    TraceCollector,
-    TraceSession,
-    TraceSpan,
-)
-from .provider import CompatibleChatOpenAI  # noqa: F401
-from .session import AgentSession, create_agent_session  # noqa: F401
-from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
-from .workflow import BaseWorkflow  # noqa: F401
-
-__all__ = [
-    "ATTACHMENT_HOOK_BLOCKING_ERROR",
-    "ATTACHMENT_HOOK_CANCELLED",
-    "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
-    "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
-    "ATTACHMENT_HOOK_SUCCESS",
-    "create_loop_agent",
-    "create_agent_session",
-    "AgentSession",
-    "CollectingEventSink",
-    "McpClientManager",
-    "McpConfigResolver",
-    "McpConnectedClient",
-    "McpRuntimeController",
-    "McpToolCaller",
-    "BaseWorkflow",
-    "EventAdapterState",
-    "LangchainAgentEvent",
-    "LangchainAgentEventType",
-    "LangGraphToLangchainAgentEventAdapter",
-    "TraceCollector",
-    "TraceSession",
-    "TraceSpan",
-    "CompatibleChatOpenAI",
-    "HealthCheck",
-    "HealthReport",
-    "PreflightResult",
-    "preflight",
-    "sdk_health",
-]
+"""
+LangChain-based agent utilities for CodeBaseX.
+
+This package provides:
+- LangChain-AgentX LangGraph agent factory (`loop`)
+
+Typical usage:
+
+```python
+from langchain_agentx import create_loop_agent
+```
+"""
+
+__version__ = "2.3.8"
+
+from .mcp.call import McpToolCaller
+from .mcp.client_manager import McpClientManager, McpConnectedClient
+from .mcp.controller import McpRuntimeController
+from .mcp.config.resolver import McpConfigResolver
+from .mcp.events import CollectingEventSink
+from .loop import (  # noqa: F401
+    create_loop_agent,
+)
+
+from .loop.hook import (  # noqa: F401
+    ATTACHMENT_HOOK_BLOCKING_ERROR,
+    ATTACHMENT_HOOK_CANCELLED,
+    ATTACHMENT_HOOK_NON_BLOCKING_ERROR,
+    ATTACHMENT_HOOK_STOPPED_CONTINUATION,
+    ATTACHMENT_HOOK_SUCCESS,
+)
+from .observability import (  # noqa: F401
+    EventAdapterState,
+    LangchainAgentEvent,
+    LangchainAgentEventType,
+    LangGraphToLangchainAgentEventAdapter,
+    TraceCollector,
+    TraceSession,
+    TraceSpan,
+)
+from .provider import CompatibleChatOpenAI  # noqa: F401
+from .session import AgentSession, create_agent_session  # noqa: F401
+from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
+from .workflow import BaseWorkflow  # noqa: F401
+
+__all__ = [
+    "ATTACHMENT_HOOK_BLOCKING_ERROR",
+    "ATTACHMENT_HOOK_CANCELLED",
+    "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
+    "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
+    "ATTACHMENT_HOOK_SUCCESS",
+    "create_loop_agent",
+    "create_agent_session",
+    "AgentSession",
+    "CollectingEventSink",
+    "McpClientManager",
+    "McpConfigResolver",
+    "McpConnectedClient",
+    "McpRuntimeController",
+    "McpToolCaller",
+    "BaseWorkflow",
+    "EventAdapterState",
+    "LangchainAgentEvent",
+    "LangchainAgentEventType",
+    "LangGraphToLangchainAgentEventAdapter",
+    "TraceCollector",
+    "TraceSession",
+    "TraceSpan",
+    "CompatibleChatOpenAI",
+    "HealthCheck",
+    "HealthReport",
+    "PreflightResult",
+    "preflight",
+    "sdk_health",
+]

langchain_agentx/command/prompt_shell.py

@@ -1,123 +1,123 @@
-"""
-command/prompt_shell.py — Prompt 内嵌 shell 命令执行（CC executeShellCommandsInPrompt 对齐）。
-
-职责：
-    解析并执行 prompt 中的 !`command` 占位，将输出内联替换；执行前走路由权限检查。
-
-链路位置：
-    由 command/builtin/commit* 在展开 prompt 前调用。
-"""
-
-from __future__ import annotations
-
-import re
-from collections.abc import Callable, Sequence
-from pathlib import Path
-from typing import Protocol
-
-from langchain_agentx.tool_runtime.models import ToolExecutionContext
-from langchain_agentx.tool_runtime.permission_context import set_command_bash_allow_rules
-from langchain_agentx.tool_runtime.session_store import AgentSessionStore
-from langchain_agentx.utils.subprocess_text import TextSubprocessRunner, default_text_subprocess_runner
-
-_INLINE_PATTERN = re.compile(r"!`([^`]+)`")
-
-
-class PromptShellPermissionError(RuntimeError):
-    """prompt 内嵌 shell 命令未通过 Bash 权限检查。"""
-
-
-class _ShellRunner(Protocol):
-    def run_text(
-        self,
-        argv: list[str],
-        *,
-        cwd: str | Path | None = None,
-        timeout_sec: float | None = None,
-    ) -> tuple[int, str, str]: ...
-
-
-def _default_runner_call(
-    runner: TextSubprocessRunner,
-    command: str,
-    *,
-    cwd: str | Path | None,
-) -> tuple[int, str, str]:
-    completed = runner.run(
-        ["bash", "-lc", command],
-        cwd=cwd,
-        timeout=30.0,
-        capture_output=True,
-    )
-    stdout = completed.stdout or ""
-    stderr = completed.stderr or ""
-    if completed.returncode != 0 and not stdout.strip():
-        return completed.returncode, "", stderr.strip() or f"exit {completed.returncode}"
-    return completed.returncode, stdout, stderr
-
-
-def _assert_prompt_shell_permission(
-    command: str,
-    *,
-    bash_allow_rules: Sequence[str] | None,
-    cwd: str | Path | None,
-) -> None:
-    from langchain_agentx.tools.bash.tool import BashRuntimeTool
-
-    store = AgentSessionStore("prompt-shell")
-    if bash_allow_rules:
-        set_command_bash_allow_rules(store, bash_allow_rules)
-    workspace_root = str(cwd) if cwd is not None else None
-    ctx = ToolExecutionContext(
-        tool_name="Bash",
-        tool_call_id="prompt-shell",
-        input_args={"command": command},
-        state={},
-        session_store=store,
-        workspace_root=workspace_root,
-        cwd=workspace_root,
-    )
-    l1 = BashRuntimeTool().run_l1_permission_check({"command": command}, ctx)
-    if l1.outcome == "deny":
-        message = (l1.decision.message if l1.decision else None) or "Permission denied"
-        raise PromptShellPermissionError(
-            f'Shell command permission check failed for "!`{command}`": {message}',
-        )
-
-
-async def execute_shell_commands_in_prompt(
-    text: str,
-    *,
-    cwd: str | Path | None = None,
-    runner: TextSubprocessRunner | None = None,
-    shell_runner: Callable[[str], tuple[int, str, str]] | None = None,
-    bash_allow_rules: Sequence[str] | None = None,
-    check_permissions: bool = True,
-) -> str:
-    """将 text 中所有 !`command` 替换为命令 stdout（失败时内联 stderr/exit）。"""
-    if "!`" not in text:
-        return text
-
-    text_runner = runner or default_text_subprocess_runner()
-    result = text
-
-    for match in list(_INLINE_PATTERN.finditer(text)):
-        command = match.group(1).strip()
-        if not command:
-            continue
-        if check_permissions and shell_runner is None:
-            _assert_prompt_shell_permission(
-                command,
-                bash_allow_rules=bash_allow_rules,
-                cwd=cwd,
-            )
-        if shell_runner is not None:
-            _code, stdout, stderr = shell_runner(command)
-        else:
-            _code, stdout, stderr = _default_runner_call(text_runner, command, cwd=cwd)
-        replacement = stdout.strip() if stdout.strip() else stderr.strip()
-        if not replacement:
-            replacement = "(no output)"
-        result = result.replace(match.group(0), replacement, 1)
-
-    return result
+"""
+command/prompt_shell.py — Prompt 内嵌 shell 命令执行（CC executeShellCommandsInPrompt 对齐）。
+
+职责：
+    解析并执行 prompt 中的 !`command` 占位，将输出内联替换；执行前走路由权限检查。
+
+链路位置：
+    由 command/builtin/commit* 在展开 prompt 前调用。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Protocol
+
+from langchain_agentx.tool_runtime.models import ToolExecutionContext
+from langchain_agentx.tool_runtime.permission_context import set_command_bash_allow_rules
+from langchain_agentx.tool_runtime.session_store import AgentSessionStore
+from langchain_agentx.utils.subprocess_text import TextSubprocessRunner, default_text_subprocess_runner
+
+_INLINE_PATTERN = re.compile(r"!`([^`]+)`")
+
+
+class PromptShellPermissionError(RuntimeError):
+    """prompt 内嵌 shell 命令未通过 Bash 权限检查。"""
+
+
+class _ShellRunner(Protocol):
+    def run_text(
+        self,
+        argv: list[str],
+        *,
+        cwd: str | Path | None = None,
+        timeout_sec: float | None = None,
+    ) -> tuple[int, str, str]: ...
+
+
+def _default_runner_call(
+    runner: TextSubprocessRunner,
+    command: str,
+    *,
+    cwd: str | Path | None,
+) -> tuple[int, str, str]:
+    completed = runner.run(
+        ["bash", "-lc", command],
+        cwd=cwd,
+        timeout=30.0,
+        capture_output=True,
+    )
+    stdout = completed.stdout or ""
+    stderr = completed.stderr or ""
+    if completed.returncode != 0 and not stdout.strip():
+        return completed.returncode, "", stderr.strip() or f"exit {completed.returncode}"
+    return completed.returncode, stdout, stderr
+
+
+def _assert_prompt_shell_permission(
+    command: str,
+    *,
+    bash_allow_rules: Sequence[str] | None,
+    cwd: str | Path | None,
+) -> None:
+    from langchain_agentx.tools.bash.tool import BashRuntimeTool
+
+    store = AgentSessionStore("prompt-shell")
+    if bash_allow_rules:
+        set_command_bash_allow_rules(store, bash_allow_rules)
+    workspace_root = str(cwd) if cwd is not None else None
+    ctx = ToolExecutionContext(
+        tool_name="Bash",
+        tool_call_id="prompt-shell",
+        input_args={"command": command},
+        state={},
+        session_store=store,
+        workspace_root=workspace_root,
+        cwd=workspace_root,
+    )
+    l1 = BashRuntimeTool().run_l1_permission_check({"command": command}, ctx)
+    if l1.outcome == "deny":
+        message = (l1.decision.message if l1.decision else None) or "Permission denied"
+        raise PromptShellPermissionError(
+            f'Shell command permission check failed for "!`{command}`": {message}',
+        )
+
+
+async def execute_shell_commands_in_prompt(
+    text: str,
+    *,
+    cwd: str | Path | None = None,
+    runner: TextSubprocessRunner | None = None,
+    shell_runner: Callable[[str], tuple[int, str, str]] | None = None,
+    bash_allow_rules: Sequence[str] | None = None,
+    check_permissions: bool = True,
+) -> str:
+    """将 text 中所有 !`command` 替换为命令 stdout（失败时内联 stderr/exit）。"""
+    if "!`" not in text:
+        return text
+
+    text_runner = runner or default_text_subprocess_runner()
+    result = text
+
+    for match in list(_INLINE_PATTERN.finditer(text)):
+        command = match.group(1).strip()
+        if not command:
+            continue
+        if check_permissions and shell_runner is None:
+            _assert_prompt_shell_permission(
+                command,
+                bash_allow_rules=bash_allow_rules,
+                cwd=cwd,
+            )
+        if shell_runner is not None:
+            _code, stdout, stderr = shell_runner(command)
+        else:
+            _code, stdout, stderr = _default_runner_call(text_runner, command, cwd=cwd)
+        replacement = stdout.strip() if stdout.strip() else stderr.strip()
+        if not replacement:
+            replacement = "(no output)"
+        result = result.replace(match.group(0), replacement, 1)
+
+    return result

langchain_agentx/loop/graph/factory.py

@@ -602,7 +602,9 @@ class LoopGraphBuilder:
             else HooksConfigSnapshot()
         )
         if session_store is not None:
-            session_store.hooks_snapshot = self._hook_snapshot
+            # G-2 / LOCK-7：子图不得覆盖父 session_store.hooks_snapshot
+            if not self._is_subagent:
+                session_store.hooks_snapshot = self._hook_snapshot
             from langchain_agentx.tools.skill.repository_factory import build_skill_repository
 
             session_store.skill_repository = build_skill_repository(
@@ -970,6 +972,7 @@ class LoopGraphBuilder:
             tool_registry=self._loop_loader.registry,
             tool_loader=self._services.loader,
             model=model,
+            hooks=self._services.hooks,
             workspace_root=str(self._workspace_root),
             agent_home_segment=self._workspace_cfg.agent_home_segment,
             parent_run_id=session_id or None,
@@ -1032,6 +1035,7 @@ class LoopGraphBuilder:
             tool_registry=self._loop_loader.registry,
             tool_loader=self._services.loader,
             model=model,
+            hooks=self._services.hooks,
             workspace_root=str(self._workspace_root),
             agent_home_segment=self._workspace_cfg.agent_home_segment,
             parent_run_id=session_id or None,
@@ -2429,6 +2433,12 @@ class LoopGraphBuilder:
             configurable_dict["capabilities"] = self._services.capabilities
         if self._session_memory_manager is not None:
             configurable_dict["session_memory_manager"] = self._session_memory_manager
+        if self._services.hooks is not None:
+            from langchain_agentx.tool_runtime.prompt.session_mode import (
+                PARENT_HOOK_REGISTRY_CONFIG_KEY,
+            )
+
+            configurable_dict[PARENT_HOOK_REGISTRY_CONFIG_KEY] = self._services.hooks
         if "configurable" in config:
             # Merge existing configurable keys (e.g., tool_loader, session_store)
             configurable_dict = {**config["configurable"], **configurable_dict}

langchain_agentx/loop/hook/agent_frontmatter_registration.py

@@ -0,0 +1,51 @@
+"""loop/hook/agent_frontmatter_registration.py — 自定义 agent frontmatter hooks
+
+职责：将 ``agents/*.md`` frontmatter ``hooks`` 注册到子 ``HookRegistry``（D-SELF 路径 B）。
+链路：``SubagentOrchestrator`` compose 之后 · LOCK-5 Stop→SUBAGENT_STOP。
+CC：``registerFrontmatterHooks(..., isAgent=true)``。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+from langchain_agentx.loop.hook.types import HookEvent
+from langchain_agentx.tools.skill.hook_registration import iter_skill_hook_specs
+
+if TYPE_CHECKING:
+    from langchain_agentx.loop.hook.registry import HookRegistry
+
+
+def register_agent_frontmatter_hooks(
+    target: HookRegistry | None,
+    *,
+    hooks_config: dict[str, Any] | None,
+    agent_root: Path | str | None = None,
+    agent_name: str | None = None,
+    is_subagent: bool = True,
+) -> int:
+    """注册 agent markdown frontmatter hooks；返回注册条数。"""
+    _ = agent_name
+    if target is None or not hooks_config:
+        return 0
+
+    stop_event = HookEvent.SUBAGENT_STOP if is_subagent else None
+    root = agent_root if agent_root is not None else "."
+    specs = iter_skill_hook_specs(
+        skill_root=root,
+        frontmatter={"hooks": hooks_config},
+        stop_hook_event=stop_event,
+        extra_env_defaults={"CLAUDE_AGENT_DIR": str(Path(root))},
+    )
+    if not specs:
+        return 0
+
+    registered = 0
+    for spec in specs:
+        target.register_session_spec(spec)
+        registered += 1
+    return registered
+
+
+__all__ = ["register_agent_frontmatter_hooks"]

langchain_agentx/loop/hook/registry.py

@@ -17,7 +17,10 @@ registry.py — HookRegistry 用户侧入口。
 
 from __future__ import annotations
 
+import copy
+from dataclasses import replace
 from typing import Any, Callable
+from uuid import uuid4
 
 from .config import HookSpec, HooksConfigSnapshot
 from .types import HookEvent
@@ -145,6 +148,22 @@ class HookRegistry:
         for snapshot in self._snapshots:
             snapshot.unregister_session_hook(hook_id)
 
+    def register_session_spec(self, spec: HookSpec) -> str:
+        """追加 session 来源 HookSpec（skill/agent frontmatter 等）。"""
+        session_spec = HookSpec(
+            event=spec.event,
+            executor_type=spec.executor_type,
+            config=dict(spec.config),
+            matcher=spec.matcher,
+            timeout=spec.timeout,
+            managed=spec.managed,
+            source="session",
+            once=spec.once,
+            on_success=spec.on_success,
+        )
+        self._specs.append(session_spec)
+        return session_spec.hook_id
+
     # ── P2 注册 API ──
 
     def add_command(
@@ -301,6 +320,29 @@ class HookRegistry:
         self._snapshots.append(snapshot)
         return snapshot
 
+    def fork_for_subagent(
+        self,
+        inherited_events: frozenset[HookEvent],
+        *,
+        fresh_state: bool = True,
+    ) -> HookRegistry:
+        """过滤 clone 父 registry specs 到子 loop（LOCK-2；fresh_state 预留计数器隔离扩展）。"""
+        child = HookRegistry()
+        for spec in self._specs:
+            if spec.event not in inherited_events:
+                continue
+            if fresh_state:
+                config = copy.deepcopy(spec.config)
+            else:
+                config = dict(spec.config)
+            cloned = replace(
+                spec,
+                hook_id=uuid4().hex,
+                config=config,
+            )
+            child._specs.append(cloned)
+        return child
+
     def __len__(self) -> int:
         return len(self._specs)
 

langchain_agentx/loop/subagent/context.py

@@ -30,6 +30,8 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any, Literal
 
+from langchain_agentx.loop.hook.types import HookEvent
+
 from langchain_agentx.observability.events.finish_outcome import (
     RecoveryPolicy,
     RecoveryPolicyMode,
@@ -120,6 +122,16 @@ class SubagentContext:
     mcp_child_session: Any = None
     """子 Agent inline MCP 会话；cleanup / runner finally detach。"""
 
+    # D-INHERIT：子 loop HookRegistry（orchestrator compose 后注入）
+    hooks: Any = None  # HookRegistry | None
+    inherit_hooks: bool | frozenset[HookEvent] | None = True
+    """True/None → DEFAULT_SUBAGENT_INHERITED_EVENTS；False → 不继承；frozenset → 自定义事件集。"""
+
+    progress_host_kind: str | None = None
+    """Skill fork：``skill_progress`` 时 runner 只冒泡 CC 同构 skill progress，不发 subagent 双通道。"""
+    skill_prompt: str = ""
+    """Skill fork：↔ CC ``onProgress`` ``data.prompt``（skill 正文）。"""
+
 
 @dataclass
 class SubagentResult:
@@ -164,6 +176,7 @@ def create_subagent_context(
     query_source: str | None = None,
     is_builtin_subagent: bool = False,
     recovery: RecoveryPolicy | RecoveryPolicyMode | None = None,
+    inherit_hooks: bool | frozenset[HookEvent] | None = True,
 ) -> SubagentContext:
     """工厂函数：从父上下文创建子 Agent 上下文
 
@@ -341,6 +354,7 @@ def create_subagent_context(
         thinking_generation_enabled=thinking_generation_enabled,
         query_source=resolved_query_source,
         recovery=resolved_recovery,
+        inherit_hooks=inherit_hooks,
     )
 
 
@@ -378,6 +392,8 @@ class ForkedParentRuntime:
     tool_registry: Any
     tool_loader: Any
     model: Any
+    hooks: Any = None
+    """父 loop HookRegistry（后台 fork D-INHERIT · P4）。"""
     workspace_root: str = ""
     agent_home_segment: str = ".langchain_agentx"
     parent_run_id: str | None = None

langchain_agentx/loop/subagent/forked_runner.py

@@ -123,6 +123,16 @@ class ForkedAgentRunner:
                 can_use_tool=params.can_use_tool,
                 share_abort_controller=params.share_abort_controller,
             )
+            from langchain_agentx.loop.subagent.hooks_pipeline import (
+                SubagentHookParentView,
+                apply_subagent_hooks_pipeline_async,
+            )
+
+            await apply_subagent_hooks_pipeline_async(
+                sub_ctx,
+                SubagentHookParentView.from_forked_parent_runtime(self._parent_runtime),
+                subagent_type=sub_ctx.subagent_type,
+            )
             result = await self._get_orchestrator().run_isolated(
                 sub_ctx,
                 loader=self._fork_loader(sub_ctx, params.can_use_tool),

langchain_agentx/loop/subagent/graph.py

@@ -139,5 +139,6 @@ def create_subagent_graph(
         loader=loader,
         session_store=ctx.session_store,
         capabilities=ctx.capabilities,
+        hooks=getattr(ctx, "hooks", None),
     )
     return create_loop_agent(model, config=config, services=services)

langchain_agentx/loop/subagent/hook_attachment_messages.py

@@ -0,0 +1,46 @@
+"""loop/subagent/hook_attachment_messages.py — CC hook_additional_context 消息形态（P5）
+
+对齐 CC ``createAttachmentMessage({ type: 'hook_additional_context', ... })``；
+SDK 使用 ``role: user`` + ``metadata.attachment``（与 plan_mode / memdir 一致）。
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from langchain_agentx.loop.message_contract import to_record
+
+
+def build_subagent_start_hook_messages(
+    contexts: list[str],
+    *,
+    hook_name: str = "SubagentStart",
+    hook_event: str = "SubagentStart",
+    tool_use_id: str | None = None,
+) -> list[dict[str, Any]]:
+    """将 SUBAGENT_START additional_context 转为可注入 initial_messages 的记录。"""
+    if not contexts:
+        return []
+    tid = tool_use_id if tool_use_id else str(uuid.uuid4())
+    text = "\n\n".join(c.strip() for c in contexts if isinstance(c, str) and c.strip())
+    return [
+        to_record(
+            {
+                "role": "user",
+                "content": text,
+                "metadata": {
+                    "attachment": {
+                        "type": "hook_additional_context",
+                        "content": list(contexts),
+                        "hookName": hook_name,
+                        "toolUseID": tid,
+                        "hookEvent": hook_event,
+                    }
+                },
+            }
+        )
+    ]
+
+
+__all__ = ["build_subagent_start_hook_messages"]