@mseep/obsidian-agent-client 0.10.6

package/.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build with VitePress
+        run: npm run docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/relay_to_openclaw.yml

@@ -0,0 +1,59 @@
+# Relay GitHub events to OpenClaw via webhook
+# OpenClaw translates the event into Japanese and posts it to Discord as an embed
+#
+# Required secrets:
+#   OPENCLAW_WEBHOOK_URL   - OpenClaw hooks endpoint URL
+#   OPENCLAW_HOOKS_TOKEN   - Bearer token for OpenClaw hooks authentication
+#   OPENCLAW_DISCORD_CHANNEL - Discord channel ID for delivery
+
+name: Relay to OpenClaw
+
+on:
+  issues:
+    types: [opened, reopened]
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened]
+  pull_request_review_comment:
+    types: [created]
+  discussion:
+    types: [created]
+  discussion_comment:
+    types: [created]
+
+jobs:
+  relay:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Forward event to OpenClaw
+        env:
+          GH_EVENT: ${{ toJSON(github.event) }}
+          OPENCLAW_WEBHOOK_URL: ${{ secrets.OPENCLAW_WEBHOOK_URL }}
+          OPENCLAW_HOOKS_TOKEN: ${{ secrets.OPENCLAW_HOOKS_TOKEN }}
+          OPENCLAW_DISCORD_CHANNEL: ${{ secrets.OPENCLAW_DISCORD_CHANNEL }}
+        run: |
+          EVENT_NAME="${{ github.event_name }}"
+          REPO="${{ github.repository }}"
+          NUMBER=$(echo "$GH_EVENT" | jq -r '.issue.number // .pull_request.number // .discussion.number // ""')
+          TITLE=$(echo "$GH_EVENT" | jq -r '.issue.title // .pull_request.title // .discussion.title // ""')
+          BODY=$(echo "$GH_EVENT" | jq -r '.comment.body // .issue.body // .pull_request.body // .discussion.body // ""' | head -c 4000)
+          URL=$(echo "$GH_EVENT" | jq -r '.comment.html_url // .issue.html_url // .pull_request.html_url // .discussion.html_url // ""')
+          USER=$(echo "$GH_EVENT" | jq -r '.sender.login // ""')
+
+          jq -n \
+            --arg event "$EVENT_NAME" \
+            --arg repo "$REPO" \
+            --arg number "$NUMBER" \
+            --arg title "$TITLE" \
+            --arg user "$USER" \
+            --arg url "$URL" \
+            --arg body "$BODY" \
+            --arg ch "discord" \
+            --arg to "$OPENCLAW_DISCORD_CHANNEL" \
+            '{message: ("event: " + $event + "\nrepo: " + $repo + "\nnumber: #" + $number + "\ntitle: " + $title + "\nauthor: " + $user + "\nurl: " + $url + "\n\nbody:\n" + $body), deliver: false, channel: $ch, to: $to, name: "GitHub", agentId: "github-hook"}' | \
+          curl -sf -X POST \
+            "${OPENCLAW_WEBHOOK_URL}/hooks/agent" \
+            -H "Authorization: Bearer ${OPENCLAW_HOOKS_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d @-

package/.github/workflows/release.yaml

@@ -0,0 +1,45 @@
+name: Release Obsidian plugin
+
+on:
+    push:
+        tags:
+            - "*"
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+            id-token: write
+            attestations: write
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Use Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "22.x"
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Build plugin
+              run: npm run build
+
+            - name: Attest build provenance
+              uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2
+              with:
+                  subject-path: |
+                      main.js
+                      styles.css
+
+            - name: Create release
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                  tag="${GITHUB_REF#refs/tags/}"
+
+                  gh release create "$tag" \
+                    --title="$tag" \
+                    --draft \
+                    main.js manifest.json styles.css

package/.prettierignore

@@ -0,0 +1,10 @@
+node_modules/
+.git/
+.github/
+.serena/
+.claude/
+main.js
+*.json
+*.md
+data.json
+docs/

package/.prettierrc

@@ -0,0 +1,13 @@
+{
+	"useTabs": true,
+	"tabWidth": 4,
+	"semi": true,
+	"singleQuote": false,
+	"quoteProps": "as-needed",
+	"trailingComma": "all",
+	"bracketSpacing": true,
+	"arrowParens": "always",
+	"endOfLine": "lf",
+	"printWidth": 80,
+	"proseWrap": "preserve"
+}

