Merge pull request #25 from HarnessLab/update_17_4

Implemented the next missing parity slice around agent configurations.

Author: abdoelsayed2016

PARITY_CHECKLIST.md

@@ -114,6 +114,9 @@ Done:
 - [x] Query-engine runtime context-reduction summaries
 - [x] Query-engine runtime lineage summaries
 - [x] Query-engine runtime resumed-child orchestration summaries
+- [x] Filesystem-backed custom agent discovery from `~/.claude/agents` and `./.claude/agents`
+- [x] Active agent override precedence across built-in, user, and project agent definitions
+- [x] Custom agent resolution in the `Agent` tool with model, tool-filter, and initial-prompt support
 
 Missing:
 
@@ -141,6 +144,7 @@ Done:
 - [x] `agent-context` command
 - [x] `agent-context-raw` command
 - [x] `token-budget` command
+- [x] `agents` command
 - [x] Local background session mode
 - [x] Local background session listing (`agent-ps`)
 - [x] Local background session logs (`agent-logs`)
@@ -195,6 +199,7 @@ Done:
 - [x] Local planning guidance section in the Python system prompt
 - [x] Local task guidance section in the Python system prompt
 - [x] Local LSP guidance section in the Python system prompt
+- [x] Local agent-configuration guidance section in the Python system prompt
 
 - [x] Product metadata/branding from `constants/product.ts` — ported to `src/prompt_constants.py`
 - [x] API limits constants from `constants/apiLimits.ts` — ported to `src/prompt_constants.py`
@@ -312,7 +317,7 @@ Done (53 slash command names in 37 specs):
 Missing npm slash commands (from `src/commands/` — 80+ commands total):
 
 - [x] `/add-dir` — Add a new working directory
-- [ ] `/agents` — Manage agent configurations
+- [x] `/agents` — Inspect local agent configurations and show active definitions
 - [x] `/branch` — Create a branch of the current conversation
 - [ ] `/bridge` — Connect for remote-control sessions
 - [ ] `/btw` — Quick side question without interrupting main conversation
@@ -361,6 +366,7 @@ Missing npm slash commands (from `src/commands/` — 80+ commands total):
 - [ ] Feature-gated: `/buddy`, `/fork`, `/peers`, `/proactive`, `/torch`, `/workflows` (full), etc.
 - [ ] Internal: `/backfill-sessions`, `/break-cache`, `/bughunter`, `/commit-push-pr`, `/init-verifiers`, `/mock-limits`, `/version`, `/ultraplan`, `/autofix-pr`, etc.
 - [x] `/commit` — Create a git commit (prompt-type with injected git context)
+- [ ] Full `/agents` parity for create/edit/delete flows and multi-source management UI
 
 ## 6. Built-in Tools
 

README.md

@@ -31,6 +31,7 @@
 | 🆕 | **Plugin Runtime** | Full manifest-based plugin system — hooks, tool aliases, virtual tools, tool blocking |
 | 🆕 | **Nested Agent Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
 | 🆕 | **Agent Manager** | Lineage tracking, group membership, batch summaries for nested agents |
+| 🆕 | **Custom Agent Profiles** | Discover local markdown-defined agents from `~/.claude/agents` and `./.claude/agents` and use them through the `Agent` tool |
 | 🆕 | **Cost Tracking & Budgets** | Token budgets, cost budgets, tool-call limits, model-call limits, session-turn limits |
 | 🆕 | **Structured Output** | JSON schema response mode with `--response-schema-file` |
 | 🆕 | **Context Compaction** | Auto-snip, auto-compact, and reactive compaction on prompt-too-long errors |
@@ -87,6 +88,7 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
 | 🧰 **Core Tools** | File read / write / edit, glob search, grep search, shell execution |
 | 🔌 **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking |
 | 🪆 **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
+| 🧩 **Custom Agents** | Load local agent profiles from `~/.claude/agents` and `./.claude/agents`, inspect them via `/agents`, and delegate with `subagent_type` |
 | 📡 **Streaming** | Token-by-token streaming output with `--stream` |
 | 💬 **Slash Commands** | Local commands for context, config, account, search, MCP, remote, tasks, plan, hooks, and model control |
 | 🌐 **Remote Runtime** | Manifest-backed remote profiles with local `remote-mode`, `ssh-mode`, `teleport-mode`, and connect/disconnect state |
@@ -134,7 +136,7 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
 - [x] Ollama, LiteLLM Proxy, and OpenRouter backends
 - [x] Core tools: `list_dir`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `bash`
 - [x] Context building and `/context`-style usage reporting
