feat(energy): compose the starter agent's toolbelt inline in the notebook

[ethancjackson]

What & why

The starter agent (99_starter_agent.ipynb) hid its capabilities behind boolean toggles (enable_search, enable_code_exec), which obscured the one thing worth teaching: an agent is a persona plus a list of tools you assemble. This PR makes that list the thing you edit, right in the notebook.

It also wires in the previously demo-only ForecastTool (AutoARIMA run_forecast) — the affordance that lets an agent call a statistical forecast directly, without writing forecasting code. Until now no starter/adaptive agent had it in its toolset; now arima_forecast() puts it one line away.

Scoped to implementations/energy_oil_forecasting only.

The new shape

Notebook §1 becomes a readable toolbelt — comment a line to drop a tool, uncomment to add:

from energy_oil_forecasting.starter_agent import tools, build_starter_agent_config

toolbelt = [
    tools.news_search(),      # cutoff-aware Google Search (proxy-only)
    tools.arima_forecast(),   # AutoARIMA anchor — call a forecast directly, no code-gen
    # tools.code_sandbox(),   # E2B Python sandbox (needs E2B_API_KEY) — uncomment to add
]
config = build_starter_agent_config(model=AGENT_MODEL, tools=toolbelt)

How it works

The three capabilities land in three different AgentConfig fields (search sub-agent, code sandbox, function tool). A small ToolSpec descriptor is the seam: each factory returns one, carrying the config fragment it fills, its playbook skill, any prompt supplement, and a token-budget floor. build_starter_agent_config folds a Sequence[ToolSpec] onto the config and routes each fragment — so the notebook never touches ADK plumbing.

• New starter_agent/tools.py — ToolSpec + news_search(), code_sandbox(), arima_forecast().
• Refactored build_starter_agent_config — booleans → tools=[...] fold.
• arima_forecast() takes data_service / series_id / frequency, so it generalizes past WTI (and constructs offline for tests).
• Notebook §4 "make it yours" now steers to editing the toolbelt and writing your own ToolSpec factory (was: a cold reference to analyst_agent.build_wti_tool_config).

Testing

• New test_starter_agent.py (6 tests): each factory routes to exactly one field, composition populates all fields, routing is order-independent.
• Full energy suite: 17 passed.
• make lint (full pre-commit CI mirror: ruff, ruff-format, mypy, nbqa): clean.
• Smoke-tested the config build and the lazy root_agent (adk web) path.

🤖 Generated with Claude Code