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

langchain_agentx/tool_runtime/state_bridge.py

@@ -0,0 +1,164 @@
+"""
+runtime/state_bridge.py — 工具级最小共享状态管理
+
+职责：
+    管理工具执行过程中的跨工具共享状态，维护：
+    - last_read_map：记录每个文件最近一次被读取的信息，
+      为 write/edit 工具的 read-before-write 约束提供基础
+    - tool_audit：工具调用审计日志，记录每次工具执行的关键信息
+    - last_glob_summary（v2-D）：最近一次 Glob 的摘要，供 Read/Grep 等读侧 **hint**（不替代授权）
+
+    状态存储在 ToolExecutionContext.state（LangGraph state）中，
+    通过固定 key 读写，不引入独立的状态存储。
+
+与 CC 对比：
+    CC 中通过 ToolUseContext.readFileState 维护文件读取状态，
+    通过 getAppState / setAppState 读写应用级状态。
+    本框架将这些能力收敛到 ToolStateBridge，通过 LangGraph state
+    作为底层存储，保持与 agent loop 的状态一致性。
+    v1：last_read_map、tool_audit；v2-D：last_glob_summary（可选写入，见 GlobRuntimeTool.after_invoke）。
+    不承担业务 workflow state。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import ToolExecutionContext
+
+
+class ToolStateBridge:
+    """
+    工具级最小共享状态管理器。
+
+    通过 ToolExecutionContext.state（LangGraph state dict）读写状态，
+    使用固定 key 隔离工具框架状态与业务状态。
+
+    维护：
+        last_read_map      — 文件最近读取记录（为 read-before-write 规则服务）
+        tool_audit         — 工具调用审计日志
+        last_glob_summary  — 最近一次 Glob 摘要（仅路径样本，防 state 膨胀）
+
+    不承担：
+        业务 workflow state
+        UI 临时态
+        task state
+    """
+
+    LAST_READ_MAP_KEY = "_tool_last_read_map"
+    AUDIT_LOG_KEY = "_tool_audit_log"
+    LAST_GLOB_SUMMARY_KEY = "_tool_last_glob_summary"
+    MAX_GLOB_SAMPLE_PATHS = 32
+
+    # ---- last_read_map ----
+
+    def get_last_read_map(self, ctx: ToolExecutionContext) -> dict[str, Any]:
+        """
+        获取 last_read_map。
+
+        结构：{ file_path: { tool_call_id, ts, line_start, line_end } }
+        不存在时返回空 dict（不修改 state）。
+        """
+        return ctx.state.get(self.LAST_READ_MAP_KEY) or {}
+
+    def set_last_read_map(
+        self,
+        ctx: ToolExecutionContext,
+        value: dict[str, Any],
+    ) -> None:
+        """更新 last_read_map，整体替换。"""
+        ctx.state[self.LAST_READ_MAP_KEY] = value
+
+    def record_read(
+        self,
+        ctx: ToolExecutionContext,
+        file_path: str,
+        *,
+        line_start: int | None = None,
+        line_end: int | None = None,
+    ) -> None:
+        """
+        记录一次文件读取，更新 last_read_map 中对应条目。
+
+        ReadRuntimeTool.after_invoke() 调用此方法，
+        WriteRuntimeTool / EditRuntimeTool 的 check_permissions() 检查此记录。
+        """
+        last_read_map = self.get_last_read_map(ctx)
+        last_read_map[file_path] = {
+            "tool_call_id": ctx.tool_call_id,
+            "ts": ctx.now_ts,
+            "line_start": line_start,
+            "line_end": line_end,
+        }
+        self.set_last_read_map(ctx, last_read_map)
+
+    def has_been_read(self, ctx: ToolExecutionContext, file_path: str) -> bool:
+        """
+        检查文件是否已被读取过（用于 read-before-write 约束）。
+        """
+        return file_path in self.get_last_read_map(ctx)
+
+    # ---- tool_audit ----
+
+    def append_audit(
+        self,
+        ctx: ToolExecutionContext,
+        record: dict[str, Any],
+    ) -> None:
+        """
+        追加一条审计记录到 tool_audit 列表。
+
+        record 建议包含：
+            tool        — 工具名
+            tool_call_id — 调用 ID
+            ts          — 时间戳
+            以及工具特定的关键字段（如 file_path、lines_read 等）
+        """
+        audit_log: list = ctx.state.get(self.AUDIT_LOG_KEY) or []
+        audit_log.append(record)
+        ctx.state[self.AUDIT_LOG_KEY] = audit_log
+
+    def get_audit_log(self, ctx: ToolExecutionContext) -> list[dict[str, Any]]:
+        """获取完整审计日志，不存在时返回空列表。"""
+        return ctx.state.get(self.AUDIT_LOG_KEY) or []
+
+    # ---- last_glob_summary（v2-D，本工程专有；CC 无对等）----
+
+    def record_last_glob(
+        self,
+        ctx: ToolExecutionContext,
+        *,
+        pattern: str,
+        search_root: str,
+        filenames: list[str],
+        num_files_page: int,
+        total_matches: int,
+        truncated: bool,
+        offset: int,
+    ) -> None:
+        """
+        覆盖写入最近一次 Glob 摘要（**不**用于 PolicyEngine，仅供 hint）。
+
+        ``filenames`` 为当前页相对路径列表；仅持久化前 ``MAX_GLOB_SAMPLE_PATHS`` 条。
+        """
+        sample = list(filenames[: self.MAX_GLOB_SAMPLE_PATHS])
+        ctx.state[self.LAST_GLOB_SUMMARY_KEY] = {
+            "pattern": pattern,
+            "search_root": search_root,
+            "sample_paths": sample,
+            "num_files_page": int(num_files_page),
+            "total_matches": int(total_matches),
+            "truncated": bool(truncated),
+            "offset": int(offset),
+            "tool_call_id": ctx.tool_call_id,
+            "ts": ctx.now_ts,
+        }
+
+    def get_last_glob_summary(self, ctx: ToolExecutionContext) -> dict[str, Any] | None:
+        """读取最近一次 Glob 摘要；不存在或类型不对时返回 ``None``。"""
+        raw = ctx.state.get(self.LAST_GLOB_SUMMARY_KEY)
+        return raw if isinstance(raw, dict) else None
+
+    def clear_last_glob_summary(self, ctx: ToolExecutionContext) -> None:
+        """清除摘要（测试或显式重置会话工具态时使用）。"""
+        ctx.state.pop(self.LAST_GLOB_SUMMARY_KEY, None)

langchain_agentx/tools/__init__.py

@@ -0,0 +1,26 @@
+"""
+内置工具包（见 `docs/design-docs/tool-runtime/langchain-tool-runtime-framework.md`）。
+
+工具体系实现状态：
+    P1（已完成）：ReadRuntimeTool — 文本/图片/PDF/Notebook 读取
+    P2（已完成）：GrepRuntimeTool / GlobRuntimeTool — 只读搜索工具
+    P3（待实现）：WriteRuntimeTool / EditRuntimeTool
+    P4（已完成）：BashRuntimeTool
+"""
+
+from .agent import AgentRuntimeTool
+from .bash import BashRuntimeTool
+from .glob import GlobRuntimeTool
+from .grep import GrepRuntimeTool
+from .read import ReadRuntimeTool
+from .skill import SkillRuntimeTool
+
+__all__ = [
+    "ReadRuntimeTool",
+    "AgentRuntimeTool",
+    "BashRuntimeTool",
+    "GlobRuntimeTool",
+    "GrepRuntimeTool",
+    "SkillRuntimeTool",
+]
+

langchain_agentx/tools/agent/__init__.py

@@ -0,0 +1,9 @@
+"""
+tools/agent — AgentRuntimeTool 包
+
+AgentRuntimeTool 为多 Agent 委派入口，负责启动子 Agent 执行复杂多步任务。
+"""
+
+from .tool import AgentRuntimeTool
+
+__all__ = ["AgentRuntimeTool"]

langchain_agentx/tools/agent/backend.py

@@ -0,0 +1,53 @@
+"""
+tools/agent/backend.py — Agent 工具池与执行模式决策
+
+职责：提供 should_run_async 与 assemble_tool_pool，避免策略细节堆入 tool.py。
+在整体链路中的位置：AgentRuntimeTool.invoke() 调用本模块后再调 run_subagent()。
+CC 对照：src/tools/AgentTool/agentToolUtils.ts 与 AgentTool.tsx 的 shouldRunAsync。
+当前裁剪范围：v1 默认同步，支持 run_in_background 显式触发与全局禁用开关。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_agentx.tool_runtime.models import ToolExecutionContext
+
+    from .models import AgentToolInput
+    from .registry.config import SubagentConfig
+
+# 不变量：子 Agent 永远不能调用 Agent 工具本身，避免递归绕过深度限制。
+_ALWAYS_DISALLOWED_FOR_SUBAGENT = {"Agent", "agent"}
+
+
+def _background_disabled() -> bool:
+    raw = os.getenv("LANGCHAIN_AGENTX_DISABLE_BACKGROUND_TASKS", "")
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def should_run_async(data: "AgentToolInput", ctx: "ToolExecutionContext") -> bool:
+    """决定是否走异步路径。"""
+    if _background_disabled():
+        return False
+    return bool(data.run_in_background)
+
+
+def assemble_tool_pool(
+    all_tools: list,
+    config: "SubagentConfig",
+    is_async: bool = False,
+) -> list:
+    """
+    组装子 Agent 工具池。
+
+    规则：先应用 config.tool_filter（若有），再强制移除 always-disallowed。
+    """
+    _ = is_async  # v1 预留参数，v2 可按异步模式再收紧工具集。
+    filtered = config.tool_filter(all_tools) if config.tool_filter else list(all_tools)
+    return [
+        tool
+        for tool in filtered
+        if getattr(tool, "name", "") not in _ALWAYS_DISALLOWED_FOR_SUBAGENT
+    ]