-- [x] Slash commands: `/help`, `/context`, `/context-raw`, `/prompt`, `/permissions`, `/model`, `/tools`, `/memory`, `/status`, `/clear`
+- [x] Slash commands: `/help`, `/context`, `/context-raw`, `/token-budget`, `/prompt`, `/permissions`, `/model`, `/tools`, `/agents`, `/memory`, `/status`, `/clear`
 - [x] Session persistence and `agent-resume` flow
 - [x] Permission system (read-only, write, shell, unsafe tiers)
 - [x] Streaming token-by-token assistant output
@@ -149,6 +151,7 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
 - [x] File history journaling with snapshot IDs and replay summaries
 - [x] Nested agent delegation with dependency-aware topological batching
 - [x] Agent manager with lineage tracking and group membership
+- [x] Filesystem-backed custom agent profiles with built-in/user/project precedence
 - [x] Local daemon-style background command family
 - [x] Local background session workflows: `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, `agent-kill`
 - [x] Local remote runtime: manifest discovery, profile listing, connect/disconnect persistence, and CLI/slash flows
@@ -205,6 +208,7 @@ claw-code/
 │   ├── agent_runtime.py          # Core agent loop (LocalCodingAgent)
 │   ├── agent_tools.py            # Tool definitions & execution engine
 │   ├── agent_prompting.py        # System prompt assembly
+│   ├── agent_registry.py         # Built-in + filesystem-backed custom agent discovery
 │   ├── agent_context.py          # Context building & CLAUDE.md discovery
 │   ├── agent_context_usage.py    # Context usage estimation & reporting
 │   ├── agent_session.py          # Session state management
@@ -446,6 +450,7 @@ python3 -m src.main agent \
 | `agent-context` | Show estimated context usage |
 | `agent-context-raw` | Show the raw context snapshot |
 | `token-budget` | Show prompt-window budget, reserves, and soft/hard input limits |
+| `agents [agent_type]` | List active local agent definitions or show one agent profile |
 | `agent-resume <id> <prompt>` | Resume a saved session |
 
 ### Runtime Utility Commands
@@ -545,6 +550,7 @@ These are handled **locally** before the model loop:
 | `/permissions` | — | Show active tool permission mode |
 | `/model` | — | Show or update the active model |
 | `/tools` | — | List registered tools with permission status |
+| `/agents` | — | List active local agent definitions or show one profile |
 | `/memory` | — | Show loaded CLAUDE.md memory bundle |
 | `/status` | `/session` | Show runtime/session status summary |
 | `/clear` | — | Clear ephemeral runtime state |
@@ -554,9 +560,42 @@ python3 -m src.main agent "/help"
 python3 -m src.main agent "/context" --cwd .
 python3 -m src.main agent "/token-budget" --cwd .
 python3 -m src.main agent "/tools" --cwd .
+python3 -m src.main agent "/agents" --cwd .
 python3 -m src.main agent "/status" --cwd .
 ```
 
+### Custom Agent Definitions
+
+Custom agent profiles can live in either of these directories:
+
+- `./.claude/agents/*.md`
+- `~/.claude/agents/*.md`
+
+Project agents override user agents, and user agents override built-ins when the `agent_type` matches.
+
+Example agent file:
+
+```md
+---
+name: reviewer
+description: "Review implementation changes carefully."
+tools: read_file, grep_search
+model: Qwen/Qwen3-Coder-30B-A3B-Instruct
+initialPrompt: Start by identifying the highest-risk files.
+---
+
+Inspect code changes and summarize correctness risks, regressions, and missing tests.
+```
+
+Inspect the loaded profiles:
+
+```bash
+python3 -m src.main agents --cwd .
+python3 -m src.main agents reviewer --cwd .
+python3 -m src.main agent "/agents" --cwd .
+python3 -m src.main agent "/agents show reviewer" --cwd .
+```
+
 ### Utility Commands
 
 ```bash

TESTING_GUIDE.md

@@ -580,6 +580,24 @@ EOF
 mkdir -p ./test_cases_tasks
 ```
 
+### 4.9 Custom agent definitions
+
+```bash
+mkdir -p ./test_cases_agents/.claude/agents
+
+cat > ./test_cases_agents/.claude/agents/reviewer.md <<'EOF'
+---
+name: reviewer
+description: "Review implementation changes carefully."
+tools: read_file, grep_search
+model: Qwen/Qwen3-Coder-30B-A3B-Instruct
+initialPrompt: Start by identifying the highest-risk files.
+---
+
+Inspect code changes and summarize correctness risks, regressions, and missing tests.
+EOF
+```
+
 ## 5. Slash Command Matrix
 
 Slash commands are handled locally before the model loop.
@@ -601,6 +619,8 @@ python3 -m src.main agent "/permissions" --cwd ./test_cases
 python3 -m src.main agent "/model" --cwd ./test_cases
 python3 -m src.main agent "/model demo-model" --cwd ./test_cases
 python3 -m src.main agent "/tools" --cwd ./test_cases
