[Feature Request] Agent Pre-Prompt Initialization Hook for Context Gathering

Feature Request: Agent Pre-Prompt Initialization Hook for Context Gathering

Clarification: When This Feature Is Needed

This is NOT intended to replace the recommended pattern of users providing context upfront when invoking agents. That pattern is efficient and gives users control:

@implementer Add validation to update_project() function

Files you'll need (read these first):
- pm/src/pm/models.py (line 29-36 - ProjectStage enum)
- pm/src/pm/db_operations.py (line 603 - update_project function)

This feature is specifically for cases where:

1. Skills/Commands need to be reviewed - Agent needs to read skill definitions or command files to understand available workflows before proposing
2. MCP server queries - Agent needs to fetch external data (Linear issues, GitHub PRs, documentation) that the user doesn't have locally
3. Exploratory/discovery tasks - Agent needs to discover context that the user doesn't know about yet

Problem Statement

Currently, when agents are invoked, they cannot execute tools before generating their initial prompt proposal. The workflow is strictly:

1. Agent invoked
2. Initial prompt generated (from static config + conversation context only, no tool execution)
3. User approves/modifies prompt
4. Agent executes with tools (only after approval)

This creates limitations for specific scenarios where agents need dynamic context gathering.

Motivating Use Cases

Use Case 1: Agent Needs to Review Available Skills

User: @implementer use the appropriate skill for this task

