[phernandez]

Why

Cloud now exposes only the bm_* 1.0 tools, but core recovery messages still told agents to call removed tools, sometimes with unsupported parameters such as project_id. The bundled read manual also omitted Cloud's hosted read options.

What Changed

• Use bm_read, bm_write, bm_edit, bm_delete, bm_search, bm_move, bm_list, and bm_context in recovery guidance, API conflict messages, prompt templates, and cross-tool help.
• Translate example arguments to the public tool names (project, command, mode, items, since, path, and destination). Preserve external project IDs in recovery calls to avoid ambiguous project names.
• Include read-before-retry guidance in JSON edit revision conflicts as well as text errors.
• Document Cloud's versions, version, cursor, view, and review_mode options, defaults, and incompatible combinations in bm-read(3).
• Add real API regression coverage for refused edits/deletes and a signature-to-manual guard for every exported bm_* tool, including tools hidden at startup.

Implementation Details

Core's bm_read does not accept Cloud's five additional parameters. The manual therefore retains its generated core SYNOPSIS/PARAMETERS and documents a separate hosted signature and Cloud parameters, checked against hosted_bm_read in the Cloud repository. No Cloud-only behavior is added to the local tool.

Legacy compatibility tool implementations and their wire names remain intact. Their recovery guidance now points agents to the public tool surface; creating a missing note recommends bm_write because bm_edit never creates notes.

The new manual guard inspects exported Python signatures instead of the visible registry, so optional project-deletion tools cannot silently escape coverage.

Testing

• Combined MCP recovery, edit, delete, read, write, search, move, context, resource, example, and manual suites: passed (command below).
• uv run pytest tests/api/v2/test_prompt_router.py tests/api/v2/test_knowledge_router.py -k 'prompt or conflict or exists' --import-mode=importlib -q -o addopts= --tb=short: 9 passed.
• just fast-check: passed (Ruff checks/formatting and full typecheck).
• just doctor: passed, including sandboxed write/index/search.
• git diff --check: passed.

Combined suite command:

uv run pytest tests/mcp/test_tool_guidance.py tests/mcp/test_tool_delete_note.py tests/mcp/test_tool_edit_note.py tests/mcp/test_tool_write_note.py tests/mcp/test_tool_search.py tests/mcp/test_tool_move_note.py tests/mcp/test_tool_read_note.py tests/mcp/test_tool_build_context.py tests/mcp/test_man_resources.py tests/mcp/test_model_facing_call_examples.py tests/test_man_pages.py tests/test_bm_tool_manual_parameters.py --import-mode=importlib -n 4 --dist=loadfile -q -o addopts= --tb=short

Risks / Follow-ups

Changes primarily affect guidance and documentation; JSON edit conflicts gain an additive message field. Cloud-only documentation is curated from the hosted wrapper, while automated signature coverage checks the core tools shipped by this repository. SQLite was exercised locally; the PR matrix covers the remaining platforms and Postgres.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-25T17:58:56.029690Z	c5bc425	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.