+python3 -m src.main agent "/agents" --cwd ./test_cases_agents
+python3 -m src.main agent "/agents show reviewer" --cwd ./test_cases_agents
 python3 -m src.main agent "/memory" --cwd ./test_cases
 python3 -m src.main agent "/status" --cwd ./test_cases
 python3 -m src.main agent "/session" --cwd ./test_cases
@@ -678,6 +698,8 @@ python3 -m src.main agent-prompt --cwd ./test_cases
 python3 -m src.main agent-context --cwd ./test_cases
 python3 -m src.main agent-context-raw --cwd ./test_cases
 python3 -m src.main token-budget --cwd ./test_cases
+python3 -m src.main agents --cwd ./test_cases_agents
+python3 -m src.main agents reviewer --cwd ./test_cases_agents
 ```
 
 ### 6.2 Extra working directories and `CLAUDE.md` toggle

src/__init__.py

@@ -11,6 +11,14 @@
     set_system_prompt_injection,
 )
 from .agent_manager import AgentManager
+from .agent_registry import (
+    AgentLoadError,
+    AgentRegistrySnapshot,
+    find_agent_definition,
+    load_agent_registry,
+    render_agent_detail,
+    render_agents_report,
+)
 from .agent_runtime import LocalCodingAgent
 from .agent_session import AgentMessage, AgentSessionState
 from .agent_tools import build_tool_context, default_tool_registry, execute_tool
@@ -42,7 +50,9 @@
 __all__ = [
     'AgentContextSnapshot',
     'AgentManager',
+    'AgentLoadError',
     'AgentPermissions',
+    'AgentRegistrySnapshot',
     'AgentRunResult',
     'AgentRuntimeConfig',
     'AccountProfile',
@@ -114,10 +124,14 @@
     'describe_token_counter',
     'estimate_chat_overhead',
     'execute_tool',
+    'find_agent_definition',
     'format_token_budget',
     'get_system_context',
     'get_user_context',
+    'load_agent_registry',
     'load_session',
+    'render_agent_detail',
+    'render_agents_report',
     'run_parity_audit',
     'save_session',
     'set_system_prompt_injection',

src/agent_prompting.py

@@ -6,6 +6,7 @@
 from .agent_context import build_context_snapshot
 from .agent_tools import AgentTool
 from .agent_types import AgentRuntimeConfig, ModelConfig
+from .builtin_agents import AgentDefinition, format_agent_listing
 
 SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'
 
@@ -76,6 +77,7 @@ def build_system_prompt_parts(
     prompt_context: PromptContext,
     runtime_config: AgentRuntimeConfig,
     tools: dict[str, AgentTool],
+    available_agents: tuple[AgentDefinition, ...] = (),
     custom_system_prompt: str | None = None,
     append_system_prompt: str | None = None,
     override_system_prompt: str | None = None,
@@ -90,6 +92,7 @@ def build_system_prompt_parts(
         get_doing_tasks_section(),
         get_actions_section(),
         get_using_your_tools_section(enabled_tool_names),
+        get_agent_guidance_section(enabled_tool_names, available_agents),
         get_plugin_guidance_section(prompt_context),
         get_mcp_guidance_section(prompt_context),
         get_remote_guidance_section(prompt_context),
@@ -204,6 +207,26 @@ def get_tone_and_style_section() -> str:
     return '\n'.join(['# Tone and style', *prepend_bullets(items)])
 
 
+def get_agent_guidance_section(
+    enabled_tool_names: set[str],
+    available_agents: tuple[AgentDefinition, ...],
+) -> str:
+    if 'Agent' not in enabled_tool_names and 'delegate_agent' not in enabled_tool_names:
+        return ''
+    items: list[str] = [
+        'Use the Agent tool when a bounded subtask can be delegated to a specialized agent profile.',
+        'Pick a specific subagent_type when one of the available agent profiles clearly fits the task.',
+    ]
+    if not available_agents:
+        return '\n'.join(['# Agents', *prepend_bullets(items)])
+    rendered_agents = list(format_agent_listing(available_agents[:20]).splitlines())
+    items.append('Available agent types:')
+    items.append(rendered_agents)
+    if len(available_agents) > 20:
+        items.append(f'... plus {len(available_agents) - 20} more agent definitions.')
+    return '\n'.join(['# Agents', *prepend_bullets(items)])
+
+
 def get_plugin_guidance_section(prompt_context: PromptContext) -> str:
     plugin_cache = prompt_context.user_context.get('pluginCache')
     plugin_runtime = prompt_context.user_context.get('pluginRuntime')