Current behavior:
Agent proposes: "I'll implement this task"
[Generic - doesn't know what skills are available]

With pre_prompt_tools:
Agent (pre-prompt):
1. Reads ~/.claude/skills/ directory
2. Reviews skill definitions to find relevant one

Agent proposes: "I'll use the 'docs-lookup' skill to fetch documentation,
then implement based on the patterns found..."

Use Case 2: MCP Server Data Required

User: @implementer implement Linear issue CON-430

Current behavior:
User must manually fetch issue details and paste them
OR agent proposes generic plan, then fetches during execution

With pre_prompt_tools:
Agent (pre-prompt):
1. Calls mcp__linear__get_issue("CON-430")
2. Reviews issue description and requirements

Agent proposes: "I'll implement Linear issue CON-430 'Add JWT authentication'.
Based on the issue acceptance criteria, I'll create middleware in auth.ts
following the pattern described..."

Use Case 3: Understanding Command/Workflow Logic

User: @offload /docs fastapi background tasks

Current behavior:
Agent proposes generic plan without knowing if /docs command exists or what it does

With pre_prompt_tools:
Agent (pre-prompt):
1. Reads ~/.claude/commands/docs.md to understand command behavior
2. Checks if Context7 MCP server is available

Agent proposes: "I'll execute /docs using the Context7 MCP server to fetch
FastAPI background task documentation, then summarize the findings..."

Use Case 4: Discovery Tasks

User: @debugger find where authentication errors are logged

Current behavior:
Agent proposes: "I'll search for authentication errors"
[Needs user approval before it can even start searching]

With pre_prompt_tools:
Agent (pre-prompt):
1. Greps for "authentication" + "error" patterns
2. Identifies relevant log files

Agent proposes: "I found authentication errors in 3 locations:
- auth.service.ts:145 (invalid token errors)
- middleware/jwt.ts:89 (expired token errors)
- api/login.ts:203 (failed login attempts)
I'll investigate the middleware errors first as they're most frequent..."

Proposed Solution

Add a new agent configuration field: pre_prompt_tools that allows agents to execute specific tools before generating their initial prompt proposal.

Configuration Example

---
name: implementer
description: Interactive agent for implementing features
tools: Read, Grep, Glob, Bash, Edit, Write
pre_prompt_tools: Read, Grep, Glob, mcp__linear__get_issue  # NEW: Tools for context gathering
model: sonnet
---

# Implementer Agent

When invoked, I can use Read, Grep, Glob, and Linear MCP tools to gather 
context before proposing my initial plan to the user.

Behavior

1. Agent invoked (e.g., @implementer implement CON-430)
2. Pre-prompt execution phase (NEW):

• Agent uses pre_prompt_tools to gather dynamic context
• Queries MCP servers for external data
• Reads skill/command definitions
• Discovers relevant code patterns

1. Initial prompt generated with full context
2. User approves/modifies the informed prompt
3. Agent executes the approved plan

Safety & Limitations

• Read-only tools only: pre_prompt_tools should only allow non-destructive operations:
• ✅ Read, Grep, Glob, Bash (read-only commands), MCP read operations
• ❌ Edit, Write, Bash (write commands)
• Token budget limit: Impose a limit (e.g., 10k tokens) on pre-prompt tool usage
• Timeout: Hard timeout (e.g., 30 seconds) for pre-prompt phase
• User visibility: Show [Gathering context...] indicator during pre-prompt phase
• Optional: Pre-prompt phase should be skippable with a flag like --no-pre-prompt

Relationship to Current Best Practices

This does NOT replace the recommended pattern where users provide file paths upfront. That pattern remains the most efficient for:

• Known file-based tasks
• Structured implementations
• When user knows exactly what context is needed

This feature complements it by handling cases where:

• Context is external (MCP servers)
• Context needs discovery (finding relevant files/patterns)
• Context is meta (skill definitions, command logic)

Related Issues & Context

This builds on several related feature requests:

• #4908 - Scoped Context Passing for Subagents
• #4073 - SwitchContext tool for isolated editing sessions
• #2058 - Mode-specific permissions

Benefits

For Dynamic Context Scenarios

• MCP integration - Agents can auto-fetch Linear issues, GitHub PRs, documentation
• Skill awareness - Agents can review available skills before proposing
• Discovery tasks - Agents can find relevant code before proposing analysis

For User Experience

• Informed proposals - Agent proposes with specific external data already fetched
• Reduced friction - User doesn't need to manually fetch MCP data before agent invocation
• Better decisions - User approves/rejects based on complete picture including external data

Does NOT Change

• User control - Users still approve/modify prompts before execution
• Token efficiency - Users can still provide context upfront when they know what's needed
• Recommended pattern - Providing file paths upfront remains the best practice for file-based tasks

Implementation Suggestions

Phase 1: Basic Pre-Prompt Tools

pre_prompt_tools: Read, Grep, Glob

Agent can use listed tools before generating initial prompt.

Phase 2: MCP Tool Support (Primary Use Case)

pre_prompt_tools: Read, mcp__linear__get_issue, mcp__context7__get-library-docs

Agent can fetch external data via MCP before prompt generation.

Phase 3: Conditional Pre-Prompt

pre_prompt_mode: auto  # Agent decides if pre-prompt gathering needed

Agent analyzes user request and automatically gathers relevant context only when necessary.

Alternatives Considered

1. Always allow all read-only tools in pre-prompt phase

• Concern: Too permissive, could waste tokens
• Why rejected: Better to have explicit control

1. User manually provides context before invoking agent

• Current behavior and remains recommended for file-based tasks
• Why insufficient: Doesn't work for MCP data, skill discovery, or exploratory tasks

1. No pre-prompt phase, rely on conversation context only

• Current behavior
• Why insufficient for specific cases: Cannot access MCP servers, skill definitions, or perform discovery

Configuration Compatibility

Backward Compatible: If pre_prompt_tools is not specified, agent behaves as current (no pre-prompt phase).

# Old agent (no change in behavior)
---
name: old-agent
tools: Read, Edit, Write
---

# New agent (with pre-prompt phase for MCP/discovery)
---
name: new-agent
tools: Read, Edit, Write
pre_prompt_tools: Read, mcp__linear__get_issue
---

Priority

Medium-High - This addresses specific but important use cases:

• MCP server integration workflows
• Skill-aware agent behavior
• Discovery and exploratory tasks

Does NOT affect the recommended pattern for structured, file-based tasks.

---

Submitted by: Community user
Related to: Agent lifecycle, MCP integration, skill awareness
Impact: Users working with MCP servers, custom skills, and discovery tasks