docs(extensions): correct excludeTools examples that never match - #28963

Summary

docs/extensions/best-practices.md told extension authors to write

{ "excludeTools": ["run_shell_command(rm -rf *)"] }

and stated that this "ensures the CLI blocks dangerous commands". It does not.
Extension excludeTools entries are compared against whole tool names, so an
entry containing (...) matches nothing and is silently dropped — the tool stays
available to the model with no warning.

This corrects the two extension doc pages and the shipped example manifest to
show a form that actually takes effect.

Details

Config.getExcludeTools() folds extension.excludeTools into a Set
(packages/core/src/config/config.ts:2431-2439), and ToolRegistry.isActiveTool
tests membership directly (packages/core/src/tools/tool-registry.ts:637):

return !possibleNames.some((name) => excludeTools?.has(name));

possibleNames holds the tool's real names — run_shell_command, its class
name, and MCP-qualified variants — none of which equal
"run_shell_command(rm -rf *)".

The parenthesised toolName(args) shape is real syntax, but it belongs to
tools.core / tools.allowed, which are parsed by mapToolsToRules
(packages/core/src/policy/config.ts:445-476). Extension excludeTools never
goes through that path.

For the "block one specific command" case the page was describing, that
capability now lives in the policy engine: the settings-level tools.exclude was
deprecated in its favour (#18508, documented at docs/tools/shell.md:158 and
docs/cli/enterprise.md:267), and extensions can ship rules in a policies/
directory. The TOML snippet added here mirrors the shipped example extension in
packages/cli/src/commands/extensions/examples/policies/.

Note on decision: that example extension uses ask_user for rm -rf, but the
original prose promised the CLI "blocks" the command, so deny preserves the
stated intent. Happy to switch it to ask_user if you'd rather the two examples
match exactly.

Related Issues

Related to #28962

How to Validate

The exclusion behaviour, using the real Config and ToolRegistry:

const config = new Config(params);
vi.spyOn(config, 'getExcludeTools').mockReturnValue(new Set(entry));
const registry = await config.createToolRegistry();
registry.getAllTools().some((t) => t.name === 'run_shell_command');

The policy snippet added to best-practices.md, loaded through the real
extension policy loader and evaluated by PolicyEngine:

loadExtensionPolicies('my-safe-extension', '<ext>/policies')
  -> 0 errors, 1 rule
run_shell_command {"command":"rm -rf /tmp/victim"}  ->  deny
run_shell_command {"command":"ls -la"}              ->  allow

Docs checks:

npx prettier --check docs/extensions/best-practices.md docs/extensions/reference.md \
  packages/cli/src/commands/extensions/examples/exclude-tools/gemini-extension.json
npm run lint

Pre-Merge Checklist

• Updated relevant documentation and README (if needed) — this PR is the
  documentation change
• Added/updated tests (if needed) — n/a, no source behaviour changes
• Noted breaking changes (if any) — none; docs and one example manifest only
• Validated on required platforms/methods:
  • MacOS
    • npm run