feat(cortex-agents): implement Plan Mode & Spec Mode system (#207)

Implements AGENT_3 mission from ORCHESTRATE/AGENT_3_MODES.md.

## New Features

### Operation Mode System (cortex-agents)
- Added OperationMode enum (Build/Plan/Spec) with full lifecycle support
- Build mode: Full access to modify files and execute commands
- Plan mode: Read-only, describes changes without applying them
- Spec mode: Generates detailed implementation plans for user approval

### Spec Plan System (cortex-agents/src/spec/)
- SpecPlan: Structured specification with title, summary, steps, file changes
- SpecStep: Individual implementation step with dependencies
- FileChange: Describes file operations (Create/Modify/Delete/Rename)
- ApprovalManager: Handles async approval flow with timeout support
- ModeTransition: Manages transitions between modes with system prompt updates

### Permission Filtering
- filter_for_mode(): Restricts permissions based on operation mode
- for_mode(): Factory method for mode-appropriate permissions
- Plan/Spec modes block write operations

### TUI Integration (cortex-core, cortex-tui)
- ModeIndicator widget: Displays current mode with icon and color
- ToggleOperationMode action: Cycles Build -> Plan -> Spec -> Build
- ApproveSpec/RejectSpec actions: Handle spec plan approval workflow
- AppState.operation_mode: Tracks current mode in TUI state

## Tests
- 53 tests added for cortex-agents spec system
- 4 tests added for ModeIndicator widget
- All existing tests pass

Resolves: ORCHESTRATE/AGENT_3_MODES.md

Co-authored-by: Droid Agent <droid@factory.ai>

Author: echobt

cortex-agents/src/lib.rs

@@ -7,6 +7,23 @@
 //! - **general**: Sub-agent for parallel tasks
 //! - **research**: Read-only investigation agent
 //!
+//! # Operation Modes
+//!
+//! Agents can operate in different modes that control their capabilities:
+//! - **Build**: Full access to modify files and execute commands
+//! - **Plan**: Read-only, describes changes without applying them
+//! - **Spec**: Generates a detailed plan for user approval before building
+//!
+//! ```rust,ignore
+//! use cortex_agents::spec::OperationMode;
+//!
+//! let mode = OperationMode::Build;
+//! assert!(mode.can_write());
+//!
+//! let mode = OperationMode::Plan;
+//! assert!(!mode.can_write());
+//! ```
+//!
 //! # @Mention Support
 //!
 //! Users can invoke subagents directly using @agent syntax:
@@ -88,6 +105,7 @@ pub mod permission;
 pub mod prompt;
 pub mod registry;
 pub mod routing;
+pub mod spec;
 pub mod task;
 
 pub use agent::{
@@ -115,6 +133,10 @@ pub use mention::{
 pub use permission::{Permission, PermissionConfig};
 pub use prompt::{build_system_prompt, build_system_prompt_with_mentions, build_tool_context};
 pub use registry::{AgentRegistry, SMALL_MODEL_AGENTS};
+pub use spec::{
+    ApprovalDecision, ApprovalManager, ApprovalRequest, ChangeType, FileChange, ModeTransition,
+    OperationMode, SpecPlan, SpecStep,
+};
 
 // Re-export collaboration types
 pub use collab::{

cortex-agents/src/permission.rs

@@ -1,5 +1,9 @@
 //! Permission system for agents.
+//!
+//! This module provides permission configuration for controlling what agents
+//! can do, including file operations, command execution, and web access.
 
+use crate::spec::OperationMode;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 
@@ -84,6 +88,53 @@ impl PermissionConfig {
     pub fn can_execute_bash(&self, command: &str) -> bool {
         self.bash.check(command).is_allowed()
     }
+
+    /// Filter permissions based on the operation mode.
+    ///
+    /// In Plan and Spec modes, write operations are denied.
+    /// This returns a new `PermissionConfig` with appropriate restrictions.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use cortex_agents::permission::PermissionConfig;
+    /// use cortex_agents::spec::OperationMode;
+    ///
+    /// let config = PermissionConfig::full_access();
+    /// let filtered = config.filter_for_mode(OperationMode::Plan);
+    /// assert!(filtered.edit.is_denied());
+    /// ```
+    pub fn filter_for_mode(&self, mode: OperationMode) -> Self {
+        match mode {
+            OperationMode::Build => self.clone(),
+            OperationMode::Plan | OperationMode::Spec => {
+                Self {
+                    edit: Permission::Deny,
+                    bash: BashPermissions::read_only(),
+                    // Keep read-only permissions
+                    webfetch: self.webfetch,
+                    doom_loop: self.doom_loop,
+                    external_directory: self.external_directory,
+                }
+            }
+        }
+    }
+
+    /// Check if write operations are allowed in the current config.
+    pub fn can_write(&self) -> bool {
+        self.edit.is_allowed()
+    }
+
+    /// Create a permission config appropriate for the given mode.
+    ///
+    /// This is a convenience method that returns the right config
+    /// for each operation mode.
+    pub fn for_mode(mode: OperationMode) -> Self {
+        match mode {
+            OperationMode::Build => Self::full_access(),
+            OperationMode::Plan | OperationMode::Spec => Self::read_only(),
+        }
+    }
 }
 
 /// Bash command permissions with pattern matching.
@@ -230,4 +281,48 @@ mod tests {
         assert!(config.edit.is_denied());
         assert!(config.webfetch.is_allowed());
     }
+
+    #[test]
+    fn test_filter_for_mode_build() {
+        let config = PermissionConfig::full_access();
+        let filtered = config.filter_for_mode(OperationMode::Build);
+
+        assert!(filtered.edit.is_allowed());
+        assert!(filtered.can_write());
+    }
+
+    #[test]
+    fn test_filter_for_mode_plan() {
+        let config = PermissionConfig::full_access();
+        let filtered = config.filter_for_mode(OperationMode::Plan);
+
+        assert!(filtered.edit.is_denied());
+        assert!(!filtered.can_write());
+        // Read-only bash commands should still work
+        assert!(filtered.bash.check("ls -la").is_allowed());
+        assert!(filtered.bash.check("cat file.txt").is_allowed());
+        // Write commands should be denied/ask
+        assert!(filtered.bash.check("rm -rf /").is_denied());
+    }
+
+    #[test]
+    fn test_filter_for_mode_spec() {
+        let config = PermissionConfig::full_access();
+        let filtered = config.filter_for_mode(OperationMode::Spec);
+
+        assert!(filtered.edit.is_denied());
+        assert!(!filtered.can_write());
+    }
+
+    #[test]
+    fn test_for_mode() {
+        let build_config = PermissionConfig::for_mode(OperationMode::Build);
+        assert!(build_config.can_write());
+
+        let plan_config = PermissionConfig::for_mode(OperationMode::Plan);
+        assert!(!plan_config.can_write());
+
+        let spec_config = PermissionConfig::for_mode(OperationMode::Spec);
+        assert!(!spec_config.can_write());
+    }
 }