diff --git a/agent-sdk-client/config.py b/agent-sdk-client/config.py
index 8dfdca7..89b008b 100644
--- a/agent-sdk-client/config.py
+++ b/agent-sdk-client/config.py
@@ -28,20 +28,27 @@ def extract_command(text: Optional[str]) -> Optional[str]:
return command
-def _load_config(config_path: Path = DEFAULT_CONFIG_PATH) -> tuple[list[str], dict[str, str]]:
- """Load agent/local commands from TOML config file."""
+def _load_config(config_path: Path = DEFAULT_CONFIG_PATH) -> tuple[list[str], dict[str, str], list[int | str]]:
+ """Load commands and security config from TOML config file.
+
+ Returns:
+ Tuple of (agent_commands, local_commands, user_whitelist).
+ """
if not config_path.exists():
- return [], {}
+ return [], {}, ['all']
try:
with config_path.open('rb') as f:
data = tomllib.load(f)
+
+ # Load agent commands
agent_commands = data.get('agent_commands', {}).get('commands', [])
if not isinstance(agent_commands, list):
logger.warning("Agent commands config is not a list; ignoring configuration")
agent_commands = []
agent_commands = [cmd for cmd in agent_commands if isinstance(cmd, str)]
+ # Load local commands
local_commands_raw = data.get('local_commands', {})
if not isinstance(local_commands_raw, dict):
logger.warning("Local commands config is not a table; ignoring configuration")
@@ -52,10 +59,28 @@ def _load_config(config_path: Path = DEFAULT_CONFIG_PATH) -> tuple[list[str], di
if isinstance(name, str) and isinstance(value, str)
}
- return agent_commands, local_commands
+ # Load security whitelist
+ security = data.get('security', {})
+ whitelist = security.get('user_whitelist', ['all'])
+ if not isinstance(whitelist, list):
+ logger.warning("user_whitelist is not a list; using default ['all']")
+ whitelist = ['all']
+ else:
+ validated = []
+ for item in whitelist:
+ if item == 'all':
+ validated.append('all')
+ elif isinstance(item, int):
+ validated.append(item)
+ else:
+ logger.warning(f"Invalid whitelist entry: {item}; skipping")
+ whitelist = validated if validated else ['all']
+
+ return agent_commands, local_commands, whitelist
+
except (OSError, tomllib.TOMLDecodeError) as exc: # pragma: no cover - defensive logging
- logger.warning("Failed to load command configuration: %s", exc)
- return [], {}
+ logger.warning("Failed to load configuration: %s", exc)
+ return [], {}, ['all']
@dataclass
@@ -68,11 +93,12 @@ class Config:
queue_url: str
agent_commands: list[str]
local_commands: dict[str, str]
+ user_whitelist: list[int | str]
@classmethod
def from_env(cls, config_path: Optional[Path] = None) -> 'Config':
"""Load configuration from environment variables."""
- agent_cmds, local_cmds = _load_config(config_path or DEFAULT_CONFIG_PATH)
+ agent_cmds, local_cmds, whitelist = _load_config(config_path or DEFAULT_CONFIG_PATH)
return cls(
telegram_token=os.getenv('TELEGRAM_BOT_TOKEN', ''),
agent_server_url=os.getenv('AGENT_SERVER_URL', ''),
@@ -80,6 +106,7 @@ def from_env(cls, config_path: Optional[Path] = None) -> 'Config':
queue_url=os.getenv('QUEUE_URL', ''),
agent_commands=agent_cmds,
local_commands=local_cmds,
+ user_whitelist=whitelist,
)
def get_command(self, text: Optional[str]) -> Optional[str]:
diff --git a/agent-sdk-client/config.toml b/agent-sdk-client/config.toml
index 4186b4e..49d677a 100644
--- a/agent-sdk-client/config.toml
+++ b/agent-sdk-client/config.toml
@@ -8,3 +8,9 @@ commands = [
[local_commands]
# Local-only commands handled by the client
help = "Hello World"
+
+[security]
+# User IDs allowed to add bot to groups and send private messages.
+# Use ["all"] to allow everyone (default behavior).
+# Example with specific users: user_whitelist = [123456789, 987654321]
+user_whitelist = ["all"]
diff --git a/agent-sdk-client/handler.py b/agent-sdk-client/handler.py
index ae3cd9f..b598fc8 100644
--- a/agent-sdk-client/handler.py
+++ b/agent-sdk-client/handler.py
@@ -2,6 +2,7 @@
Receives Telegram webhook, writes to SQS, returns 200 immediately.
"""
+import asyncio
import json
import logging
from typing import Any
@@ -11,6 +12,7 @@
from telegram import Bot, Update
from config import Config
+from security import is_user_allowed, should_leave_group
logger = logging.getLogger()
logger.setLevel(logging.INFO)
@@ -169,11 +171,35 @@ def lambda_handler(event: dict, context: Any) -> dict:
logger.debug('Ignoring non-update webhook')
return {'statusCode': 200}
+ # Handle my_chat_member event (bot added to group)
+ if update.my_chat_member:
+ if should_leave_group(update, config.user_whitelist):
+ chat_id = update.my_chat_member.chat.id
+ inviter_id = update.my_chat_member.from_user.id
+ asyncio.run(bot.leave_chat(chat_id))
+ logger.info(
+ f"Left unauthorized group",
+ extra={'chat_id': chat_id, 'inviter_id': inviter_id},
+ )
+ _send_metric('SecurityBlock.UnauthorizedGroup')
+ return {'statusCode': 200}
+
message = update.message or update.edited_message
if not message or not message.text:
logger.debug('Ignoring webhook without text message')
return {'statusCode': 200}
+ # Check private message whitelist
+ if message.chat.type == 'private':
+ user_id = message.from_user.id if message.from_user else None
+ if user_id and not is_user_allowed(user_id, config.user_whitelist):
+ logger.info(
+ f"Blocked private message from unauthorized user",
+ extra={'user_id': user_id},
+ )
+ _send_metric('SecurityBlock.UnauthorizedPrivate')
+ return {'statusCode': 200}
+
cmd = config.get_command(message.text)
if cmd and config.is_local_command(cmd):
_handle_local_command(bot, message, config, cmd)
diff --git a/agent-sdk-client/security.py b/agent-sdk-client/security.py
new file mode 100644
index 0000000..1478ce7
--- /dev/null
+++ b/agent-sdk-client/security.py
@@ -0,0 +1,42 @@
+"""Security module for Telegram Bot access control."""
+from telegram import Update
+
+
+def is_user_allowed(user_id: int, whitelist: list[int | str]) -> bool:
+ """Check if user is in whitelist.
+
+ Args:
+ user_id: Telegram user ID to check.
+ whitelist: List of allowed user IDs, or ['all'] to allow everyone.
+
+ Returns:
+ True if user is allowed, False otherwise.
+ """
+ if 'all' in whitelist:
+ return True
+ return user_id in whitelist
+
+
+def should_leave_group(update: Update, whitelist: list[int | str]) -> bool:
+ """Check if bot should leave a group based on who added it.
+
+ Args:
+ update: Telegram Update object with my_chat_member event.
+ whitelist: List of allowed user IDs who can add bot to groups.
+
+ Returns:
+ True if bot should leave (added by unauthorized user), False otherwise.
+ """
+ if not update.my_chat_member:
+ return False
+
+ member_update = update.my_chat_member
+ old_status = member_update.old_chat_member.status
+ new_status = member_update.new_chat_member.status
+
+ # Bot being added to group (status changed from left/kicked to member/administrator)
+ if old_status in ('left', 'kicked') and new_status in ('member', 'administrator'):
+ inviter_id = member_update.from_user.id
+ return not is_user_allowed(inviter_id, whitelist)
+
+ return False
diff --git a/docs/authropic-agent-sdk-official/plugin-in-sdk.md b/docs/authropic-agent-sdk-official/plugin-in-sdk.md
new file mode 100644
index 0000000..5e8f50b
--- /dev/null
+++ b/docs/authropic-agent-sdk-official/plugin-in-sdk.md
@@ -0,0 +1,346 @@
+# Plugins in the SDK
+
+Load custom plugins to extend Claude Code with commands, agents, skills, and hooks through the Agent SDK
+
+---
+
+Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add custom slash commands, agents, skills, hooks, and MCP servers to your agent sessions.
+
+## What are plugins?
+
+Plugins are packages of Claude Code extensions that can include:
+- **Commands**: Custom slash commands
+- **Agents**: Specialized subagents for specific tasks
+- **Skills**: Model-invoked capabilities that Claude uses autonomously
+- **Hooks**: Event handlers that respond to tool use and other events
+- **MCP servers**: External tool integrations via Model Context Protocol
+
+For complete information on plugin structure and how to create plugins, see [Plugins](https://code.claude.com/docs/en/plugins).
+
+## Loading plugins
+
+Load plugins by providing their local file system paths in your options configuration. The SDK supports loading multiple plugins from different locations.
+
+
+
+```typescript TypeScript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+ prompt: "Hello",
+ options: {
+ plugins: [
+ { type: "local", path: "./my-plugin" },
+ { type: "local", path: "/absolute/path/to/another-plugin" }
+ ]
+ }
+})) {
+ // Plugin commands, agents, and other features are now available
+}
+```
+
+```python Python
+import asyncio
+from claude_agent_sdk import query
+
+async def main():
+ async for message in query(
+ prompt="Hello",
+ options={
+ "plugins": [
+ {"type": "local", "path": "./my-plugin"},
+ {"type": "local", "path": "/absolute/path/to/another-plugin"}
+ ]
+ }
+ ):
+ # Plugin commands, agents, and other features are now available
+ pass
+
+asyncio.run(main())
+```
+
+
+
+### Path specifications
+
+Plugin paths can be:
+- **Relative paths**: Resolved relative to your current working directory (e.g., `"./plugins/my-plugin"`)
+- **Absolute paths**: Full file system paths (e.g., `"/home/user/plugins/my-plugin"`)
+
+
+The path should point to the plugin's root directory (the directory containing `.claude-plugin/plugin.json`).
+
+
+## Verifying plugin installation
+
+When plugins load successfully, they appear in the system initialization message. You can verify that your plugins are available:
+
+
+
+```typescript TypeScript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+ prompt: "Hello",
+ options: {
+ plugins: [{ type: "local", path: "./my-plugin" }]
+ }
+})) {
+ if (message.type === "system" && message.subtype === "init") {
+ // Check loaded plugins
+ console.log("Plugins:", message.plugins);
+ // Example: [{ name: "my-plugin", path: "./my-plugin" }]
+
+ // Check available commands from plugins
+ console.log("Commands:", message.slash_commands);
+ // Example: ["/help", "/compact", "my-plugin:custom-command"]
+ }
+}
+```
+
+```python Python
+import asyncio
+from claude_agent_sdk import query
+
+async def main():
+ async for message in query(
+ prompt="Hello",
+ options={"plugins": [{"type": "local", "path": "./my-plugin"}]}
+ ):
+ if message.type == "system" and message.subtype == "init":
+ # Check loaded plugins
+ print("Plugins:", message.data.get("plugins"))
+ # Example: [{"name": "my-plugin", "path": "./my-plugin"}]
+
+ # Check available commands from plugins
+ print("Commands:", message.data.get("slash_commands"))
+ # Example: ["/help", "/compact", "my-plugin:custom-command"]
+
+asyncio.run(main())
+```
+
+
+
+## Using plugin commands
+
+Commands from plugins are automatically namespaced with the plugin name to avoid conflicts. The format is `plugin-name:command-name`.
+
+
+
+```typescript TypeScript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+// Load a plugin with a custom /greet command
+for await (const message of query({
+ prompt: "/my-plugin:greet", // Use plugin command with namespace
+ options: {
+ plugins: [{ type: "local", path: "./my-plugin" }]
+ }
+})) {
+ // Claude executes the custom greeting command from the plugin
+ if (message.type === "assistant") {
+ console.log(message.content);
+ }
+}
+```
+
+```python Python
+import asyncio
+from claude_agent_sdk import query, AssistantMessage, TextBlock
+
+async def main():
+ # Load a plugin with a custom /greet command
+ async for message in query(
+ prompt="/demo-plugin:greet", # Use plugin command with namespace
+ options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]}
+ ):
+ # Claude executes the custom greeting command from the plugin
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(f"Claude: {block.text}")
+
+asyncio.run(main())
+```
+
+
+
+
+If you installed a plugin via the CLI (e.g., `/plugin install my-plugin@marketplace`), you can still use it in the SDK by providing its installation path. Check `~/.claude/plugins/` for CLI-installed plugins.
+
+
+## Complete example
+
+Here's a full example demonstrating plugin loading and usage:
+
+
+
+```typescript TypeScript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import * as path from "path";
+
+async function runWithPlugin() {
+ const pluginPath = path.join(__dirname, "plugins", "my-plugin");
+
+ console.log("Loading plugin from:", pluginPath);
+
+ for await (const message of query({
+ prompt: "What custom commands do you have available?",
+ options: {
+ plugins: [
+ { type: "local", path: pluginPath }
+ ],
+ maxTurns: 3
+ }
+ })) {
+ if (message.type === "system" && message.subtype === "init") {
+ console.log("Loaded plugins:", message.plugins);
+ console.log("Available commands:", message.slash_commands);
+ }
+
+ if (message.type === "assistant") {
+ console.log("Assistant:", message.content);
+ }
+ }
+}
+
+runWithPlugin().catch(console.error);
+```
+
+```python Python
+#!/usr/bin/env python3
+"""Example demonstrating how to use plugins with the Agent SDK."""
+
+from pathlib import Path
+import anyio
+from claude_agent_sdk import (
+ AssistantMessage,
+ ClaudeAgentOptions,
+ TextBlock,
+ query,
+)
+
+
+async def run_with_plugin():
+ """Example using a custom plugin."""
+ plugin_path = Path(__file__).parent / "plugins" / "demo-plugin"
+
+ print(f"Loading plugin from: {plugin_path}")
+
+ options = ClaudeAgentOptions(
+ plugins=[
+ {"type": "local", "path": str(plugin_path)}
+ ],
+ max_turns=3,
+ )
+
+ async for message in query(
+ prompt="What custom commands do you have available?",
+ options=options
+ ):
+ if message.type == "system" and message.subtype == "init":
+ print(f"Loaded plugins: {message.data.get('plugins')}")
+ print(f"Available commands: {message.data.get('slash_commands')}")
+
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(f"Assistant: {block.text}")
+
+
+if __name__ == "__main__":
+ anyio.run(run_with_plugin)
+```
+
+
+
+## Plugin structure reference
+
+A plugin directory must contain a `.claude-plugin/plugin.json` manifest file. It can optionally include:
+
+```
+my-plugin/
+├── .claude-plugin/
+│ └── plugin.json # Required: plugin manifest
+├── commands/ # Custom slash commands
+│ └── custom-cmd.md
+├── agents/ # Custom agents
+│ └── specialist.md
+├── skills/ # Agent Skills
+│ └── my-skill/
+│ └── SKILL.md
+├── hooks/ # Event handlers
+│ └── hooks.json
+└── .mcp.json # MCP server definitions
+```
+
+For detailed information on creating plugins, see:
+- [Plugins](https://code.claude.com/docs/en/plugins) - Complete plugin development guide
+- [Plugins reference](https://code.claude.com/docs/en/plugins-reference) - Technical specifications and schemas
+
+## Common use cases
+
+### Development and testing
+
+Load plugins during development without installing them globally:
+
+```typescript
+plugins: [
+ { type: "local", path: "./dev-plugins/my-plugin" }
+]
+```
+
+### Project-specific extensions
+
+Include plugins in your project repository for team-wide consistency:
+
+```typescript
+plugins: [
+ { type: "local", path: "./project-plugins/team-workflows" }
+]
+```
+
+### Multiple plugin sources
+
+Combine plugins from different locations:
+
+```typescript
+plugins: [
+ { type: "local", path: "./local-plugin" },
+ { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
+]
+```
+
+## Troubleshooting
+
+### Plugin not loading
+
+If your plugin doesn't appear in the init message:
+
+1. **Check the path**: Ensure the path points to the plugin root directory (containing `.claude-plugin/`)
+2. **Validate plugin.json**: Ensure your manifest file has valid JSON syntax
+3. **Check file permissions**: Ensure the plugin directory is readable
+
+### Commands not available
+
+If plugin commands don't work:
+
+1. **Use the namespace**: Plugin commands require the `plugin-name:command-name` format
+2. **Check init message**: Verify the command appears in `slash_commands` with the correct namespace
+3. **Validate command files**: Ensure command markdown files are in the `commands/` directory
+
+### Path resolution issues
+
+If relative paths don't work:
+
+1. **Check working directory**: Relative paths are resolved from your current working directory
+2. **Use absolute paths**: For reliability, consider using absolute paths
+3. **Normalize paths**: Use path utilities to construct paths correctly
+
+## See also
+
+- [Plugins](https://code.claude.com/docs/en/plugins) - Complete plugin development guide
+- [Plugins reference](https://code.claude.com/docs/en/plugins-reference) - Technical specifications
+- [Slash Commands](/docs/en/agent-sdk/slash-commands) - Using slash commands in the SDK
+- [Subagents](/docs/en/agent-sdk/subagents) - Working with specialized agents
+- [Skills](/docs/en/agent-sdk/skills) - Using Agent Skills
\ No newline at end of file