Expose spawned agent identity to lifecycle hooks

[catkins]

Description

This is the alternate existing-hook approach to #4016. Instead of adding a per-agent post-registration hook, this threads the registered spawned agent identity into the existing once-per-process lifecycle hooks.

The agent-startup hook already runs after all spawned workers have registered. This PR exposes the complete registered worker set to both agent-startup and agent-shutdown, so hook consumers can set up and tear down per-agent resources without making extra API calls.

Context

• Alternate approach to Support post-registration hook and inject agent env into lifecycle hooks #4016

Changes

• Adds narrow AgentWorker accessors for the registered agent ID and name.
• Passes the registered worker list into agent-startup and agent-shutdown.
• Injects BUILDKITE_AGENT_IDS and BUILDKITE_AGENT_NAMES into both hooks as comma-separated lists in spawn order.
• Adds focused coverage for empty, single-agent, multi-agent, startup-hook, and shutdown-hook env behavior.
• Updates docs/agent-start.md to document the lifecycle hook env values.

Testing

• Tests have run locally (with go test ./...). Buildkite employees may check this if the pipeline has run automatically.
• Code is formatted (with go tool gofumpt -extra -w .)

Local commands run:

• mise exec -- go tool gofumpt -extra -w agent/agent_worker.go clicommand/agent_start.go clicommand/agent_start_test.go
• mise exec -- go tool gofumpt -extra -w clicommand/agent_start.go clicommand/agent_start_test.go
• mise exec -- go test ./clicommand -run 'TestAgentStartupHook|TestAgentStartupHookEnv|TestAgentShutdownHook'
• mise exec -- go test ./agent -run 'Test'
• mise exec -- go test ./clicommand ./agent
• mise exec -- go vet ./clicommand ./agent
• mise exec -- golangci-lint run

Buildkite verification:

• Latest parent build passed: https://buildkite.com/buildkite/agent/builds/12942
• Latest E2E child build passed: https://buildkite.com/buildkite/agent-e2e-tests/builds/1394
• GitHub checks are green for 9bc5b7ae.

Local Buildkite smoke against https://agent.buildkite.localhost/v3:

• Started local Rails app with mise exec -- bin/rails server -p 3000 in ../buildkite.
• Verified https://buildkite.localhost returned 302 to /login and https://agent.buildkite.localhost/v3 routed through Rails.
• Ran this branch with:
  mise exec -- go run . start --endpoint https://agent.buildkite.localhost/v3 --token bkct_test --tags queue=default --hooks-path /tmp/buildkite-agent-startup-hook-smoke --build-path /tmp/buildkite-agent-startup-builds --spawn 2 --name codex-startup-smoke-%spawn --disconnect-after-idle-timeout 3 --no-feature-reporting --no-command-eval --debug
• Observed two successful POST /v3/register responses and agent-startup output:
  • startup ids=019ef27f-b86e-4686-921f-95ce8ec56025,019ef27f-b86e-48e3-ad77-5203e58b706e
  • startup names=codex-startup-smoke-1,codex-startup-smoke-2
• Observed both agents disconnect after idle timeout with successful POST /v3/disconnect responses.

Full mise exec -- go test ./... was also attempted earlier, but it fails outside this change in internal/job TestVerifyCommit/fails_when_commit_is_not_on_branch; rerunning mise exec -- go test ./internal/job -run TestVerifyCommit -count=1 reproduced the same failure with git reporting origin/feature-b as not a valid object. The transient internal/shell TestContextCancelInterrupts failure from the full run passed on direct rerun.

Affiliation (optional, external contributors)

Buildkite employee.

Disclosures / Credits

Implemented with Codex assistance.

[DrJosh9000]

Since all the values of script passed to this function are constants, I think they would be better of as fixtures.