feat: create-branch safe output

[jamesadevine]

Summary

Add a create-branch safe output that allows agents to create new branches in Azure DevOps repositories without immediately creating a pull request.

ADO API

POST /_apis/git/repositories/{repo}/refs?api-version=7.1

Request body:

[{
  "name": "refs/heads/feature/my-branch",
  "oldObjectId": "0000000000000000000000000000000000000000",
  "newObjectId": "{sourceCommitSha}"
}]

Agent Parameters

• name (required) — Branch name (e.g., feature/my-analysis)
• source-branch (optional) — Branch to create from (default: main)
• source-commit (optional) — Specific commit SHA (overrides source-branch)
• repository (optional) — Repository alias (default: self)

Front Matter Configuration (safe-outputs.create-branch)

• branch-pattern — Regex pattern branch names must match (e.g., ^agent/.*$)
• allowed-repositories — Restrict which repos can have branches created
• allowed-source-branches — Restrict which branches can be used as source

Use Cases

• Feature branch preparation before manual PR creation
• Release branch creation agents
• Experiment branch management
• Multi-step workflows where branch is created first, then populated in subsequent runs

Notes

Branch creation is partially covered by create-pull-request (which auto-creates a branch). This tool is useful when the agent wants to create a branch without immediately creating a PR.

Security Considerations

• Branch name regex validation prevents injection
• Repository allow-list
• Source branch validation (can't branch from arbitrary refs)
• Create-only semantics (can't overwrite existing branches)

Priority

Tier 3 — Niche, partially overlaps with create-pull-request. Low complexity.