docs: clarify shell tool mode availability

[cyq1017]

Problem

• exec_shell 模式可用性不一致 #2328 reports that shell tools appear available in YOLO but not Agent mode, and the docs did not show the mode/config boundary in one place.

Change

• Add a compact mode/tool availability matrix to docs/MODES.md.
• Note in docs/TOOL_SURFACE.md that shell tools are catalog-visible only when shell access is enabled, with YOLO enabling shell automatically.

Verification

• git diff --check

Refs #2328

Greptile Summary

This documentation-only PR adds a compact mode/tool-availability matrix to docs/MODES.md and a shell-access preamble to docs/TOOL_SURFACE.md, directly addressing the confusion reported in #2328 about shell tools being visible in YOLO but not Agent mode.

• docs/MODES.md: A new "Tool availability by mode" table maps five tool families across Plan / Agent / YOLO, followed by an explanatory paragraph that ties the allow_shell config key to catalog visibility and contrasts it with YOLO's automatic enablement.
• docs/TOOL_SURFACE.md: A four-line note is inserted above the Shell section explaining when shell tools appear in the model-visible catalog, referencing allow_shell = true, YOLO's automatic activation, and Plan mode's exclusion.

Confidence Score: 5/5

Documentation-only change with no runtime code modified; safe to merge.

Both changed files are pure documentation. The matrix and prose accurately reflect the existing runtime behaviour described in the surrounding text. One minor omission (missing approval-gate label in the Shell/Agent cell) is called out but does not introduce incorrect information — the correct description remains visible immediately above the table.

No files require special attention; both changes are documentation additions.

Important Files Changed

Filename	Overview
docs/MODES.md	Added a "Tool availability by mode" matrix table and explanatory paragraph; the Shell tools row omits the per-call approval gate that the surrounding prose still describes for Agent mode.
docs/TOOL_SURFACE.md	Added a shell-availability preamble before the Shell tool table; accurately describes the allow_shell / YOLO / Plan mode conditions with no factual issues.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User requests shell tool] --> B{Active TUI mode?}
    B -->|Plan| C[Shell access OFF\nTool not in catalog]
    B -->|Agent| D{allow_shell = true?}
    B -->|YOLO| G[Shell access ON\nTrust mode ON\nAuto-approved]
    D -->|No| E[Shell tools absent\nfrom model catalog]
    D -->|Yes, via config/profile\nor runtime session| F[Shell tools in catalog\nApproval prompt per call]

Loading

_{Reviews (2): Last reviewed commit: "docs: polish mode availability table" | Re-trigger Greptile}

[gemini-code-assist]

Code Review

This pull request updates the documentation in docs/MODES.md and docs/TOOL_SURFACE.md to detail tool availability across different execution modes (Plan, Agent, and YOLO). The feedback suggests centering the status columns in the markdown table to improve readability and making minor grammatical and terminology adjustments in the shell tools description for consistency.

[gemini-code-assist]

Right-aligning text columns (like "yes", "no", "approval-gated") in Markdown tables can make the text look jagged and harder to read. Centering these short status values improves the visual layout and readability of the table.

Suggested change

	|---|---:|---:|---:|
	|---|:---:|:---:|:---:|

[gemini-code-assist]

Adding a comma after "In Agent mode" improves readability, and using "YOLO mode" instead of just "YOLO" keeps the terminology consistent with "Agent mode" and "Plan mode" used in the same sentence.

[Hmbown]

Thanks @cyq1017. I harvested this docs slice into #2504 for v0.8.50 triage as fda2141b7 and 9e9326990, with a small local follow-up cbd6239f3 to make the Agent-mode shell row explicit that calls remain approval-gated after allow_shell = true.

This is useful clarification for the shell-tool mode boundary in #2328. Local verification on the harvest branch:

• cargo test -p codewhale-tui --all-features --locked allowed_tools -- --nocapture
• cargo fmt --all -- --check
• git diff --check
• ./scripts/release/check-versions.sh