Add comprehensive SDK documentation

[patniko]

Summary

This PR adds comprehensive documentation for the Copilot SDK covering debugging, hooks, MCP servers, and SDK/CLI compatibility.

Changes

New Documentation Structure

docs/
├── compatibility.md          # SDK vs CLI feature comparison
├── debugging.md              # General SDK debugging guide
├── getting-started.md        # (existing)
├── hooks/
│   ├── overview.md           # Hooks introduction & quick start
│   ├── pre-tool-use.md       # Permission control hook
│   ├── post-tool-use.md      # Result transformation hook
│   ├── user-prompt-submitted.md  # Prompt modification hook
│   ├── session-lifecycle.md  # Session start/end hooks
│   └── error-handling.md     # Error handling hook
└── mcp/
    ├── overview.md           # MCP configuration (moved from docs/mcp.md)
    └── debugging.md          # MCP-specific debugging

Details

Debugging Guide (docs/debugging.md)

• Enable debug logging for all 4 SDKs
• Common issues and solutions
• Connection troubleshooting
• Platform-specific issues (Windows, macOS, Linux)

MCP Documentation (docs/mcp/)

• Reorganized existing MCP doc into mcp/overview.md
• Added detailed mcp/debugging.md for MCP-specific troubleshooting
• Windows .NET executable configuration examples
• Protocol testing instructions

Hooks Documentation (docs/hooks/)

• Complete coverage of all 6 hook types
• Code examples for Node.js, Python, Go, and .NET
• Common patterns (logging, blocking tools, redaction, rate limiting)
• Best practices for each hook type

Compatibility Guide (docs/compatibility.md)

• Documents which CLI features are available via SDK
• Lists CLI-only features (like --share, slash commands)
• Provides workarounds for common CLI-only features
• Explains protocol limitations

Testing

Documentation only - no code changes.

Related Issues

Addresses common questions about:

• MCP server configuration (especially Windows/.NET)
• Session export functionality
• Hook usage patterns

[Copilot]

Pull request overview

This PR introduces a substantial documentation expansion for the Copilot SDK, focusing on debugging, MCP server troubleshooting, session hooks, and a feature compatibility matrix between the SDKs and the Copilot CLI.

Changes:

• Adds a general SDK-wide debugging guide plus a dedicated MCP debugging guide, including platform-specific troubleshooting and protocol testing steps.
• Introduces comprehensive hook documentation (pre/post tool use, user prompt, session lifecycle, error handling) with multi-language examples (Node.js, Python, Go, .NET).
• Documents SDK vs CLI feature compatibility, including which interactive CLI features are not exposed via JSON-RPC and suggested SDK-level workarounds.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
docs/mcp/overview.md	Refactors the MCP overview to point to the new dedicated MCP debugging guide, and updates cross-links to the general getting-started/debugging docs.
docs/mcp/debugging.md	New MCP-specific debugging guide covering manual protocol tests, common failure modes, and platform-specific configuration tips, including .NET and NPX examples.
docs/hooks/overview.md	Provides a high-level overview of all available session hooks, with quick-start examples for each SDK and links to the individual hook guides.
docs/hooks/pre-tool-use.md	Documents the onPreToolUse hook’s input/output contract and shows patterns for permission gating, argument rewriting, path restriction, and output suppression across languages.
docs/hooks/post-tool-use.md	Documents onPostToolUse semantics and illustrates logging, redaction, truncation, summarization, and auditing patterns for tool results.
docs/hooks/user-prompt-submitted.md	Describes the user-prompt-submitted hook and demonstrates logging, prompt templating, shortcuts, content filtering, rate limiting, and preference injection, but currently mis-documents the hook output shape and uses unsupported fields.
docs/hooks/session-lifecycle.md	Explains session start/end hooks with examples for adding project/user context, cleaning up resources, tracking metrics, and saving state; includes one example with inconsistent in-memory state (startTime) and misaligned input/output field descriptions.
docs/hooks/error-handling.md	Introduces the error hook with examples for logging, monitoring, user-friendly messaging, suppression, pattern tracking, and alerting, but the documented input/output fields and example payloads don’t match the actual ErrorOccurredHook* types.
docs/debugging.md	Adds a general debugging guide (log levels, CLI path/auth issues, connection modes, tool issues, platform quirks, MCP debugging pointer) but some environment-variable and Python log-directory examples do not reflect the current SDK APIs.
docs/compatibility.md	New SDK/CLI feature compatibility matrix plus workarounds (permission handling, export, usage, compaction), though the token-usage and infinite-session examples are partially out of sync with the actual event and config types.

Comments suppressed due to low confidence (4)

docs/debugging.md:50

• Similarly to the Node section, this Python example implies that COPILOT_LOG_LEVEL controls SDK logging, but CopilotClient never reads that environment variable and instead uses the log_level option to compute the --log-level CLI flag. To avoid surprising behavior, this should either be removed or rewritten to demonstrate reading COPILOT_LOG_LEVEL in user code and threading it into CopilotClient(log_level=...).

