add plan tool

Author: alexylon

AGENTS.md

@@ -83,6 +83,7 @@ src/
 │   ├── bashexec.rs      # Sandboxed bash execution
 │   ├── codesearch.rs    # Ripgrep integration
 │   ├── image.rs         # Image handling (local paths, URLs)
+│   ├── plan.rs          # Task-plan validation and terminal rendering
 │   ├── permissions.rs   # 3-tier command permission system
 │   ├── tool_name.rs     # Type-safe tool name enum
 │   ├── types.rs         # Tool definitions for API
@@ -130,6 +131,11 @@ src/
 - Trims to MAX_MESSAGES (500) to prevent token overflow
 - Builds system prompt with features list and custom instructions
 
+**src/tools/plan.rs**
+- Validates `update_plan` payloads and enforces one `in_progress` step
+- Builds compact model-facing acknowledgements and styled terminal checklists
+- Safe-mode compatible because it does not read, write, execute commands, or access the network
+
 **src/tools/filesystem.rs**
 - validate_path: Security-critical path validation
 - All operations check sandboxing before execution
@@ -321,7 +327,7 @@ cargo test -- --nocapture     # Show println output
 
 1. Add variant to `src/tools/tool_name.rs` (ToolName enum, as_str, from_str)
 2. Define tool schema in `src/tools/types.rs` and add to tool lists
-3. Implement execution in `src/tools/mod.rs` (ToolExecutor::execute match arm)
+3. Implement execution in `src/tools/executor.rs` (ToolExecutor::execute match arm)
 4. Add tests in `src/tools/tests.rs`
 5. Update README.md with tool description
 
