Git-aware tool / autonomous PR creation

[hellodk]

Summary

Add a Git-aware tool to the agent toolkit that enables autonomous pull request creation from within the VS Code extension. This tool should understand git context, handle branch management, and automate the complete PR workflow including commit message generation, branch protection, and CI/CD handling.

Problem Statement

Currently, Champ agents can edit files and commit changes, but they lack:

1. Context awareness of git branch state, upstream tracking, and merge conflicts
2. Autonomous PR creation via GitHub API with intelligent title/description generation
3. Git workflow orchestration (create branch, push, open PR, wait for checks) as a single coordinated action
4. Safety guardrails to prevent accidental force-pushes or PR overwrites

Acceptance Criteria

• New GitTool class in src/tools/ that implements the Tool interface
• Tool exposes create_pr() action to agents with required parameters: branch_name, pr_title, pr_body, base_branch (default 'main')
• Tool reads current git state (current branch, tracking branch, dirty status, remote URL) without shell commands—use git library or spawn git binary with safe argument passing only
• Tool detects and rejects operations if:
  • Working directory has uncommitted changes (user must stage/commit first)
  • Remote is not configured (user must set up GitHub remote)
  • Current branch is already tracking a remote with open PR (prevent duplicate PR attempts)
• Tool generates intelligent PR title from the top commit message (first 72 chars) if not provided
• Tool generates PR body from commit log (git log base_branch..HEAD) with formatted changelog
• Calls GitHub API via octokit (or equivalent) using GITHUB_TOKEN from env or VS Code SecretStorage
• Tool returns PR URL and metadata (PR number, state, checks URL) so agents can report back to user
• Full test suite with mocked GitHub API, git operations, and error cases:
  • test_git_tool_rejects_dirty_working_dir — verify it fails if git status shows uncommitted changes
  • test_git_tool_detects_missing_remote — verify it fails gracefully if no origin is configured
  • test_git_tool_generates_pr_title_from_commit — verify title extraction from first commit
  • test_git_tool_generates_pr_body_from_log — verify changelog from git log range
  • test_git_tool_creates_pr_via_github_api — verify API call shape and response handling
  • test_git_tool_handles_auth_failure — verify error message if GITHUB_TOKEN is missing/invalid
  • test_git_tool_handles_conflict — verify graceful error if base_branch..HEAD has merge conflicts
• Integration test: agent orchestration flow that chains File edits → Commit → GitTool.create_pr() and verifies the complete workflow
• Tool supports optional parameters:
  • draft=true — create as draft PR (useful for review-before-merge workflows)
  • auto_merge_method — set squash/rebase/merge strategy and auto-merge flag
  • reviewers — auto-request reviewers (list of GitHub usernames)
  • labels — auto-add labels (e.g., 'feature', 'bugfix') to the PR
• Safety: tool refuses to push to main or master directly (must create a branch first)
• Documentation in docs/TOOLS_REFERENCE.md with examples:
  • Example 1: Agent creating a feature branch, editing, and opening a PR in one shot
  • Example 2: Agent respecting existing PRs (detect and report instead of overwriting)
  • Example 3: Handling authentication failures and retry logic

Implementation Notes

• The tool should be usable in all 5 modes (Agent, Ask, Manual, Plan, Composer)
• In Manual mode, require approval before pushing/creating PR
• In Composer mode, integrate with the existing Plan→Diff→Apply workflow so PR creation is a post-apply step
• Reuse workspace path protection utilities already in place (resolveInWorkspace, etc.)
• Do NOT shell out to git unnecessarily—use a git library (e.g., isomorphic-git, simple-git) if available, or carefully escape shell arguments
• Agent system prompt must be updated to teach agents when/how to use this tool appropriately

Related Issues

• Multi-root workspace: config only reads from first folder; active-editor folder ignored #58 (multi-root workspace config resolution) — ensure GitTool respects per-workspace git state
• MCP integration roadmap — consider exposing GitTool as an MCP server capability in future

Tests Required

See acceptance criteria section above. Full test file: test/unit/tools/git.test.ts