feat: Workspace toolkit + GitHubContextProvider (HITL, edit-via-PR)

[ashpreetbedi]

Summary

This PR ships two related primitives that release together as 2.6.2:

1. Workspace — a polished local-machine toolkit at libs/agno/agno/tools/workspace.py that gives agents read/list/search/write/edit/move/delete/shell access to a root directory tree, with destructive operations gated by Agno's built-in human-in-the-loop confirmation by default.
2. GitHubContextProvider — a context provider at libs/agno/agno/context/github/ that gives agents navigation + edit-via-PR access to a Git repository hosted on GitHub. Two-tool surface (query_<id> / update_<id>) with read/write sub-agents bound to different toolsets, mirroring DatabaseContextProvider.

They ship together because the update_<id> path of GitHubContextProvider builds on Workspace for file ops inside per-task worktrees.

---

1. Workspace toolkit

This closes the polish gap with the Claude Agent SDK tab on the homepage. The new homepage snippet for the Agno SDK tab now reads:

tools=[Workspace(
    ".",
    allowed=["read", "list", "search"],
    confirm=["write", "edit", "delete", "shell"],
)]

Mutually exclusive allowed= / confirm= partitions of short aliases — auto-pass vs. approval-required. Aliases translate internally to descriptive method names (read_file, write_file, …) so the LLM tool spec stays self-explanatory.

What's in it

• 8 method pairs (sync + async): read_file, list_files, search_content, write_file, edit_file, move_file, delete_file, run_command.
• Line-numbered read_file output (cat -n style) — chunk reads preserve actual file line numbers so the agent can chain into edit_file precisely.
• edit_file with replace_all=False — unique-or-fail by default; flip for renames.
• Rich list_files entries ({path, type, size}) with optional recursive=True, max_depth=3 for tree-style exploration.
• Atomic write_file (writes .tmp then os.replace).
• run_command strips ANSI before tailing output (saves tokens on npm/pip/etc.).
• Path-scoping enforcement via inherited Toolkit._check_path. Explicitly NOT a process sandbox — the docstring spells this out and points at Daytona for untrusted code.
• Opt-in require_read_before_write=True blocks writes/edits/moves/deletes on existing files until the agent has read them this session. Catches the "agent hallucinated the file's contents" bug class.

Permission model