langchain_agentx/tools/agent/built_in/__init__.py

@@ -0,0 +1,19 @@
+"""
+tools/agent/built_in — 内置 Subagent 类型定义（仅配置 + register）
+
+职责：各子模块提供 SubagentConfig 与 register(registry)，不在包级做自注册。
+在整体链路中的位置：builtin_subagent_loader 按需 import 子模块并调用 register；
+      也可在测试中 `from langchain_agentx.tools.agent.built_in import general` 等单独引用。
+CC 对照：src/tools/AgentTool/built-in/ 目录。
+
+注意：装载策略与进程单例见同目录上一级的 ``builtin_subagent_loader.py``。
+"""
+
+__all__ = [
+    "general",
+    "explore",
+    "plan",
+    "verification",
+    "statusline_setup",
+    "agentx_guide",
+]

langchain_agentx/tools/agent/built_in/agentx_guide.py

@@ -0,0 +1,65 @@
+"""
+tools/agent/built_in/agentx_guide.py — agentx-guide 内置类型
+
+职责：定义面向 langchain_agentx 项目的文档与配置指导 subagent。
+在整体链路中的位置：builtin_subagent_loader 在 LANGCHAIN_AGENTX_BUILTIN_AGENTX_GUIDE 时调用 register()。
+CC 对照：src/tools/AgentTool/built-in/claudeCodeGuideAgent.ts（语义本地化）。
+当前裁剪范围：v3 保留 guide 能力，但名称与语义切换为本工程。
+
+典型使用场景：
+1) 用户询问本工程能力、目录结构、配置方式、运行/测试命令；
+2) 用户询问 `agent_home`、workspace、tool runtime、loop/observability 等约定；
+3) 用户需要基于仓库文档给出排障路径或最佳实践建议。
+"""
+
+from __future__ import annotations
+
+from ..registry.config import SubagentConfig
+from ..registry.registry import SubagentRegistry
+
+_ALLOWED = frozenset({"Read", "Glob", "Grep", "WebFetch", "WebSearch"})
+
+_SYSTEM_PROMPT = """You are the project guide agent for langchain_agentx.
+
+Your goal is to answer "how to use / how to configure / where to find" questions
+for this repository with evidence and actionable steps.
+
+Primary sources (in order):
+1. Local project docs and rules first (`CLAUDE.md`, `README.md`, `docs/`).
+2. Local code and tests as behavior truth source.
+3. Web search/fetch only when local docs do not cover the question.
+
+Guidelines:
+- Always prioritize repository-local documentation and code reality.
+- Cite exact local file paths used for your answer.
+- Keep responses concise, practical, and configuration-aware.
+- If information is missing, state uncertainty and propose the next best check.
+- Do not assume Claude Code official documentation applies unless explicitly asked.
+"""
+
+
+def _guide_tool_filter(all_tools: list) -> list:
+    return [t for t in all_tools if getattr(t, "name", "") in _ALLOWED]
+
+
+AGENTX_GUIDE_AGENT = SubagentConfig(
+    name="agentx-guide",
+    description=(
+        "Guide agent for langchain_agentx usage, configuration, troubleshooting, "
+        "and workflow best practices."
+    ),
+    when_to_use=(
+        "Use this agent when the user asks questions about langchain_agentx: features, "
+        "configuration, agent_home/workspace conventions, tool runtime, loop/observability, "
+        "or how to run/test the project. Answers from local docs and code first."
+    ),
+    system_prompt_factory=lambda: _SYSTEM_PROMPT,
+    tool_filter=_guide_tool_filter,
+    tools_description="Read, Glob, Grep, WebFetch, WebSearch",
+    default_max_steps=None,
+    allow_async=False,
+    tags={"guide", "docs", "project-specific"},
+)
+
+def register(registry: SubagentRegistry) -> None:
+    registry.register(AGENTX_GUIDE_AGENT)