package/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+	"recommendations": [
+		"esbenp.prettier-vscode",
+		"dbaeumer.vscode-eslint",
+		"editorconfig.editorconfig"
+	]
+}

package/.vscode/settings.json

@@ -0,0 +1,37 @@
+{
+	"editor.formatOnSave": true,
+	"editor.defaultFormatter": "esbenp.prettier-vscode",
+	"editor.codeActionsOnSave": {
+		"source.fixAll.eslint": "explicit"
+	},
+	"editor.tabSize": 4,
+	"editor.insertSpaces": false,
+	"editor.detectIndentation": false,
+	"files.eol": "\n",
+	"files.insertFinalNewline": true,
+	"files.trimTrailingWhitespace": true,
+	"[typescript]": {
+		"editor.defaultFormatter": "esbenp.prettier-vscode"
+	},
+	"[typescriptreact]": {
+		"editor.defaultFormatter": "esbenp.prettier-vscode"
+	},
+	"[javascript]": {
+		"editor.defaultFormatter": "esbenp.prettier-vscode"
+	},
+	"[javascriptreact]": {
+		"editor.defaultFormatter": "esbenp.prettier-vscode"
+	},
+	"[css]": {
+		"editor.defaultFormatter": "esbenp.prettier-vscode"
+	},
+	"eslint.validate": [
+		"javascript",
+		"javascriptreact",
+		"typescript",
+		"typescriptreact"
+	],
+	"eslint.enable": true,
+	"prettier.requireConfig": true,
+	"prettier.useEditorConfig": true
+}

package/.zed/settings.json

@@ -0,0 +1,42 @@
+{
+	"tab_size": 4,
+	"hard_tabs": true,
+	"format_on_save": "on",
+	"remove_trailing_whitespace_on_save": true,
+	"ensure_final_newline_on_save": true,
+	"languages": {
+		"TypeScript": {
+			"tab_size": 4,
+			"hard_tabs": true,
+			"formatter": "prettier",
+			"code_actions_on_format": {
+				"source.fixAll.eslint": false
+			},
+			"format_on_save": "on"
+		},
+		"TSX": {
+			"tab_size": 4,
+			"hard_tabs": true,
+			"formatter": "prettier",
+			"code_actions_on_format": {
+				"source.fixAll.eslint": false
+			},
+			"format_on_save": "on"
+		},
+		"JavaScript": {
+			"tab_size": 4,
+			"hard_tabs": true,
+			"formatter": "prettier",
+			"code_actions_on_format": {
+				"source.fixAll.eslint": false
+			},
+			"format_on_save": "on"
+		},
+		"CSS": {
+			"tab_size": 4,
+			"hard_tabs": true,
+			"formatter": "prettier",
+			"format_on_save": "on"
+		}
+	}
+}

package/AGENTS.md