Or via environment variable:
```bash
COPILOT_LOG_LEVEL=debug python your_app.py

**docs/debugging.md:68**
* The Go section also suggests that `COPILOT_LOG_LEVEL` can be used to control logging, but `ClientOptions` and `NewClient` in `go/client.go` never consult this environment variable and always pass the `LogLevel` option directly to `--log-level`. Like the Node/Python notes above, this should be clarified or removed so users don’t expect the env var alone to change the SDK’s log level.

Or via environment variable:

COPILOT_LOG_LEVEL=debug go run main.go

**docs/hooks/user-prompt-submitted.md:213**
* The examples that use `reject` / `rejectReason` in the hook output (e.g., this content filtering snippet) are inconsistent with the actual `UserPromptSubmittedHookOutput` types, which do not define these fields. To avoid compile-time errors in TypeScript and no-op behavior in other SDKs, these examples should be rewritten to use the supported fields (e.g., `modifiedPrompt`, `additionalContext`, or `suppressOutput`) or another documented mechanism for rejecting prompts.

const BLOCKED_PATTERNS = [
/password\s*[:=]/i,
/api[_-]?key\s*[:=]/i,
/secret\s*[:=]/i,
];

const session = await client.createSession({
hooks: {
onUserPromptSubmitted: async (input) => {
for (const pattern of BLOCKED_PATTERNS) {
if (pattern.test(input.prompt)) {
return {
reject: true,
rejectReason: "Please don't include sensitive credentials in your prompts. Use environment variables instead.",
};
}

**docs/hooks/error-handling.md:96**
* This example (and the similar one in the Python section) logs `input.errorType` and `input.stack`, but `ErrorOccurredHookInput` in all SDKs exposes `errorContext` and `recoverable` instead, and does not have `stack` or `errorType` properties. To avoid confusing users and causing type errors, please update the examples to use the actual fields (`errorContext`, `recoverable`) or adjust the type definitions and implementation if you intend to support the documented shape.

const session = await client.createSession({
hooks: {
onErrorOccurred: async (input, invocation) => {
console.error([${invocation.sessionId}] Error: ${input.error});
console.error( Type: ${input.errorType});
if (input.stack) {
console.error( Stack: ${input.stack});
}
return null;

</details>

[Copilot]

The COPILOT_LOG_LEVEL example suggests that setting this environment variable will control SDK logging, but none of the language clients read COPILOT_LOG_LEVEL—Node, Python, Go, and .NET all drive the CLI log level from the explicit logLevel/log_level option and --log-level CLI flag. As written, COPILOT_LOG_LEVEL=debug node your-app.js will not change the SDK client’s log level; consider either removing this snippet or showing how to read COPILOT_LOG_LEVEL in your app and pass it into the CopilotClient options.

This issue also appears in the following locations of the same file:

• line 47
• line 65

[Copilot]

The input/output schema described for ErrorOccurredHookInput/ErrorOccurredHookOutput doesn't match the implemented hook types: the SDKs expose errorContext and recoverable on the input (not errorType, stack, or context) and suppressOutput, errorHandling, retryCount, and userNotification on the output (not additionalContext, suppressError, or modifiedMessage). This table should be brought in line with the concrete types in nodejs/src/types.ts, python/copilot/types.py, go/types.go, and dotnet/src/Types.cs, and the property names in the examples below (e.g., input.errorType, input.stack) should be updated accordingly.

[Copilot]

The Node.js example for token usage tracking listens on "assistant.turn_end" and reads event.data.usage, but the generated session events only attach usage information on the separate "assistant.usage" event with fields like inputTokens/outputTokens. This snippet should instead subscribe to "assistant.usage" and read the documented usage fields from event.data so it matches the actual event model.

Suggested change

	session.on("assistant.turn_end", (event) => {
	console.log("Tokens used:", event.data.usage);
	session.on("assistant.usage", (event) => {
	console.log("Tokens used:", {
	input: event.data.inputTokens,
	output: event.data.outputTokens,
	});

[Copilot]

The documented UserPromptSubmittedHookOutput shape here doesn't match the actual SDK types: in all 4 SDKs the output only supports modifiedPrompt, additionalContext, and suppressOutput (see UserPromptSubmittedHookOutput in nodejs/src/types.ts, python/copilot/types.py, go/types.go, and dotnet/src/Types.cs). There are no reject or rejectReason fields, so returning them will either fail type-checking (TypeScript) or be ignored by the CLI; this table should drop reject/rejectReason and mention suppressOutput instead.

Suggested change

	| `reject` | boolean | If true, reject the prompt entirely |
	| `rejectReason` | string | Explanation shown when prompt is rejected |
	| `suppressOutput` | boolean | If true, do not send any assistant message back to the user |

[Copilot]

In this "Log Session Summary" example, sessionData is declared as { prompts: number; tools: number }, but onSessionEnd later reads data.startTime, which is never stored. Either the map type and onSessionStart handler should be extended to record a startTime (e.g., from input.timestamp), or the duration computation should be removed/rewritten so it only uses fields that are actually tracked.