langchain_agentx/tools/agent/built_in/explore.py

@@ -0,0 +1,80 @@
+"""
+tools/agent/built_in/explore.py — Explore 内置类型
+
+职责：定义只读探索型 subagent，并提供工具过滤函数。
+在整体链路中的位置：backend.assemble_tool_pool() 调用 config.tool_filter 执行过滤。
+CC 对照：src/tools/AgentTool/built-in/exploreAgent.ts。
+当前裁剪范围：v1 禁写工具集合固定，异步执行关闭。
+"""
+
+from __future__ import annotations
+
+from ..registry.config import SubagentConfig
+from ..registry.registry import SubagentRegistry
+
+_DISALLOWED = frozenset({"Agent", "agent", "Edit", "Write", "NotebookEdit"})
+
+_SYSTEM_PROMPT = """You are a file search specialist for langchain_agentx. \
+You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting, moving, or copying files
+- Creating temporary files anywhere, including /tmp
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use Glob for broad file pattern matching
+- Use Grep for searching file contents with regex
+- Use Read when you know the specific file path you need to read
+- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, or any file creation/modification
+- Adapt your search thoroughness based on the caller's request: "quick" for basic searches, \
+"medium" for moderate exploration, "very thorough" for comprehensive analysis
+- Wherever possible spawn multiple parallel tool calls for grepping and reading files
+- Communicate your final report directly as a regular message — do NOT attempt to create files
+
+Complete the search request efficiently and report findings clearly."""
+
+
+def _explore_tool_filter(all_tools: list) -> list:
+    """只保留 Explore 可用工具。"""
+    return [t for t in all_tools if getattr(t, "name", "") not in _DISALLOWED]
+
+
+EXPLORE_AGENT_MIN_QUERIES = 3  # CC 对照：exploreAgent.ts EXPLORE_AGENT_MIN_QUERIES
+
+EXPLORE_AGENT = SubagentConfig(
+    name="Explore",
+    description=(
+        "Fast readonly agent specialized for exploring codebases, finding files, "
+        "and answering structure/usage questions."
+    ),
+    when_to_use=(
+        'Fast agent specialized for exploring codebases. Use this when you need to quickly find files '
+        'by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), '
+        'or answer questions about the codebase (eg. "how do API endpoints work?"). '
+        'When calling this agent, specify the desired thoroughness level: "quick" for basic searches, '
+        '"medium" for moderate exploration, or "very thorough" for comprehensive analysis across '
+        "multiple locations and naming conventions."
+    ),
+    system_prompt_factory=lambda: _SYSTEM_PROMPT,
+    tool_filter=_explore_tool_filter,
+    tools_description="All tools except Agent/Edit/Write/NotebookEdit",
+    default_max_steps=None,
+    allow_async=False,
+    tags={"readonly", "search", "explore"},
+)
+
+
+def register(registry: SubagentRegistry) -> None:
+    registry.register(EXPLORE_AGENT)

