crabcode 0.1.1__tar.gz → 0.1.3__tar.gz

{crabcode-0.1.1 → crabcode-0.1.3}/.gitignore

@@ -10,4 +10,5 @@ build/
 .ruff_cache/
 .crabcode/
 .claude/
-.DS_Store
+.DS_Store
+node_modules

{crabcode-0.1.1 → crabcode-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crabcode
-Version: 0.1.1
+Version: 0.1.3
 Summary: CrabCode - AI coding assistant in the terminal
 Requires-Python: >=3.10
 Requires-Dist: anthropic>=0.40.0
@@ -12,6 +12,21 @@ Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: tiktoken>=0.7.0
 Requires-Dist: typer>=0.12.0
+Provides-Extra: all
+Requires-Dist: agent-client-protocol>=0.9.0; extra == 'all'
+Requires-Dist: anthropic[bedrock]>=0.40.0; extra == 'all'
+Requires-Dist: anthropic[vertex]>=0.40.0; extra == 'all'
+Requires-Dist: fastapi>=0.115.0; extra == 'all'
+Requires-Dist: grpcio-health-checking>=1.65.0; extra == 'all'
+Requires-Dist: grpcio>=1.65.0; extra == 'all'
+Requires-Dist: httpx>=0.27.0; extra == 'all'
+Requires-Dist: modelscope>=1.10.0; extra == 'all'
+Requires-Dist: playwright>=1.48.0; extra == 'all'
+Requires-Dist: sentence-transformers>=2.0.0; extra == 'all'
+Requires-Dist: sse-starlette>=2.0.0; extra == 'all'
+Requires-Dist: tree-sitter-language-pack>=1.0.0; extra == 'all'
+Requires-Dist: usearch>=2.12.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'all'
 Provides-Extra: bedrock
 Requires-Dist: anthropic[bedrock]>=0.40.0; extra == 'bedrock'
 Provides-Extra: browser

{crabcode-0.1.1 → crabcode-0.1.3}/README.md

@@ -30,12 +30,15 @@ pip install crabcode[search]
 pip install crabcode[bedrock]   # AWS Bedrock
 pip install crabcode[vertex]    # Google Vertex AI
 
+# With gateway server support
+pip install crabcode[gateway]
+
+# Install all optional features at once
+pip install crabcode[all]
+
 # Combine extras
 pip install crabcode[search,bedrock]
-# Example: browser + search
 pip install crabcode[browser,search]
-# With gateway server support
-pip install crabcode[gateway]
 ```
 
 ### Development
@@ -146,7 +149,7 @@ crabcode gateway --password secret
 
 **WebSocket `/ws`** supports incoming commands (`send_message`, `permission_response`, `choice_response`, `push_context`) and outgoing event payloads — a single connection handles all interaction, making it ideal for VSCode extensions.
 
-**gRPC** service is available when `--grpc-port` is set, with streaming `SendMessage` and `SubscribeEvents` RPCs. See `packages/gateway/crabcode_gateway/grpc_/proto/crabcode.proto` for the full service definition.
+**gRPC** service is available when `--grpc-port` is set, with streaming `SendMessage` and `SubscribeEvents` RPCs. See `packages/gateway/crabcode_gateway/grpc/proto/crabcode.proto` for the full service definition.
 
 ### ACP (Agent Client Protocol) Support
 
@@ -243,6 +246,9 @@ Or configure in `~/.crabcode/settings.json`:
     "model": "gpt-4o",
     "base_url": "https://api.openai.com/v1",
     "api_key_env": "OPENAI_API_KEY",
+    "http_headers": {
+      "X-Workspace": "crabcode"
+    },
     "thinking_enabled": false,
     "max_tokens": 16384
   },
@@ -260,12 +266,17 @@ Or configure in `~/.crabcode/settings.json`:
 | `model` | Model ID | — |
 | `base_url` | Custom API endpoint (for routers or local deployments) | — |
 | `api_key_env` | **Name** of the env var that holds the API key (not the key itself) | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` |
+| `http_headers` | Extra HTTP headers to attach to every API request for this config | `{}` |
 | `format` | Wire format for router mode: `anthropic` \| `openai` \| `codex` | — |
 | `thinking_enabled` | Enable extended thinking (set `false` for models that don't support it) | `true` |
 | `thinking_budget` | Thinking token budget | `10000` |
+| `reasoning_effort` | OpenAI Responses/Codex reasoning effort; when set, this takes precedence over the `thinking_budget` mapping. Options: `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` | — |
 | `max_tokens` | Maximum output tokens | `16384` |
 | `timeout` | API call timeout in seconds (prevents hanging on slow/unresponsive APIs) | `300` |
 | `context_window` | Override the model's context window size (tokens). Used when auto-detection fails or is inaccurate — see [Context Window](#context-window) below. | auto-detected |
+| `prompt_cache_key` | Prompt cache routing key for OpenAI Responses/Codex requests; defaults to `http_headers.session_id` when omitted | — |
+| `prompt_cache_retention` | OpenAI Responses/Codex prompt cache retention policy: `in_memory` \| `24h` | — |
+| `extra_body` | Provider-specific fields appended to the request JSON body | `{}` |
 
 The `env` map lets you define environment variables directly in the config file — they are injected at startup so you don't need to `export` them in your shell.
 
@@ -1365,6 +1376,6 @@ crabcode/
 │       │   ├── types.py        # ACP types + tool kind mapping
 │       │   └── transport.py    # stdio transport (run_agent wrapper)
 │       ├── routes/             # FastAPI route groups (session, agent, config, event, health)
-│       └── grpc_/              # gRPC service + proto definition
+│       └── grpc/               # gRPC service + proto definition
 └── tests/
 ```

{crabcode-0.1.1 → crabcode-0.1.3}/README.zh-CN.md

@@ -30,12 +30,15 @@ pip install crabcode[search]
 pip install crabcode[bedrock]   # AWS Bedrock
 pip install crabcode[vertex]    # Google Vertex AI
 
+# 含网关服务器支持
+pip install crabcode[gateway]
+
+# 一键安装全部可选特性
+pip install crabcode[all]
+
 # 组合安装
 pip install crabcode[search,bedrock]
-# 示例：浏览器 + 搜索
 pip install crabcode[browser,search]
-# 含网关服务器支持
-pip install crabcode[gateway]
 ```
 
 ### 开发模式
@@ -146,7 +149,7 @@ crabcode gateway --password secret
 
 **WebSocket `/ws`** 支持收发命令（`send_message`、`permission_response`、`choice_response`、`push_context`）和事件推送 —— 单个连接即可完成所有交互，适合 VSCode 扩展使用。
 
-**gRPC** 在启用 `--grpc-port` 后可用，提供流式 `SendMessage` 和 `SubscribeEvents` RPC。完整服务定义见 `packages/gateway/crabcode_gateway/grpc_/proto/crabcode.proto`。
+**gRPC** 在启用 `--grpc-port` 后可用，提供流式 `SendMessage` 和 `SubscribeEvents` RPC。完整服务定义见 `packages/gateway/crabcode_gateway/grpc/proto/crabcode.proto`。
 
 ### ACP（Agent Client Protocol）支持
 
@@ -243,6 +246,9 @@ export AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/
     "model": "gpt-4o",
     "base_url": "https://api.openai.com/v1",
     "api_key_env": "OPENAI_API_KEY",
+    "http_headers": {
+      "X-Workspace": "crabcode"
+    },
     "thinking_enabled": false,
     "max_tokens": 16384
   },
@@ -260,12 +266,17 @@ export AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/
 | `model` | 模型 ID | — |
 | `base_url` | 自定义 API 地址（适用于第三方转发或本地部署） | — |
 | `api_key_env` | 存放 API Key 的**环境变量名**（不是 Key 本身） | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` |
+| `http_headers` | 为该配置的每次 API 请求附加额外 HTTP Header | `{}` |
 | `format` | Router 模式下的协议格式：`anthropic` \| `openai` \| `codex` \| `ollama` \| `gemini` \| `azure` | — |
 | `thinking_enabled` | 是否启用思考模式（不支持该功能的模型需设为 `false`） | `true` |
 | `thinking_budget` | 思考 token 预算 | `10000` |
+| `reasoning_effort` | OpenAI Responses/Codex 推理强度；显式配置时优先于 `thinking_budget` 映射。可选：`none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` | — |
 | `max_tokens` | 最大输出 token 数 | `16384` |
 | `timeout` | API 调用超时时间（秒），防止网络卡住时无限等待 | `300` |
 | `context_window` | 覆盖模型的上下文窗口大小（token 数）。当自动检测失败或不准确时使用——详见下方[上下文窗口管理](#上下文窗口管理)。 | 自动检测 |
+| `prompt_cache_key` | OpenAI Responses/Codex 请求的 Prompt Cache 路由 key；未配置时默认使用 `http_headers.session_id` | — |
+| `prompt_cache_retention` | OpenAI Responses/Codex Prompt Cache 保留策略：`in_memory` \| `24h` | — |
+| `extra_body` | 追加到请求 JSON body 的 provider 专用字段 | `{}` |
 
 `env` 字段用于直接在配置文件中定义环境变量，启动时会自动注入，无需在 shell 中 `export`。
 
@@ -1361,6 +1372,6 @@ crabcode/
 │       │   ├── types.py        # ACP 类型定义 + 工具类型映射
 │       │   └── transport.py    # stdio 传输层（run_agent 封装）
 │       ├── routes/             # FastAPI 路由组（session、agent、config、event、health）
-│       └── grpc_/              # gRPC 服务 + proto 定义
+│       └── grpc/               # gRPC 服务 + proto 定义
 └── tests/
 ```

{crabcode-0.1.1 → crabcode-0.1.3}/packages/cli/crabcode_cli/__init__.py

@@ -1,3 +1,3 @@
 """CrabCode CLI - terminal frontend."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

crabcode-0.1.3/packages/cli/crabcode_cli/__main__.py

@@ -0,0 +1,4 @@
+from crabcode_cli.app import entry
+
+if __name__ == "__main__":
+    entry()

{crabcode-0.1.1 → crabcode-0.1.3}/packages/cli/crabcode_cli/app.py

@@ -31,6 +31,7 @@ def main(
     cwd: Optional[str] = typer.Option(None, "--cwd", help="Working directory"),
     resume: Optional[str] = typer.Option(None, "-r", "--resume", help="Resume a session by ID"),
     continue_last: bool = typer.Option(False, "-c", "--continue", help="Continue most recent session"),
+    image: Optional[list[str]] = typer.Option(None, "-i", "--image", help="Image file(s) to attach (repeatable)"),
 ) -> None:
     """CrabCode — AI coding assistant in the terminal."""
     from crabcode_core.types.config import ApiConfig, CrabCodeSettings
@@ -51,6 +52,8 @@ def main(
         settings.api.base_url = file_settings.api.base_url
     if file_settings.api.api_key_env:
         settings.api.api_key_env = file_settings.api.api_key_env
+    if file_settings.api.http_headers:
+        settings.api.http_headers = dict(file_settings.api.http_headers)
     if file_settings.api.format:
         settings.api.format = file_settings.api.format
     if not file_settings.api.thinking_enabled:
@@ -94,6 +97,30 @@ def main(
                 err=True,
             )
 
+    # Read image files into base64 attachments
+    image_attachments: list[dict[str, str]] | None = None
+    if image:
+        import base64
+        import mimetypes
+        from pathlib import Path
+
+        image_attachments = []
+        for img_path_str in image:
+            img_path = Path(img_path_str)
+            if not img_path.exists():
+                typer.echo(f"Error: image file not found: {img_path_str}", err=True)
+                raise typer.Exit(1)
+            if img_path.stat().st_size > 20 * 1024 * 1024:
+                typer.echo(f"Error: image file too large (>20MB): {img_path_str}", err=True)
+                raise typer.Exit(1)
+            media_type = mimetypes.guess_type(img_path_str)[0] or "image/png"
+            if not media_type.startswith("image/"):
+                typer.echo(f"Error: not an image file: {img_path_str}", err=True)
+                raise typer.Exit(1)
+            with open(img_path, "rb") as f:
+                data = base64.b64encode(f.read()).decode("ascii")
+            image_attachments.append({"media_type": media_type, "data": data})
+
     stdin_text = ""
     if not sys.stdin.isatty():
         stdin_text = sys.stdin.read().strip()
@@ -105,12 +132,12 @@ def main(
             raise typer.Exit(1)
 
         from crabcode_cli.pipe import run_pipe
-        asyncio.run(run_pipe(text, settings=settings, cwd=work_dir))
+        asyncio.run(run_pipe(text, settings=settings, cwd=work_dir, images=image_attachments))
         return
 
     if prompt:
         from crabcode_cli.pipe import run_pipe
-        asyncio.run(run_pipe(prompt, settings=settings, cwd=work_dir))
+        asyncio.run(run_pipe(prompt, settings=settings, cwd=work_dir, images=image_attachments))
         return
 
     resume_id: str | None = None

{crabcode-0.1.1 → crabcode-0.1.3}/packages/cli/crabcode_cli/pipe.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-import asyncio
+import json
+import os
 import sys
 
 from crabcode_core.events import CoreSession
@@ -21,16 +22,56 @@ from crabcode_core.types.event import (
     TurnCompleteEvent,
 )
 
+_DEBUG_TOOL_PAYLOAD = os.getenv("CRABCODE_DEBUG_TOOL_PAYLOAD", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+    "on",
+}
+
+
+def _format_token_count(tokens: int) -> str:
+    if tokens >= 1_000_000:
+        return f"{tokens / 1_000_000:.1f}M"
+    if tokens >= 1_000:
+        return f"{tokens // 1_000}k"
+    return str(tokens)
+
+
+def _format_percent(percent: float) -> str:
+    rounded = round(percent)
+    if abs(percent - rounded) < 0.05:
+        return f"{rounded}%"
+    return f"{percent:.1f}%"
+
+
+def _format_context_usage(event: TurnCompleteEvent) -> str | None:
+    used = max(0, int(getattr(event, "context_used_tokens", 0) or 0))
+    window = max(0, int(getattr(event, "context_window_tokens", 0) or 0))
+    if not used and not window:
+        return None
+    if not window:
+        return f"Context: {_format_token_count(used)} tokens used (window unknown)"
+
+    used_percent = max(0.0, float(getattr(event, "context_used_percent", 0.0) or 0.0))
+    remaining_percent = max(0.0, 100.0 - used_percent)
+    return (
+        f"Context: {_format_percent(used_percent)} used "
+        f"({_format_percent(remaining_percent)} remaining) · "
+        f"{_format_token_count(used)} tokens used of {_format_token_count(window)}"
+    )
+
 
 async def run_pipe(
     prompt: str,
     settings: CrabCodeSettings | None = None,
     cwd: str = ".",
+    images: list[dict[str, str]] | None = None,
 ) -> None:
     """Run a single prompt through the core and print the response."""
     session = CoreSession(cwd=cwd, settings=settings)
     try:
-        async for event in session.send_message(prompt):
+        async for event in session.send_message(prompt, images=images):
             if isinstance(event, StreamTextEvent):
                 sys.stdout.write(safe_utf8_str(event.text))
                 sys.stdout.flush()
@@ -38,6 +79,9 @@ async def run_pipe(
                 pass
             elif isinstance(event, ToolUseEvent):
                 sys.stderr.write(f"\n[Tool: {event.tool_name}]\n")
+                if _DEBUG_TOOL_PAYLOAD:
+                    pretty = json.dumps(event.tool_input, ensure_ascii=False, indent=2)
+                    sys.stderr.write(f"{pretty}\n")
                 sys.stderr.flush()
             elif isinstance(event, PermissionRequestEvent):
                 await session.respond_permission(
@@ -64,7 +108,10 @@ async def run_pipe(
                 if not event.recoverable:
                     sys.exit(1)
             elif isinstance(event, TurnCompleteEvent):
-                pass
+                usage_text = _format_context_usage(event)
+                if usage_text:
+                    sys.stderr.write(f"\n{usage_text}\n")
+                    sys.stderr.flush()
     finally:
         await session.close()
 

{crabcode-0.1.1 → crabcode-0.1.3}/packages/cli/crabcode_cli/repl.py

@@ -4,11 +4,13 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import json
 import os
 import sys
 import time
 from datetime import datetime
 from pathlib import Path
+from typing import Any
 
 from prompt_toolkit import PromptSession
 from prompt_toolkit.completion import Completer, Completion
@@ -66,6 +68,42 @@ _ANSI_ENABLED = _supports_ansi_output()
 console = Console(no_color=not _ANSI_ENABLED, force_terminal=_ANSI_ENABLED)
 
 
+def _format_token_count(tokens: int) -> str:
+    if tokens >= 1_000_000:
+        return f"{tokens / 1_000_000:.1f}M"
+    if tokens >= 1_000:
+        return f"{tokens // 1_000}k"
+    return str(tokens)
+
+
+def _format_percent(percent: float) -> str:
+    rounded = round(percent)
+    if abs(percent - rounded) < 0.05:
+        return f"{rounded}%"
+    return f"{percent:.1f}%"
+
+
+def _render_context_usage(event: TurnCompleteEvent) -> None:
+    used = max(0, int(getattr(event, "context_used_tokens", 0) or 0))
+    window = max(0, int(getattr(event, "context_window_tokens", 0) or 0))
+    if not used and not window:
+        return
+
+    if window:
+        used_percent = max(0.0, float(getattr(event, "context_used_percent", 0.0) or 0.0))
+        remaining_percent = max(0.0, 100.0 - used_percent)
+        console.print(
+            "  [dim]Context: "
+            f"{_format_percent(used_percent)} used "
+            f"({_format_percent(remaining_percent)} remaining) · "
+            f"{_format_token_count(used)} tokens used of {_format_token_count(window)}[/]"
+        )
+    else:
+        console.print(
+            f"  [dim]Context: {_format_token_count(used)} tokens used (window unknown)[/]"
+        )
+
+
 # Slash commands with their arguments for auto-completion
 _SLASH_COMMANDS: dict[str, list[str]] = {
     "/help": [],
@@ -98,6 +136,7 @@ _SLASH_COMMANDS: dict[str, list[str]] = {
     "/resume": [],  # Dynamic: session IDs
     "/exit": [],
     "/quit": [],
+    "/image": [],  # Dynamic: file path
 }
 
 
@@ -244,6 +283,7 @@ class _CrabCodeCompleter(Completer):
             "/revert": "revert files + conversation to checkpoint",
             "/undo": "undo last checkpoint (revert files + conversation)",
             "/resume": "resume session",
+            "/image": "attach image to next message",
             "/exit": "exit CrabCode",
             "/quit": "exit CrabCode",
         }
@@ -516,6 +556,27 @@ def _tool_summary(name: str, inp: dict) -> str:
     return (raw[:200] + "…") if len(raw) > 200 else raw
 
 
+def _debug_tool_payload_enabled() -> bool:
+    return os.getenv("CRABCODE_DEBUG_TOOL_PAYLOAD", "").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+        "on",
+    }
+
+
+def _render_full_tool_payload(tool_name: str, tool_input: dict) -> None:
+    payload = json.dumps(tool_input, ensure_ascii=False, indent=2)
+    console.print(
+        Panel(
+            Text(payload, style="dim"),
+            title=f"[bold yellow]Debug Payload: {tool_name}[/]",
+            border_style="yellow",
+            expand=False,
+        )
+    )
+
+
 def _render_saved_partial_reply(text: str) -> None:
     """Echo assistant text that was persisted after interrupt (visible in scrollback)."""
     body = text.rstrip()
@@ -558,6 +619,8 @@ def _render_tool_use(event: ToolUseEvent) -> None:
             expand=False,
         )
     )
+    if _debug_tool_payload_enabled():
+        _render_full_tool_payload(event.tool_name, event.tool_input)
 
 
 def _truncate_display(display: str, max_lines: int = 50, max_chars: int = 50_000) -> str:
@@ -699,8 +762,21 @@ def _render_session_history(messages: list[Message], max_messages: int = 50) ->
 async def _prompt_permission(
     event: PermissionRequestEvent,
     session: CoreSession,
+    batch_state: dict | None = None,
 ) -> None:
     """Prompt the user for tool permission and push response to session."""
+    # If a previous request in this batch was denied, auto-deny silently
+    if batch_state and batch_state.get("denied"):
+        await session.respond_permission(
+            PermissionResponseEvent(
+                tool_use_id=event.tool_use_id, allowed=False, agent_id=event.agent_id
+            )
+        )
+        console.print(
+            f"  [dim red]✗ {event.tool_name} auto-denied (batch)[/]"
+        )
+        return
+
     summary = _tool_summary(event.tool_name, event.tool_input)
     if event.reason:
         summary = f"{summary}\n\nReason: {event.reason}"
@@ -713,17 +789,19 @@ async def _prompt_permission(
         )
     )
 
-    loop = asyncio.get_event_loop()
+    perm_prompt_session: PromptSession[str] = PromptSession()
     while True:
         try:
-            choice = await loop.run_in_executor(
-                None,
-                lambda: input(
-                    f"  Allow {event.tool_name}? "
-                    "(y)es / (n)o / (a)lways allow: "
-                ).strip().lower(),
+            choice = await perm_prompt_session.prompt_async(
+                HTML(
+                    f"  Allow <b>{event.tool_name}</b>? "
+                    "(y)es / (n)o / (a)lways allow / (f)eedback: "
+                )
             )
+            choice = choice.strip().lower()
         except (EOFError, KeyboardInterrupt):
+            if batch_state is not None:
+                batch_state["denied"] = True
             await session.respond_permission(
                 PermissionResponseEvent(
                     tool_use_id=event.tool_use_id, allowed=False, agent_id=event.agent_id
@@ -739,6 +817,8 @@ async def _prompt_permission(
             )
             return
         elif choice in ("n", "no"):
+            if batch_state is not None:
+                batch_state["denied"] = True
             await session.respond_permission(
                 PermissionResponseEvent(
                     tool_use_id=event.tool_use_id, allowed=False, agent_id=event.agent_id
@@ -755,8 +835,28 @@ async def _prompt_permission(
                 )
             )
             return
+        elif choice in ("f", "feedback"):
+            try:
+                feedback_session: PromptSession[str] = PromptSession()
+                feedback = await feedback_session.prompt_async(
+                    HTML("  Feedback (what to do instead): ")
+                )
+                feedback = feedback.strip()
+            except (EOFError, KeyboardInterrupt):
+                feedback = ""
+            if batch_state is not None:
+                batch_state["denied"] = True
+            await session.respond_permission(
+                PermissionResponseEvent(
+                    tool_use_id=event.tool_use_id,
+                    allowed=False,
+                    agent_id=event.agent_id,
+                    feedback=feedback or None,
+                )
+            )
+            return
         else:
-            console.print("  [dim]Please enter y, n, or a[/]")
+            console.print("  [dim]Please enter y, n, a, or f[/]")
 
 
 async def _interactive_select(question: str, options: list[str], multiple: bool = False) -> list[str]:
@@ -1058,6 +1158,7 @@ async def _run_plan_executor_with_runtime_events(
     producer = asyncio.create_task(_produce_plan_events())
     forwarder = asyncio.create_task(_forward_agent_events())
     active_stream_agent: str | None = None
+    batch_state: dict = {"denied": False}
 
     try:
         while True:
@@ -1095,6 +1196,11 @@ async def _run_plan_executor_with_runtime_events(
                 console.print(
                     f"  [{style}]agent {event.agent_id[:8]} · {event.status} · {event.title}[/]"
                 )
+            elif isinstance(event, StreamModeEvent):
+                if event.mode == "tool-input":
+                    batch_state["denied"] = False
+            elif isinstance(event, TurnCompleteEvent):
+                batch_state["denied"] = False
             elif isinstance(event, ToolUseEvent):
                 _render_tool_use(event)
             elif isinstance(event, ToolResultEvent):
@@ -1106,7 +1212,7 @@ async def _run_plan_executor_with_runtime_events(
                 else:
                     _render_tool_result(event)
             elif isinstance(event, PermissionRequestEvent):
-                await _prompt_permission(event, session)
+                await _prompt_permission(event, session, batch_state)
             elif isinstance(event, ChoiceRequestEvent):
                 await _prompt_choice(event, session)
             elif isinstance(event, ErrorEvent):
@@ -1165,6 +1271,9 @@ async def run_repl(
 
     session = CoreSession(cwd=cwd, settings=settings)
 
+    # Pending image attachments for the next user message
+    pending_images: list[dict[str, str]] = []
+
     global _display_settings
     _display_settings = settings.display if settings else None
 
@@ -1227,6 +1336,8 @@ async def run_repl(
                 mode = getattr(session, '_agent_mode', 'agent')
                 if mode == "plan":
                     prompt_html = HTML("<b><ansiblue>[plan]</ansiblue> <ansicyan>❯ </ansicyan></b>")
+                elif pending_images:
+                    prompt_html = HTML("<b><ansicyan>❯ 📎 </ansicyan></b>")
                 else:
                     prompt_html = HTML("<b><ansicyan>❯ </ansicyan></b>")
                 user_input = await prompt_session.prompt_async(prompt_html)
@@ -1270,7 +1381,7 @@ async def run_repl(
             ctrl_c_exit.clear()
 
             if user_input.startswith("/"):
-                result = await _handle_command(user_input, session, settings)
+                result = await _handle_command(user_input, session, settings, pending_images)
                 if result is False:
                     break
                 if isinstance(result, str):
@@ -1305,7 +1416,10 @@ async def run_repl(
 
             plan_pending = False
             try:
-                async for event in session.send_message(user_input):
+                send_images = pending_images.copy() if pending_images else None
+                pending_images.clear()
+                batch_state: dict = {"denied": False}
+                async for event in session.send_message(user_input, images=send_images):
                     if isinstance(event, StreamModeEvent):
                         if event.mode == "requesting":
                             spinner.start()
@@ -1318,6 +1432,7 @@ async def run_repl(
                         elif event.mode == "responding":
                             await _stop_spinner_with_thinking()
                         elif event.mode == "tool-input":
+                            batch_state["denied"] = False
                             await _stop_spinner_with_thinking()
                             if streamed_text:
                                 sys.stdout.write("\n")
@@ -1378,7 +1493,7 @@ async def run_repl(
                             sys.stdout.write("\n")
                             sys.stdout.flush()
                             streamed_text = ""
-                        await _prompt_permission(event, session)
+                        await _prompt_permission(event, session, batch_state)
 
                     elif isinstance(event, ChoiceRequestEvent):
                         await _stop_spinner_with_thinking()
@@ -1468,6 +1583,11 @@ async def run_repl(
 
                     elif isinstance(event, TurnCompleteEvent):
                         await _stop_spinner_with_thinking()
+                        if streamed_text:
+                            sys.stdout.write("\n")
+                            sys.stdout.flush()
+                            streamed_text = ""
+                        _render_context_usage(event)
                         if getattr(session, '_current_plan', None) and session.agent_mode == "agent":
                             plan_pending = True
 
@@ -1568,6 +1688,7 @@ async def _handle_command(
     command: str,
     session: CoreSession,
     settings: CrabCodeSettings | None,
+    pending_images: list[dict[str, str]] | None = None,
 ) -> bool | str:
     """Handle slash commands.
 
@@ -1583,6 +1704,42 @@ async def _handle_command(
     # --- Built-in commands take priority over skill names ---
     skills = getattr(session, "skills", [])
 
+    if cmd == "/image":
+        if not arg:
+            if pending_images is not None and pending_images:
+                console.print(f"[dim]{len(pending_images)} image(s) attached for next message.[/]")
+            else:
+                console.print("[dim]Usage: /image <path> [path2 ...][/]")
+            return True
+        import base64
+        import mimetypes
+        from pathlib import Path
+
+        paths = arg.split()
+        added = 0
+        for p in paths:
+            img_path = Path(p).expanduser()
+            if not img_path.exists():
+                console.print(f"[bold red]File not found: {p}[/]")
+                continue
+            if img_path.stat().st_size > 20 * 1024 * 1024:
+                console.print(f"[bold red]File too large (>20MB): {p}[/]")
+                continue
+            media_type = mimetypes.guess_type(str(img_path))[0] or "image/png"
+            if not media_type.startswith("image/"):
+                console.print(f"[bold red]Not an image: {p} (detected: {media_type})[/]")
+                continue
+            with open(img_path, "rb") as f:
+                data = base64.b64encode(f.read()).decode("ascii")
+            if pending_images is not None:
+                pending_images.append({"media_type": media_type, "data": data})
+            added += 1
+            size_kb = img_path.stat().st_size / 1024
+            console.print(f"  [green]✓[/] Attached: {p} ({media_type}, {size_kb:.0f}KB)")
+        if added and pending_images is not None:
+            console.print(f"[dim]{len(pending_images)} image(s) will be sent with your next message.[/]")
+        return True
+
     if cmd == "/help":
         skills_section = ""
         if skills:
@@ -1629,6 +1786,7 @@ async def _handle_command(
             "[bold]/revert <id|#>[/] — revert files + conversation to a checkpoint\n"
             "[bold]/undo[/] — revert last checkpoint (files + conversation)\n"
             "[bold]/resume <id>[/] — resume a previous session\n"
+            "[bold]/image <path>[/] — attach image(s) to your next message\n"
             "[bold]/exit[/] — exit CrabCode\n"
             f"[bold]Ctrl+C[/] — interrupt; press again within {_CTRL_C_EXIT_WINDOW_S:.0f}s to exit\n"
             "\n"