feat: add Chat History API documentation and recommended usage for Claude SDK (#165)

Co-authored-by: Johan Broberg <johanb@microsoft.com>

Author: pontemonti

packages/agents-a365-tooling-extensions-claude/docs/design.md

@@ -201,3 +201,80 @@ private readonly orchestratorName: string = "Claude";
 // Results in User-Agent header:
 // "Agent365SDK/1.0.0 (Windows_NT; Node.js v18.0.0; Claude)"
 ```
+
+## Chat History API
+
+> **Last Assessed:** January 2026  
+> **Claude SDK Version:** ^0.1.30 (workspace), `unstable_v2` APIs added in v0.1.54  
+> **Tracking Issue:** [#164 - Claude SDK: Monitor for chat history API availability](https://github.com/microsoft/Agent365-nodejs/issues/164)
+
+### Current State
+
+Unlike the OpenAI extension which provides `sendChatHistoryAsync` via `OpenAIConversationsSession.getItems()`, the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) **does not expose programmatic access to conversation history**.
+
+The SDK includes experimental `unstable_v2_*` session APIs (added in v0.1.54):
+- `unstable_v2_createSession` - Creates a new session for multi-turn conversations
+- `unstable_v2_resumeSession` - Resumes an existing session by ID
+- `unstable_v2_prompt` - One-shot convenience function for single-turn queries
+
+However, these APIs only provide:
+- `session.send(message)` - Send a message to Claude
+- `session.stream()` - Stream back response messages
+- `session.close()` - Close the session
+
+**There is no `session.getHistory()` or equivalent method** to retrieve past messages from a session. Sessions maintain context internally for Claude to reference, but this history is opaque to SDK consumers.
+
+### Recommended Approach
+
+Developers should use the generic `sendChatHistory` method from `@microsoft/agents-a365-tooling` by manually constructing `ChatHistoryMessage[]`:
+
+```typescript
+import { McpToolServerConfigurationService, ChatHistoryMessage } from '@microsoft/agents-a365-tooling';
+import { TurnContext } from '@microsoft/agents-hosting';
+
+// Build chat history from your conversation tracking
+const chatHistory: ChatHistoryMessage[] = [
+  {
+    id: 'msg-001',
+    role: 'user',
+    content: 'Can you help me find my recent emails?',
+    timestamp: new Date('2026-01-27T10:00:00Z')
+  },
+  {
+    id: 'msg-002',
+    role: 'assistant',
+    content: 'I\'d be happy to help you find your recent emails. Let me search for them now.',
+    timestamp: new Date('2026-01-27T10:00:05Z')
+  },
+  {
+    id: 'msg-003',
+    role: 'user',
+    content: 'Great, show me emails from the last week.',
+    timestamp: new Date('2026-01-27T10:00:30Z')
+  }
+];
+
+// Send to MCP platform for real-time threat protection
+const configService = new McpToolServerConfigurationService();
+const result = await configService.sendChatHistory(turnContext, chatHistory);
+
+if (!result.success) {
+  console.error('Failed to send chat history:', result.error);
+}
+```
+
+### Revisit Criteria
+
+This limitation should be re-evaluated when any of the following occur:
+
+1. **Claude SDK adds history retrieval API** - Monitor for `session.getHistory()`, `session.getMessages()`, or similar methods
+2. **`unstable_v2` APIs stabilize** - When APIs lose the `unstable_` prefix, review for new capabilities
+3. **SDK version upgrade** - When upgrading `@anthropic-ai/claude-agent-sdk`, check changelog for history-related features
+4. **Anthropic documentation updates** - Monitor [TypeScript V2 Preview docs](https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview) and [GitHub repo](https://github.com/anthropics/claude-agent-sdk-typescript)
+
+### References
+
+- [Claude Agent SDK - TypeScript V2 Preview](https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview)
+- [Claude Agent SDK - GitHub Repository](https://github.com/anthropics/claude-agent-sdk-typescript)
+- [Claude Agent SDK - npm Package](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
+- [OpenAI Extension sendChatHistory PR #157](https://github.com/microsoft/Agent365-nodejs/pull/157)