langchain_agentx/tools/agent/built_in/general.py

@@ -0,0 +1,57 @@
+"""
+tools/agent/built_in/general.py — general-purpose 内置类型
+
+职责：定义通用 subagent 配置并完成自注册，不承载组合决策。
+在整体链路中的位置：builtin_subagent_loader / 测试调用 register() 装入 SubagentRegistry；被 AgentRuntimeTool 使用。
+CC 对照：src/tools/AgentTool/built-in/generalPurposeAgent.ts。
+当前裁剪范围：v1 全工具集（tool_filter=None），异步允许标记仅保留配置位。
+"""
+
+from __future__ import annotations
+
+from ..registry.config import SubagentConfig
+from ..registry.registry import SubagentRegistry
+
+_SYSTEM_PROMPT = """You are an agent for langchain_agentx. Given the user's message, \
+use available tools to complete the task fully and efficiently. \
+When you complete the task, respond with a concise report covering what was done \
+and any key findings — the caller will relay this to the user, so it only needs the essentials.
+
+Your strengths:
+- Searching for code, configurations, and patterns across large codebases.
+- Analyzing multiple files to understand system architecture.
+- Investigating complex questions that require exploring many files.
+- Performing multi-step research and implementation tasks.
+
+Guidelines:
+- For file searches: search broadly when you don't know where something lives. Use Read when you know the specific file path.
+- For analysis: start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files unless explicitly requested.
+"""
+
+GENERAL_PURPOSE_AGENT = SubagentConfig(
+    name="general-purpose",
+    description=(
+        "General-purpose agent for researching complex questions, searching for code, "
+        "and executing multi-step tasks."
+    ),
+    when_to_use=(
+        "General-purpose agent for researching complex questions, searching for code, "
+        "and executing multi-step tasks. When you are searching for a keyword or file and "
+        "are not confident that you will find the right match in the first few tries use "
+        "this agent to perform the search for you."
+    ),
+    system_prompt_factory=lambda: _SYSTEM_PROMPT,
+    tool_filter=None,
+    tools_description="All tools",
+    default_max_steps=None,
+    allow_async=True,
+    tags={"general", "multi-step"},
+)
+
+
+def register(registry: SubagentRegistry) -> None:
+    """将本内置类型注册到给定 registry（不做全局副作用）。"""
+    registry.register(GENERAL_PURPOSE_AGENT)

