Preserve local project context across compaction and todo updates

This change makes compaction summaries durable under .claude/memory,
feeds those saved memory files back into prompt context, updates /memory
to report both instruction and project-memory files, and moves TodoWrite
persistence to a human-readable .claude/todos.md file.

Constraint: Reuse existing compaction, prompt loading, and slash-command plumbing rather than add a new subsystem
Constraint: Keep persisted project state under Claude-local .claude/ paths
Rejected: Introduce a dedicated memory service module | larger diff with no clear user benefit for this task
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Project memory files are loaded as prompt context, so future format changes must preserve concise readable content
Tested: cargo fmt --all --manifest-path rust/Cargo.toml
Tested: cargo clippy --manifest-path rust/Cargo.toml --all-targets --all-features -- -D warnings
Tested: cargo test --manifest-path rust/Cargo.toml --all
Not-tested: Long-term retention/cleanup policy for .claude/memory growth

rust/README.md

@@ -102,6 +102,13 @@ cd rust
 cargo run -p rusty-claude-cli -- --model claude-sonnet-4-20250514 prompt "List the key crates in this workspace"
 ```
 
+Restrict enabled tools in an interactive session:
+
+```bash
+cd rust
+cargo run -p rusty-claude-cli -- --allowedTools read,glob
+```
+
 ### 2) REPL mode
 
 Start the interactive shell:
@@ -123,6 +130,10 @@ Inside the REPL, useful commands include:
 /memory
 /config
 /init
+/diff
+/version
+/export notes.txt
+/session list
 /exit
 ```
 
@@ -169,6 +180,10 @@ cargo run -p rusty-claude-cli -- --resume session.json /memory /config
 - `/config [env|hooks|model]` — inspect discovered Claude config
 - `/memory` — inspect loaded instruction memory files
 - `/init` — create a starter `CLAUDE.md`
+- `/diff` — show the current git diff for the workspace
+- `/version` — print version and build metadata locally
+- `/export [file]` — export the current conversation transcript
+- `/session [list|switch <session-id>]` — inspect or switch managed local sessions
 - `/exit` — leave the REPL
 
 ## Environment variables

rust/crates/api/src/client.rs

@@ -392,8 +392,52 @@ pub fn resolve_saved_oauth_token(config: &OAuthConfig) -> Result<Option<OAuthTok
     let Some(token_set) = load_saved_oauth_token()? else {
         return Ok(None);
     };
+    resolve_saved_oauth_token_set(config, token_set).map(Some)
+}
+
+pub fn resolve_startup_auth_source<F>(load_oauth_config: F) -> Result<AuthSource, ApiError>
+where
+    F: FnOnce() -> Result<Option<OAuthConfig>, ApiError>,
+{
+    if let Some(api_key) = read_env_non_empty("ANTHROPIC_API_KEY")? {
+        return match read_env_non_empty("ANTHROPIC_AUTH_TOKEN")? {
+            Some(bearer_token) => Ok(AuthSource::ApiKeyAndBearer {
+                api_key,
+                bearer_token,
+            }),
+            None => Ok(AuthSource::ApiKey(api_key)),
+        };
+    }
+    if let Some(bearer_token) = read_env_non_empty("ANTHROPIC_AUTH_TOKEN")? {
+        return Ok(AuthSource::BearerToken(bearer_token));
+    }
+
+    let Some(token_set) = load_saved_oauth_token()? else {
+        return Err(ApiError::MissingApiKey);
+    };
     if !oauth_token_is_expired(&token_set) {
-        return Ok(Some(token_set));
+        return Ok(AuthSource::BearerToken(token_set.access_token));
+    }
+    if token_set.refresh_token.is_none() {
+        return Err(ApiError::ExpiredOAuthToken);
+    }
+
+    let Some(config) = load_oauth_config()? else {
+        return Err(ApiError::Auth(
+            "saved OAuth token is expired; runtime OAuth config is missing".to_string(),
+        ));
+    };
+    Ok(AuthSource::from(resolve_saved_oauth_token_set(
+        &config, token_set,
+    )?))
+}
+
+fn resolve_saved_oauth_token_set(
+    config: &OAuthConfig,
+    token_set: OAuthTokenSet,
+) -> Result<OAuthTokenSet, ApiError> {
+    if !oauth_token_is_expired(&token_set) {
+        return Ok(token_set);
     }
     let Some(refresh_token) = token_set.refresh_token.clone() else {
         return Err(ApiError::ExpiredOAuthToken);
@@ -403,18 +447,28 @@ pub fn resolve_saved_oauth_token(config: &OAuthConfig) -> Result<Option<OAuthTok
         client
             .refresh_oauth_token(
                 config,
-                &OAuthRefreshRequest::from_config(config, refresh_token, Some(token_set.scopes)),
+                &OAuthRefreshRequest::from_config(
+                    config,
+                    refresh_token,
+                    Some(token_set.scopes.clone()),
+                ),
             )
             .await
     })?;
