feat!: replace tool visibility flags with a single exposure option

[frostming]

What changed and why

Tools had three overlapping boolean flags controlling where they can be called from (agent_use, preserve, and a newly needed "code mode only" behavior). Their combinations were partly invalid and hard to reason about, so they are folded into one option:

@tool()                    # exposure="auto" (default)
@tool(exposure="direct")   # was preserve=True
@tool(exposure="code")     # new: callable only from run_code
@tool(exposure="command")  # was agent_use=False

exposure	Outside code mode	In code mode
"auto" (default)	Model calls it directly	Only from run_code
"direct"	Model calls it directly	Model calls it directly; not in tools.*
"code"	Unavailable; tool_describe does not describe it	Only from run_code
"command"	Comma command only	Comma command only

deferred stays a separate flag: it controls when a definition is loaded, not where the tool is callable.

exposure="code" tools are never offered to the model directly: they are dropped outside code mode (including when run_code is not allowed), excluded from <deferred_tools> and tool_describe, and treated as unknown by the before_tool_call recovery fallback. User comma commands can still invoke them. An unknown exposure value raises ValueError.

⚠️ Breaking change

agent_use= and preserve= are removed from Tool, Tool.from_callable and @tool, and Tool.code_use is removed. Plugins must switch to exposure="command" / exposure="direct". bub-contrib (bub-acp-server, bub-qq) is updated in a follow-up PR once this merges, since it tracks bub main.

Impacted modules

• src/bub/tools.py: ToolExposure, Tool.exposure
• src/bub/builtin/agent.py, builtin/tools.py, builtin/hook_impl.py, builtin/spill.py, builtin/codemode/__init__.py
• Docs: build/tools.mdx, concepts/tape-and-context.mdx (en + zh-cn)

Verification

• uv run ruff check .
• uv run mypy src
• uv run pytest -q — 604 passed, 1 skipped
• New tests in tests/test_tool_loading.py cover code tools being hidden outside code mode, exposed to code in code mode, and not described by tool_describe.
• bub-contrib bub-acp-server and bub-qq tests pass against this branch with the follow-up edits (343 passed).

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	bub	aac27d6	Commit Preview URL Branch Preview URL	Oct 09 2026, 08:57 AM