fix(tools): align Plan tool handler with schema definition

[echobt]

Summary

The Plan tool had a critical mismatch between its schema definition and handler implementation:

• Schema expected: title, description, tasks, agent_analyses (all required)
• Handler processed: only todos string parameter

This caused function calls to fail when LLMs generated Plan tool calls based on the schema but the handler couldn't process the rich parameters.

Changes

cortex-engine: src/cortex-engine/src/tools/handlers/plan.rs

• Updated PlanHandler to properly parse all schema parameters
• Added input structs: PlanArgs, PlanTaskInput, AgentAnalysisInput
• Added support for:
  • architecture - High-level architecture description
  • tech_stack - Technologies and tools to be used
  • use_cases - User stories and use cases
  • risks - Identified risks with levels and mitigations
  • success_criteria - Definition of done criteria
  • timeline - Estimated completion timeline
  • estimated_changes - Scope estimate
• Convert tasks and agent_analyses to internal formats
• Generate rich markdown output with all plan sections
• Return structured plan data in metadata for TUI rendering

cortex-app-server: src/cortex-app-server/src/tools/definitions.rs

• Aligned Plan tool definition to match the engine schema
• Added all missing properties to ensure consistency

Testing

• cargo check -p cortex-engine -p cortex-app-server passes
• No new compiler warnings introduced

Impact

This ensures consistent Plan tool behavior across the codebase and fixes the broken function call flow for the Plan tool.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR successfully aligns the Plan tool's schema definition with its handler implementation in cortex-engine, resolving a critical mismatch that caused LLM-generated function calls to fail.

Key Changes

Schema Updates (definitions.rs):

• Added agent_analyses as required field for multi-agent expert analysis
• Added optional fields: architecture, tech_stack, use_cases, risks, success_criteria, timeline
• Enhanced task schema with subtasks, dependencies, complexity, and estimated_time
• Updated description to emphasize multi-agent expert perspectives

Handler Updates (plan.rs):

• Replaced simple todos string parameter with rich structured input (PlanArgs, PlanTaskInput, AgentAnalysisInput)
• Added comprehensive markdown generation with sections for architecture, tech stack, expert analyses, risks, and success criteria
• Removed #[allow(dead_code)] from AgentAnalysis as it's now actively used
• Status changed from "active" to "pending_approval" to match workflow expectations
• Validation updated from 50 items to 50 tasks (semantically clearer)

Concerns

Container Mode Incompatibility: The cortex-app-server/src/tools/planning.rs:62-94 implementation (used in container mode) was not updated and only handles title, description, tasks, and estimated_changes. Since agent_analyses is now required in the schema, this will cause deserialization failures when the Plan tool is called in container mode.

Confidence Score: 3/5

• Safe to merge for engine mode, but will break Plan tool in container mode due to missing agent_analyses handling
• The engine implementation is well-structured and correctly aligned with the schema. However, there's a critical inconsistency: the container mode implementation in planning.rs wasn't updated to handle the new required agent_analyses field, which will cause runtime failures in that deployment mode.
• src/cortex-app-server/src/tools/planning.rs requires updates to handle new schema parameters

Important Files Changed

Filename	Overview
src/cortex-engine/src/tools/handlers/plan.rs	Comprehensive refactor aligning handler with schema - adds rich plan metadata structures and markdown generation
src/cortex-app-server/src/tools/definitions.rs	Schema updated to include agent_analyses, architecture, tech_stack, and other rich planning fields

Sequence Diagram

sequenceDiagram
    participant LLM
    participant ToolRouter
    participant PlanHandler
    participant TUI

    LLM->>ToolRouter: Plan tool call with rich params
    Note over LLM: {title, description, tasks,<br/>agent_analyses, architecture,<br/>tech_stack, risks, etc.}
    
    ToolRouter->>PlanHandler: execute(arguments, context)
    
    PlanHandler->>PlanHandler: Parse JSON to PlanArgs struct
    Note over PlanHandler: Validates agent_analyses<br/>and tasks are present
    
    PlanHandler->>PlanHandler: Validate max 50 tasks
    
    PlanHandler->>PlanHandler: Convert PlanTaskInput → PlanTask
    Note over PlanHandler: Map status strings to enum<br/>(pending/in_progress/completed)
    
    PlanHandler->>PlanHandler: Convert AgentAnalysisInput → AgentAnalysis
    
    PlanHandler->>PlanHandler: Generate rich markdown output
    Note over PlanHandler: Includes sections:<br/>Architecture, Tech Stack, Tasks,<br/>Expert Analyses, Risks,<br/>Success Criteria, Timeline
    
    PlanHandler->>PlanHandler: Build plan_data JSON
    Note over PlanHandler: Full structured plan<br/>with status: "pending_approval"
    
    PlanHandler-->>ToolRouter: ToolResult with markdown + metadata
    ToolRouter-->>LLM: Success with formatted plan
    LLM-->>TUI: Display plan for user approval

Loading

[greptile-apps]

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

The schema now requires agent_analyses, but src/cortex-app-server/src/tools/planning.rs:62-94 (container mode implementation) doesn't handle this parameter - it only processes title, description, tasks, and estimated_changes. This will cause failures when LLMs call the Plan tool in container mode with the new required agent_analyses field.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/cortex-app-server/src/tools/definitions.rs
Line: 477:477

Comment:
The schema now requires `agent_analyses`, but `src/cortex-app-server/src/tools/planning.rs:62-94` (container mode implementation) doesn't handle this parameter - it only processes `title`, `description`, `tasks`, and `estimated_changes`. This will cause failures when LLMs call the Plan tool in container mode with the new required `agent_analyses` field.

How can I resolve this? If you propose a fix, please make it concise.

[echobt]

✅ Issue Addressed

The concern raised by Greptile about planning.rs not handling the agent_analyses parameter has been already fixed in commit da80b54.

Looking at the current state:

• src/cortex-app-server/src/tools/planning.rs now handles:
  • agent_analyses (line 77)
  • architecture (line 73)
  • tech_stack (line 74)
  • use_cases (line 76)
  • risks (line 78)
  • success_criteria (line 79)
  • timeline (line 80)

All tests pass:

cargo test -p cortex-app-server -p cortex-engine
# 1213 tests pass

The PR is ready for review and merge.