@@ -0,0 +1,330 @@
+# Agent Client Plugin - LLM Developer Guide
+
+## Overview
+Obsidian plugin for AI agent interaction (Claude Code, Codex, Gemini CLI, custom agents) via ACP.
+
+**Tech**: React 19, TypeScript, Obsidian API, Agent Client Protocol (ACP)
+
+## Architecture
+
+```
+src/
+├── types/                       # Type definitions (no logic, no dependencies)
+│   ├── chat.ts                  # ChatMessage, MessageContent, PromptContent, AttachedFile, ActivePermission
+│   ├── session.ts               # ChatSession, SessionUpdate (12-type union), SessionInfo, Capabilities
+│   ├── agent.ts                 # AgentConfig, agent settings (Claude/Codex/Gemini/Custom)
+│   └── errors.ts                # AcpError, ProcessError, ErrorInfo
+├── acp/                         # ACP protocol (SDK dependency confined here)
+│   ├── acp-client.ts            # Process lifecycle, UI-facing API (AcpClient class)
+│   ├── acp-handler.ts           # SDK event handler + sessionId filter + listener broadcast
+│   ├── type-converter.ts        # ACP SDK ↔ internal type conversion
+│   ├── permission-handler.ts    # Permission queue, auto-approve, Promise resolution
+│   └── terminal-handler.ts      # Terminal process create/output/kill
+├── services/                    # Business logic (non-React, no React imports)
+│   ├── vault-service.ts         # Vault access + fuzzy search + CM6 selection tracking
+│   ├── settings-service.ts      # Reactive settings store (observer pattern only)
+│   ├── session-storage.ts       # Session metadata + message file I/O (sessions/*.json)
+│   ├── settings-normalizer.ts   # Settings validation helpers (str, bool, num, enumVal, etc.)
+│   ├── session-helpers.ts       # Agent config building, API key injection (pure functions)
+│   ├── session-state.ts         # Session state updates (legacy mode/model, config restore)
+│   ├── message-state.ts         # Message array transforms (upsert, merge, streaming apply)
+│   ├── message-sender.ts        # Prompt preparation + sending (pure functions)
+│   ├── chat-exporter.ts         # Markdown export with frontmatter
+│   ├── view-registry.ts         # Multi-view management, focus, broadcast
+│   └── update-checker.ts        # Agent/plugin version checking
+├── hooks/                       # React custom hooks (state + logic)
+│   ├── useAgent.ts              # Facade: composes useAgentSession + useAgentMessages
+│   ├── useAgentSession.ts       # Session lifecycle, config options, optimistic updates
+│   ├── useAgentMessages.ts      # Message state, streaming (RAF batch), permissions
+│   ├── useSuggestions.ts        # @[[note]] mentions + /command suggestions (unified)
+│   ├── useSessionHistory.ts     # Session list/load/resume/fork
+│   ├── useChatActions.ts        # Business callbacks (send, newChat, export, restart, etc.)
+│   ├── useHistoryModal.ts       # Session history modal lifecycle
+│   └── useSettings.ts           # Settings subscription (useSyncExternalStore)
+├── ui/                          # React components
+│   ├── ChatContext.ts           # React Context (plugin, acpClient, vaultService, settingsService)
+│   ├── ChatPanel.tsx            # Orchestrator: calls hooks, workspace events, rendering
+│   ├── ChatView.tsx             # Sidebar view (ItemView wrapper)
+│   ├── FloatingChatView.tsx     # Floating window (position/drag/resize)
+│   ├── ChatHeader.tsx           # Header (sidebar + floating variants)
+│   ├── MessageList.tsx          # Virtualized message list (@tanstack/react-virtual)
+│   ├── MessageBubble.tsx        # Single message rendering (content dispatch, copy button)
+│   ├── ToolCallBlock.tsx        # Tool call + diff display (word-level highlighting)
+│   ├── TerminalBlock.tsx        # Terminal output polling
+│   ├── InputArea.tsx            # Textarea, attachments, mentions, history
+│   ├── InputToolbar.tsx         # Config/mode/model selectors, usage, send button
+│   ├── SuggestionPopup.tsx      # Mention/command dropdown
+│   ├── PermissionBanner.tsx     # Permission request buttons
+│   ├── ErrorBanner.tsx          # Error/notification overlay
+│   ├── SessionHistoryModal.tsx  # Session history modal (list + confirm delete)
+│   ├── FloatingButton.tsx       # Draggable launch button
+│   ├── SettingsTab.ts           # Plugin settings UI
+│   ├── view-host.ts             # IChatViewHost interface
+│   └── shared/
+│       ├── IconButton.tsx       # Icon button + Lucide icon wrapper
+│       ├── MarkdownRenderer.tsx # Obsidian markdown rendering
+│       └── AttachmentStrip.tsx  # Attachment preview strip
+├── utils/                       # Shared utilities (pure functions)
+│   ├── platform.ts              # Shell, WSL, Windows env, command building
+│   ├── paths.ts                 # Path resolution, file:// URI
+│   ├── error-utils.ts           # ACP error conversion
+│   ├── mention-parser.ts        # @[[note]] detection/extraction
+│   └── logger.ts                # Debug-mode logger
+├── plugin.ts                    # Obsidian plugin lifecycle, settings persistence
+└── main.ts                      # Entry point
+```
+
+## Data Flow
+
+### ACP Event Flow (single path)
+```
+Agent Process → ACP SDK → AcpHandler (sessionId filter) → listeners broadcast
+  → useAgentSession (session-level: commands, mode, config, usage, error)
+  → useAgentMessages (message-level: text chunks, tool calls, plan)
+  → useAgent (facade, 1 onSessionUpdate subscription)
+```
+
+All events flow through a single `onSessionUpdate` channel. No special paths for permissions or errors.
+
+### Permission Flow
+```
+Agent requestPermission → PermissionManager.request() → onSessionUpdate (tool_call)
+User clicks approve/reject → PermissionManager.respond() → onSessionUpdate (tool_call_update)
+```
+
+## Key Components
+
+### ChatPanel (`ui/ChatPanel.tsx`)
+Central orchestrator component.
+- **Hook Composition**: Calls useAgent, useSuggestions, useSessionHistory, useChatActions, useHistoryModal, useSettings
+- **Workspace Events**: Handles hotkeys via ref pattern (stable event registration)
+- **Callback Registration**: IChatViewContainer callbacks via refs
+- **Rendering**: Renders ChatHeader, MessageList, InputArea directly
+
+ChatPanel does NOT route session updates — that's handled internally by useAgent.
+
+### ChatView / FloatingChatView (`ui/ChatView.tsx`, `ui/FloatingChatView.tsx`)
+Thin wrappers that:
+- Create services (AcpClient, VaultService) in lifecycle methods
+- Provide ChatContext (plugin, acpClient, vaultService, settingsService)
+- Render `<ChatPanel variant="sidebar" | "floating" />`
+- Implement IChatViewContainer for broadcast commands
+
+FloatingChatView uses `onRegisterExpanded` callback (not CustomEvent) for expand/collapse.
+
+### Hooks (`hooks/`)
+
+**useAgent** (facade): Comp훈oses useAgentSession + useAgentMessages
+- Single `onSessionUpdate` subscription
+- Unified `handleSessionUpdate` dispatches to both sub-hooks
+- Return is `useMemo`-wrapped for referential stability
+
+**useAgentSession**: Session lifecycle + config
+- `createSession()`: Build config, inject API keys, initialize + newSession
+- `setConfigOption()`: Optimistic update + rollback on error
+- `setMode()` / `setModel()`: Legacy API (deprecated, still used by many agents)
+- Session-level update handler (commands, mode, config, usage, process_error)
+- Uses `sessionRef` pattern to stabilize callback deps
+
+**useAgentMessages**: Messaging + streaming + permissions
+- `sendMessage()`: Prepare (auto-mention, path conversion) → send via AcpClient
+- RAF batching: streaming updates accumulated per-frame via `requestAnimationFrame`
+- Tool call index: `Map<string, number>` for O(1) upsert
+- `ignoreUpdatesRef`: suppresses history replay during session/load
+- Permission: `activePermission` (useMemo derivation), approve/reject callbacks
+
+**useSuggestions**: @mention + /command (unified)
+- Mention detection, note searching, dropdown interaction
+- Slash command filtering and selection
+- Auto-mention toggle coordination (slash commands disable auto-mention)
+- Return is `useMemo`-wrapped (mentions + commands objects)
+
+**useChatActions**: Business callbacks
+- handleSendMessage, handleNewChat, handleExportChat, handleRestartAgent, etc.
+- Uses individual method deps (not whole agent object) for stability
+- Owns restoredMessage and agentUpdateNotification state
+
+**useSessionHistory**: Session persistence
+- `restoreSession()`: Load/resume with local message fallback
+- `forkSession()`: Create new branch from existing session
+- 5-minute cache with invalidation
+- Return is `useMemo`-wrapped
+
+**useHistoryModal**: Modal lifecycle
+- Lazy modal creation, props synchronization
+- Session operation callbacks (restore, fork, delete)
+
+### ACP Client (`acp/acp-client.ts`) + ACP Handler (`acp/acp-handler.ts`)
+
+**AcpClient** — UI-facing API and process lifecycle:
+- spawn() with login shell, JSON-RPC via ndJsonStream
+- initialize() → newSession() → sendPrompt() → cancel() → disconnect()
+- Session management: listSessions, loadSession, resumeSession, forkSession
+- Owns PermissionManager, TerminalManager, AcpHandler
+- `currentSessionId` set before `await` in loadSession/resumeSession to prevent replay filtering
+- Single exit point: `onSessionUpdate` (multiple listeners via Set)
+
+**AcpHandler** — SDK event receiver:
+- sessionUpdate: converts ACP types → domain types → broadcast to listeners
+- sessionId filter: only emits updates matching `currentSessionId`
+- requestPermission → PermissionManager
+- Terminal operations → TerminalManager
+
+### Services (`services/`)
+
+**VaultService**: Vault access + file index + fuzzy search + CM6 selection tracking
+**SettingsService**: Reactive settings store (observer pattern for useSyncExternalStore). Session storage delegated to SessionStorage.
+**SessionStorage**: Session metadata CRUD (in plugin settings) + message file I/O (sessions/*.json)
+**settings-normalizer**: Validation helpers (str, bool, num, enumVal, obj, strRecord, xyPoint) + toAgentConfig + parseChatFontSize
+**session-helpers**: Pure functions — buildAgentConfigWithApiKey, findAgentSettings, getAvailableAgents
+**session-state**: Pure functions — applyLegacyValue, tryRestoreConfigOption, restoreLegacyConfig
+**message-state**: Pure functions — applySingleUpdate, applyUpsertToolCall, mergeToolCallContent, findActivePermission, selectOption
+**message-sender**: Pure functions — preparePrompt (embedded context vs XML text, shared helpers), sendPreparedPrompt (auth retry)
+
+## Types
+
+### SessionUpdate (`types/session.ts`)
+Union type for all session update events from the agent:
+
+```typescript
+type SessionUpdate =
+  | AgentMessageChunk        // Text chunk from agent's response
+  | AgentThoughtChunk        // Text chunk from agent's reasoning
+  | UserMessageChunk         // Text chunk from user message (session/load)
+  | ToolCall                 // New tool call event
+  | ToolCallUpdate           // Update to existing tool call
+  | Plan                     // Agent's task plan
+  | AvailableCommandsUpdate  // Slash commands changed
+  | CurrentModeUpdate        // Mode changed
+  | SessionInfoUpdate        // Session metadata changed
+  | UsageUpdate              // Context window usage
+  | ConfigOptionUpdate       // Config options changed
+  | ProcessErrorUpdate;      // Process-level error (spawn failure, command not found)
+```
+
+### Key Interfaces
+
+```typescript
+// services/vault-service.ts
+interface IVaultAccess {
+  readNote(path: string): Promise<string>;
+  searchNotes(query: string): Promise<NoteMetadata[]>;
+  getActiveNote(): Promise<NoteMetadata | null>;
+  listNotes(): Promise<NoteMetadata[]>;
+}
+
+// services/settings-service.ts
+interface ISettingsAccess {
+  getSnapshot(): AgentClientPluginSettings;
+  updateSettings(updates: Partial<AgentClientPluginSettings>): Promise<void>;
+  subscribe(listener: () => void): () => void;
+  // Session storage methods (delegated to SessionStorage internally)
+  saveSession(info: SavedSessionInfo): Promise<void>;
+  getSavedSessions(agentId?: string, cwd?: string): SavedSessionInfo[];
+  deleteSession(sessionId: string): Promise<void>;
+  saveSessionMessages(sessionId: string, agentId: string, messages: ChatMessage[]): Promise<void>;
+  loadSessionMessages(sessionId: string): Promise<ChatMessage[] | null>;
+  deleteSessionMessages(sessionId: string): Promise<void>;
+}
+```
+
+## Development Rules
+
+### Architecture
+1. **useAgent as facade**: Composes useAgentSession + useAgentMessages. ChatPanel calls useAgent, not sub-hooks directly.
+2. **Services have zero React imports**: Pure functions and classes in `services/`. No useState, useCallback, React.Dispatch, etc.
+3. **ACP isolation**: All `@agentclientprotocol/sdk` imports confined to `acp/`. AcpClient is UI-facing, AcpHandler is SDK-facing.
+4. **Types have zero deps**: No `obsidian`, no SDK, no React in `types/`
+5. **Single event channel**: All agent events (messages, session updates, permissions, errors) flow through `onSessionUpdate`. No special callback paths.
+6. **Context for services**: plugin, acpClient, vaultService, settingsService via ChatContext
+
+### Performance Patterns
+1. **useMemo for return stability**: useAgent, useSuggestions, useSessionHistory wrap return objects in useMemo to prevent cascading re-renders
+2. **sessionRef pattern**: useAgentSession stores session in useRef for callback access without adding session to deps
+3. **Individual method deps**: useChatActions uses `agent.sendMessage` not `agent` as deps — prevents callback recreation when unrelated state changes
+4. **Workspace event refs**: ChatPanel stores event handler callbacks in refs, keeping useEffect deps minimal
+5. **RAF batching**: useAgentMessages batches streaming updates per animation frame (~60fps) instead of per-chunk
+6. **React.memo**: MessageBubble, ToolCallBlock, TerminalBlock wrapped for skip-render optimization
+7. **Virtual scroll**: MessageList uses @tanstack/react-virtual for large conversations
+8. **O(1) tool call index**: Map<string, number> for tool call upsert without linear scan
+
+### Obsidian Plugin Review (CRITICAL)
+1. No innerHTML/outerHTML - use createEl/createDiv/createSpan
+2. NO detach leaves in onunload (antipattern)
+3. Styles in CSS only - no JS style manipulation
+4. Use Platform interface - not process.platform
+5. Minimize `any` - use proper types
+
+### Naming Conventions
+- Types: `kebab-case.ts` in `types/`
+- ACP: `kebab-case.ts` in `acp/`
+- Services: `kebab-case.ts` in `services/`
+- Hooks: `use*.ts` in `hooks/`
+- Components: `PascalCase.tsx` in `ui/`
+- Utils: `kebab-case.ts` in `utils/`
+
+### Code Patterns
+1. React hooks for state management
+2. useCallback/useMemo for performance (see Performance Patterns above)
+3. useRef for cleanup function access and stale closure prevention
+4. Error handling: try-catch async ops
+5. Logging: Logger class (respects debugMode). Avoid excessive per-keystroke logging.
+6. **Upsert pattern**: Use `setMessages` functional updates to avoid race conditions with tool_call updates
+7. **Ref pattern for callbacks**: IChatViewContainer and workspace event handlers use refs for latest values
+8. **Context value stability**: ChatContext value created once (service instances), wrapped in useMemo
+9. **Stable empty arrays**: Use module-level constants (e.g., `EMPTY_COMMANDS`) instead of inline `[]` in hook args
+
+## Common Tasks
+
+### Add New Feature Hook
+1. Create `hooks/use[Feature].ts`
+2. Define state with useState/useReducer
+3. Export functions and state
+4. Call the hook in `ui/ChatPanel.tsx`
+5. Pass state/callbacks to child components as props
+6. Wrap return object in `useMemo` if passed as dependency to other hooks
+
+### Add Agent Type
+1. Add settings type in `types/agent.ts`
+2. Add config and defaults in `plugin.ts`
+3. Add API key injection in `services/session-helpers.ts`
+4. Update `ui/SettingsTab.ts` for configuration UI
+
+### Modify Message Types
+1. Update `ChatMessage`/`MessageContent` in `types/chat.ts`
+2. If adding new session update type:
+   - Add to `SessionUpdate` union in `types/session.ts`
+   - Handle in `hooks/useAgentMessages.ts` (for message-level) or `hooks/useAgentSession.ts` (for session-level)
+3. Update `acp/acp-handler.ts` `sessionUpdate()` to emit the new type
+4. Update `ui/MessageBubble.tsx` `ContentBlock` to render new type
+
+### Add New Session Update Type
+1. Define interface in `types/session.ts`
+2. Add to `SessionUpdate` union type
+3. Handle in `hooks/useAgentSession.ts` `handleSessionUpdate()` (for session-level)
+4. Or handle via `applySingleUpdate()` in `services/message-state.ts` (for message-level)
+5. No routing needed in ChatPanel — useAgent handles dispatch internally
+
+### Debug
+1. Settings → Developer Settings → Debug Mode ON
+2. Open DevTools (Cmd+Option+I / Ctrl+Shift+I)
+3. Filter logs: `[AcpClient]`, `[AcpHandler]`, `[PermissionManager]`, `[VaultService]`
+
+## ACP Protocol
+
+**Communication**: JSON-RPC 2.0 over stdin/stdout
+
+**Methods**: initialize, newSession, authenticate, prompt, cancel, setSessionConfigOption
+**Notifications**: session/update (agent_message_chunk, agent_thought_chunk, user_message_chunk, tool_call, tool_call_update, plan, available_commands_update, current_mode_update, session_info_update, usage_update, config_option_update)
+**Requests**: requestPermission
+**Session Management** (unstable): session/list, session/load, session/resume, session/fork
+
+**Agents**:
+- Claude Code: `@agentclientprotocol/claude-agent-acp` (ANTHROPIC_API_KEY)
+- Codex: `@zed-industries/codex-acp` (OPENAI_API_KEY)
+- Gemini CLI: `@google/gemini-cli` (GEMINI_API_KEY)
+- Custom: Any ACP-compatible agent
+
+---
+
+**Last Updated**: April 2026 | **Architecture**: useAgent facade + sub-hooks | **Version**: 0.10.0-preview.1