docs(sdk): Add missing file-based agent features documentation

[VascoSch92]

Summary

This PR adds documentation for file-based agent features that are implemented in the software-agent-sdk but were not previously documented.

Changes

Updated Frontmatter Fields Table

Added the following fields to the documentation table:

• mcp_servers - MCP server configurations for external tools
• hooks - Lifecycle hook configurations
• permission_mode - Action confirmation control
• profile_store_dir - Custom LLM profile directory

New "Advanced Features" Section

Added a comprehensive new section with detailed examples for:

1. MCP Servers - Shows how to define inline MCP server configurations in agent markdown files, enabling agents to use external tools like mcp-server-fetch without any Python code.

2. Hooks - Documents how to configure lifecycle hooks directly in agent files, including:

   • All hook event types (pre_tool_use, post_tool_use, user_prompt_submit, session_start, session_end, stop)
   • Matcher patterns (wildcard, exact match, regex)
   • Links to the main Hooks guide for more details

3. Permission Mode - Explains the security feature for controlling action confirmations:

   • always_confirm - Requires approval for all actions
   • never_confirm - No approval needed
   • confirm_risky - Only confirm risky actions (with security analyzer)

Verification

These features were verified against the source code in software-agent-sdk:

• openhands-sdk/openhands/sdk/subagent/schema.py - AgentDefinition class
• openhands-sdk/openhands/sdk/hooks/config.py - HookConfig class
• Tests in tests/sdk/subagent/test_subagent_schema.py

Related

• Existing Hooks guide
• Existing MCP guide
• Existing Security guide

[all-hands-bot]

🟢 Good taste - Accurate documentation for real features.

Verification Summary:
Cloned OpenHands/software-agent-sdk and verified all documented features against source code:

✅ Field names - All four new fields (mcp_servers, hooks, permission_mode, profile_store_dir) exist in AgentDefinition schema
✅ Hook event types - All six event types match HOOK_EVENT_FIELDS in source
✅ Permission modes - All three modes (always_confirm, never_confirm, confirm_risky) match _VALID_PERMISSION_MODES
✅ Examples - YAML formats match test fixtures in test_subagent_schema.py
✅ Data types - Field types and descriptions match the schema

Why this is good:

• Solves a real problem: Features existed in code but were undocumented
• Simple and straightforward: Just fills documentation gaps
• Accurate: Every claim verified against actual implementation
• Well-structured: Examples are clear and follow existing patterns

Verdict: ✅ Worth merging - Fills legitimate documentation gaps with accurate information.

[all-hands-bot]

🟢 Good taste - Accurate documentation for real features.

Verification Summary:
Cloned OpenHands/software-agent-sdk and verified all documented features against source code:

✅ Field names - All four new fields (mcp_servers, hooks, permission_mode, profile_store_dir) exist in AgentDefinition schema
✅ Hook event types - All six event types match HOOK_EVENT_FIELDS in source
✅ Permission modes - All three modes (always_confirm, never_confirm, confirm_risky) match implementation
✅ MCP format - Configuration structure matches source examples
✅ Tests exist - All features have test coverage in tests/sdk/subagent/test_subagent_schema.py

Notable: The profile_store_dir table description ("when using a named model") is actually MORE accurate than the source code docstring - verified against usage in registry.py line 213-214 where it's only accessed when model != "inherit".

No hallucinations. No fantasy APIs. Documentation matches reality. Merge it.

[xingyaoww]

Thank you!