langchain_agentx/tools/agent/built_in/plan.py

@@ -0,0 +1,89 @@
+"""
+tools/agent/built_in/plan.py — Plan 内置类型
+
+职责：定义规划型 subagent，并提供偏规划场景工具过滤函数。
+在整体链路中的位置：backend.assemble_tool_pool() 通过 config.tool_filter 生效。
+CC 对照：src/tools/AgentTool/built-in/planAgent.ts。
+当前裁剪范围：v1 禁 Agent/Edit/Bash，保留 Write 便于产出计划文本。
+"""
+
+from __future__ import annotations
+
+from ..registry.config import SubagentConfig
+from ..registry.registry import SubagentRegistry
+
+_DISALLOWED = frozenset({"Agent", "agent", "Edit", "Write", "NotebookEdit"})
+
+_SYSTEM_PROMPT = """You are a software architect and planning specialist for langchain_agentx. \
+Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting, moving, or copying files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+
+## Your Process
+
+1. **Understand Requirements**: Focus on the requirements provided throughout the design process.
+
+2. **Explore Thoroughly**:
+   - Read any files provided to you in the initial prompt
+   - Find existing patterns and conventions using Glob, Grep, and Read
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+   - NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, or any file creation/modification
+
+3. **Design Solution**:
+   - Create implementation approach based on existing patterns
+   - Consider trade-offs and architectural decisions
+   - Follow existing conventions where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.py
+- path/to/file2.py
+
+REMEMBER: You can ONLY explore and plan. You CANNOT modify any files."""
+
+
+def _plan_tool_filter(all_tools: list) -> list:
+    return [t for t in all_tools if getattr(t, "name", "") not in _DISALLOWED]
+
+
+PLAN_AGENT = SubagentConfig(
+    name="Plan",
+    description=(
+        "Planning-focused agent for architecture decisions, implementation plans, "
+        "and scoped task decomposition."
+    ),
+    when_to_use=(
+        "Software architect agent for designing implementation plans. "
+        "Use this when you need to plan the implementation strategy for a task. "
+        "Returns step-by-step plans, identifies critical files, and considers architectural trade-offs."
+    ),
+    system_prompt_factory=lambda: _SYSTEM_PROMPT,
+    tool_filter=_plan_tool_filter,
+    tools_description="All tools except Agent/Edit/Write/NotebookEdit",
+    default_max_steps=None,
+    allow_async=False,
+    tags={"readonly", "planning"},
+)
+
+
+def register(registry: SubagentRegistry) -> None:
+    registry.register(PLAN_AGENT)

