klaude-code 2.24.0__tar.gz → 2.25.0__tar.gz

{klaude_code-2.24.0 → klaude_code-2.25.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.3
 Name: klaude-code
-Version: 2.24.0
+Version: 2.25.0
 Summary: Minimal code agent CLI
-Requires-Dist: anthropic>=0.66.0
+Requires-Dist: anthropic[bedrock]>=0.66.0
 Requires-Dist: chardet>=5.2.0,<6
 Requires-Dist: diff-match-patch>=20241021
 Requires-Dist: filelock>=3.20.3
@@ -32,14 +32,17 @@ Minimal code agent CLI.
 - **Keep reasoning item in context**: Interleaved thinking support
 - **Model-aware tools**: Claude Code tool set for Opus, `apply_patch` for GPT-5/Codex
 - **Reminders**: Cooldown-based todo tracking, instruction reinforcement and external file change reminder
-- **Sub-agents**: Task, Explore
-- **Structured sub-agent output**: Main agent defines JSON schema and get schema-compliant responses via constrained decoding
+- **Sub-agents**: General Purpose, Finder, Code Reviewer, Code Simplifier (+ fork-context variant)
 - **Recursive `@file` mentions**: Circular dependency protection, relative path resolution
 - **External file sync**: Monitoring for external edits (linter, manual)
 - **Interrupt handling**: Ctrl+C preserves partial responses and synthesizes tool cancellation results
 - **Output truncation**: Large outputs saved to file system with snapshot links
 - **Agent Skills**: Built-in + user + project Agent Skills (with implicit invocation by Skill tool or explicit invocation by typing `//skill` or `/skill`)
-- **Sessions**: Resumable with `--continue`
+- **Prompt caching**: Append-only message history maximizes prefix cache hits (cached tokens cost 10% of base input)
+- **Context management**: Auto-compaction, Rewind (rollback to checkpoint), Handoff (compress and continue in fresh context)
+- **Auto memory**: Persistent cross-session memory per project (`~/.klaude/projects/<project>/memory/`)
+- **Web UI**: Browser-based interface via `klaude web` or `/web` slash command
+- **Sessions**: Resumable with `--continue`, forkable with `/fork-session`
 - **Extras**: Slash commands, sub-agents, image paste, terminal notifications, auto-theming
 
 ## Installation
@@ -118,8 +121,10 @@ export OPENAI_API_KEY=sk-xxx             # GPT models
 export OPENROUTER_API_KEY=sk-or-xxx      # OpenRouter (multi-provider)
 export DEEPSEEK_API_KEY=sk-xxx           # DeepSeek models
 export MOONSHOT_API_KEY=sk-xxx           # Moonshot/Kimi models
-export BRAVE_API_KEY=BSA-xxx             # Brave Search (optional, WebSearch provider)
-export EXA_API_KEY=exa-xxx               # Exa Search (optional, WebSearch provider)
+export MINIMAX_API_KEY=xxx               # MiniMax models
+export GOOGLE_API_KEY=xxx                # Google Gemini models (or GEMINI_API_KEY)
+export EXA_API_KEY=exa-xxx               # Exa Search (optional, WebSearch provider, preferred)
+export BRAVE_API_KEY=BSA-xxx             # Brave Search (optional, WebSearch provider, fallback)
 
 # Then just run:
 klaude
@@ -151,9 +156,9 @@ Klaude tries these entries in order and uses the first available model. `fast_mo
 | openrouter       | `OPENROUTER_API_KEY`                                                         | gpt-5.3-codex, gpt-5.3-codex-xhigh, gpt-5.4-high, gpt-5.4-xhigh, kimi, haiku, sonnet, sonnet-no-thinking, opus, gemini-pro, gemini-flash, grok, minimax, glm |
 | google           | `GOOGLE_API_KEY` or `GEMINI_API_KEY`                                         | gemini-pro, gemini-flash                                                                                |
 | google-vertex    | `GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` | gemini-pro, gemini-flash                                                                                |
-| bedrock          | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`                   | sonnet                                                                                                   |
 | deepseek         | `DEEPSEEK_API_KEY`                                                           | deepseek                                                                                                 |
 | moonshot         | `MOONSHOT_API_KEY`                                                           | kimi                                                                                                     |
+| minimax          | `MINIMAX_API_KEY`                                                            | m2.7, m2.7:highspeed                                                                                     |
 | cerebras         | `CEREBRAS_API_KEY`                                                           | glm                                                                                                      |
 | claude-max       | N/A (OAuth)                                             | sonnet, sonnet-no-thinking, opus, haiku                                                                 |
 | codex            | N/A (OAuth)                                                                  | gpt-5.3-codex, gpt-5.3-codex-xhigh, gpt-5.4-high, gpt-5.4-xhigh   |
@@ -167,7 +172,9 @@ List all configured providers and models:
 klaude list
 ```
 
-Models from providers without a valid API key are shown as dimmed/unavailable.
+Models from providers without valid credentials are shown as dimmed/unavailable.
+
+Bedrock is supported as a custom provider rather than a built-in one. See `docs/bedrock-setup.md`.
 
 #### Authentication
 
@@ -184,6 +191,7 @@ klaude auth login google      # Set GOOGLE_API_KEY
 klaude auth login openrouter  # Set OPENROUTER_API_KEY
 klaude auth login deepseek    # Set DEEPSEEK_API_KEY
 klaude auth login moonshot    # Set MOONSHOT_API_KEY
+klaude auth login minimax    # Set MINIMAX_API_KEY
 
 # OAuth login for subscription-based providers
 klaude auth login codex       # ChatGPT Pro subscription
@@ -257,17 +265,23 @@ provider_list:
 
 ##### Sub-agent Model Configuration
 
-`sub_agent_models` only accepts sub-agent types. Current supported keys are:
+`sub_agent_models` accepts registered sub-agent type names as keys. Current supported keys are:
 
-- `general-purpose` (Task sub-agent)
-- `explore` (Explore sub-agent)
+- `general-purpose` - Autonomous multi-step task executor
+- `general-purpose-fork-context` - Same as above but inherits parent conversation history
+- `finder` - Fast codebase search and exploration
+- `code-reviewer` - Identifies bugs in proposed changes
+- `code-simplifier` - Refines code for clarity and consistency
 
-If a sub-agent type is not configured, it falls back to the main agent model.
+If a sub-agent type is not configured, it falls back to the main agent model. Each key also accepts a list for fallback ordering.
 
 ```yaml
 sub_agent_models:
   general-purpose: sonnet
-  explore: haiku
+  finder:
+    - haiku
+    - gemini-flash
+  code-reviewer: opus
 ```
 
 ##### Supported Protocols
@@ -276,9 +290,13 @@ sub_agent_models:
 - `openai` - OpenAI Chat Completion API
 - `responses` - OpenAI Responses API (for o-series, GPT-5, Codex)
 - `codex_oauth` - OpenAI Codex CLI (OAuth-based, for ChatGPT Pro subscribers)
+- `github_copilot_oauth` - GitHub Copilot (OAuth-based)
 - `openrouter` - OpenRouter API (handling `reasoning_details` for interleaved thinking)
 - `google` - Google Gemini API
-- `bedrock` - AWS Bedrock for Claude(uses AWS credentials instead of api_key)
+- `google_vertex` - Google Vertex AI (uses GCP credentials)
+- `bedrock` - AWS Bedrock for Claude (uses AWS credentials instead of api_key)
+
+For a working Bedrock provider example, see `docs/bedrock-setup.md`.
 
 List configured providers and models:
 
@@ -308,19 +326,20 @@ Inside the interactive session (`klaude`), use these commands to streamline your
 - `/...` supports mixed completion for commands + skills (command names take priority on conflicts).
 - `//...` shows skill-only completion and triggers skills explicitly.
 
+- `/copy` - Copy last assistant message to clipboard.
+- `/compact` - Clear conversation history but keep a summary in context.
+- `/fork-session` - Fork current session from a selected point.
+- `/refresh-terminal` - Refresh terminal display.
+- `/web` - Switch to web UI mode.
+- `/new` - Start a new session (clears context).
 - `/model` - Switch the active LLM during the session.
-- `/thinking` - Configure model thinking/reasoning level.
-- `/clear` - Clear the current conversation context.
-- `/copy` - Copy last assistant message.
+- `/sub-agent-model` - Configure sub-agent models at runtime.
+- `/thinking` - Change thinking/reasoning level.
 - `/status` - Show session usage statistics (cost, tokens, model breakdown).
-- `/resume` - Select and resume a previous session.
-- `/fork-session` - Fork current session to a new session ID (supports interactive fork point selection).
-- `/export` - Export last assistant message to a temp Markdown file.
+- `/login` - Login to provider or configure API key.
+- `/logout` - Logout from provider.
+- `/continue` - Continue current session without a new user message.
 - `/debug [filters]` - Toggle debug mode and configure debug filters.
-- `/init` - Bootstrap a new project structure or module.
-- `/dev-doc [feature]` - Generate a comprehensive execution plan for a feature.
-- `/terminal-setup` - Configure terminal for Shift+Enter support.
-- `/help` - List all available commands.
 
 
 ### Input Shortcuts
@@ -328,7 +347,7 @@ Inside the interactive session (`klaude`), use these commands to streamline your
 | Key                  | Action                                      |
 | -------------------- | ------------------------------------------- |
 | `Enter`              | Submit input                                |
-| `Shift+Enter`        | Insert newline (requires `/terminal-setup`) |
+| `Shift+Enter`        | Insert newline (terminal-dependent)         |
 | `Ctrl+J`             | Insert newline                              |
 | `Ctrl+L`             | Open model picker overlay                   |
 | `Ctrl+T`             | Open thinking level picker overlay          |
@@ -343,5 +362,62 @@ The main agent can spawn specialized sub-agents for specific tasks:
 
 | Sub-Agent | Purpose |
 |-----------|---------|
-| **Explore** | Fast codebase exploration - find files, search code, answer questions about the codebase |
-| **Task** | Handle complex multi-step tasks autonomously |
+| **General Purpose** | Handle complex multi-step tasks autonomously |
+| **General Purpose (Fork Context)** | Same as above, but inherits the parent agent's full conversation history |
+| **Finder** | Fast codebase exploration - find files, search code, answer questions about the codebase |
+| **Code Reviewer** | Identify real bugs in proposed changes |
+| **Code Simplifier** | Refine recently changed code for clarity and consistency |
+
+### Web UI
+
+Klaude includes a browser-based interface as an alternative to the terminal TUI.
+
+```bash
+# Start web UI directly
+klaude web
+
+# With options
+klaude web --port 9000 --host 0.0.0.0 --no-open
+```
+
+You can also switch from TUI to web mid-session with the `/web` slash command. The web UI provides the same capabilities as the TUI: multi-session management, file browsing, tool execution, and real-time streaming.
+
+### Prompt Caching
+
+Klaude is designed to maximize prefix cache hit rates across LLM API calls. Cached tokens are priced at ~10% of base input tokens, so high cache hit rates significantly reduce cost.
+
+**Append-only message history.** The conversation history is strictly append-only. New messages, tool results, and attachments are always appended to the end of the message array, never inserted or modified in the middle. Any mutation to the head of the messages array (compressing old tool results, replacing images, reordering tool definitions) would invalidate the prefix cache and force a full re-tokenization.
+
+Design choices that preserve prefix stability:
+- **Stable system prompt**: The system prompt is composed of a static base prompt + stable tool strategy block + environment info, avoiding per-turn variation.
+- **Stable JSON serialization**: Tool schemas and provider payloads use `canonicalize_json()` for deterministic key ordering across calls.
+- **Cache control markers**: For Anthropic and OpenRouter (Claude models), `cache_control: {"type": "ephemeral"}` is placed on the system prompt and the last message part to hint the provider's caching boundary.
+- **Compaction preserves prefix**: When context is compacted, the summary is prepended as a new first message while keeping the retained tail intact -- no existing message bytes are modified.
+- **Fork-context sub-agents**: Sub-agents with `fork_context=True` inherit the parent's full system prompt and tool list to maximize prefix cache sharing.
+
+The TUI displays cache hit rate per turn in the metadata line (e.g. `cache 12.5k (98%)`). Rates below 90% are highlighted as a warning.
+
+### Context Management
+
+The agent automatically manages context window limits:
+
+- **Auto-compaction**: When the conversation approaches the model's context limit, older messages are summarized and replaced with a compact summary. The agent also recovers from context overflow errors by compacting and retrying.
+- **Rewind**: The agent can roll back the conversation to a previous checkpoint (automatically inserted at key points). File system changes are preserved; only conversation history is rewound.
+- **Handoff**: The agent can compress the current conversation into a summary and continue in a fresh context. Useful for very long sessions where context quality degrades.
+
+### Auto Memory
+
+Klaude maintains persistent memory per project across sessions. Memory files are stored in `~/.klaude/projects/<project-key>/memory/` with a `MEMORY.md` index file. The agent automatically loads relevant memories at session start and can save new memories during a session.
+
+Memory types include user preferences, feedback/corrections, project context, and external references.
+
+### Project Configuration Files
+
+Klaude reads instruction files from your project directory to customize agent behavior:
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Project-level instructions checked into version control (shared with team) |
+| `CLAUDE.md` | Personal instructions (typically gitignored) |
+
+These files are loaded automatically and injected into the system prompt. They can be placed at the project root or in subdirectories for scoped instructions.

{klaude_code-2.24.0 → klaude_code-2.25.0}/README.md

@@ -7,14 +7,17 @@ Minimal code agent CLI.
 - **Keep reasoning item in context**: Interleaved thinking support
 - **Model-aware tools**: Claude Code tool set for Opus, `apply_patch` for GPT-5/Codex
 - **Reminders**: Cooldown-based todo tracking, instruction reinforcement and external file change reminder
-- **Sub-agents**: Task, Explore
-- **Structured sub-agent output**: Main agent defines JSON schema and get schema-compliant responses via constrained decoding
+- **Sub-agents**: General Purpose, Finder, Code Reviewer, Code Simplifier (+ fork-context variant)
 - **Recursive `@file` mentions**: Circular dependency protection, relative path resolution
 - **External file sync**: Monitoring for external edits (linter, manual)
 - **Interrupt handling**: Ctrl+C preserves partial responses and synthesizes tool cancellation results
 - **Output truncation**: Large outputs saved to file system with snapshot links
 - **Agent Skills**: Built-in + user + project Agent Skills (with implicit invocation by Skill tool or explicit invocation by typing `//skill` or `/skill`)
-- **Sessions**: Resumable with `--continue`
+- **Prompt caching**: Append-only message history maximizes prefix cache hits (cached tokens cost 10% of base input)
+- **Context management**: Auto-compaction, Rewind (rollback to checkpoint), Handoff (compress and continue in fresh context)
+- **Auto memory**: Persistent cross-session memory per project (`~/.klaude/projects/<project>/memory/`)
+- **Web UI**: Browser-based interface via `klaude web` or `/web` slash command
+- **Sessions**: Resumable with `--continue`, forkable with `/fork-session`
 - **Extras**: Slash commands, sub-agents, image paste, terminal notifications, auto-theming
 
 ## Installation
@@ -93,8 +96,10 @@ export OPENAI_API_KEY=sk-xxx             # GPT models
 export OPENROUTER_API_KEY=sk-or-xxx      # OpenRouter (multi-provider)
 export DEEPSEEK_API_KEY=sk-xxx           # DeepSeek models
 export MOONSHOT_API_KEY=sk-xxx           # Moonshot/Kimi models
-export BRAVE_API_KEY=BSA-xxx             # Brave Search (optional, WebSearch provider)
-export EXA_API_KEY=exa-xxx               # Exa Search (optional, WebSearch provider)
+export MINIMAX_API_KEY=xxx               # MiniMax models
+export GOOGLE_API_KEY=xxx                # Google Gemini models (or GEMINI_API_KEY)
+export EXA_API_KEY=exa-xxx               # Exa Search (optional, WebSearch provider, preferred)
+export BRAVE_API_KEY=BSA-xxx             # Brave Search (optional, WebSearch provider, fallback)
 
 # Then just run:
 klaude
@@ -126,9 +131,9 @@ Klaude tries these entries in order and uses the first available model. `fast_mo
 | openrouter       | `OPENROUTER_API_KEY`                                                         | gpt-5.3-codex, gpt-5.3-codex-xhigh, gpt-5.4-high, gpt-5.4-xhigh, kimi, haiku, sonnet, sonnet-no-thinking, opus, gemini-pro, gemini-flash, grok, minimax, glm |
 | google           | `GOOGLE_API_KEY` or `GEMINI_API_KEY`                                         | gemini-pro, gemini-flash                                                                                |
 | google-vertex    | `GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` | gemini-pro, gemini-flash                                                                                |
-| bedrock          | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`                   | sonnet                                                                                                   |
 | deepseek         | `DEEPSEEK_API_KEY`                                                           | deepseek                                                                                                 |
 | moonshot         | `MOONSHOT_API_KEY`                                                           | kimi                                                                                                     |
+| minimax          | `MINIMAX_API_KEY`                                                            | m2.7, m2.7:highspeed                                                                                     |
 | cerebras         | `CEREBRAS_API_KEY`                                                           | glm                                                                                                      |
 | claude-max       | N/A (OAuth)                                             | sonnet, sonnet-no-thinking, opus, haiku                                                                 |
 | codex            | N/A (OAuth)                                                                  | gpt-5.3-codex, gpt-5.3-codex-xhigh, gpt-5.4-high, gpt-5.4-xhigh   |
@@ -142,7 +147,9 @@ List all configured providers and models:
 klaude list
 ```
 
-Models from providers without a valid API key are shown as dimmed/unavailable.
+Models from providers without valid credentials are shown as dimmed/unavailable.
+
+Bedrock is supported as a custom provider rather than a built-in one. See `docs/bedrock-setup.md`.
 
 #### Authentication
 
@@ -159,6 +166,7 @@ klaude auth login google      # Set GOOGLE_API_KEY
 klaude auth login openrouter  # Set OPENROUTER_API_KEY
 klaude auth login deepseek    # Set DEEPSEEK_API_KEY
 klaude auth login moonshot    # Set MOONSHOT_API_KEY
+klaude auth login minimax    # Set MINIMAX_API_KEY
 
 # OAuth login for subscription-based providers
 klaude auth login codex       # ChatGPT Pro subscription
@@ -232,17 +240,23 @@ provider_list:
 
 ##### Sub-agent Model Configuration
 
-`sub_agent_models` only accepts sub-agent types. Current supported keys are:
+`sub_agent_models` accepts registered sub-agent type names as keys. Current supported keys are:
 
-- `general-purpose` (Task sub-agent)
-- `explore` (Explore sub-agent)
+- `general-purpose` - Autonomous multi-step task executor
+- `general-purpose-fork-context` - Same as above but inherits parent conversation history
+- `finder` - Fast codebase search and exploration
+- `code-reviewer` - Identifies bugs in proposed changes
+- `code-simplifier` - Refines code for clarity and consistency
 
-If a sub-agent type is not configured, it falls back to the main agent model.
+If a sub-agent type is not configured, it falls back to the main agent model. Each key also accepts a list for fallback ordering.
 
 ```yaml
 sub_agent_models:
   general-purpose: sonnet
-  explore: haiku
+  finder:
+    - haiku
+    - gemini-flash
+  code-reviewer: opus
 ```
 
 ##### Supported Protocols
@@ -251,9 +265,13 @@ sub_agent_models:
 - `openai` - OpenAI Chat Completion API
 - `responses` - OpenAI Responses API (for o-series, GPT-5, Codex)
 - `codex_oauth` - OpenAI Codex CLI (OAuth-based, for ChatGPT Pro subscribers)
+- `github_copilot_oauth` - GitHub Copilot (OAuth-based)
 - `openrouter` - OpenRouter API (handling `reasoning_details` for interleaved thinking)
 - `google` - Google Gemini API
-- `bedrock` - AWS Bedrock for Claude(uses AWS credentials instead of api_key)
+- `google_vertex` - Google Vertex AI (uses GCP credentials)
+- `bedrock` - AWS Bedrock for Claude (uses AWS credentials instead of api_key)
+
+For a working Bedrock provider example, see `docs/bedrock-setup.md`.
 
 List configured providers and models:
 
@@ -283,19 +301,20 @@ Inside the interactive session (`klaude`), use these commands to streamline your
 - `/...` supports mixed completion for commands + skills (command names take priority on conflicts).
 - `//...` shows skill-only completion and triggers skills explicitly.
 
+- `/copy` - Copy last assistant message to clipboard.
+- `/compact` - Clear conversation history but keep a summary in context.
+- `/fork-session` - Fork current session from a selected point.
+- `/refresh-terminal` - Refresh terminal display.
+- `/web` - Switch to web UI mode.
+- `/new` - Start a new session (clears context).
 - `/model` - Switch the active LLM during the session.
-- `/thinking` - Configure model thinking/reasoning level.
-- `/clear` - Clear the current conversation context.
-- `/copy` - Copy last assistant message.
+- `/sub-agent-model` - Configure sub-agent models at runtime.
+- `/thinking` - Change thinking/reasoning level.
 - `/status` - Show session usage statistics (cost, tokens, model breakdown).
-- `/resume` - Select and resume a previous session.
-- `/fork-session` - Fork current session to a new session ID (supports interactive fork point selection).
-- `/export` - Export last assistant message to a temp Markdown file.
+- `/login` - Login to provider or configure API key.
+- `/logout` - Logout from provider.
+- `/continue` - Continue current session without a new user message.
 - `/debug [filters]` - Toggle debug mode and configure debug filters.
-- `/init` - Bootstrap a new project structure or module.
-- `/dev-doc [feature]` - Generate a comprehensive execution plan for a feature.
-- `/terminal-setup` - Configure terminal for Shift+Enter support.
-- `/help` - List all available commands.
 
 
 ### Input Shortcuts
@@ -303,7 +322,7 @@ Inside the interactive session (`klaude`), use these commands to streamline your
 | Key                  | Action                                      |
 | -------------------- | ------------------------------------------- |
 | `Enter`              | Submit input                                |
-| `Shift+Enter`        | Insert newline (requires `/terminal-setup`) |
+| `Shift+Enter`        | Insert newline (terminal-dependent)         |
 | `Ctrl+J`             | Insert newline                              |
 | `Ctrl+L`             | Open model picker overlay                   |
 | `Ctrl+T`             | Open thinking level picker overlay          |
@@ -318,5 +337,62 @@ The main agent can spawn specialized sub-agents for specific tasks:
 
 | Sub-Agent | Purpose |
 |-----------|---------|
-| **Explore** | Fast codebase exploration - find files, search code, answer questions about the codebase |
-| **Task** | Handle complex multi-step tasks autonomously |
+| **General Purpose** | Handle complex multi-step tasks autonomously |
+| **General Purpose (Fork Context)** | Same as above, but inherits the parent agent's full conversation history |
+| **Finder** | Fast codebase exploration - find files, search code, answer questions about the codebase |
+| **Code Reviewer** | Identify real bugs in proposed changes |
+| **Code Simplifier** | Refine recently changed code for clarity and consistency |
+
+### Web UI
+
+Klaude includes a browser-based interface as an alternative to the terminal TUI.
+
+```bash
+# Start web UI directly
+klaude web
+
+# With options
+klaude web --port 9000 --host 0.0.0.0 --no-open
+```
+
+You can also switch from TUI to web mid-session with the `/web` slash command. The web UI provides the same capabilities as the TUI: multi-session management, file browsing, tool execution, and real-time streaming.
+
+### Prompt Caching
+
+Klaude is designed to maximize prefix cache hit rates across LLM API calls. Cached tokens are priced at ~10% of base input tokens, so high cache hit rates significantly reduce cost.
+
+**Append-only message history.** The conversation history is strictly append-only. New messages, tool results, and attachments are always appended to the end of the message array, never inserted or modified in the middle. Any mutation to the head of the messages array (compressing old tool results, replacing images, reordering tool definitions) would invalidate the prefix cache and force a full re-tokenization.
+
+Design choices that preserve prefix stability:
+- **Stable system prompt**: The system prompt is composed of a static base prompt + stable tool strategy block + environment info, avoiding per-turn variation.
+- **Stable JSON serialization**: Tool schemas and provider payloads use `canonicalize_json()` for deterministic key ordering across calls.
+- **Cache control markers**: For Anthropic and OpenRouter (Claude models), `cache_control: {"type": "ephemeral"}` is placed on the system prompt and the last message part to hint the provider's caching boundary.
+- **Compaction preserves prefix**: When context is compacted, the summary is prepended as a new first message while keeping the retained tail intact -- no existing message bytes are modified.
+- **Fork-context sub-agents**: Sub-agents with `fork_context=True` inherit the parent's full system prompt and tool list to maximize prefix cache sharing.
+
+The TUI displays cache hit rate per turn in the metadata line (e.g. `cache 12.5k (98%)`). Rates below 90% are highlighted as a warning.
+
+### Context Management
+
+The agent automatically manages context window limits:
+
+- **Auto-compaction**: When the conversation approaches the model's context limit, older messages are summarized and replaced with a compact summary. The agent also recovers from context overflow errors by compacting and retrying.
+- **Rewind**: The agent can roll back the conversation to a previous checkpoint (automatically inserted at key points). File system changes are preserved; only conversation history is rewound.
+- **Handoff**: The agent can compress the current conversation into a summary and continue in a fresh context. Useful for very long sessions where context quality degrades.
+
+### Auto Memory
+
+Klaude maintains persistent memory per project across sessions. Memory files are stored in `~/.klaude/projects/<project-key>/memory/` with a `MEMORY.md` index file. The agent automatically loads relevant memories at session start and can save new memories during a session.
+
+Memory types include user preferences, feedback/corrections, project context, and external references.
+
+### Project Configuration Files
+
+Klaude reads instruction files from your project directory to customize agent behavior:
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Project-level instructions checked into version control (shared with team) |
+| `CLAUDE.md` | Personal instructions (typically gitignored) |
+
+These files are loaded automatically and injected into the system prompt. They can be placed at the project root or in subdirectories for scoped instructions.

{klaude_code-2.24.0 → klaude_code-2.25.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "uv_build"
 
 [project]
 name = "klaude-code"
-version = "2.24.0"
+version = "2.25.0"
 description = "Minimal code agent CLI"
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
-    "anthropic>=0.66.0",
+    "anthropic[bedrock]>=0.66.0",
     "chardet>=5.2.0,<6",
     "diff-match-patch>=20241021",
     "filelock>=3.20.3",
@@ -102,6 +102,7 @@ include = [
 [tool.importlinter]
 root_packages = ["klaude_code"]
 include_external_packages = false
+exclude_type_checking_imports = true
 
 [[tool.importlinter.contracts]]
 name = "Layered architecture"
@@ -111,7 +112,8 @@ layers = [
     "klaude_code.tui",
     "klaude_code.web",
     "klaude_code.app",
-    "klaude_code.core",
+    "klaude_code.agent",
+    "klaude_code.tool | klaude_code.prompts | klaude_code.control",
     "klaude_code.skill",
     "klaude_code.session",
     "klaude_code.config",
@@ -121,3 +123,7 @@ layers = [
     "klaude_code.log",
     "klaude_code.const",
 ]
+ignore_imports = [
+    # prompts lazy-imports skill.manager for system prompt assembly
+    "klaude_code.prompts.* -> klaude_code.skill.*",
+]

{klaude_code-2.24.0/src/klaude_code/core → klaude_code-2.25.0/src/klaude_code}/agent/agent.py

@@ -2,15 +2,15 @@ from __future__ import annotations
 
 from collections.abc import AsyncGenerator, Awaitable, Callable, Iterable
 
-from klaude_code.core.agent.task import SessionContext, TaskExecutionContext, TaskExecutor
-from klaude_code.core.agent_profile import AgentProfile, Reminder
-from klaude_code.core.tool import build_todo_context, get_registry
-from klaude_code.core.tool.context import RunSubtask
+from klaude_code.agent.agent_profile import AgentProfile
+from klaude_code.agent.task import SessionContext, TaskExecutionContext, TaskExecutor
 from klaude_code.llm import LLMClientABC
 from klaude_code.log import DebugType, log_debug
 from klaude_code.protocol import events, model, user_interaction
 from klaude_code.protocol.message import UserInputPayload
 from klaude_code.session import Session
+from klaude_code.tool import build_todo_context, get_registry
+from klaude_code.tool.context import RunSubtask
 
 
 class Agent:
@@ -36,7 +36,7 @@ class Agent:
         self.profile: AgentProfile = profile
         self.compact_llm_client: LLMClientABC | None = compact_llm_client
         self._current_task: TaskExecutor | None = None
-        self._request_user_interaction = request_user_interaction
+        self.request_user_interaction = request_user_interaction
         if not self.session.model_name:
             self.session.model_name = profile.llm_client.model_name
 
@@ -68,14 +68,13 @@ class Agent:
             file_change_summary=self.session.file_change_summary,
             todo_context=build_todo_context(self.session),
             run_subtask=run_subtask,
-            request_user_interaction=self._request_user_interaction,
+            request_user_interaction=self.request_user_interaction,
         )
         context = TaskExecutionContext(
             session=self.session,
             session_ctx=session_ctx,
             profile=self.profile,
             tool_registry=get_registry(),
-            process_reminder=self._process_reminder,
             sub_agent_state=self.session.sub_agent_state,
             compact_llm_client=self.compact_llm_client,
         )
@@ -92,7 +91,7 @@ class Agent:
     async def replay_history(self) -> AsyncGenerator[events.Event]:
         """Yield UI events reconstructed from saved conversation history."""
 
-        if len(self.session.conversation_history) == 0:
+        if not self.session.conversation_history:
             return
 
         yield events.ReplayHistoryEvent(
@@ -101,13 +100,6 @@ class Agent:
             session_id=self.session.id,
         )
 
-    async def _process_reminder(self, reminder: Reminder) -> AsyncGenerator[events.DeveloperMessageEvent]:
-        """Process a single reminder and yield events if it produces output."""
-        item = await reminder(self.session)
-        if item is not None:
-            self.session.append_history([item])
-            yield events.DeveloperMessageEvent(session_id=self.session.id, item=item)
-
     def set_model_profile(self, profile: AgentProfile) -> None:
         """Apply a fully constructed profile to the agent."""