crabcode 0.1.4__tar.gz → 0.1.5__tar.gz

crabcode-0.1.5/.github/workflows/document-engine-wheels.yml

@@ -0,0 +1,40 @@
+name: Document engine offline wheels
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "pyproject.toml"
+      - "packages/gateway/**"
+      - "scripts/build_document_engine_bundle.py"
+      - ".github/workflows/document-engine-wheels.yml"
+
+jobs:
+  offline-install:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Build CrabCode wheel
+        run: |
+          python -m pip install build
+          python -m build --wheel
+      - name: Resolve platform wheelhouse
+        run: |
+          python -m pip download --only-binary=:all: --dest wheelhouse BabelDOC==0.6.4
+          python -c "from pathlib import Path; import shutil; shutil.copy2(next(Path('dist').glob('crabcode-*.whl')), 'wheelhouse')"
+      - name: Verify fully offline installation
+        shell: bash
+        run: |
+          python -m venv engine-venv
+          if [[ "$RUNNER_OS" == "Windows" ]]; then PYTHON=engine-venv/Scripts/python.exe; else PYTHON=engine-venv/bin/python; fi
+          "$PYTHON" -m pip install --no-index --find-links wheelhouse BabelDOC==0.6.4
+          "$PYTHON" -m pip install --no-index --no-deps --find-links wheelhouse crabcode
+          "$PYTHON" -c "import babeldoc; import crabcode_gateway.document_worker"

crabcode-0.1.5/.github/workflows/windows-compat.yml

