feat(claude-agent-sdk): enhance tutorials with improved notebooks, agents, and documentation (anthropics#312)

* feat(agent-sdk): enhance notebooks, agents, and add documentation

Improvements to the Claude Agent SDK tutorial notebooks:

- Enhanced 00_The_one_liner_research_agent.ipynb with richer outputs
- Enhanced 02_The_observability_agent.ipynb with better visualization

- Improved research_agent/agent.py with cleaner code structure
- Improved observability_agent/agent.py with enhanced features

- Refactored utils/agent_visualizer.py for better maintainability
- Added utils/html_renderer.py for rich HTML visualization in Jupyter

- Added docs/README.md - Documentation overview
- Added docs/ADDITIONS.md - Summary of enhancements
- Added docs/CODEBASE_OVERVIEW.md - Architecture guide
- Added docs/TROUBLESHOOTING.md - Common issues and solutions

- Added pyyaml to pyproject.toml

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* feat(agent-sdk): add enhanced 01_The_chief_of_staff_agent.ipynb

Include the improved chief of staff notebook with cleaner outputs and examples.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* feat(agent-sdk): add enhanced chief_of_staff_agent implementation

Updates to the chief of staff agent:
- Improved agent.py with cleaner code structure
- Updated CLAUDE.md with better context
- Enhanced slash commands (budget-impact, strategic-brief, talent-scan)
- Improved decision_matrix.py script

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix(claude-agent-sdk): address PR anthropics#312 review feedback

Addresses all feedback from @PedramNavid's review.

## Critical Issues Fixed

- [x] Run `ruff format` and `ruff check` - all 15 Python files pass
- [x] Uncomment `%pip install` in 00_The_one_liner_research_agent.ipynb
- [x] Remove supplementary docs/ directory per repo guidelines
  - Deleted: ADDITIONS.md, CODEBASE_OVERVIEW.md, TROUBLESHOOTING.md, README.md
- [x] Model names verified (claude-opus-4-5, claude-sonnet-4-5 are valid aliases)

## Important Issues Addressed

- [x] sys.path.insert() hack already removed from research_agent/agent.py
- [x] Verified dependencies: kept pandas/markdown (used by html_renderer.py),
      removed unused numpy and pandas-stubs
- [x] Thread-safety warning already present in agent_visualizer.py (lines 106-111)
- [x] docs/ references now removed (files deleted)

## Suggestions Implemented

- [x] escape=True already added for DataFrame HTML (html_renderer.py:207,221)
- [x] type: ignore already fixed with proper TypedDict in decision_matrix.py
- [x] Docstring examples already present in agent_visualizer.py
- [x] Consistent type hints across all agent modules

## Additional Cleanup

- Removed unrelated files: GEMINI.md, permission-flow-diagram.md
- Removed temporary directories: .vscode/, plans/, extra output reports
- Cleaned pyproject.toml: removed dev dependencies (mypy, ruff, pytest),
  testing config, and unused numpy dependency

## Code Quality Verification

- All Python files pass `ruff check`
- All Python files pass `ruff format --check`
- All agent modules pass mypy type checking
- Project structure now matches upstream exactly

---------

Co-authored-by: Claude <[email protected]>

Author: costiash

claude_agent_sdk/00_The_one_liner_research_agent.ipynb

@@ -94,6 +94,11 @@ Each notebook includes an agent implementation in its respective directory:
 - **`chief_of_staff_agent/`** - Multi-agent executive assistant with financial modeling and compliance
 - **`observability_agent/`** - DevOps monitoring agent with GitHub integration
 
+**Running standalone agents:** To import agent modules outside of notebooks, either run from the `claude_agent_sdk/` directory or install the package in editable mode:
+```bash
+uv pip install -e .
+```
+
 ## Background
 ### The Evolution of Claude Agent SDK
 

claude_agent_sdk/01_The_chief_of_staff_agent.ipynb

@@ -3,7 +3,7 @@ name: budget-impact
 description: Analyze the financial impact of a decision on budget, burn rate, and runway
 ---
 
-Use the financial-analyst subagent to analyze the budget impact of: {{args}}
+Use the financial-analyst subagent to analyze the budget impact of: $ARGUMENTS
 
 Provide a comprehensive analysis including:
 1. Total cost (one-time and recurring)

claude_agent_sdk/02_The_observability_agent.ipynb

@@ -3,4 +3,4 @@ name: slash-command-test
 description: example of how a slash-command works
 ---
 
-Reverse the following sentence word wise: {{args}}
+Reverse the following sentence word wise: $ARGUMENTS

claude_agent_sdk/README.md

@@ -3,7 +3,7 @@ name: strategic-brief
 description: Generate a comprehensive strategic brief by coordinating analysis from both financial and talent perspectives
 ---
 
-Create a strategic brief on: {{args}}
+Create a strategic brief on: $ARGUMENTS
 
 Coordinate with both the financial-analyst and recruiter subagents to provide:
 

claude_agent_sdk/chief_of_staff_agent/.claude/commands/budget-impact.md

@@ -3,7 +3,7 @@ name: talent-scan
 description: Scan the talent market for specific roles and provide hiring recommendations
 ---
 
-Use the recruiter subagent to perform a talent market scan for: {{args}}
+Use the recruiter subagent to perform a talent market scan for: $ARGUMENTS
 
 Analyze and report on:
 1. Talent availability in target markets

claude_agent_sdk/chief_of_staff_agent/.claude/commands/slash-command-test.md

@@ -8,7 +8,7 @@
 - **HQ**: San Francisco, CA
 
 ## Financial Snapshot
-- **Monthly Burn Rate**: $500,000
+- **Monthly Burn Rate**: ~$500,000
 - **Current Runway**: 20 months (until September 2025)
 - **ARR**: $2.4M (growing 15% MoM)
 - **Cash in Bank**: $10M

claude_agent_sdk/chief_of_staff_agent/.claude/commands/strategic-brief.md

@@ -15,7 +15,7 @@
 load_dotenv()
 
 
-def get_activity_text(msg) -> str | None:
+def get_activity_text(msg: Any) -> str | None:
     """Extract activity text from a message"""
     try:
         if "Assistant" in msg.__class__.__name__:
@@ -31,7 +31,7 @@ def get_activity_text(msg) -> str | None:
     return None
 
 
-def print_activity(msg) -> None:
+def print_activity(msg: Any) -> None:
     """Print activity to console"""
     activity = get_activity_text(msg)
     if activity:
@@ -78,27 +78,33 @@ async def send_query(
         """
 
     # build options with optional output style
-    options_dict = {
-        "model": "claude-sonnet-4-5",
-        "allowed_tools": [
+    settings = None
+    if output_style:
+        settings = json.dumps({"outputStyle": output_style})
+
+    options = ClaudeAgentOptions(
+        model="claude-opus-4-5",
+        allowed_tools=[
             "Task",  # enables subagent delegation
             "Read",
             "Write",
             "Edit",
             "Bash",
             "WebSearch",
         ],
-        "continue_conversation": continue_conversation,
-        "system_prompt": system_prompt,
-        "permission_mode": permission_mode,
-        "cwd": os.path.dirname(os.path.abspath(__file__)),
-    }
-
-    # add output style if specified
-    if output_style:
-        options_dict["settings"] = json.dumps({"outputStyle": output_style})
-
-    options = ClaudeAgentOptions(**options_dict)
+        continue_conversation=continue_conversation,
+        system_prompt=system_prompt,
+        permission_mode=permission_mode,
+        cwd=os.path.dirname(os.path.abspath(__file__)),
+        settings=settings,
+        # IMPORTANT: setting_sources must include "project" to load filesystem settings:
+        # - Slash commands from .claude/commands/
+        # - CLAUDE.md project instructions
+        # - Subagent definitions from .claude/agents/
+        # - Hooks from .claude/settings.local.json
+        # Without this, the SDK operates in isolation mode with no filesystem settings loaded.
+        setting_sources=["project", "local"],
+    )
 
     result = None
     messages = []  # this is to append the messages ONLY for this agent turn