-    save_oauth_credentials(&runtime::OAuthTokenSet {
-        access_token: refreshed.access_token.clone(),
-        refresh_token: refreshed.refresh_token.clone(),
+    let resolved = OAuthTokenSet {
+        access_token: refreshed.access_token,
+        refresh_token: refreshed.refresh_token.or(token_set.refresh_token),
         expires_at: refreshed.expires_at,
-        scopes: refreshed.scopes.clone(),
+        scopes: refreshed.scopes,
+    };
+    save_oauth_credentials(&runtime::OAuthTokenSet {
+        access_token: resolved.access_token.clone(),
+        refresh_token: resolved.refresh_token.clone(),
+        expires_at: resolved.expires_at,
+        scopes: resolved.scopes.clone(),
     })
     .map_err(ApiError::from)?;
-    Ok(Some(refreshed))
+    Ok(resolved)
 }
 
 fn client_runtime_block_on<F, T>(future: F) -> Result<T, ApiError>
@@ -571,8 +625,8 @@ mod tests {
     use runtime::{clear_oauth_credentials, save_oauth_credentials, OAuthConfig};
 
     use crate::client::{
-        now_unix_timestamp, oauth_token_is_expired, resolve_saved_oauth_token, AnthropicClient,
-        AuthSource, OAuthTokenSet,
+        now_unix_timestamp, oauth_token_is_expired, resolve_saved_oauth_token,
+        resolve_startup_auth_source, AnthropicClient, AuthSource, OAuthTokenSet,
     };
     use crate::types::{ContentBlockDelta, MessageRequest};
 
@@ -760,6 +814,95 @@ mod tests {
         std::fs::remove_dir_all(config_home).expect("cleanup temp dir");
     }
 
+    #[test]
+    fn resolve_startup_auth_source_uses_saved_oauth_without_loading_config() {
+        let _guard = env_lock();
+        let config_home = temp_config_home();
+        std::env::set_var("CLAUDE_CONFIG_HOME", &config_home);
+        std::env::remove_var("ANTHROPIC_AUTH_TOKEN");
+        std::env::remove_var("ANTHROPIC_API_KEY");
+        save_oauth_credentials(&runtime::OAuthTokenSet {
+            access_token: "saved-access-token".to_string(),
+            refresh_token: Some("refresh".to_string()),
+            expires_at: Some(now_unix_timestamp() + 300),
+            scopes: vec!["scope:a".to_string()],
+        })
+        .expect("save oauth credentials");
+
+        let auth = resolve_startup_auth_source(|| panic!("config should not be loaded"))
+            .expect("startup auth");
+        assert_eq!(auth.bearer_token(), Some("saved-access-token"));
+
+        clear_oauth_credentials().expect("clear credentials");
+        std::env::remove_var("CLAUDE_CONFIG_HOME");
+        std::fs::remove_dir_all(config_home).expect("cleanup temp dir");
+    }
+
+    #[test]
+    fn resolve_startup_auth_source_errors_when_refreshable_token_lacks_config() {
+        let _guard = env_lock();
+        let config_home = temp_config_home();
+        std::env::set_var("CLAUDE_CONFIG_HOME", &config_home);
+        std::env::remove_var("ANTHROPIC_AUTH_TOKEN");
+        std::env::remove_var("ANTHROPIC_API_KEY");
+        save_oauth_credentials(&runtime::OAuthTokenSet {
+            access_token: "expired-access-token".to_string(),
+            refresh_token: Some("refresh-token".to_string()),
+            expires_at: Some(1),
+            scopes: vec!["scope:a".to_string()],
+        })
+        .expect("save expired oauth credentials");
+
+        let error =
+            resolve_startup_auth_source(|| Ok(None)).expect_err("missing config should error");
+        assert!(
+            matches!(error, crate::error::ApiError::Auth(message) if message.contains("runtime OAuth config is missing"))
+        );
+
+        let stored = runtime::load_oauth_credentials()
+            .expect("load stored credentials")
+            .expect("stored token set");
+        assert_eq!(stored.access_token, "expired-access-token");
+        assert_eq!(stored.refresh_token.as_deref(), Some("refresh-token"));
+
+        clear_oauth_credentials().expect("clear credentials");
+        std::env::remove_var("CLAUDE_CONFIG_HOME");
+        std::fs::remove_dir_all(config_home).expect("cleanup temp dir");
+    }
+
+    #[test]
+    fn resolve_saved_oauth_token_preserves_refresh_token_when_refresh_response_omits_it() {
+        let _guard = env_lock();
+        let config_home = temp_config_home();
+        std::env::set_var("CLAUDE_CONFIG_HOME", &config_home);
+        std::env::remove_var("ANTHROPIC_AUTH_TOKEN");
+        std::env::remove_var("ANTHROPIC_API_KEY");
+        save_oauth_credentials(&runtime::OAuthTokenSet {
+            access_token: "expired-access-token".to_string(),
+            refresh_token: Some("refresh-token".to_string()),
+            expires_at: Some(1),
+            scopes: vec!["scope:a".to_string()],
+        })
+        .expect("save expired oauth credentials");
+
+        let token_url = spawn_token_server(
+            "{\"access_token\":\"refreshed-token\",\"expires_at\":9999999999,\"scopes\":[\"scope:a\"]}",
+        );
+        let resolved = resolve_saved_oauth_token(&sample_oauth_config(token_url))
+            .expect("resolve refreshed token")
+            .expect("token set present");
+        assert_eq!(resolved.access_token, "refreshed-token");
+        assert_eq!(resolved.refresh_token.as_deref(), Some("refresh-token"));
+        let stored = runtime::load_oauth_credentials()
+            .expect("load stored credentials")
+            .expect("stored token set");
+        assert_eq!(stored.refresh_token.as_deref(), Some("refresh-token"));
+
+        clear_oauth_credentials().expect("clear credentials");
+        std::env::remove_var("CLAUDE_CONFIG_HOME");
+        std::fs::remove_dir_all(config_home).expect("cleanup temp dir");
+    }
+
     #[test]
     fn message_request_stream_helper_sets_stream_true() {
         let request = MessageRequest {

rust/crates/api/src/lib.rs

@@ -4,8 +4,8 @@ mod sse;
 mod types;
 
 pub use client::{
-    oauth_token_is_expired, resolve_saved_oauth_token, AnthropicClient, AuthSource, MessageStream,
-    OAuthTokenSet,
+    oauth_token_is_expired, resolve_saved_oauth_token, resolve_startup_auth_source,
+    AnthropicClient, AuthSource, MessageStream, OAuthTokenSet,
 };
 pub use error::ApiError;
 pub use sse::{parse_frame, SseParser};

rust/crates/runtime/src/compact.rs

@@ -1,3 +1,6 @@
+use std::fs;
+use std::time::{SystemTime, UNIX_EPOCH};
+
 use crate::session::{ContentBlock, ConversationMessage, MessageRole, Session};
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -90,6 +93,7 @@ pub fn compact_session(session: &Session, config: CompactionConfig) -> Compactio
     let preserved = session.messages[keep_from..].to_vec();
     let summary = summarize_messages(removed);
     let formatted_summary = format_compact_summary(&summary);
+    persist_compact_summary(&formatted_summary);
     let continuation = get_compact_continuation_message(&summary, true, !preserved.is_empty());
 
     let mut compacted_messages = vec![ConversationMessage {
@@ -110,6 +114,35 @@ pub fn compact_session(session: &Session, config: CompactionConfig) -> Compactio
     }
 }
 
+fn persist_compact_summary(formatted_summary: &str) {
+    if formatted_summary.trim().is_empty() {
+        return;
+    }
+
+    let Ok(cwd) = std::env::current_dir() else {
+        return;
+    };
+    let memory_dir = cwd.join(".claude").join("memory");
+    if fs::create_dir_all(&memory_dir).is_err() {
+        return;
+    }
+
+    let path = memory_dir.join(compact_summary_filename());
+    let _ = fs::write(path, render_memory_file(formatted_summary));
+}
+
+fn compact_summary_filename() -> String {
+    let timestamp = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+    format!("summary-{timestamp}.md")
+}
+
+fn render_memory_file(formatted_summary: &str) -> String {
+    format!("# Project memory\n\n{}\n", formatted_summary.trim())
+}
+
 fn summarize_messages(messages: &[ConversationMessage]) -> String {
     let user_messages = messages
         .iter()
@@ -378,14 +411,21 @@ fn collapse_blank_lines(content: &str) -> String {
 mod tests {
     use super::{
         collect_key_files, compact_session, estimate_session_tokens, format_compact_summary,
-        infer_pending_work, should_compact, CompactionConfig,
+        infer_pending_work, render_memory_file, should_compact, CompactionConfig,
     };
+    use std::fs;
+    use std::time::{SystemTime, UNIX_EPOCH};
+
     use crate::session::{ContentBlock, ConversationMessage, MessageRole, Session};
 
     #[test]
     fn formats_compact_summary_like_upstream() {
         let summary = "<analysis>scratch</analysis>\n<summary>Kept work</summary>";
         assert_eq!(format_compact_summary(summary), "Summary:\nKept work");
+        assert_eq!(
+            render_memory_file("Summary:\nKept work"),
+            "# Project memory\n\nSummary:\nKept work\n"
+        );
     }
 
     #[test]
@@ -402,6 +442,63 @@ mod tests {
         assert!(result.formatted_summary.is_empty());
     }
 
+    #[test]
+    fn persists_compacted_summaries_under_dot_claude_memory() {
+        let _guard = crate::test_env_lock();
+        let temp = std::env::temp_dir().join(format!(
+            "runtime-compact-memory-{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .expect("time after epoch")
+                .as_nanos()
+        ));
+        fs::create_dir_all(&temp).expect("temp dir");
+        let previous = std::env::current_dir().expect("cwd");
+        std::env::set_current_dir(&temp).expect("set cwd");
+
+        let session = Session {
+            version: 1,
+            messages: vec![
+                ConversationMessage::user_text("one ".repeat(200)),
+                ConversationMessage::assistant(vec![ContentBlock::Text {
+                    text: "two ".repeat(200),
+                }]),
+                ConversationMessage::tool_result("1", "bash", "ok ".repeat(200), false),
+                ConversationMessage {
+                    role: MessageRole::Assistant,
+                    blocks: vec![ContentBlock::Text {
+                        text: "recent".to_string(),
+                    }],
+                    usage: None,
+                },
+            ],
+        };
+
+        let result = compact_session(
+            &session,
+            CompactionConfig {
+                preserve_recent_messages: 2,
+                max_estimated_tokens: 1,
+            },
+        );
+        let memory_dir = temp.join(".claude").join("memory");
+        let files = fs::read_dir(&memory_dir)
+            .expect("memory dir exists")
+            .flatten()
+            .map(|entry| entry.path())
+            .collect::<Vec<_>>();
+
+        assert_eq!(result.removed_message_count, 2);
+        assert_eq!(files.len(), 1);
+        let persisted = fs::read_to_string(&files[0]).expect("memory file readable");
+
+        std::env::set_current_dir(previous).expect("restore cwd");
+        fs::remove_dir_all(temp).expect("cleanup temp dir");
+
+        assert!(persisted.contains("# Project memory"));
+        assert!(persisted.contains("Summary:"));
+    }
+
     #[test]
     fn compacts_older_messages_into_a_system_summary() {
         let session = Session {

rust/crates/runtime/src/config.rs

@@ -14,6 +14,13 @@ pub enum ConfigSource {
     Local,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResolvedPermissionMode {
+    ReadOnly,
+    WorkspaceWrite,
+    DangerFullAccess,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConfigEntry {
     pub source: ConfigSource,
@@ -31,6 +38,8 @@ pub struct RuntimeConfig {
 pub struct RuntimeFeatureConfig {
     mcp: McpConfigCollection,
     oauth: Option<OAuthConfig>,
+    model: Option<String>,
+    permission_mode: Option<ResolvedPermissionMode>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
@@ -165,11 +174,23 @@ impl ConfigLoader {
 
     #[must_use]
     pub fn discover(&self) -> Vec<ConfigEntry> {
+        let user_legacy_path = self.config_home.parent().map_or_else(
+            || PathBuf::from(".claude.json"),
+            |parent| parent.join(".claude.json"),
+        );
         vec![
+            ConfigEntry {
+                source: ConfigSource::User,
+                path: user_legacy_path,
+            },
             ConfigEntry {
                 source: ConfigSource::User,
                 path: self.config_home.join("settings.json"),
             },
+            ConfigEntry {
+                source: ConfigSource::Project,
+                path: self.cwd.join(".claude.json"),
+            },
             ConfigEntry {
                 source: ConfigSource::Project,
                 path: self.cwd.join(".claude").join("settings.json"),
@@ -195,14 +216,15 @@ impl ConfigLoader {
             loaded_entries.push(entry);
         }
 
+        let merged_value = JsonValue::Object(merged.clone());
+
         let feature_config = RuntimeFeatureConfig {
             mcp: McpConfigCollection {
                 servers: mcp_servers,
             },
-            oauth: parse_optional_oauth_config(
-                &JsonValue::Object(merged.clone()),
-                "merged settings.oauth",
-            )?,
+            oauth: parse_optional_oauth_config(&merged_value, "merged settings.oauth")?,
+            model: parse_optional_model(&merged_value),
+            permission_mode: parse_optional_permission_mode(&merged_value)?,
         };
 
         Ok(RuntimeConfig {
@@ -257,6 +279,16 @@ impl RuntimeConfig {
     pub fn oauth(&self) -> Option<&OAuthConfig> {
         self.feature_config.oauth.as_ref()
     }
+
+    #[must_use]
+    pub fn model(&self) -> Option<&str> {
+        self.feature_config.model.as_deref()
+    }
+
+    #[must_use]
+    pub fn permission_mode(&self) -> Option<ResolvedPermissionMode> {
+        self.feature_config.permission_mode
+    }
 }
 
 impl RuntimeFeatureConfig {
@@ -269,6 +301,16 @@ impl RuntimeFeatureConfig {
     pub fn oauth(&self) -> Option<&OAuthConfig> {
         self.oauth.as_ref()
     }
+
+    #[must_use]
+    pub fn model(&self) -> Option<&str> {
+        self.model.as_deref()
+    }
+
+    #[must_use]
+    pub fn permission_mode(&self) -> Option<ResolvedPermissionMode> {
+        self.permission_mode
+    }
 }
 
 impl McpConfigCollection {
@@ -307,6 +349,7 @@ impl McpServerConfig {
 fn read_optional_json_object(
     path: &Path,
 ) -> Result<Option<BTreeMap<String, JsonValue>>, ConfigError> {
+    let is_legacy_config = path.file_name().and_then(|name| name.to_str()) == Some(".claude.json");
     let contents = match fs::read_to_string(path) {
         Ok(contents) => contents,
         Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
@@ -317,14 +360,20 @@ fn read_optional_json_object(
         return Ok(Some(BTreeMap::new()));
     }
 
-    let parsed = JsonValue::parse(&contents)
-        .map_err(|error| ConfigError::Parse(format!("{}: {error}", path.display())))?;
-    let object = parsed.as_object().ok_or_else(|| {
-        ConfigError::Parse(format!(
+    let parsed = match JsonValue::parse(&contents) {
+        Ok(parsed) => parsed,
+        Err(error) if is_legacy_config => return Ok(None),
+        Err(error) => return Err(ConfigError::Parse(format!("{}: {error}", path.display()))),
+    };
+    let Some(object) = parsed.as_object() else {
+        if is_legacy_config {
+            return Ok(None);
+        }
+        return Err(ConfigError::Parse(format!(
             "{}: top-level settings value must be a JSON object",
             path.display()
-        ))
-    })?;
+        )));
+    };
     Ok(Some(object.clone()))
 }
 
@@ -355,6 +404,47 @@ fn merge_mcp_servers(
     Ok(())
 }
 
+fn parse_optional_model(root: &JsonValue) -> Option<String> {
+    root.as_object()
+        .and_then(|object| object.get("model"))
+        .and_then(JsonValue::as_str)
+        .map(ToOwned::to_owned)
+}
+
+fn parse_optional_permission_mode(
+    root: &JsonValue,
+) -> Result<Option<ResolvedPermissionMode>, ConfigError> {
+    let Some(object) = root.as_object() else {
+        return Ok(None);
+    };
+    if let Some(mode) = object.get("permissionMode").and_then(JsonValue::as_str) {
+        return parse_permission_mode_label(mode, "merged settings.permissionMode").map(Some);
+    }
+    let Some(mode) = object
+        .get("permissions")
+        .and_then(JsonValue::as_object)
+        .and_then(|permissions| permissions.get("defaultMode"))
+        .and_then(JsonValue::as_str)
+    else {
+        return Ok(None);
+    };
+    parse_permission_mode_label(mode, "merged settings.permissions.defaultMode").map(Some)
+}
+
+fn parse_permission_mode_label(
+    mode: &str,
+    context: &str,
+) -> Result<ResolvedPermissionMode, ConfigError> {
+    match mode {
+        "default" | "plan" | "read-only" => Ok(ResolvedPermissionMode::ReadOnly),
+        "acceptEdits" | "auto" | "workspace-write" => Ok(ResolvedPermissionMode::WorkspaceWrite),
+        "dontAsk" | "danger-full-access" => Ok(ResolvedPermissionMode::DangerFullAccess),
+        other => Err(ConfigError::Parse(format!(
+            "{context}: unsupported permission mode {other}"
+        ))),
+    }
+}
+
 fn parse_optional_oauth_config(
     root: &JsonValue,
     context: &str,
@@ -594,7 +684,8 @@ fn deep_merge_objects(
 #[cfg(test)]
 mod tests {
     use super::{
-        ConfigLoader, ConfigSource, McpServerConfig, McpTransport, CLAUDE_CODE_SETTINGS_SCHEMA_NAME,
+        ConfigLoader, ConfigSource, McpServerConfig, McpTransport, ResolvedPermissionMode,
+        CLAUDE_CODE_SETTINGS_SCHEMA_NAME,
     };
     use crate::json::JsonValue;
     use std::fs;
@@ -635,14 +726,24 @@ mod tests {
         fs::create_dir_all(cwd.join(".claude")).expect("project config dir");
         fs::create_dir_all(&home).expect("home config dir");
 
+        fs::write(
+            home.parent().expect("home parent").join(".claude.json"),
+            r#"{"model":"haiku","env":{"A":"1"},"mcpServers":{"home":{"command":"uvx","args":["home"]}}}"#,
+        )
+        .expect("write user compat config");
         fs::write(
             home.join("settings.json"),
-            r#"{"model":"sonnet","env":{"A":"1"},"hooks":{"PreToolUse":["base"]}}"#,
+            r#"{"model":"sonnet","env":{"A2":"1"},"hooks":{"PreToolUse":["base"]},"permissions":{"defaultMode":"plan"}}"#,
         )
         .expect("write user settings");
+        fs::write(
+            cwd.join(".claude.json"),
+            r#"{"model":"project-compat","env":{"B":"2"}}"#,
+        )
+        .expect("write project compat config");
         fs::write(
             cwd.join(".claude").join("settings.json"),
-            r#"{"env":{"B":"2"},"hooks":{"PostToolUse":["project"]}}"#,
+            r#"{"env":{"C":"3"},"hooks":{"PostToolUse":["project"]},"mcpServers":{"project":{"command":"uvx","args":["project"]}}}"#,
         )
         .expect("write project settings");
         fs::write(
@@ -656,25 +757,37 @@ mod tests {
             .expect("config should load");
 
         assert_eq!(CLAUDE_CODE_SETTINGS_SCHEMA_NAME, "SettingsSchema");
-        assert_eq!(loaded.loaded_entries().len(), 3);
+        assert_eq!(loaded.loaded_entries().len(), 5);
         assert_eq!(loaded.loaded_entries()[0].source, ConfigSource::User);
         assert_eq!(
             loaded.get("model"),
             Some(&JsonValue::String("opus".to_string()))
         );
+        assert_eq!(loaded.model(), Some("opus"));
+        assert_eq!(
+            loaded.permission_mode(),
+            Some(ResolvedPermissionMode::WorkspaceWrite)
+        );
         assert_eq!(
             loaded
                 .get("env")
                 .and_then(JsonValue::as_object)
                 .expect("env object")
                 .len(),
-            2
+            4
         );
         assert!(loaded
             .get("hooks")
             .and_then(JsonValue::as_object)
             .expect("hooks object")
             .contains_key("PreToolUse"));
+        assert!(loaded
+            .get("hooks")
+            .and_then(JsonValue::as_object)
+            .expect("hooks object")
+            .contains_key("PostToolUse"));
+        assert!(loaded.mcp().get("home").is_some());
+        assert!(loaded.mcp().get("project").is_some());
 
         fs::remove_dir_all(root).expect("cleanup temp dir");
     }

rust/crates/runtime/src/conversation.rs

@@ -408,13 +408,14 @@ mod tests {
                 .sum::<i32>();
             Ok(total.to_string())
         });
-        let permission_policy = PermissionPolicy::new(PermissionMode::Prompt);
+        let permission_policy = PermissionPolicy::new(PermissionMode::WorkspaceWrite);
         let system_prompt = SystemPromptBuilder::new()
             .with_project_context(ProjectContext {
                 cwd: PathBuf::from("/tmp/project"),
                 current_date: "2026-03-31".to_string(),
                 git_status: None,
                 instruction_files: Vec::new(),
+                memory_files: Vec::new(),
             })
             .with_os("linux", "6.8")
             .build();
@@ -487,7 +488,7 @@ mod tests {
             Session::new(),
             SingleCallApiClient,
             StaticToolExecutor::new(),
-            PermissionPolicy::new(PermissionMode::Prompt),
+            PermissionPolicy::new(PermissionMode::WorkspaceWrite),
             vec!["system".to_string()],
         );
 
@@ -536,7 +537,7 @@ mod tests {
             session,
             SimpleApi,
             StaticToolExecutor::new(),
-            PermissionPolicy::new(PermissionMode::Allow),
+            PermissionPolicy::new(PermissionMode::DangerFullAccess),
             vec!["system".to_string()],
         );
 
@@ -563,7 +564,7 @@ mod tests {
             Session::new(),
             SimpleApi,
             StaticToolExecutor::new(),
-            PermissionPolicy::new(PermissionMode::Allow),
+            PermissionPolicy::new(PermissionMode::DangerFullAccess),
             vec!["system".to_string()],
         );
         runtime.run_turn("a", None).expect("turn a");

rust/crates/runtime/src/lib.rs

@@ -25,7 +25,8 @@ pub use config::{
     ConfigEntry, ConfigError, ConfigLoader, ConfigSource, McpClaudeAiProxyServerConfig,
     McpConfigCollection, McpOAuthConfig, McpRemoteServerConfig, McpSdkServerConfig,
     McpServerConfig, McpStdioServerConfig, McpTransport, McpWebSocketServerConfig, OAuthConfig,
-    RuntimeConfig, RuntimeFeatureConfig, ScopedMcpServerConfig, CLAUDE_CODE_SETTINGS_SCHEMA_NAME,
+    ResolvedPermissionMode, RuntimeConfig, RuntimeFeatureConfig, ScopedMcpServerConfig,
+    CLAUDE_CODE_SETTINGS_SCHEMA_NAME,
 };
 pub use conversation::{
     ApiClient, ApiRequest, AssistantEvent, ConversationRuntime, RuntimeError, StaticToolExecutor,
@@ -76,3 +77,11 @@ pub use session::{ContentBlock, ConversationMessage, MessageRole, Session, Sessi
 pub use usage::{
     format_usd, pricing_for_model, ModelPricing, TokenUsage, UsageCostEstimate, UsageTracker,
 };
+
+#[cfg(test)]
+pub(crate) fn test_env_lock() -> std::sync::MutexGuard<'static, ()> {
+    static LOCK: std::sync::OnceLock<std::sync::Mutex<()>> = std::sync::OnceLock::new();
+    LOCK.get_or_init(|| std::sync::Mutex::new(()))
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}

rust/crates/runtime/src/oauth.rs

@@ -448,7 +448,6 @@ fn decode_hex(byte: u8) -> Result<u8, String> {
 
 #[cfg(test)]
 mod tests {
-    use std::sync::{Mutex, OnceLock};
     use std::time::{SystemTime, UNIX_EPOCH};
 
     use super::{
@@ -470,10 +469,7 @@ mod tests {
     }
 
     fn env_lock() -> std::sync::MutexGuard<'static, ()> {
-        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
-        LOCK.get_or_init(|| Mutex::new(()))
-            .lock()
-            .expect("env lock")
+        crate::test_env_lock()
     }
 
     fn temp_config_home() -> std::path::PathBuf {

rust/crates/runtime/src/permissions.rs

@@ -1,16 +1,29 @@
 use std::collections::BTreeMap;
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum PermissionMode {
-    Allow,
-    Deny,
-    Prompt,
+    ReadOnly,
+    WorkspaceWrite,
+    DangerFullAccess,
+}
+
+impl PermissionMode {
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::ReadOnly => "read-only",
+            Self::WorkspaceWrite => "workspace-write",
+            Self::DangerFullAccess => "danger-full-access",
+        }
+    }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PermissionRequest {
     pub tool_name: String,
     pub input: String,
+    pub current_mode: PermissionMode,
+    pub required_mode: PermissionMode,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -31,31 +44,41 @@ pub enum PermissionOutcome {
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PermissionPolicy {
-    default_mode: PermissionMode,
-    tool_modes: BTreeMap<String, PermissionMode>,
+    active_mode: PermissionMode,
+    tool_requirements: BTreeMap<String, PermissionMode>,
 }
 
 impl PermissionPolicy {
     #[must_use]
-    pub fn new(default_mode: PermissionMode) -> Self {
+    pub fn new(active_mode: PermissionMode) -> Self {
         Self {
-            default_mode,
-            tool_modes: BTreeMap::new(),
+            active_mode,
+            tool_requirements: BTreeMap::new(),
         }
     }
 
     #[must_use]
-    pub fn with_tool_mode(mut self, tool_name: impl Into<String>, mode: PermissionMode) -> Self {
-        self.tool_modes.insert(tool_name.into(), mode);
+    pub fn with_tool_requirement(
+        mut self,
+        tool_name: impl Into<String>,
+        required_mode: PermissionMode,
+    ) -> Self {
+        self.tool_requirements
+            .insert(tool_name.into(), required_mode);
         self
     }
 
     #[must_use]
-    pub fn mode_for(&self, tool_name: &str) -> PermissionMode {
-        self.tool_modes
+    pub fn active_mode(&self) -> PermissionMode {
+        self.active_mode
+    }
+
+    #[must_use]
+    pub fn required_mode_for(&self, tool_name: &str) -> PermissionMode {
+        self.tool_requirements
             .get(tool_name)
             .copied()
-            .unwrap_or(self.default_mode)
+            .unwrap_or(PermissionMode::DangerFullAccess)
     }
 
     #[must_use]
@@ -65,23 +88,43 @@ impl PermissionPolicy {
         input: &str,
         mut prompter: Option<&mut dyn PermissionPrompter>,
     ) -> PermissionOutcome {
-        match self.mode_for(tool_name) {
-            PermissionMode::Allow => PermissionOutcome::Allow,
-            PermissionMode::Deny => PermissionOutcome::Deny {
-                reason: format!("tool '{tool_name}' denied by permission policy"),
-            },
-            PermissionMode::Prompt => match prompter.as_mut() {
-                Some(prompter) => match prompter.decide(&PermissionRequest {
-                    tool_name: tool_name.to_string(),
-                    input: input.to_string(),
-                }) {
+        let current_mode = self.active_mode();
+        let required_mode = self.required_mode_for(tool_name);
+        if current_mode >= required_mode {
+            return PermissionOutcome::Allow;
+        }
+
+        let request = PermissionRequest {
+            tool_name: tool_name.to_string(),
+            input: input.to_string(),
+            current_mode,
+            required_mode,
+        };
+
+        if current_mode == PermissionMode::WorkspaceWrite
+            && required_mode == PermissionMode::DangerFullAccess
+        {
+            return match prompter.as_mut() {
+                Some(prompter) => match prompter.decide(&request) {
                     PermissionPromptDecision::Allow => PermissionOutcome::Allow,
                     PermissionPromptDecision::Deny { reason } => PermissionOutcome::Deny { reason },
                 },
                 None => PermissionOutcome::Deny {
-                    reason: format!("tool '{tool_name}' requires interactive approval"),
+                    reason: format!(
+                        "tool '{tool_name}' requires approval to escalate from {} to {}",
+                        current_mode.as_str(),
+                        required_mode.as_str()
+                    ),
                 },
-            },
+            };
+        }
+
+        PermissionOutcome::Deny {
+            reason: format!(
+                "tool '{tool_name}' requires {} permission; current mode is {}",
+                required_mode.as_str(),
+                current_mode.as_str()
+            ),
         }
     }
 }
@@ -93,25 +136,92 @@ mod tests {
         PermissionPrompter, PermissionRequest,
     };
 
-    struct AllowPrompter;
+    struct RecordingPrompter {
+        seen: Vec<PermissionRequest>,
+        allow: bool,
+    }
 
-    impl PermissionPrompter for AllowPrompter {
+    impl PermissionPrompter for RecordingPrompter {
         fn decide(&mut self, request: &PermissionRequest) -> PermissionPromptDecision {
-            assert_eq!(request.tool_name, "bash");
-            PermissionPromptDecision::Allow
+            self.seen.push(request.clone());
+            if self.allow {
+                PermissionPromptDecision::Allow
+            } else {
+                PermissionPromptDecision::Deny {
+                    reason: "not now".to_string(),
+                }
+            }
         }
     }
 
     #[test]
-    fn uses_tool_specific_overrides() {
-        let policy = PermissionPolicy::new(PermissionMode::Deny)
-            .with_tool_mode("bash", PermissionMode::Prompt);
+    fn allows_tools_when_active_mode_meets_requirement() {
+        let policy = PermissionPolicy::new(PermissionMode::WorkspaceWrite)
+            .with_tool_requirement("read_file", PermissionMode::ReadOnly)
+            .with_tool_requirement("write_file", PermissionMode::WorkspaceWrite);
+
+        assert_eq!(
+            policy.authorize("read_file", "{}", None),
+            PermissionOutcome::Allow
+        );
+        assert_eq!(
+            policy.authorize("write_file", "{}", None),
+            PermissionOutcome::Allow
+        );
+    }
+
+    #[test]
+    fn denies_read_only_escalations_without_prompt() {
+        let policy = PermissionPolicy::new(PermissionMode::ReadOnly)
+            .with_tool_requirement("write_file", PermissionMode::WorkspaceWrite)
+            .with_tool_requirement("bash", PermissionMode::DangerFullAccess);
 
-        let outcome = policy.authorize("bash", "echo hi", Some(&mut AllowPrompter));
-        assert_eq!(outcome, PermissionOutcome::Allow);
         assert!(matches!(
-            policy.authorize("edit", "x", None),
-            PermissionOutcome::Deny { .. }
+            policy.authorize("write_file", "{}", None),
+            PermissionOutcome::Deny { reason } if reason.contains("requires workspace-write permission")
+        ));
+        assert!(matches!(
+            policy.authorize("bash", "{}", None),
+            PermissionOutcome::Deny { reason } if reason.contains("requires danger-full-access permission")
+        ));
+    }
+
+    #[test]
+    fn prompts_for_workspace_write_to_danger_full_access_escalation() {
+        let policy = PermissionPolicy::new(PermissionMode::WorkspaceWrite)
+            .with_tool_requirement("bash", PermissionMode::DangerFullAccess);
+        let mut prompter = RecordingPrompter {
+            seen: Vec::new(),
+            allow: true,
+        };
+
+        let outcome = policy.authorize("bash", "echo hi", Some(&mut prompter));
+
+        assert_eq!(outcome, PermissionOutcome::Allow);
+        assert_eq!(prompter.seen.len(), 1);
+        assert_eq!(prompter.seen[0].tool_name, "bash");
+        assert_eq!(
+            prompter.seen[0].current_mode,
+            PermissionMode::WorkspaceWrite
+        );
+        assert_eq!(
+            prompter.seen[0].required_mode,
+            PermissionMode::DangerFullAccess
+        );
+    }
+
+    #[test]
+    fn honors_prompt_rejection_reason() {
+        let policy = PermissionPolicy::new(PermissionMode::WorkspaceWrite)
+            .with_tool_requirement("bash", PermissionMode::DangerFullAccess);
+        let mut prompter = RecordingPrompter {
+            seen: Vec::new(),
+            allow: false,
+        };
+
+        assert!(matches!(
+            policy.authorize("bash", "echo hi", Some(&mut prompter)),
+            PermissionOutcome::Deny { reason } if reason == "not now"
         ));
     }
 }

rust/crates/runtime/src/prompt.rs

@@ -51,6 +51,7 @@ pub struct ProjectContext {
     pub current_date: String,
     pub git_status: Option<String>,
     pub instruction_files: Vec<ContextFile>,
+    pub memory_files: Vec<ContextFile>,
 }
 
 impl ProjectContext {
@@ -60,11 +61,13 @@ impl ProjectContext {
     ) -> std::io::Result<Self> {
         let cwd = cwd.into();
         let instruction_files = discover_instruction_files(&cwd)?;
+        let memory_files = discover_memory_files(&cwd)?;
         Ok(Self {
             cwd,
             current_date: current_date.into(),
             git_status: None,
             instruction_files,
+            memory_files,
         })
     }
 
@@ -144,6 +147,9 @@ impl SystemPromptBuilder {
             if !project_context.instruction_files.is_empty() {
                 sections.push(render_instruction_files(&project_context.instruction_files));
             }
+            if !project_context.memory_files.is_empty() {
+                sections.push(render_memory_files(&project_context.memory_files));
+            }
         }
         if let Some(config) = &self.config {
             sections.push(render_config_section(config));
@@ -186,7 +192,7 @@ pub fn prepend_bullets(items: Vec<String>) -> Vec<String> {
     items.into_iter().map(|item| format!(" - {item}")).collect()
 }
 
-fn discover_instruction_files(cwd: &Path) -> std::io::Result<Vec<ContextFile>> {
+fn discover_context_directories(cwd: &Path) -> Vec<PathBuf> {
     let mut directories = Vec::new();
     let mut cursor = Some(cwd);
     while let Some(dir) = cursor {
@@ -194,6 +200,11 @@ fn discover_instruction_files(cwd: &Path) -> std::io::Result<Vec<ContextFile>> {
         cursor = dir.parent();
     }
     directories.reverse();
+    directories
+}
+
+fn discover_instruction_files(cwd: &Path) -> std::io::Result<Vec<ContextFile>> {
+    let directories = discover_context_directories(cwd);
 
     let mut files = Vec::new();
     for dir in directories {
@@ -201,6 +212,7 @@ fn discover_instruction_files(cwd: &Path) -> std::io::Result<Vec<ContextFile>> {
             dir.join("CLAUDE.md"),
             dir.join("CLAUDE.local.md"),
             dir.join(".claude").join("CLAUDE.md"),
+            dir.join(".claude").join("instructions.md"),
         ] {
             push_context_file(&mut files, candidate)?;
         }
@@ -208,6 +220,26 @@ fn discover_instruction_files(cwd: &Path) -> std::io::Result<Vec<ContextFile>> {
     Ok(dedupe_instruction_files(files))
 }
 
+fn discover_memory_files(cwd: &Path) -> std::io::Result<Vec<ContextFile>> {
+    let mut files = Vec::new();
+    for dir in discover_context_directories(cwd) {
+        let memory_dir = dir.join(".claude").join("memory");
+        let Ok(entries) = fs::read_dir(&memory_dir) else {
+            continue;
+        };
+        let mut paths = entries
+            .flatten()
+            .map(|entry| entry.path())
+            .filter(|path| path.is_file())
+            .collect::<Vec<_>>();
+        paths.sort();
+        for path in paths {
+            push_context_file(&mut files, path)?;
+        }
+    }
+    Ok(dedupe_instruction_files(files))
+}
+
 fn push_context_file(files: &mut Vec<ContextFile>, path: PathBuf) -> std::io::Result<()> {
     match fs::read_to_string(&path) {
         Ok(content) if !content.trim().is_empty() => {
@@ -250,6 +282,12 @@ fn render_project_context(project_context: &ProjectContext) -> String {
             project_context.instruction_files.len()
         ));
     }
+    if !project_context.memory_files.is_empty() {
+        bullets.push(format!(
+            "Project memory files discovered: {}.",
+            project_context.memory_files.len()
+        ));
+    }
     lines.extend(prepend_bullets(bullets));
     if let Some(status) = &project_context.git_status {
         lines.push(String::new());
@@ -260,7 +298,15 @@ fn render_project_context(project_context: &ProjectContext) -> String {
 }
 
 fn render_instruction_files(files: &[ContextFile]) -> String {
-    let mut sections = vec!["# Claude instructions".to_string()];
+    render_context_file_section("# Claude instructions", files)
+}
+
+fn render_memory_files(files: &[ContextFile]) -> String {
+    render_context_file_section("# Project memory", files)
+}
+
+fn render_context_file_section(title: &str, files: &[ContextFile]) -> String {
+    let mut sections = vec![title.to_string()];
     let mut remaining_chars = MAX_TOTAL_INSTRUCTION_CHARS;
     for file in files {
         if remaining_chars == 0 {
@@ -452,8 +498,9 @@ fn get_actions_section() -> String {
 mod tests {
     use super::{
         collapse_blank_lines, display_context_path, normalize_instruction_content,
-        render_instruction_content, render_instruction_files, truncate_instruction_content,
-        ContextFile, ProjectContext, SystemPromptBuilder, SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
+        render_instruction_content, render_instruction_files, render_memory_files,
+        truncate_instruction_content, ContextFile, ProjectContext, SystemPromptBuilder,
+        SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
     };
     use crate::config::ConfigLoader;
     use std::fs;
@@ -468,6 +515,10 @@ mod tests {
         std::env::temp_dir().join(format!("runtime-prompt-{nanos}"))
     }
 
+    fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+        crate::test_env_lock()
+    }
+
     #[test]
     fn discovers_instruction_files_from_ancestor_chain() {
         let root = temp_dir();
@@ -477,10 +528,21 @@ mod tests {
         fs::write(root.join("CLAUDE.local.md"), "local instructions")
             .expect("write local instructions");
         fs::create_dir_all(root.join("apps")).expect("apps dir");
+        fs::create_dir_all(root.join("apps").join(".claude")).expect("apps claude dir");
         fs::write(root.join("apps").join("CLAUDE.md"), "apps instructions")
             .expect("write apps instructions");
+        fs::write(
+            root.join("apps").join(".claude").join("instructions.md"),
+            "apps dot claude instructions",
+        )
+        .expect("write apps dot claude instructions");
         fs::write(nested.join(".claude").join("CLAUDE.md"), "nested rules")
             .expect("write nested rules");
+        fs::write(
+            nested.join(".claude").join("instructions.md"),
+            "nested instructions",
+        )
+        .expect("write nested instructions");
 
         let context = ProjectContext::discover(&nested, "2026-03-31").expect("context should load");
         let contents = context
@@ -495,12 +557,43 @@ mod tests {
                 "root instructions",
                 "local instructions",
                 "apps instructions",
-                "nested rules"
+                "apps dot claude instructions",
+                "nested rules",
+                "nested instructions"
             ]
         );
         fs::remove_dir_all(root).expect("cleanup temp dir");
     }
 
+    #[test]
+    fn discovers_project_memory_files_from_ancestor_chain() {
+        let root = temp_dir();
+        let nested = root.join("apps").join("api");
+        fs::create_dir_all(root.join(".claude").join("memory")).expect("root memory dir");
+        fs::create_dir_all(nested.join(".claude").join("memory")).expect("nested memory dir");
+        fs::write(
+            root.join(".claude").join("memory").join("2026-03-30.md"),
+            "root memory",
+        )
+        .expect("write root memory");
+        fs::write(
+            nested.join(".claude").join("memory").join("2026-03-31.md"),
+            "nested memory",
+        )
+        .expect("write nested memory");
+
+        let context = ProjectContext::discover(&nested, "2026-03-31").expect("context should load");
+        let contents = context
+            .memory_files
+            .iter()
+            .map(|file| file.content.as_str())
+            .collect::<Vec<_>>();
+
+        assert_eq!(contents, vec!["root memory", "nested memory"]);
+        assert!(render_memory_files(&context.memory_files).contains("# Project memory"));
+        fs::remove_dir_all(root).expect("cleanup temp dir");
+    }
+
     #[test]
     fn dedupes_identical_instruction_content_across_scopes() {
         let root = temp_dir();
@@ -574,7 +667,12 @@ mod tests {
         )
         .expect("write settings");
 
+        let _guard = env_lock();
         let previous = std::env::current_dir().expect("cwd");
+        let original_home = std::env::var("HOME").ok();
+        let original_claude_home = std::env::var("CLAUDE_CONFIG_HOME").ok();
+        std::env::set_var("HOME", &root);
+        std::env::set_var("CLAUDE_CONFIG_HOME", root.join("missing-home"));
         std::env::set_current_dir(&root).expect("change cwd");
         let prompt = super::load_system_prompt(&root, "2026-03-31", "linux", "6.8")
             .expect("system prompt should load")
@@ -584,6 +682,16 @@ mod tests {
 ",
             );
         std::env::set_current_dir(previous).expect("restore cwd");
+        if let Some(value) = original_home {
+            std::env::set_var("HOME", value);
+        } else {
+            std::env::remove_var("HOME");
+        }
+        if let Some(value) = original_claude_home {
+            std::env::set_var("CLAUDE_CONFIG_HOME", value);
+        } else {
+            std::env::remove_var("CLAUDE_CONFIG_HOME");
+        }
 
         assert!(prompt.contains("Project rules"));
         assert!(prompt.contains("permissionMode"));
@@ -631,6 +739,29 @@ mod tests {
         assert!(rendered.chars().count() <= 4_000 + "\n\n[truncated]".chars().count());
     }
 
+    #[test]
+    fn discovers_dot_claude_instructions_markdown() {
+        let root = temp_dir();
+        let nested = root.join("apps").join("api");
+        fs::create_dir_all(nested.join(".claude")).expect("nested claude dir");
+        fs::write(
+            nested.join(".claude").join("instructions.md"),
+            "instruction markdown",
+        )
+        .expect("write instructions.md");
+
+        let context = ProjectContext::discover(&nested, "2026-03-31").expect("context should load");
+        assert!(context
+            .instruction_files
+            .iter()
+            .any(|file| file.path.ends_with(".claude/instructions.md")));
+        assert!(
+            render_instruction_files(&context.instruction_files).contains("instruction markdown")
+        );
+
+        fs::remove_dir_all(root).expect("cleanup temp dir");
+    }
+
     #[test]
     fn renders_instruction_file_metadata() {
         let rendered = render_instruction_files(&[ContextFile {

rust/crates/rusty-claude-cli/src/app.rs

@@ -2,7 +2,7 @@ use std::io::{self, Write};
 use std::path::PathBuf;
 
 use crate::args::{OutputFormat, PermissionMode};
-use crate::input::LineEditor;
+use crate::input::{LineEditor, ReadOutcome};
 use crate::render::{Spinner, TerminalRenderer};
 use runtime::{ConversationClient, ConversationMessage, RuntimeError, StreamEvent, UsageSummary};
 
@@ -111,16 +111,21 @@ impl CliApp {
     }
 
     pub fn run_repl(&mut self) -> io::Result<()> {
-        let editor = LineEditor::new("› ");
+        let mut editor = LineEditor::new("› ", Vec::new());
         println!("Rusty Claude CLI interactive mode");
         println!("Type /help for commands. Shift+Enter or Ctrl+J inserts a newline.");
 
-        while let Some(input) = editor.read_line()? {
-            if input.trim().is_empty() {
-                continue;
+        loop {
+            match editor.read_line()? {
+                ReadOutcome::Submit(input) => {
+                    if input.trim().is_empty() {
+                        continue;
+                    }
+                    self.handle_submission(&input, &mut io::stdout())?;
+                }
+                ReadOutcome::Cancel => continue,
+                ReadOutcome::Exit => break,
             }
-
-            self.handle_submission(&input, &mut io::stdout())?;
         }
 
         Ok(())

rust/crates/rusty-claude-cli/src/input.rs

@@ -1,9 +1,8 @@
 use std::io::{self, IsTerminal, Write};
 
-use crossterm::cursor::MoveToColumn;
+use crossterm::cursor::{MoveDown, MoveToColumn, MoveUp};
 use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyModifiers};
 use crossterm::queue;
-use crossterm::style::Print;
 use crossterm::terminal::{disable_raw_mode, enable_raw_mode, Clear, ClearType};
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -85,21 +84,124 @@ impl InputBuffer {
         self.buffer.clear();
         self.cursor = 0;
     }
+
+    pub fn replace(&mut self, value: impl Into<String>) {
+        self.buffer = value.into();
+        self.cursor = self.buffer.len();
+    }
+
+    #[must_use]
+    fn current_command_prefix(&self) -> Option<&str> {
+        if self.cursor != self.buffer.len() {
+            return None;
+        }
+        let prefix = &self.buffer[..self.cursor];
+        if prefix.contains(char::is_whitespace) || !prefix.starts_with('/') {
+            return None;
+        }
+        Some(prefix)
+    }
+
+    pub fn complete_slash_command(&mut self, candidates: &[String]) -> bool {
+        let Some(prefix) = self.current_command_prefix() else {
+            return false;
+        };
+
+        let matches = candidates
+            .iter()
+            .filter(|candidate| candidate.starts_with(prefix))
+            .map(String::as_str)
+            .collect::<Vec<_>>();
+        if matches.is_empty() {
+            return false;
+        }
+
+        let replacement = longest_common_prefix(&matches);
+        if replacement == prefix {
+            return false;
+        }
+
+        self.replace(replacement);
+        true
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RenderedBuffer {
+    lines: Vec<String>,
+    cursor_row: u16,
+    cursor_col: u16,
+}
+
+impl RenderedBuffer {
+    #[must_use]
+    pub fn line_count(&self) -> usize {
+        self.lines.len()
+    }
+
+    fn write(&self, out: &mut impl Write) -> io::Result<()> {
+        for (index, line) in self.lines.iter().enumerate() {
+            if index > 0 {
+                writeln!(out)?;
+            }
+            write!(out, "{line}")?;
+        }
+        Ok(())
+    }
+
+    #[cfg(test)]
+    #[must_use]
+    pub fn lines(&self) -> &[String] {
+        &self.lines
+    }
+
+    #[cfg(test)]
+    #[must_use]
+    pub fn cursor_position(&self) -> (u16, u16) {
+        (self.cursor_row, self.cursor_col)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ReadOutcome {
+    Submit(String),
+    Cancel,
+    Exit,
 }
 
 pub struct LineEditor {
     prompt: String,
+    continuation_prompt: String,
+    history: Vec<String>,
+    history_index: Option<usize>,
+    draft: Option<String>,
+    completions: Vec<String>,
 }
 
 impl LineEditor {
     #[must_use]
-    pub fn new(prompt: impl Into<String>) -> Self {
+    pub fn new(prompt: impl Into<String>, completions: Vec<String>) -> Self {
         Self {
             prompt: prompt.into(),
+            continuation_prompt: String::from("> "),
+            history: Vec::new(),
+            history_index: None,
+            draft: None,
+            completions,
         }
     }
 
-    pub fn read_line(&self) -> io::Result<Option<String>> {
+    pub fn push_history(&mut self, entry: impl Into<String>) {
+        let entry = entry.into();
+        if entry.trim().is_empty() {
+            return;
+        }
+        self.history.push(entry);
+        self.history_index = None;
+        self.draft = None;
+    }
+
+    pub fn read_line(&mut self) -> io::Result<ReadOutcome> {
         if !io::stdin().is_terminal() || !io::stdout().is_terminal() {
             return self.read_line_fallback();
         }
@@ -107,29 +209,43 @@ impl LineEditor {
         enable_raw_mode()?;
         let mut stdout = io::stdout();
         let mut input = InputBuffer::new();
-        self.redraw(&mut stdout, &input)?;
+        let mut rendered_lines = 1usize;
+        self.redraw(&mut stdout, &input, rendered_lines)?;
 
         loop {
             let event = event::read()?;
             if let Event::Key(key) = event {
-                match Self::handle_key(key, &mut input) {
-                    EditorAction::Continue => self.redraw(&mut stdout, &input)?,
+                match self.handle_key(key, &mut input) {
+                    EditorAction::Continue => {
+                        rendered_lines = self.redraw(&mut stdout, &input, rendered_lines)?;
+                    }
                     EditorAction::Submit => {
                         disable_raw_mode()?;
                         writeln!(stdout)?;
-                        return Ok(Some(input.as_str().to_owned()));
+                        self.history_index = None;
+                        self.draft = None;
+                        return Ok(ReadOutcome::Submit(input.as_str().to_owned()));
                     }
                     EditorAction::Cancel => {
                         disable_raw_mode()?;
                         writeln!(stdout)?;
-                        return Ok(None);
+                        self.history_index = None;
+                        self.draft = None;
+                        return Ok(ReadOutcome::Cancel);
+                    }
+                    EditorAction::Exit => {
+                        disable_raw_mode()?;
+                        writeln!(stdout)?;
+                        self.history_index = None;
+                        self.draft = None;
+                        return Ok(ReadOutcome::Exit);
                     }
                 }
             }
         }
     }
 
-    fn read_line_fallback(&self) -> io::Result<Option<String>> {
+    fn read_line_fallback(&self) -> io::Result<ReadOutcome> {
         let mut stdout = io::stdout();
         write!(stdout, "{}", self.prompt)?;
         stdout.flush()?;
@@ -137,22 +253,32 @@ impl LineEditor {
         let mut buffer = String::new();
         let bytes_read = io::stdin().read_line(&mut buffer)?;
         if bytes_read == 0 {
-            return Ok(None);
+            return Ok(ReadOutcome::Exit);
         }
 
         while matches!(buffer.chars().last(), Some('\n' | '\r')) {
             buffer.pop();
         }
-        Ok(Some(buffer))
+        Ok(ReadOutcome::Submit(buffer))
     }
 
-    fn handle_key(key: KeyEvent, input: &mut InputBuffer) -> EditorAction {
+    #[allow(clippy::too_many_lines)]
+    fn handle_key(&mut self, key: KeyEvent, input: &mut InputBuffer) -> EditorAction {
         match key {
             KeyEvent {
                 code: KeyCode::Char('c'),
                 modifiers,
                 ..
-            } if modifiers.contains(KeyModifiers::CONTROL) => EditorAction::Cancel,
+            } if modifiers.contains(KeyModifiers::CONTROL) => {
+                if input.as_str().is_empty() {
+                    EditorAction::Exit
+                } else {
+                    input.clear();
+                    self.history_index = None;
+                    self.draft = None;
+                    EditorAction::Cancel
+                }
+            }
             KeyEvent {
                 code: KeyCode::Char('j'),
                 modifiers,
@@ -194,6 +320,25 @@ impl LineEditor {
                 input.move_right();
                 EditorAction::Continue
             }
+            KeyEvent {
+                code: KeyCode::Up, ..
+            } => {
+                self.navigate_history_up(input);
+                EditorAction::Continue
+            }
+            KeyEvent {
+                code: KeyCode::Down,
+                ..
+            } => {
+                self.navigate_history_down(input);
+                EditorAction::Continue
+            }
+            KeyEvent {
+                code: KeyCode::Tab, ..
+            } => {
+                input.complete_slash_command(&self.completions);
+                EditorAction::Continue
+            }
             KeyEvent {
                 code: KeyCode::Home,
                 ..
@@ -211,6 +356,8 @@ impl LineEditor {
                 code: KeyCode::Esc, ..
             } => {
                 input.clear();
+                self.history_index = None;
+                self.draft = None;
                 EditorAction::Cancel
             }
             KeyEvent {
@@ -219,22 +366,74 @@ impl LineEditor {
                 ..
             } if modifiers.is_empty() || modifiers == KeyModifiers::SHIFT => {
                 input.insert(ch);
+                self.history_index = None;
+                self.draft = None;
                 EditorAction::Continue
             }
             _ => EditorAction::Continue,
         }
     }
 
-    fn redraw(&self, out: &mut impl Write, input: &InputBuffer) -> io::Result<()> {
-        let display = input.as_str().replace('\n', "\\n\n> ");
+    fn navigate_history_up(&mut self, input: &mut InputBuffer) {
+        if self.history.is_empty() {
+            return;
+        }
+
+        match self.history_index {
+            Some(0) => {}
+            Some(index) => {
+                let next_index = index - 1;
+                input.replace(self.history[next_index].clone());
+                self.history_index = Some(next_index);
+            }
+            None => {
+                self.draft = Some(input.as_str().to_owned());
+                let next_index = self.history.len() - 1;
+                input.replace(self.history[next_index].clone());
+                self.history_index = Some(next_index);
+            }
+        }
+    }
+
+    fn navigate_history_down(&mut self, input: &mut InputBuffer) {
+        let Some(index) = self.history_index else {
+            return;
+        };
+
+        if index + 1 < self.history.len() {
+            let next_index = index + 1;
+            input.replace(self.history[next_index].clone());
+            self.history_index = Some(next_index);
+            return;
+        }
+
+        input.replace(self.draft.take().unwrap_or_default());
+        self.history_index = None;
+    }
+
+    fn redraw(
+        &self,
+        out: &mut impl Write,
+        input: &InputBuffer,
+        previous_line_count: usize,
+    ) -> io::Result<usize> {
+        let rendered = render_buffer(&self.prompt, &self.continuation_prompt, input);
+        if previous_line_count > 1 {
+            queue!(out, MoveUp(saturating_u16(previous_line_count - 1)))?;
+        }
+        queue!(out, MoveToColumn(0), Clear(ClearType::FromCursorDown),)?;
+        rendered.write(out)?;
         queue!(
             out,
+            MoveUp(saturating_u16(rendered.line_count().saturating_sub(1))),
             MoveToColumn(0),
-            Clear(ClearType::CurrentLine),
-            Print(&self.prompt),
-            Print(display),
         )?;
-        out.flush()
+        if rendered.cursor_row > 0 {
+            queue!(out, MoveDown(rendered.cursor_row))?;
+        }
+        queue!(out, MoveToColumn(rendered.cursor_col))?;
+        out.flush()?;
+        Ok(rendered.line_count())
     }
 }
 
@@ -243,11 +442,76 @@ enum EditorAction {
     Continue,
     Submit,
     Cancel,
+    Exit,
+}
+
+#[must_use]
+pub fn render_buffer(
+    prompt: &str,
+    continuation_prompt: &str,
+    input: &InputBuffer,
+) -> RenderedBuffer {
+    let before_cursor = &input.as_str()[..input.cursor];
+    let cursor_row = saturating_u16(before_cursor.chars().filter(|ch| *ch == '\n').count());
+    let cursor_line = before_cursor.rsplit('\n').next().unwrap_or_default();
+    let cursor_prompt = if cursor_row == 0 {
+        prompt
+    } else {
+        continuation_prompt
+    };
+    let cursor_col = saturating_u16(cursor_prompt.chars().count() + cursor_line.chars().count());
+
+    let mut lines = Vec::new();
+    for (index, line) in input.as_str().split('\n').enumerate() {
+        let prefix = if index == 0 {
+            prompt
+        } else {
+            continuation_prompt
+        };
+        lines.push(format!("{prefix}{line}"));
+    }
+    if lines.is_empty() {
+        lines.push(prompt.to_string());
+    }
+
+    RenderedBuffer {
+        lines,
+        cursor_row,
+        cursor_col,
+    }
+}
+
+#[must_use]
+fn longest_common_prefix(values: &[&str]) -> String {
+    let Some(first) = values.first() else {
+        return String::new();
+    };
+
+    let mut prefix = (*first).to_string();
+    for value in values.iter().skip(1) {
+        while !value.starts_with(&prefix) {
+            prefix.pop();
+            if prefix.is_empty() {
+                break;
+            }
+        }
+    }
+    prefix
+}
+
+#[must_use]
+fn saturating_u16(value: usize) -> u16 {
+    u16::try_from(value).unwrap_or(u16::MAX)
 }
 
 #[cfg(test)]
 mod tests {
-    use super::InputBuffer;
+    use super::{render_buffer, InputBuffer, LineEditor};
+    use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+
+    fn key(code: KeyCode) -> KeyEvent {
+        KeyEvent::new(code, KeyModifiers::NONE)
+    }
 
     #[test]
     fn supports_basic_line_editing() {
@@ -266,4 +530,119 @@ mod tests {
         assert_eq!(input.as_str(), "hix");
         assert_eq!(input.cursor(), 2);
     }
+
+    #[test]
+    fn completes_unique_slash_command() {
+        let mut input = InputBuffer::new();
+        for ch in "/he".chars() {
+            input.insert(ch);
+        }
+
+        assert!(input.complete_slash_command(&[
+            "/help".to_string(),
+            "/hello".to_string(),
+            "/status".to_string(),
+        ]));
+        assert_eq!(input.as_str(), "/hel");
+
+        assert!(input.complete_slash_command(&["/help".to_string(), "/status".to_string()]));
+        assert_eq!(input.as_str(), "/help");
+    }
+
+    #[test]
+    fn ignores_completion_when_prefix_is_not_a_slash_command() {
+        let mut input = InputBuffer::new();
+        for ch in "hello".chars() {
+            input.insert(ch);
+        }
+
+        assert!(!input.complete_slash_command(&["/help".to_string()]));
+        assert_eq!(input.as_str(), "hello");
+    }
+
+    #[test]
+    fn history_navigation_restores_current_draft() {
+        let mut editor = LineEditor::new("› ", vec![]);
+        editor.push_history("/help");
+        editor.push_history("status report");
+
+        let mut input = InputBuffer::new();
+        for ch in "draft".chars() {
+            input.insert(ch);
+        }
+
+        let _ = editor.handle_key(key(KeyCode::Up), &mut input);
+        assert_eq!(input.as_str(), "status report");
+
+        let _ = editor.handle_key(key(KeyCode::Up), &mut input);
+        assert_eq!(input.as_str(), "/help");
+
+        let _ = editor.handle_key(key(KeyCode::Down), &mut input);
+        assert_eq!(input.as_str(), "status report");
+
+        let _ = editor.handle_key(key(KeyCode::Down), &mut input);
+        assert_eq!(input.as_str(), "draft");
+    }
+
+    #[test]
+    fn tab_key_completes_from_editor_candidates() {
+        let mut editor = LineEditor::new(
+            "› ",
+            vec![
+                "/help".to_string(),
+                "/status".to_string(),
+                "/session".to_string(),
+            ],
+        );
+        let mut input = InputBuffer::new();
+        for ch in "/st".chars() {
+            input.insert(ch);
+        }
+
+        let _ = editor.handle_key(key(KeyCode::Tab), &mut input);
+        assert_eq!(input.as_str(), "/status");
+    }
+
+    #[test]
+    fn renders_multiline_buffers_with_continuation_prompt() {
+        let mut input = InputBuffer::new();
+        for ch in "hello\nworld".chars() {
+            if ch == '\n' {
+                input.insert_newline();
+            } else {
+                input.insert(ch);
+            }
+        }
+
+        let rendered = render_buffer("› ", "> ", &input);
+        assert_eq!(
+            rendered.lines(),
+            &["› hello".to_string(), "> world".to_string()]
+        );
+        assert_eq!(rendered.cursor_position(), (1, 7));
+    }
+
+    #[test]
+    fn ctrl_c_exits_only_when_buffer_is_empty() {
+        let mut editor = LineEditor::new("› ", vec![]);
+        let mut empty = InputBuffer::new();
+        assert!(matches!(
+            editor.handle_key(
+                KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL),
+                &mut empty,
+            ),
+            super::EditorAction::Exit
+        ));
+
+        let mut filled = InputBuffer::new();
+        filled.insert('x');
+        assert!(matches!(
+            editor.handle_key(
+                KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL),
+                &mut filled,
+            ),
+            super::EditorAction::Cancel
+        ));
+        assert!(filled.as_str().is_empty());
+    }
 }

rust/crates/tools/src/lib.rs

@@ -6,7 +6,7 @@ use std::time::{Duration, Instant};
 use reqwest::blocking::Client;
 use runtime::{
     edit_file, execute_bash, glob_search, grep_search, read_file, write_file, BashCommandInput,
-    GrepSearchInput,
+    GrepSearchInput, PermissionMode,
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
@@ -45,6 +45,7 @@ pub struct ToolSpec {
     pub name: &'static str,
     pub description: &'static str,
     pub input_schema: Value,
+    pub required_permission: PermissionMode,
 }
 
 #[must_use]
@@ -66,6 +67,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["command"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::DangerFullAccess,
         },
         ToolSpec {
             name: "read_file",
@@ -80,6 +82,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["path"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "write_file",
@@ -93,6 +96,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["path", "content"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::WorkspaceWrite,
         },
         ToolSpec {
             name: "edit_file",
@@ -108,6 +112,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["path", "old_string", "new_string"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::WorkspaceWrite,
         },
         ToolSpec {
             name: "glob_search",
@@ -121,6 +126,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["pattern"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "grep_search",
@@ -146,6 +152,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["pattern"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "WebFetch",
@@ -160,6 +167,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["url", "prompt"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "WebSearch",
@@ -180,6 +188,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["query"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "TodoWrite",
@@ -207,6 +216,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["todos"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::WorkspaceWrite,
         },
         ToolSpec {
             name: "Skill",
@@ -220,6 +230,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["skill"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "Agent",
@@ -236,6 +247,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["description", "prompt"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::DangerFullAccess,
         },
         ToolSpec {
             name: "ToolSearch",
@@ -249,6 +261,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["query"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "NotebookEdit",
@@ -265,6 +278,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["notebook_path"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::WorkspaceWrite,
         },
         ToolSpec {
             name: "Sleep",
@@ -277,6 +291,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["duration_ms"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "SendUserMessage",
@@ -297,6 +312,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["message", "status"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "Config",
@@ -312,6 +328,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["setting"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::WorkspaceWrite,
         },
         ToolSpec {
             name: "StructuredOutput",
@@ -320,6 +337,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "type": "object",
                 "additionalProperties": true
             }),
+            required_permission: PermissionMode::ReadOnly,
         },
         ToolSpec {
             name: "REPL",
@@ -334,6 +352,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["code", "language"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::DangerFullAccess,
         },
         ToolSpec {
             name: "PowerShell",
@@ -349,6 +368,7 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                 "required": ["command"],
                 "additionalProperties": false
             }),
+            required_permission: PermissionMode::DangerFullAccess,
         },
     ]
 }
@@ -1179,10 +1199,9 @@ fn execute_todo_write(input: TodoWriteInput) -> Result<TodoWriteOutput, String>
     validate_todos(&input.todos)?;
     let store_path = todo_store_path()?;
     let old_todos = if store_path.exists() {
-        serde_json::from_str::<Vec<TodoItem>>(
+        parse_todo_markdown(
             &std::fs::read_to_string(&store_path).map_err(|error| error.to_string())?,
-        )
-        .map_err(|error| error.to_string())?
+        )?
     } else {
         Vec::new()
     };
@@ -1200,11 +1219,8 @@ fn execute_todo_write(input: TodoWriteInput) -> Result<TodoWriteOutput, String>
     if let Some(parent) = store_path.parent() {
         std::fs::create_dir_all(parent).map_err(|error| error.to_string())?;
     }
-    std::fs::write(
-        &store_path,
-        serde_json::to_string_pretty(&persisted).map_err(|error| error.to_string())?,
-    )
-    .map_err(|error| error.to_string())?;
+    std::fs::write(&store_path, render_todo_markdown(&persisted))
+        .map_err(|error| error.to_string())?;
 
     let verification_nudge_needed = (all_done
         && input.todos.len() >= 3
@@ -1262,7 +1278,58 @@ fn todo_store_path() -> Result<std::path::PathBuf, String> {
         return Ok(std::path::PathBuf::from(path));
     }
     let cwd = std::env::current_dir().map_err(|error| error.to_string())?;
-    Ok(cwd.join(".clawd-todos.json"))
+    Ok(cwd.join(".claude").join("todos.md"))
+}
+
+fn render_todo_markdown(todos: &[TodoItem]) -> String {
+    let mut lines = vec!["# Todo list".to_string(), String::new()];
+    for todo in todos {
+        let marker = match todo.status {
+            TodoStatus::Pending => "[ ]",
+            TodoStatus::InProgress => "[~]",
+            TodoStatus::Completed => "[x]",
+        };
+        lines.push(format!(
+            "- {marker} {} :: {}",
+            todo.content, todo.active_form
+        ));
+    }
+    lines.push(String::new());
+    lines.join("\n")
+}
+
+fn parse_todo_markdown(content: &str) -> Result<Vec<TodoItem>, String> {
+    let mut todos = Vec::new();
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if trimmed.is_empty() || trimmed.starts_with('#') {
+            continue;
+        }
+        let Some(rest) = trimmed.strip_prefix("- [") else {
+            continue;
+        };
+        let mut chars = rest.chars();
+        let status = match chars.next() {
+            Some(' ') => TodoStatus::Pending,
+            Some('~') => TodoStatus::InProgress,
+            Some('x' | 'X') => TodoStatus::Completed,
+            Some(other) => return Err(format!("unsupported todo status marker: {other}")),
+            None => return Err(String::from("malformed todo line")),
+        };
+        let remainder = chars.as_str();
+        let Some(body) = remainder.strip_prefix("] ") else {
+            return Err(String::from("malformed todo line"));
+        };
+        let Some((content, active_form)) = body.split_once(" :: ") else {
+            return Err(String::from("todo line missing active form separator"));
+        };
+        todos.push(TodoItem {
+            content: content.trim().to_string(),
+            active_form: active_form.trim().to_string(),
+            status,
+        });
+    }
+    Ok(todos)
 }
 
 fn resolve_skill_path(skill: &str) -> Result<std::path::PathBuf, String> {
@@ -2618,6 +2685,37 @@ mod tests {
         assert!(second_output["verificationNudgeNeeded"].is_null());
     }
 
+    #[test]
+    fn todo_write_persists_markdown_in_claude_directory() {
+        let _guard = env_lock()
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let temp = temp_path("todos-md-dir");
+        std::fs::create_dir_all(&temp).expect("temp dir");
+        let previous = std::env::current_dir().expect("cwd");
+        std::env::set_current_dir(&temp).expect("set cwd");
+
+        execute_tool(
+            "TodoWrite",
+            &json!({
+                "todos": [
+                    {"content": "Add tool", "activeForm": "Adding tool", "status": "in_progress"},
+                    {"content": "Run tests", "activeForm": "Running tests", "status": "pending"}
+                ]
+            }),
+        )
+        .expect("TodoWrite should succeed");
+
+        let persisted = std::fs::read_to_string(temp.join(".claude").join("todos.md"))
+            .expect("todo markdown exists");
+        std::env::set_current_dir(previous).expect("restore cwd");
+        let _ = std::fs::remove_dir_all(temp);
+
+        assert!(persisted.contains("# Todo list"));
+        assert!(persisted.contains("- [~] Add tool :: Adding tool"));
+        assert!(persisted.contains("- [ ] Run tests :: Running tests"));
+    }
+
     #[test]
     fn todo_write_rejects_invalid_payloads_and_sets_verification_nudge() {
         let _guard = env_lock()