• A name in allowed runs silently.
• A name in confirm requires user approval (Agno's requires_confirmation_tools HITL — surfaces as approval cards in the AgentOS UI; pause/resume in code).
• A name in neither isn't registered — the LLM doesn't see it.
• A name in both raises ValueError.
• Default (both None) = reads in allowed, writes in confirm.
• Type guard: confirm=True or allowed="read" raise a clear TypeError instead of confusing alias errors.

Cookbook + docs reorg

• cookbook/91_tools/workspace_tools/ — basic_usage.py, with_confirmation.py, README, TEST_LOG.
• cookbook/99_docs/home/ → cookbook/99_docs/index/ (homepage SDK tabs preserved with git mv); if __name__ block dropped — the runnable path is now fastapi dev <file>.py.
• cookbook/99_docs/first-agent/workbench.py — runnable copy of the new "Build Your First Agent" snippet (18 lines, Workspace(".") with default safe partition + enable_agentic_memory=True).

---

2. GitHubContextProvider

Read + write access to a GitHub repository cloned into a local working directory (typically a Docker volume). Mirrors DatabaseContextProvider's read/write split:

• query_<id>(question) — natural-language reads against the checkout. Backed by a sub-agent with read-only Workspace + GitReadTools (log/diff/show/blame/branches).
• update_<id>(instruction) — natural-language writes that end in a pull request. Backed by a sub-agent with full Workspace + GitWriteTools (status/add/commit/push/gh pr create/gh pr view), scoped to a per-session worktree.

What's in it

• libs/agno/agno/context/github/provider.py — GitHubContextProvider with asetup() (clone or fetch+pull, idempotent), aclose() (best-effort worktree cleanup), status() (<repo>@<branch>:<sha>), and the read/write sub-agent split.
• libs/agno/agno/context/github/tools.py — GitReadTools (5 read ops) and GitWriteTools (6 write/PR ops).
• libs/agno/agno/context/github/__init__.py — exports the provider, the toolkits, and the default instructions.
• libs/agno/tests/unit/context/test_github_provider.py — 32 tests, no network. Uses a local bare git repo as the fake remote and stubs gh via a shell script.
• cookbook/12_context/12_github.py — read demo against agno-agi/agno (always runs); write demo opens a PR if GITHUB_WRITE_REPO is set.

Key behaviors

• Worktree-per-task (Coda's pattern): each session gets its own <workdir>/worktrees/<task>/ worktree on a <prefix>/<task> branch. Parallel update_<id> calls in different sessions don't collide. Cached by run_context.session_id; ephemeral teardown when no session_id is propagated.
• Branch-prefix safety: every git push and gh pr create validates the active branch matches <pr_branch_prefix>/*. Default prefix is agno. The agent cannot push to the default branch — that's the tripwire that keeps this safe to expose.
• PAT auth: github_token kwarg or GITHUB_TOKEN env. Embedded into the clone URL so subsequent pushes inherit auth without further setup. gh calls receive the token via GH_TOKEN / GITHUB_TOKEN in the subprocess env.
• gh CLI dependency: create_pull_request and pr_status shell out to gh. Missing gh is a clear runtime error, not a silent constructor failure.
• mode=tools returns the read-only flat surface only (Workspace(allowed=READ_TOOLS) + GitReadTools). Writes need the per-session worktree, so they require mode=default (two-tool surface).

Out of scope (deferred)

• Multi-repo per provider instance. One provider = one repo.
• GitHub App / OAuth auth. PAT only.
• Direct push to default branch (refused by branch-prefix safety).
• Forking workflow. Assumes push access to the source repo.
• Mid-task conflict resolution.
• Updating Scout's contexts.py — caller-side, separate.
• Updating docs/ — separate doc PR for 2.6.2.

---

Type of change

• New feature
• Improvement (homepage + first-agent guide DX)
• Bug fix
• Breaking change
• Model update
• Other

FileTools, ShellTools, and LocalFileSystemTools are untouched — no deprecation, no breaking change for existing users.

---

Checklist

• Code complies with style guidelines
• Ran format/validation scripts (./scripts/format.sh and ./scripts/validate.sh)
• Self-review completed
• Documentation updated (comments, docstrings)
• Examples and guides: cookbook examples included for both Workspace and GitHubContextProvider; homepage + first-agent docs snippets updated (docs repo PR is separate)
• Tested in clean environment (cookbook smoke runs against gpt-5.4 end-to-end)
• Tests added/updated (61 new workspace tests + 32 new GitHub provider tests; existing FileTools / context tests still green)

Duplicate and AI-Generated PR Check

• I have searched existing open pull requests and confirmed that no other PR already addresses this issue
• If a similar PR exists, I have explained below why this PR is a better approach
• Check if this PR was entirely AI-generated (by Copilot, Claude Code, Cursor, etc.)

---

Additional Notes

Verified end-to-end:

• All workspace + context unit tests green (164 total: 61 workspace, 32 github, 71 context regression).
• ./scripts/format.sh and ./scripts/validate.sh clean for new files (pre-existing mypy errors in unrelated slack.py / drive.py / sql.py are out of scope).
• cookbook/91_tools/workspace_tools/basic_usage.py ran end-to-end against gpt-5.4 — agent called read_file → write_file → list_files.
• cookbook/91_tools/workspace_tools/with_confirmation.py ran end-to-end — read_file ran silent, edit_file paused, requirement.confirm() resumed cleanly, edit applied.

Out of scope (Workspace, captured in .context/workspace_tools_design.md for future sprints):

• multi_edit — atomic batched edits to one file (Claude Code parity).
• Background processes — run_command(background=True) + command_output(handle) + kill_command(handle).
• Dynamic confirm predicate (callable instead of static list) — touches Agno's Function layer.
• additional_roots=[...] — extend root scope to multiple dirs.
• LSP integration (Mastra has it; heavyweight).
• Lifecycle hooks (PreToolUse / PostToolUse / Stop / SessionStart / SessionEnd).

Docs repo: the matching changes to index.mdx (Agno SDK tab) and first-agent.mdx (Build Your First Agent guide) live in the docs repo and will be committed there separately.