langchain_agentx/tools/agent/built_in/statusline_setup.py

@@ -0,0 +1,64 @@
+"""
+tools/agent/built_in/statusline_setup.py — statusline-setup 内置类型
+
+职责：定义状态栏配置型 subagent，专门处理 Claude Code `statusLine` 配置迁移与维护。
+在整体链路中的位置：builtin_subagent_loader 在 CLI + BUILTIN_STATUSLINE 时调用 register()。
+CC 对照：src/tools/AgentTool/built-in/statuslineSetup.ts。
+当前裁剪范围：v3 对齐垂直场景职责，限定工具仅 Read/Edit。
+
+典型使用场景：
+1) 用户要求“配置/修改 Claude Code 状态栏”；
+2) 用户要求“把 shell PS1 迁移到 statusLine.command”；
+3) 用户要求显示模型名、当前目录、context 剩余、订阅限额等状态信息。
+"""
+
+from __future__ import annotations
+
+from ..registry.config import SubagentConfig
+from ..registry.registry import SubagentRegistry
+
+_ALLOWED = frozenset({"Read", "Edit"})
+
+_SYSTEM_PROMPT = """You are a statusline-setup specialist for Claude Code.
+
+Your job is to configure or update the user's Claude Code status line setting.
+
+Core responsibilities:
+1. Read user shell config files (prefer: ~/.zshrc, ~/.bashrc, ~/.bash_profile, ~/.profile).
+2. If asked to migrate PS1, extract PS1 and convert it to a statusLine command style.
+3. Update ~/.claude/settings.json (if it is a symlink, update the target file).
+4. For long commands, you may recommend storing command logic in ~/.claude/statusline-command.sh.
+5. Summarize what was configured and remind the caller that future status line changes
+   should continue using this statusline-setup agent.
+
+Expected output behavior:
+- Return a concise configuration summary.
+- Include the exact statusLine command/script path that was set.
+- Mention any assumptions or missing inputs that block completion.
+"""
+
+
+def _statusline_tool_filter(all_tools: list) -> list:
+    return [t for t in all_tools if getattr(t, "name", "") in _ALLOWED]
+
+
+STATUSLINE_SETUP_AGENT = SubagentConfig(
+    name="statusline-setup",
+    description=(
+        "Specialized subagent for Claude Code statusLine setup/migration "
+        "(PS1 -> statusLine.command) and settings update."
+    ),
+    when_to_use=(
+        "Use this agent to configure or update the user's Claude Code status line setting. "
+        "Handles PS1 migration to statusLine.command and ~/.claude/settings.json updates."
+    ),
+    system_prompt_factory=lambda: _SYSTEM_PROMPT,
+    tool_filter=_statusline_tool_filter,
+    tools_description="Read, Edit",
+    default_max_steps=None,
+    allow_async=False,
+    tags={"cli", "statusline"},
+)
+
+def register(registry: SubagentRegistry) -> None:
+    registry.register(STATUSLINE_SETUP_AGENT)