docs(sdk): Update built-in subagents documentation to match current implementation (#442)

* docs: update built-in subagents to match current implementation

- Update agent names from deprecated to current:
  - default → general-purpose
  - explore → code-explorer
  - bash → bash-runner
- Add missing web-researcher agent documentation
- Remove non-existent 'default cli mode' agent
- Fix tools list for general-purpose (no browser_tool_set)
- Update register_builtins_agents() parameter from cli_mode to enable_browser
- Add deprecation notice for legacy agent names

Co-authored-by: openhands <openhands@all-hands.dev>

* Apply suggestion from @VascoSch92

* Update sdk/guides/agent-file-based.mdx

Co-authored-by: OpenHands Bot <contact@all-hands.dev>

* docs: add missing 'default cli mode' to deprecation notice

Address PR review feedback: include 'default cli mode' in the deprecation
notice since it's a valid deprecated name that maps to 'general-purpose'.

Also added the deprecation version (v1.12.0) for clarity.

Co-authored-by: openhands <openhands@all-hands.dev>

---------

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: OpenHands Bot <contact@all-hands.dev>

Author: 3 people

sdk/guides/agent-file-based.mdx

@@ -116,12 +116,20 @@ By default, all agents include `finish` tool and the `think` tool.
 
 | Agent | Tools | Description |
 |--------|-------|-------|
-| **default** | `terminal`, `file_editor`, `task_tracker`, `browser_tool_set` | General-purpose agent. Used as the fallback when no agent name is specified. |
-| **default cli mode** | `terminal`, `file_editor`, `task_tracker` | Same as `default` but without browser tools (used in CLI mode). |
-| **explore** | `terminal` | Read-only codebase exploration agent. Finds files, searches code, reads source — never creates or modifies anything. |
-| **bash** | `terminal` | Command execution specialist. Runs shell commands, builds, tests, and git operations. |
+| **general-purpose** | `terminal`, `file_editor`, `task_tracker` | General-purpose agent for tasks requiring a combination of capabilities. Used as the fallback when no agent name is specified. |
+| **code-explorer** | `terminal` | Read-only codebase exploration agent. Finds files, searches code, reads source — never creates or modifies anything. |
+| **bash-runner** | `terminal` | Command execution specialist. Runs shell commands, builds, tests, linters, and git operations. Returns concise reports instead of raw output. |
+| **web-researcher** | `browser_tool_set` + MCP (`fetch`, `tavily`) | Web research specialist. Searches the web, navigates documentation, and extracts information from URLs. |
 
-In CLI mode, the `default` agent (with browser tools) is replaced by the `default cli mode` agent. In non-CLI mode, `default cli mode` is filtered out.
+When `enable_browser=False`, browser-dependent agents like `web-researcher` are not registered.
+
+<Note>
+**Deprecated names:** The following legacy names are deprecated (since v1.12.0) and will be removed in version 2.0.0:
+- `default` → use `general-purpose`
+- `default cli mode` → use `general-purpose`
+- `explore` → use `code-explorer`
+- `bash` → use `bash-runner`
+</Note>
 
 ### Registering Built-in Sub-Agents
 
@@ -130,11 +138,11 @@ Call `register_builtins_agents()` to register all built-in sub-agents. This is t
 ```python icon="python" focus={3-4, 6-7}
 from openhands.tools.preset.default import register_builtins_agents
 
-# Register built-in sub-agents (default, explore, bash)
+# Register all built-in sub-agents (including web-researcher)
 register_builtins_agents()
 
-# Or in CLI mode (swaps default for default cli mode — no browser)
-register_builtins_agents(cli_mode=True)
+# Or without browser-dependent agents (excludes web-researcher)
+register_builtins_agents(enable_browser=False)
 ```
 
 <Warning>