Close feature gaps vs official SDKs (#6)

## Summary

- Add 8 missing hook event constants, 13 new message types, and
supporting structs (`ToolProgressMessage`, `TaskMessage`)
- Add per-model usage breakdown (`ModelUsage`, `ModelUsages`) and
`WebSearchRequests` to `Usage`
- Add `RewindFiles`, query/introspection methods (`SupportedModels`,
`SupportedCommands`, `SupportedAgents`, `AccountInfo`), `StopTask`, and
runtime MCP management (`ReconnectMcpServer`, `ToggleMcpServer`,
`SetMcpServers`) to `Stream` and `Session`
- Add `NewTool[In, Out]` generic helper, `ToolServer`, and `WithTools`
convenience option for easy MCP tool definition
- Add `ListSessions` and `GetSessionMessages` top-level functions for
session history
- Add `ResumeSessionAt`, `PromptSuggestions`, and `ElicitationHandler`
options with elicitation handling in the control request loop
- Add `Transport` interface as a preparatory abstraction for future
alternative transports
- Fix `WithCWD` to set `PWD` env var matching Python SDK behaviour
(closes #5)
- Bump SDK version to 0.3.0

## Test plan

- [x] `go build ./...` compiles cleanly
- [x] `go vet ./...` passes with no issues
- [ ] Verify new `WithXxx` options follow existing patterns
- [ ] Verify new `Stream` methods follow `sendControlRequest` pattern
- [ ] Verify all new `Session` methods delegate to `Stream`
- [ ] Test `NewTool` compiles with MCP SDK's `mcp.AddTool` generic
signature

Closes #4, closes #5

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: VibeXP Bot <bot@vibexp.io>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.24"
+
+      - name: Check go fmt
+        run: |
+          output=$(gofmt -l .)
+          if [ -n "$output" ]; then
+            echo "Files not formatted:"
+            echo "$output"
+            exit 1
+          fi
+
+      - name: Run go vet
+        run: go vet ./...
+
+      - name: Check go mod tidy
+        run: |
+          go mod tidy
+          git diff --exit-code go.mod go.sum
+
+  test:
+    name: Test (Go ${{ matrix.go-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ["1.24"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Run tests
+        run: go test -v -race -count=1 ./...
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.24"
+
+      - name: Build
+        run: go build ./...

CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to Claude Agent SDK Go
+
+Thank you for your interest in contributing to Claude Agent SDK Go! We welcome contributions from everyone — whether you are a human developer or an AI agent.
+
+Regardless of the source, all contributions go through the same review process and must meet the same quality standards. We maintain strict coding standards, automated checks, and thorough reviews to keep the codebase clean, reliable, and maintainable.
+
+## Ways to Contribute
+
+- **Report bugs** — Open a GitHub issue describing the problem, steps to reproduce, and expected behavior.
+- **Request features** — Open a GitHub issue describing the feature, the motivation behind it, and any ideas for implementation.
+- **Propose ideas** — Start a discussion via a GitHub issue to gather community feedback before diving into code.
+- **Submit pull requests** — Fix bugs, implement features, improve documentation, or refactor code.
+
+## Issues Before Pull Requests
+
+**Every pull request must be linked to a GitHub issue.**
+
+Opening an issue first gives the community the opportunity to discuss the problem or feature, provide feedback on the approach, and ensure visibility into the work being planned. Pull requests created without a corresponding issue may be closed.
+
+1. Search existing issues to avoid duplicates.
+2. Open a new issue if none exists.
+3. Wait for acknowledgment or feedback before starting significant work.
+4. Reference the issue in your pull request (e.g., `Fixes #42` or `Closes #42`).
+
+## Development Setup
+
+### Prerequisites
+
+- Go 1.24+
+
+### Running Tests
+
+```bash
+go test ./...
+```
+
+### Running Linters
+
+```bash
+golangci-lint run ./...
+```
+
+## Pull Request Guidelines
+
+### Before Submitting
+
+- [ ] Your PR is linked to a GitHub issue.
+- [ ] All tests pass (`go test ./...`).
+- [ ] Go linting passes.
+- [ ] You have checked whether your changes require a documentation update — if so, include the documentation changes in the same PR.
+
+### Code Quality Standards
+
+- Write clean, readable code that follows existing patterns in the codebase.
+- Keep changes focused — one issue per pull request.
+- Add tests for new functionality and bug fixes.
+- Do not introduce security vulnerabilities (see OWASP top 10).
+- Avoid over-engineering — solve the problem at hand without unnecessary abstractions.
+
+### Documentation
+
+Check whether your changes require documentation updates. This includes:
+
+- Changes to API behavior
+- New features or configuration options
+- Changes to the development setup or build process
+- Architecture changes
+
+Include documentation updates in the same pull request as the code changes.
+
+### Commit Messages
+
+Write clear, descriptive commit messages. Use the imperative mood (e.g., "Add streaming support" not "Added streaming").
+
+## For AI Agent Contributors
+
+AI-generated contributions are welcome and go through the same process as human contributions:
+
+1. An issue must exist before a pull request is created.
+2. All automated checks (linting, tests) must pass.
+3. Code must meet the same quality and security standards.
+4. Pull requests are reviewed with the same rigor.
+
+## License
+
+By contributing to Claude Agent SDK Go, you agree that your contributions will be licensed under the [MIT License](LICENSE).

SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+We take security seriously and appreciate your help in keeping Claude Agent SDK Go safe for everyone.
+
+### GitHub Issues
+
+For most security concerns, please open a GitHub issue describing the vulnerability, its potential impact, and steps to reproduce if possible.
+
+### Private Disclosure for Critical Vulnerabilities
+
+If you discover a zero-day vulnerability or a critical issue that could be actively exploited, please report it privately by email:
+
+**hello@shaharialab.com**
+
+Use email when:
+
+- The vulnerability is a zero-day or has no known fix.
+- Public disclosure could put users at immediate risk.
+- The issue involves sensitive data exposure or remote code execution.
+- You believe the vulnerability is being actively exploited.
+
+In your email, please include:
+
+- A description of the vulnerability.
+- Steps to reproduce or a proof of concept.
+- The potential impact and affected components.
+- Any suggested fixes, if you have them.
+
+We will acknowledge your report within 48 hours and work with you to understand the scope and coordinate a fix before any public disclosure.
+
+## Supported Versions
+
+Security fixes are applied to the latest release. We recommend always running the most recent version of Claude Agent SDK Go.

claude/client.go

@@ -2,6 +2,7 @@ package claude
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"strings"
 	"sync"
@@ -77,10 +78,66 @@ func (s *Stream) SendUserMessage(msg string) error {
 	return s.write(userMsg(msg))
 }
 
-// sendControlRequest writes a control_request with the given subtype and extra
-// fields, then blocks until a matching control_response arrives or the ctx
-// is cancelled.
-func (s *Stream) sendControlRequest(subtype string, extras map[string]any) error {
+// RewindFiles asks the CLI to rewind files to the state at the given user message ID.
+func (s *Stream) RewindFiles(userMessageID string) error {
+	return s.sendControlRequest("rewind_files", map[string]any{
+		"user_message_id": userMessageID,
+	})
+}
+
+// ReconnectMcpServer asks the CLI to reconnect a named MCP server.
+func (s *Stream) ReconnectMcpServer(serverName string) error {
+	return s.sendControlRequest("reconnect_mcp_server", map[string]any{
+		"server_name": serverName,
+	})
+}
+
+// ToggleMcpServer asks the CLI to enable or disable a named MCP server.
+func (s *Stream) ToggleMcpServer(serverName string, enabled bool) error {
+	return s.sendControlRequest("toggle_mcp_server", map[string]any{
+		"server_name": serverName,
+		"enabled":     enabled,
+	})
+}
+
+// SetMcpServers asks the CLI to replace the current MCP server configuration.
+func (s *Stream) SetMcpServers(servers map[string]any) error {
+	return s.sendControlRequest("set_mcp_servers", map[string]any{
+		"mcp_servers": servers,
+	})
+}
+
+// SupportedModels queries the CLI for the list of supported models.
+// Returns the raw JSON response body.
+func (s *Stream) SupportedModels() (json.RawMessage, error) {
+	return s.sendControlRequestWithResponse("supported_models", nil)
+}
+
+// SupportedCommands queries the CLI for the list of supported commands.
+func (s *Stream) SupportedCommands() (json.RawMessage, error) {
+	return s.sendControlRequestWithResponse("supported_commands", nil)
+}
+
+// SupportedAgents queries the CLI for the list of supported agents.
+func (s *Stream) SupportedAgents() (json.RawMessage, error) {
+	return s.sendControlRequestWithResponse("supported_agents", nil)
+}
+
+// AccountInfo queries the CLI for the current account information.
+func (s *Stream) AccountInfo() (json.RawMessage, error) {
+	return s.sendControlRequestWithResponse("account_info", nil)
+}
+
+// StopTask asks the CLI to stop a running background task.
+func (s *Stream) StopTask(taskID string) error {
+	return s.sendControlRequest("stop_task", map[string]any{
+		"task_id": taskID,
+	})
+}
+
+// sendControlRequestWithResponse is like sendControlRequest but returns the raw
+// JSON response body on success.
+func (s *Stream) sendControlRequestWithResponse(subtype string, extras map[string]any) (json.RawMessage, error) {
 	reqID := newUUID()
 	respCh := make(chan controlResponse, 1)
 
@@ -102,23 +159,31 @@ func (s *Stream) sendControlRequest(subtype string, extras map[string]any) error
 		s.pendingMu.Lock()
 		delete(s.pending, reqID)
 		s.pendingMu.Unlock()
-		return fmt.Errorf("claude: %s: %w", subtype, err)
+		return nil, fmt.Errorf("claude: %s: %w", subtype, err)
 	}
 
 	select {
 	case resp := <-respCh:
 		if !resp.Success {
-			return fmt.Errorf("claude: %s: %s", subtype, resp.Error)
+			return nil, fmt.Errorf("claude: %s: %s", subtype, resp.Error)
 		}
-		return nil
+		return resp.Body, nil
 	case <-s.ctx.Done():
 		s.pendingMu.Lock()
 		delete(s.pending, reqID)
 		s.pendingMu.Unlock()
-		return s.ctx.Err()
+		return nil, s.ctx.Err()
 	}
 }
 
+// sendControlRequest writes a control_request with the given subtype and extra
+// fields, then blocks until a matching control_response arrives or the ctx
+// is cancelled.
+func (s *Stream) sendControlRequest(subtype string, extras map[string]any) error {
+	_, err := s.sendControlRequestWithResponse(subtype, extras)
+	return err
+}
+
 // Query runs the claude agent with the given prompt and returns a *Stream for
 // real-time event processing.
 //

claude/hooks.go

@@ -6,13 +6,13 @@ import "encoding/json"
 type HookEvent string
 
 const (
-	HookEventPreToolUse       HookEvent = "PreToolUse"
-	HookEventPostToolUse      HookEvent = "PostToolUse"
+	HookEventPreToolUse  HookEvent = "PreToolUse"
+	HookEventPostToolUse HookEvent = "PostToolUse"
 	// HookEventPostToolUseFailure fires after a tool call fails.
 	HookEventPostToolUseFailure HookEvent = "PostToolUseFailure"
-	HookEventNotification     HookEvent = "Notification"
-	HookEventStop             HookEvent = "Stop"
-	HookEventSubagentStop     HookEvent = "SubagentStop"
+	HookEventNotification       HookEvent = "Notification"
+	HookEventStop               HookEvent = "Stop"
+	HookEventSubagentStop       HookEvent = "SubagentStop"
 	// HookEventSubagentStart fires when a sub-agent is started.
 	HookEventSubagentStart    HookEvent = "SubagentStart"
 	HookEventPreCompact       HookEvent = "PreCompact"
@@ -25,6 +25,22 @@ const (
 	HookEventSetup            HookEvent = "Setup"
 	// HookEventPermissionRequest fires when Claude requests permission to use a tool.
 	HookEventPermissionRequest HookEvent = "PermissionRequest"
+	// HookEventSessionEnd fires when a session ends.
+	HookEventSessionEnd HookEvent = "SessionEnd"
+	// HookEventTeammateIdle fires when a teammate agent becomes idle.
+	HookEventTeammateIdle HookEvent = "TeammateIdle"
+	// HookEventTaskCompleted fires when a task completes.
+	HookEventTaskCompleted HookEvent = "TaskCompleted"
+	// HookEventElicitation fires when claude requests user elicitation.
+	HookEventElicitation HookEvent = "Elicitation"
+	// HookEventElicitationResult fires after an elicitation is resolved.
+	HookEventElicitationResult HookEvent = "ElicitationResult"
+	// HookEventConfigChange fires when configuration changes mid-session.
+	HookEventConfigChange HookEvent = "ConfigChange"
+	// HookEventWorktreeCreate fires when a git worktree is created.
+	HookEventWorktreeCreate HookEvent = "WorktreeCreate"
+	// HookEventWorktreeRemove fires when a git worktree is removed.
+	HookEventWorktreeRemove HookEvent = "WorktreeRemove"
 )
 
 // HookOutput is the return value of a HookFunc. All fields are optional.