@@ -431,6 +437,7 @@ Gitignored scratchpad for helper files the user asks to be created there — typ
 - After each important change, but only when you have finalized the current task, update if relevant:
     - `README.md`
     - `CHANGELOG.md` under `[Unreleased]`. Stick to the standard Keep-a-Changelog categories (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`) — do NOT add an `Internal` section. Pure refactors, dead-code removals, and test-only additions are not user-notable; leave them out. The changelog is for users, not contributors. Within each entry, describe the user-visible behaviour in plain English: no file paths, no bare `Type::method` shorthand, no Rust attribute syntax, no crate names. CLI flags, env vars, slash commands, and API wire formats are fine because the user encounters them directly.
+    - `STRUCTURE.md`
 - Run:
     - `cargo fmt --all`
     - `cargo clippy --all-targets -- -D warnings`

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to Sofos are documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- **Visible task plans for multi-step work.** The assistant can now call `update_plan` to show the current plan with `pending`, `in_progress`, and `completed` statuses. Plan updates are available in safe mode too because they do not read or modify files, and the terminal renders them as a compact styled checklist while the model receives only a short acknowledgement.
+
 ### Changed
 
 - **File-edit tool results are now fixed-size summaries.** `edit_file`, `write_file` (when it overwrites an existing file), and `morph_edit_file` previously returned the full syntax-highlighted diff to the model as the tool result. The colored diff carried truecolor ANSI escape sequences that roughly multiplied the byte count per line, and the tool result stayed in conversation history for every subsequent turn — so a session with many edits paid that bloated cost again on each later turn, and a single large rewrite could push the response into the hundreds of thousands of tokens. The model now sees a fixed two-line summary (`Success. Updated the following files:` followed by `M <path>`) regardless of edit size, while the terminal still renders the full colored diff exactly as before. If the model needs to verify the post-edit state it can re-read a range of the file.

README.md

@@ -63,6 +63,7 @@ Sofos provides an AI assistant inside your terminal with controlled access to yo
 - run safe build and test commands;
 - fetch documentation and use provider-native web search;
 - review local, clipboard, or web images;
+- update a visible task plan during multi-step work;
 - save and resume conversations;
 - connect to external tools through Model Context Protocol servers.
 
@@ -309,6 +310,7 @@ Provider mapping:
 | `delete_file` | Delete a file after confirmation. External paths require Write permission. |
 | `delete_directory` | Delete a directory after confirmation. External paths require Write permission. |
 | `execute_bash` | Run approved shell commands through the bash permission system. |
+| `update_plan` | Show the current multi-step task plan with `pending`, `in_progress`, and `completed` statuses. |
 | `web_fetch` | Fetch a URL and return readable text. |
 | `web_search` | Provider-native web search. |
 
@@ -322,6 +324,7 @@ Safe mode is enabled with `--safe-mode` or `/s`. It restricts the native tool se
 - `read_file`;
 - `glob_files`;
 - `search_code` when ripgrep is installed;
+- `update_plan`;
 - `web_fetch`;
 - `web_search`.
 

STRUCTURE.md

@@ -47,9 +47,10 @@
    - [7.7 `tools/codesearch.rs`](#77-toolscodesearchrs)
    - [7.8 `tools/image.rs`](#78-toolsimagers)
    - [7.9 `tools/morph_validate.rs`](#79-toolsmorph_validaters)
-   - [7.10 `tools/types.rs`](#710-toolstypesrs)
-   - [7.11 `tools/tool_name.rs`](#711-toolstool_namers)
-   - [7.12 `tools/utils.rs`](#712-toolsutilsrs)
+   - [7.10 `tools/plan.rs`](#710-toolsplanrs)
+   - [7.11 `tools/types.rs`](#711-toolstypesrs)
+   - [7.12 `tools/tool_name.rs`](#712-toolstool_namers)
+   - [7.13 `tools/utils.rs`](#713-toolsutilsrs)
 8. [`mcp/`](#8-mcp)
    - [8.1 `mcp/config.rs`](#81-mcpconfigrs)
    - [8.2 `mcp/protocol.rs`](#82-mcpprotocolrs)
@@ -277,6 +278,8 @@ src/
 │   │   # Local and web image detection, validation, encoding, and message-content conversion.
 │   ├── morph_validate.rs
 │   │   # Safety checks that reject suspicious or truncated Morph Apply output before writing files.
+│   ├── plan.rs
+│   │   # `update_plan` argument validation, model-facing acknowledgements, and terminal checklist rendering.
 │   ├── tool_name.rs
 │   │   # Type-safe native tool-name enum and string conversion logic.
 │   ├── types.rs
@@ -1019,7 +1022,24 @@ Rules:
 - Morph output must be validated against the original file.
 - Rejected Morph output leaves the original file untouched and asks the model to use `edit_file`.
 
-### 7.10 `tools/types.rs`
+### 7.10 `tools/plan.rs`
+
+`tools/plan.rs` owns the `update_plan` payload parsing and the on-screen checklist rendering.
+
+It contains:
+
+- the `PlanStepStatus`, `PlanStep`, and `PlanUpdate` types;
+- payload validation, including the at-most-one `in_progress` step rule;
+- the compact model-facing acknowledgement string;
+- the styled terminal checklist with status markers and counts.
+
+Rules:
+
+- The model receives only a short acknowledgement, never the full plan body, so conversation history stays bounded.
+- The renderer must reuse `ui::ACCENT_RGB` so the plan checklist matches the rest of sofos' colour scheme.
+- The module performs no file or network access and is safe to expose in read-only mode.
+
+### 7.11 `tools/types.rs`
 
 `tools/types.rs` owns native tool definitions exposed to providers.
 
@@ -1038,7 +1058,7 @@ Rules:
 - Tool definitions should match dispatcher parameter names and accepted aliases where possible.
 - Provider-specific server-side tools should be represented in shared `api/types.rs` but selected here where appropriate.
 
-### 7.11 `tools/tool_name.rs`
+### 7.12 `tools/tool_name.rs`
 
 `tools/tool_name.rs` owns the type-safe native tool-name enum.
 
@@ -1053,7 +1073,7 @@ Rules:
 - Native dispatch should match on `ToolName`, not raw strings.
 - Adding a tool requires updating this enum, schemas, dispatch, tests, and user documentation where applicable.
 
-### 7.12 `tools/utils.rs`
+### 7.13 `tools/utils.rs`
 
 `tools/utils.rs` owns shared tool utilities.
 

src/config.rs

@@ -83,10 +83,10 @@ pub fn max_context_tokens_for(model: &str) -> usize {
     crate::api::model_info::lookup(model).effective_window() as usize
 }
 
-/// Auto-compaction trigger for `model`. Mirrors the codex pattern of
-/// keeping the cost-shaping cap and the API ceiling as separate
-/// concepts: this is where the LLM-summary phase fires, while
-/// [`max_context_tokens_for`] is where the hard drop-trim kicks in.
+/// Auto-compaction trigger for `model`. Keeps the cost-shaping cap and
+/// the API ceiling as separate concepts: this is where the LLM-summary
+/// phase fires, while [`max_context_tokens_for`] is where the hard
+/// drop-trim kicks in.
 pub fn auto_compact_token_limit_for(model: &str) -> usize {
     crate::api::model_info::lookup(model).auto_compact_at() as usize
 }
@@ -97,7 +97,8 @@ pub fn auto_compact_token_limit_for(model: &str) -> usize {
 pub const SAFE_MODE_MESSAGE: &str = "[SYSTEM: Safe (read-only) mode has been enabled. \
                                      No file modifications or bash commands are allowed. \
                                      Available tools: list_directory, read_file, glob_files, \
-                                     search_code (when ripgrep is installed), web_fetch, web_search.]";
+                                     search_code (when ripgrep is installed), update_plan, \
+                                     web_fetch, web_search.]";
 
 /// Normal mode message shown when switching from safe mode
 pub const NORMAL_MODE_MESSAGE: &str = "[SYSTEM: Normal (unrestricted) mode has been enabled. \

src/repl/conversation/mod.rs

@@ -53,10 +53,11 @@ impl ConversationHistory {
             "5. Search the web for information",
             "6. Execute read-only bash commands (for testing code)",
             "7. View images (user includes image path or URL in their message)",
+            "8. Update a visible task plan for multi-step work",
         ];
 
         if has_code_search {
-            features.push("8. Search code using ripgrep");
+            features.push("9. Search code using ripgrep");
         }
 
         let edit_instruction = if has_morph {
@@ -90,6 +91,7 @@ When helping users:
 - Never run destructive or irreversible shell commands (e.g., rm -rf, rm, rmdir, dd, mkfs*, fdisk/parted, wipefs, chmod/chown -R on broad paths, truncate, :>, >/dev/sd*, kill -9 on system services).
 Prefer read-only commands and dry-runs; if a potentially destructive action seems necessary, stop and request explicit confirmation before proceeding.
 - Explain your reasoning when using tools
+- Use update_plan for complex or multi-step tasks, and keep exactly one step in_progress when work is underway
 
 Outside Workspace Access (three separate scopes, each prompted independently):
 - Read scope: read_file and list_directory can access absolute or ~/ paths. If not pre-configured, the user is prompted to allow access and can optionally remember the decision.

src/tools/executor.rs

@@ -8,6 +8,7 @@ use crate::tools::codesearch::CodeSearchTool;
 use crate::tools::filesystem::FileSystemTool;
 use crate::tools::morph_validate;
 use crate::tools::permissions::{self, PermissionManager};
+use crate::tools::plan;
 use crate::tools::resolve::ResolvedPath;
 use crate::tools::types::{
     add_code_search_tool, get_all_tools, get_all_tools_with_morph, get_read_only_tools,
@@ -1263,6 +1264,13 @@ impl ToolExecutor {
                 let result = self.bash_executor.execute(command)?;
                 Ok(result)
             }
+            ToolName::UpdatePlan => {
+                let update = plan::parse_plan_update(input)?;
+                return Ok(ToolExecutionResult::TextWithDisplay {
+                    text: plan::model_summary(&update),
+                    display: plan::render_plan(&update),
+                });
+            }
             ToolName::WebFetch => {
                 use futures::StreamExt;
 

src/tools/mod.rs

@@ -5,6 +5,7 @@ pub mod filesystem;
 pub mod image;
 pub mod morph_validate;
 pub mod permissions;
+pub mod plan;
 pub mod resolve;
 pub mod tool_name;
 pub mod types;