@@ -0,0 +1,52 @@
+name: Cross-platform compatibility
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+        python: ['3.10', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: python -m pip install -e . fastapi pypdf python-multipart
+      - run: python -m unittest discover -s tests -p "test_windows*.py" -v
+
+  windows-clients:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: npm ci
+        working-directory: packages/desktop
+      - run: npm test
+        working-directory: packages/desktop
+      - run: npx tsc --noEmit
+        working-directory: packages/desktop
+      - run: npm ci
+        working-directory: packages/vscode
+      - run: npm test
+        working-directory: packages/vscode
+      - run: npx tsc --noEmit
+        working-directory: packages/vscode
+      - run: cargo test --locked
+        working-directory: packages/desktop/src-tauri
+      - run: cargo test --locked windows_credentials_survive_a_new_entry -- --ignored
+        working-directory: packages/desktop/src-tauri

{crabcode-0.1.4 → crabcode-0.1.5}/.gitignore

@@ -11,4 +11,7 @@ build/
 .crabcode/
 .claude/
 .DS_Store
-node_modules
+theme-samples
+node_modules
+target/
+packages/desktop/src-tauri/gen/schemas/

{crabcode-0.1.4 → crabcode-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: crabcode
-Version: 0.1.4
+Version: 0.1.5
 Summary: CrabCode - AI coding assistant in the terminal
 Requires-Python: >=3.10
 Requires-Dist: anthropic>=0.40.0
@@ -17,12 +17,17 @@ 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: babeldoc==0.6.4; extra == 'all'
+Requires-Dist: cryptography>=42.0.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: pyjwt>=2.9.0; extra == 'all'
+Requires-Dist: pypdf>=4.0.0; extra == 'all'
+Requires-Dist: python-multipart>=0.0.9; 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'
@@ -33,12 +38,18 @@ Requires-Dist: anthropic[bedrock]>=0.40.0; extra == 'bedrock'
 Provides-Extra: browser
 Requires-Dist: playwright>=1.48.0; extra == 'browser'
 Provides-Extra: debugger
+Provides-Extra: document-translate
+Requires-Dist: babeldoc==0.6.4; extra == 'document-translate'
 Provides-Extra: gateway
 Requires-Dist: agent-client-protocol>=0.9.0; extra == 'gateway'
+Requires-Dist: cryptography>=42.0.0; extra == 'gateway'
 Requires-Dist: fastapi>=0.115.0; extra == 'gateway'
 Requires-Dist: grpcio-health-checking>=1.65.0; extra == 'gateway'
 Requires-Dist: grpcio>=1.65.0; extra == 'gateway'
 Requires-Dist: httpx>=0.27.0; extra == 'gateway'
+Requires-Dist: pyjwt>=2.9.0; extra == 'gateway'
+Requires-Dist: pypdf>=4.0.0; extra == 'gateway'
+Requires-Dist: python-multipart>=0.0.9; extra == 'gateway'
 Requires-Dist: sse-starlette>=2.0.0; extra == 'gateway'
 Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'gateway'
 Provides-Extra: search

{crabcode-0.1.4 → crabcode-0.1.5}/README.md

@@ -40,6 +40,10 @@ pip install crabcode[search,bedrock]
 pip install crabcode[browser,search]
 ```
 
+On Windows PowerShell, set environment variables with
+`$env:ANTHROPIC_API_KEY = "YourKey"` (and use the same `$env:NAME` form for
+the provider-specific keys below).
+
 ### Development
 
 ```bash
@@ -72,6 +76,11 @@ crabcode --continue      # or -c
 crabcode --resume <id>   # or -r <id>
 ```
 
+In the interactive CLI, **Enter** sends; **Ctrl+J** or **Alt/Opt+Enter** inserts a
+newline. You can also press **Esc**, then **Enter** to insert a newline. The
+input frame grows with newlines and wrapped text, and scrolls with the cursor
+when it fills the terminal. These keys also work while the agent is running.
+
 ### Persistent Goals
 
 Use `/goal` to keep a measurable objective active across turns, compaction, and
@@ -107,6 +116,10 @@ crabcode sessions search "refactor auth"
 # Export a session to Markdown or JSON
 crabcode sessions export <id> --format md --output chat.md
 
+# Fork a session from an assistant reply (full or unique-prefix IDs)
+crabcode sessions fork <session-id> <assistant-message-uuid>
+crabcode sessions fork <session-id> <assistant-message-uuid> --title "Try another approach"
+
 # Archive old sessions (older than 30 days) and clean up
 crabcode sessions prune --days 30 --delete-files
 
@@ -115,6 +128,10 @@ crabcode stats
 crabcode stats --project   # current project only
 ```
 
+Inside the interactive CLI, use `/fork [assistant-message-uuid]`; omitting the
+UUID forks from the latest completed assistant reply. UUIDs support completion
+and unique prefixes.
+
 ## Multi-API Support
 
 ### Gateway Server
@@ -135,41 +152,200 @@ crabcode gateway --port 4096 --grpc-port 50051
 crabcode gateway --password secret
 ```
 
+#### Gateway security modes
+
+Gateway authentication is disabled by default. Configure `none`, `password`,
+`publickey`, or `mixed` in the user-level `~/.crabcode/settings.json`. Project
+settings cannot override this process-level security setting.
+
+```json
+{
+  "gateway": {
+    "security": {
+      "mode": "mixed",
+      "password": "change-me",
+      "authorized_keys": "~/.ssh/authorized_keys",
+      "token_ttl_seconds": 900
+    }
+  }
+}
+```
+
+For deployments, use `CRABCODE_GATEWAY_PASSWORD` instead of a plaintext
+`password`, or configure a `password_hash` in `pbkdf2_sha256$...` format.
+`publickey` and `mixed` read `~/.ssh/authorized_keys` by default and support
+Ed25519, RSA-SHA256, and ECDSA-SHA256. In `mixed` mode either method grants
+access, so the password must still be strong.
+
+```bash
+python -c 'from getpass import getpass; from crabcode_gateway.auth import hash_password; print(hash_password(getpass("Password: ")))'
+```
+
+Password clients submit `{"grant_type":"password","password":"..."}` to
+`POST /auth/token`. Public-key clients first call `GET /auth/challenge`, sign
+the returned UTF-8 `signing_payload` locally, then submit `grant_type=publickey`,
+the authorized-key comment or `SHA256:` fingerprint as `key_id`, the challenge,
+and the Base64 signature to `POST /auth/token`. The private key never leaves the
+client. Both flows return a short-lived JWT used as
+`Authorization: Bearer <token>` for HTTP, WebSocket, and gRPC requests.
+Challenges expire after 60 seconds and are single-use. Five consecutive
+password failures are rate-limited for 60 seconds.
+An explicitly configured `jwt_secret` must be at least 32 bytes; otherwise a
+new secret is generated for each gateway process.
+
+The existing `--password` and static Bearer/Basic password behavior remains
+compatible, but new clients should exchange credentials at `/auth/token`.
+Use HTTPS/WSS whenever the gateway is exposed beyond the local machine.
+
 **HTTP API endpoints:**
 
 | Endpoint | Method | Description |
 | ---------- | -------- | ------------- |
-| `/health` | GET | Health check |
-| `/session/new` | POST | Create a new session |
+| `/health` | GET | Health check with the CrabCode version and gateway protocol compatibility range |
+| `/session/new` | POST | Create a session; accepts `cwd` plus optional `model`, `provider`, `base_url`, `api_format`, and `model_profile` overrides |
 | `/session/send` | POST | Send a message (starts query loop, events via SSE) |
 | `/session/interrupt` | POST | Interrupt current turn |
 | `/session/compact` | POST | Trigger manual compaction |
-| `/session/list` | GET | List active sessions |
-| `/session/resume` | POST | Resume a session |
+| `/session/clear` | POST | Clear the active context and persist the clear boundary |
+| `/session/messages` | GET | Read the structured active message projection |
+| `/session/fork` | POST | Atomically fork a session through any completed assistant reply; records the source session/message/title |
+| `/session/list` | GET | List persisted sessions for the current project, or for an optional `cwd` |
+| `/session/recent` | GET | List recent sessions across projects |
+| `/session/search` | POST | Search sessions by title or message |
+| `/session/resolve` | GET | Resolve a full ID, unique prefix, or current-project index |
+| `/session/resume` | POST | Resume by full ID, unique prefix, or index, with the same optional API overrides for a cold session |
+| `/session/status` | GET | Read model, mode, effort, and context-window status |
+| `/session/archive` | POST | Archive a loaded or persisted session |
+| `/session/prune` | POST | Archive stale inactive sessions and optionally purge artifacts |
+| `/session/export` | POST | Export Markdown or JSON by ID, prefix, or index |
+| `/session/stats` | GET | Read global, project, and per-model usage statistics |
 | `/agent/spawn` | POST | Spawn a sub-agent |
 | `/agent/{id}` | GET | Get agent status |
 | `/agent/list` | GET | List all agents |
+| `/agent/{id}/transcript` | GET | Read an agent transcript/log tail |
 | `/agent/{id}/cancel` | POST | Cancel an agent |
 | `/agent/{id}/input` | POST | Send input to an agent |
 | `/agent/wait` | POST | Wait for agent(s) to complete |
 | `/permission/respond` | POST | Respond to a permission request |
 | `/choice/respond` | POST | Respond to a choice request |
 | `/config/models` | GET | List available models |
+| `/config/model-settings` | GET/POST | Inspect and mutate raw/effective model settings for a working directory |
+| `/config/runtime-settings` | GET/POST | Inspect and mutate file snapshots and extra-tool settings for a working directory |
 | `/config/switch-model` | POST | Switch model |
 | `/config/switch-mode` | POST | Switch agent/plan mode |
+| `/config/reasoning-effort` | POST | Set reasoning effort |
+| `/config/ultra-mode` | POST | Toggle or set ultra mode |
+| `/config/permission-mode` | POST | Set the client tool-permission override |
 | `/config/goal` | GET/POST | View or manage the session goal |
+| `/config/plan-status` | GET | Read current plan execution status |
 | `/tools` | GET | List available tools (including MCP) |
+| `/skills` | GET | List available skills |
+| `/skills/expand` | POST | Expand a skill invocation with user input |
 | `/context` | POST | Push workspace context (active file, selection, cursor) |
+| `/context/{session_id}` | GET | Read the latest client workspace context |
+| `/workspace/info` | GET | Read the startup directory, user home, and allowed browse roots |
+| `/workspace/directories` | GET | List subdirectories within the allowed browse roots |
+| `/workspace/directories/create` | POST | Create one directory within an allowed browse root |
+| `/logs` | GET | List, tail, or clear background logs |
+| `/logs/follow` | GET | Follow a background log as SSE |
+| `/tasks`, `/tasks/{id}` | GET | List background tasks or read one task; `scope=global` lists tasks across loaded sessions |
+| `/tasks/{id}/output` | GET | Read persisted background-task output |
+| `/tasks/stop` | POST | Stop a background task |
+| `/schedule`, `/schedule/{id}` | GET | List scheduled jobs or read one job by ID/unique prefix |
+| `/schedule/{id}/runs` | GET | Read persisted execution history for a scheduled job |
+| `/schedule/create` | POST | Create a cron, interval, or one-shot job; supports enabled state, next-run override, reusable execution session, tags, and extra metadata |
+| `/schedule/pause`, `/schedule/resume` | POST | Pause or resume a scheduled job |
+| `/schedule/trigger`, `/schedule/cancel` | POST | Run a job immediately or permanently delete it |
+| `/peer/list`, `/peer/send` | GET/POST | List messageable sessions or send a peer message |
+| `/team/list`, `/team/{id}/*` | GET | Read teams, status, messages, and task boards |
+| `/team/create`, `/team/spawn`, `/team/shutdown` | POST | Manage the team lifecycle |
+| `/team/message`, `/team/broadcast` | POST | Send teammate messages |
+| `/team/remove`, `/team/messages/read` | POST | Remove a teammate or mark its messages read |
+| `/team/task/*` | POST | Add, claim, complete, or fail team tasks |
+| `/team/bridge`, `/team/{a}/bridge/{b}` | POST/GET | Register or inspect a cross-team bridge policy |
+| `/team/cross-message` | POST | Send a policy-checked cross-team message |
 | `/snapshot/checkpoint` | POST | Create checkpoint with file snapshot |
 | `/snapshot/list` | GET | List checkpoints for a session |
 | `/snapshot/revert` | POST | Revert files + conversation to a checkpoint |
 | `/snapshot/rollback` | POST | Rollback conversation only (no file restore) |
+| `/snapshot/undo` | POST | Revert the latest checkpoint |
 | `/event` | GET (SSE) | Real-time event stream with 10s heartbeat |
 | `/ws` | WebSocket | Bidirectional channel (preferred for VSCode) |
 
-**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.
+`POST /config/model-settings` accepts `action` values `upsert_model`,
+`delete_model`, `upsert_group`, `delete_group`, `set_default_model`, and
+`clear_default_model`. Mutations target `userSettings`, `projectSettings`, or
+`localSettings`; project layers require a `cwd` within the Gateway workspace.
+`POST /config/runtime-settings` accepts `set_snapshot`, `add_extra_tool`, and
+`remove_extra_tool`, using the same configuration layers. Disabling snapshots
+skips only the file-system copy; conversation checkpoints are still persisted.
+
+**WebSocket `/ws`** supports the complete interactive command path: session lifecycle (`new_session`, `resume_session`), messages and steering, interrupt, permission/choice responses, workspace context, model/mode/permission changes, and plan actions. `new_session` and `resume_session` accept the same five API override fields as the HTTP lifecycle endpoints. Overrides are rejected for an already-loaded resume target so one client cannot silently replace another client's runtime. A connection remains subscribed to every session it explicitly selects, so background events from an earlier session remain visible after the active UI switches to another one; unrelated sessions are still filtered out. Foreground and plan commands carry an `operation_id`: steering and interrupt should send that ID to avoid targeting a newer turn. Command-validation failures use a typed, non-terminal error envelope, while every admitted operation finishes with exactly one `turn_complete` event. A complete client must also consume structured session history and the session-tagged `agent_state`, `agent_output`, `team_message`, `team_state`, `task_update`, `schedule_run`, `compact`, permission/choice response, file-change, snapshot, and revert events. Schedule CRUD uses the HTTP endpoints above; clients do not need to poll for execution completion.
 
-**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.
+### Crab Desktop and Browser UI
+
+The React client in `packages/desktop` runs in a browser with `npm run dev`, or
+inside the Tauri shell with `npm run tauri dev`. Both forms support local and
+remote Gateways, projects, concurrent sessions, streaming chat, permissions,
+plans, diffs, and checkpoint recovery. Tauri additionally provides system
+credential storage and automatic local Gateway startup; browser mode connects
+to an already-running Gateway and retains passwords only for the current tab.
+
+In Desktop and the VS Code extension, every completed assistant reply can be
+forked into a new session. The new session opens immediately, preserves the
+conversation up to that reply, and shows its source session/title. Running
+turns, pending tools, permission requests, and WebSocket runtime state are not
+copied. In the VS Code chat, copy controls stay hidden until hover or focus;
+they are available for full replies, fenced code, Markdown tables, tool input
+and output, diffs, and error messages.
+
+Tauri writes non-secret UI state to `~/.crabcode/settings_desktop.json`.
+Gateway model and tool settings continue to use the normal `settings.json`.
+Desktop's **Settings → Runtime & Tools** section can edit remote file-snapshot
+settings and the `extra_tools` import-path list by configuration layer.
+
+Direct `! <cmd>` execution is intentionally a trusted-client feature: the CLI runs it in its local process and the VSCode extension sends it to a local integrated terminal. It is not exposed as a Gateway endpoint because doing so would create a permission-bypassing remote shell.
+
+#### High-fidelity PDF engine
+
+Layout-preserving PDF translation is provided by an optional, isolated
+BabelDOC 0.6.4 environment. It requires Python 3.10–3.13, uses approximately
+550 MiB for its models and fonts.
+requests still use the model selected by the active CrabCode session; model
+credentials are never passed to the BabelDOC worker.
+
+The Desktop **Document** settings show the install command. For a local Gateway,
+the Tauri app can execute it directly with the **Run install** button. The
+equivalent CLI commands are:
+
+```bash
+# Inspect, install, or remove the managed engine
+crabcode document-engine status
+crabcode document-engine install
+crabcode document-engine remove --yes
+```
+
+The default installer creates a separate virtual environment, installs the
+official BabelDOC package, downloads and verifies BabelDOC's upstream runtime
+assets, then records a local checksum manifest. Document processing is
+network-disabled after installation. Removing the engine does not delete PDFs
+that have already been translated.
+
+When the engine is ready, new full-document translations default to the
+high-fidelity path and produce a native translated PDF. The reader can switch
+between the original and translated PDFs. If high-fidelity processing fails,
+the UI offers an explicit **Retry in compatibility mode** action instead of
+silently changing engines mid-job.
+
+For a remote Gateway, run `crabcode document-engine install` on the Gateway
+host. CrabCode deliberately does not expose engine installation as a remote
+shell endpoint. Air-gapped installations can use a reviewed offline bundle:
+
+```bash
+crabcode document-engine install --bundle /path/to/crabcode-document-engine.zip
+```
+
+**gRPC** service is available when `--grpc-port` is set, with streaming conversation/event RPCs plus the typed agent, permission, choice, model, and mode RPCs defined in `packages/gateway/crabcode_gateway/grpc/proto/crabcode.proto`.
 
 ### ACP (Agent Client Protocol) Support
 
@@ -288,6 +464,7 @@ Or configure in `~/.crabcode/settings.json`:
 | `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` |
 | `codex_auth_path` | Codex CLI OAuth auth file path. Used only by the `codex` provider when no API key and no `base_url` are configured. | `$CODEX_HOME/auth.json` or `~/.codex/auth.json` |
+| `image_generation_enabled` | Explicitly enable `ImageGenerate` for a compatible Responses endpoint (`provider: "codex"`, or `provider: "router"` with `format: "codex"`). Does not affect automatic image generation availability in official Codex OAuth mode. | `false` |
 | `http_headers` | Extra HTTP headers to attach to every API request for this config | `{}` |
 | `anthropic_stream_transport` | Anthropic streaming implementation: `auto` \| `sdk` \| `httpx`. In `auto`, first-party Anthropic uses the SDK and custom `base_url` endpoints use direct SSE for proxies that reject SDK stream helper headers. | `auto` |
 | `format` | Wire format for router mode: `anthropic` \| `openai` \| `codex` | — |
@@ -317,6 +494,29 @@ For Codex OAuth, set `provider` to `codex` and omit `base_url` and API key setti
 }
 ```
 
+For a third-party Codex/Responses-compatible image generation endpoint, explicitly opt in:
+
+```json
+{
+  "models": {
+    "compatible-images": {
+      "provider": "codex",
+      "model": "your-provider-model-id",
+      "base_url": "https://your-provider.example/v1",
+      "api_key_env": "COMPATIBLE_CODEX_API_KEY",
+      "image_generation_enabled": true,
+      "timeout": 300
+    }
+  }
+}
+```
+
+Set `COMPATIBLE_CODEX_API_KEY` in the environment and select `compatible-images`. You can also put these fields under `api` or a shared `groups` entry. Omitted or `false` disables image generation for compatible endpoints; official `auth.json` mode remains automatic. Other wire formats ignore this flag.
+
+The endpoint must support `POST <base_url>/responses` with the native `image_generation` tool, `tool_choice`, `stream: true`, and `store: false`, returning a final base64 `image_generation_call.result` in Responses SSE events. An `/images/generations`-only API is not compatible with this option. Requests use the selected model ID, `api_key_env` and `http_headers`; they never load local Codex OAuth credentials for a custom endpoint. `extra_body` passes through provider-specific options, but cannot override the image request's `model`, `instructions`, `input`, `tools`, `tool_choice`, `stream`, or `store`. `prompt_cache_key` (or `http_headers.session_id`) and `prompt_cache_retention` are also forwarded when configured.
+
+After restarting with the updated configuration, ask for an image in the conversation. `ImageGenerate` accepts a `prompt` and optional `reference_image_paths` (up to five local images), saves unique files under the workspace's `output/imagegen/`, and returns inline images to Desktop and VS Code. Provider/model support and quotas still apply; enabling this flag does not add upstream image capabilities.
+
 For DeepSeek V4 thinking mode with tool calls, enable reasoning pass-through:
 
 ```json
@@ -412,13 +612,13 @@ Example:
     "pre_tool_call": [
       {
         "matcher": "Bash",
-        "command": "echo '[pre] tool=$CRABCODE_HOOK_TOOL_NAME'"
+        "command": "python -c \"import os; print('[pre] tool=' + os.getenv('CRABCODE_HOOK_TOOL_NAME', ''))\""
       }
     ],
     "post_tool_call": [
       {
         "matcher": "Bash",
-        "command": "echo '[post] tool=$CRABCODE_HOOK_TOOL_NAME'"
+        "command": "python -c \"import os; print('[post] tool=' + os.getenv('CRABCODE_HOOK_TOOL_NAME', ''))\""
       }
     ],
     "user_prompt_submit": [
@@ -429,7 +629,7 @@ Example:
     "pre_compact": [
       {
         "matcher": "manual",
-        "command": "echo '[compact] trigger is in $CRABCODE_HOOK_PAYLOAD'"
+        "command": "python -c \"import os; print('[compact] trigger is in ' + os.getenv('CRABCODE_HOOK_PAYLOAD', ''))\""
       }
     ]
   }
@@ -476,6 +676,31 @@ Define multiple model profiles in `settings.json` and switch between them at run
 
 Each entry under `models` is a full `ApiConfig` and can have its own `provider`, `base_url`, `api_key_env`, `codex_auth_path`, etc.
 
+For profiles that share a backend, define the common fields once under
+`groups` and reference the group from each model. A model field explicitly set
+under `models` overrides the value inherited from its group:
+
+```json
+{
+  "groups": {
+    "test_rourter": {
+      "provider": "codex",
+      "base_url": "https://router.example.com/v1",
+      "api_key_env": "TEST_ROUTER_KEY",
+      "reasoning_effort": "high",
+      "http_headers": {"originator": "codex_vscode"}
+    }
+  },
+  "models": {
+    "gpt-5.6": {"group": "test_rourter", "model": "gpt-5.6-sol"},
+    "gpt-5.5": {"group": "test_rourter", "model": "gpt-5.5", "reasoning_effort": "low"}
+  }
+}
+```
+
+`groups` and `models` accept the same API configuration fields. An unknown
+group leaves the model's own fields unchanged.
+
 **Select a profile at startup:**
 
 ```bash
@@ -485,7 +710,7 @@ crabcode --model-profile smart    # short: -M smart
 **Switch inside the REPL:**
 
 ```
-/model              # show active model, list all configured profiles
+/model              # open the searchable model picker and switch profiles
 /model fast         # switch to the "fast" (ollama) profile
 /model smart        # switch to the "smart" (anthropic) profile
 /model code         # switch to the "code" (openai) profile
@@ -781,6 +1006,32 @@ CrabCode automatically tracks file-system changes made during a session, allowin
 - **Git repos** (preferred): uses `git write-tree` + `git update-ref` under `refs/crabcode/` — lightweight, zero-commit snapshots that don't pollute your git history.
 - **Non-git directories**: files are copied to `.crabcode/snapshots/` for tracking.
 
+**Snapshot safety settings:**
+
+File-system snapshots are enabled by default, with a cumulative workspace-size
+ceiling of 1024 MiB. Configure them in the project or user `settings.json`:
+
+```json
+{
+  "snapshot": {
+    "enabled": true,
+    "max_size_mb": 1024
+  }
+}
+```
+
+The scanner always skips the filesystem root and the user home directory. It
+also skips `.git`, `.crabcode`, dependency and cache directories. If the
+workspace exceeds `max_size_mb`, or `enabled` is `false`, only the file-system
+copy is skipped: the conversation checkpoint is still persisted. In that case
+`/revert` can roll back the conversation but reports that no file snapshot was
+available.
+
+Desktop exposes these fields under **Settings → Runtime & Tools**. The same
+section can add or remove `extra_tools` import paths on the remote Gateway;
+the package must be installed in that Gateway environment. Changes apply to
+new sessions or after reconnecting an existing session.
+
 **Gateway API:**
 
 | Endpoint | Method | Description |
@@ -800,7 +1051,7 @@ CrabCode automatically tracks file-system changes made during a session, allowin
 | `/logs <name>` | Show tail of a specific log |
 | `/logs -f <name>` | Follow a specific log in real time (`Ctrl+C` to stop) |
 | `/logs --clear <name>` | Clear a specific log file |
-| `/model` | Show active model and all configured named models |
+| `/model` | Open a searchable model picker organized by group; ↑/↓ select, Enter switches, Esc cancels, Tab and ←/→ filter groups |
 | `/model <name>` | Switch to a named model from `settings.models` |
 | `/effort` | Show the active reasoning effort |
 | `/effort <none\|minimal\|low\|medium\|high\|xhigh\|max>` | Set reasoning effort for subsequent requests in the current runtime session |
@@ -819,16 +1070,29 @@ CrabCode automatically tracks file-system changes made during a session, allowin
 | `/wait <id>` | Wait for one agent to finish and print its summary |
 | `/cancel-agent <id>` | Cancel a running agent |
 | `/team list` | List active agent teams |
+| `/team create <name> [max]` | Create a team |
 | `/team status <team_id>` | Show team status table |
 | `/team messages <team_id>` | Show team message history |
+| `/team tasks <team_id>` | Show the shared task board |
+| `/team spawn <team_id> [options] <prompt>` | Add a teammate |
+| `/team message <team_id> <agent_id> <text>` | Send a teammate message |
+| `/team broadcast <team_id> <text>` | Broadcast to teammates |
+| `/team task-add <team_id> <description>` | Add a task |
+| `/team task-claim <team_id> <task_id> [agent_id]` | Claim a task |
+| `/team task-complete <team_id> <task_id> [result]` | Complete a task |
 | `/team shutdown <team_id>` | Shut down a team |
+| `/schedule list` | List scheduled jobs |
+| `/schedule show <job_id>` | Show scheduled job details |
+| `/schedule runs <job_id>` | Show scheduled-job run history |
+| `/schedule create <name> <type> <schedule> <prompt>` | Create a cron/interval/once job |
+| `/schedule pause\|resume\|run\|cancel <job_id>` | Manage scheduled-job lifecycle |
 | `/new` | Start a fresh session (clear in-memory conversation history) |
 | `/compact` | Manually compact conversation history to save context |
 | `/clear` | Clear current in-memory conversation messages |
 | `/sessions` | List recent saved sessions for current project |
 | `/recent` | List recent sessions across all projects |
 | `/search <query>` | Search sessions by title or message content |
-| `/resume <id>` | Resume a saved session by full/partial id or index (supports cross-project) |
+| `/resume [id]` | Browse searchable history, or resume by full/partial id or index (supports cross-project) |
 | `/archive <id>` | Archive a session (hide from listings) |
 | `/export [md\|json] [path]` | Export current session to Markdown or JSON |
 | `/stats` | Show usage statistics (tokens, sessions, models) |
@@ -846,7 +1110,7 @@ CrabCode automatically tracks file-system changes made during a session, allowin
 - For commands that take `<id>`, you can usually pass the leading prefix shown by `/agents`.
 - `/agent-send` live output is controlled by `agent.stream_send_input_output` in `settings.json`.
 - `Ctrl+C` interrupts the current operation; pressing `Ctrl+C` again within a few seconds exits.
-- `/resume` supports cross-project sessions — if the session ID belongs to another project it will be resolved automatically via the metadata database.
+- `/resume` opens a keyboard-driven history picker: type to search, ↑/↓ to browse, Enter to resume, Esc/Ctrl+C to return. Tab focuses the project filter (Cwd/All) or sort order (Updated/Created); ←/→ changes the option. `/resume <id>` still supports cross-project sessions via the metadata database.
 
 ### Plan Mode Workflow
 
@@ -993,7 +1257,17 @@ By default, CrabCode does not apply a global timeout to tool calls. Set the top-
 }
 ```
 
-Omit `tool_call_timeout` or set it to `null` to let tool calls run indefinitely. Tool-specific timeouts, such as `Bash.timeout` or `agent.timeout`, still apply independently and may be shorter.
+Omit `tool_call_timeout` or set it to `null` to disable the global limit. Filesystem and tool-specific timeouts, such as `filesystem_timeout`, `Bash.timeout`, or `agent.timeout`, still apply independently and may be shorter.
+
+The shared filesystem tool timeout defaults to **3600 seconds** for Read, Write, Edit, Glob, Grep, and Bash. Set the top-level `filesystem_timeout` field in `~/.crabcode/settings.json` or the project's `.crabcode/settings.json` to change it:
+
+```json
+{
+  "filesystem_timeout": 3600
+}
+```
+
+The value must be a finite, positive number of seconds, or `null` to disable the filesystem timeout. Omitting the field keeps the 3600-second default. It applies to both main-session and sub-agent file tools, including file snapshots performed during a tool call. An explicit `Bash.timeout` overrides this default for that invocation, even when `filesystem_timeout` is `null`; a configured `tool_call_timeout` still caps the overall execution. Operations can still be cancelled when the timeout is disabled.
 
 ## CLAUDE.md (project instructions)
 
@@ -1253,8 +1527,16 @@ The recovery helper can normalize stale `busy`/`cancelling` teammate states in a
 | Command | Description |
 | --------- | ------------- |
 | `/team list` | List active teams |
+| `/team create <name> [max]` | Create a team |
 | `/team status <team_id>` | Show team status table |
 | `/team messages <team_id>` | Show team message history |
+| `/team tasks <team_id>` | Show the shared task board |
+| `/team spawn <team_id> [options] <prompt>` | Add a teammate |
+| `/team message <team_id> <agent_id> <text>` | Send a teammate message |
+| `/team broadcast <team_id> <text>` | Broadcast to teammates |
+| `/team task-add <team_id> <description>` | Add a task |
+| `/team task-claim <team_id> <task_id> [agent_id]` | Claim a task |
+| `/team task-complete <team_id> <task_id> [result]` | Complete a task |
 | `/team shutdown <team_id>` | Shut down a team |
 
 ### Multi-model example
@@ -1538,6 +1820,8 @@ Memory and patch details:
 - `code_patch` writes explicit bytes only, stores the original bytes, can verify
   `expected_hex` before writing, and uses backend protection/cache primitives
   where available.
+- Patch hex input is validated strictly. Active patch IDs must be unique, and
+  overlapping active patches are rejected so the original bytes remain recoverable.
 - `code_restore` restores saved patches by `patch_id` or `all=true`.
 - Direct memory access is subject to operating-system process rights. Windows
   requires sufficient `OpenProcess` rights and can fail for elevated or protected
@@ -1550,6 +1834,8 @@ Process and debuggee actions default to permission confirmation. The tools retur
 `ASK` for process inspection, memory reads/writes/freezes, attach, dump, trace,
 and code patching. When `permissions.default_mode` is `"run_everything"` or legacy `permissions.run_everything` is enabled, those `ASK`
 permissions are bypassed by the normal CrabCode permission mode.
+Adapter discovery also asks for confirmation when a configured adapter declares
+a custom `probe_command`, because discovery will execute that command.
 
 The intended use is local, authorized process debugging, diagnostics, testing,
 and research. `crabcode-debugger` does not provide stealth injection,