illusion-code 0.1.3__tar.gz → 0.1.5__tar.gz

{illusion_code-0.1.3 → illusion_code-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: illusion-code
-Version: 0.1.3
+Version: 0.1.5
 Summary: Open-source Python port of Claude Code - an AI-powered CLI coding assistant
 Project-URL: Homepage, https://github.com/YunTaiHua/illusion-code
 Project-URL: Repository, https://github.com/YunTaiHua/illusion-code
@@ -483,6 +483,8 @@ Built-in 7 specialized Agents:
 | `MEMORY.md` | Project root | Project-level | Memory entry file |
 | `.illusion/mcp/*.json` | Project root | Project-level | MCP server configuration |
 | `.illusion/rules/*.md` | Project root | Project-level | Project rule files |
+| `.illusion/plugins/*/` | Global or project | Per-plugin | Plugin directories with skills, hooks, MCP |
+| `.illusion/skills/*/` | Global or project | Per-skill | Skill directories with SKILL.md |
 
 #### Credentials File (credentials.json)
 
@@ -591,17 +593,29 @@ settings.json uses the `env_N` grouped format to manage multiple environment/pro
   "sandbox": {
     "enabled": false,
     "fail_if_unavailable": false,
+    "auto_allow_bash_if_sandboxed": true,
+    "allow_unsandboxed_commands": true,
     "enabled_platforms": [],
+    "excluded_commands": [],
     "network": {
       "allowed_domains": [],
-      "denied_domains": []
+      "denied_domains": [],
+      "allow_unix_sockets": [],
+      "allow_all_unix_sockets": false,
+      "allow_local_binding": false,
+      "http_proxy_port": null,
+      "socks_proxy_port": null
     },
     "filesystem": {
       "allow_read": [],
       "deny_read": [],
       "allow_write": ["."],
       "deny_write": []
-    }
+    },
+    "ignore_violations": {},
+    "enable_weaker_nested_sandbox": false,
+    "mandatory_deny_search_depth": 3,
+    "allow_git_config": false
   },
   "enabled_plugins": {},
   "mcp_servers": {},
@@ -1035,56 +1049,128 @@ MCP servers from plugins are registered with the format `plugin_name:server_name
 
 ### Hook Configuration
 
-Hooks allow executing custom operations when specific events occur.
-
-#### Supported Hook Types
-
-| Hook Event | Description |
-|------------|-------------|
-| `PRE_TOOL_USE` | Before tool execution |
-| `POST_TOOL_USE` | After tool execution |
-| `USER_PROMPT_SUBMIT` | After user prompt submission |
-
-#### Hook Configuration Example
+Hooks allow executing custom operations when specific events occur. The hook system is fully aligned with Claude Code.
+
+#### Supported Hook Events (27 events)
+
+| Event | Matcher Field | Description |
+|-------|---------------|-------------|
+| `PreToolUse` | tool_name | Before tool execution |
+| `PostToolUse` | tool_name | After tool execution |
+| `PostToolUseFailure` | tool_name | After tool execution fails |
+| `PermissionDenied` | tool_name | After auto mode classifier denies |
+| `Notification` | notification_type | When notifications are sent |
+| `UserPromptSubmit` | — | When user submits a prompt |
+| `SessionStart` | source | New session started (startup/resume/clear/compact) |
+| `SessionEnd` | reason | Session ending |
+| `Stop` | — | Before Claude concludes response |
+| `StopFailure` | error | Turn ends due to API error |
+| `SubagentStart` | agent_type | Subagent started |
+| `SubagentStop` | agent_type | Subagent concludes |
+| `PreCompact` | trigger | Before compaction (manual/auto) |
+| `PostCompact` | trigger | After compaction |
+| `PermissionRequest` | tool_name | Permission dialog displayed |
+| `Setup` | trigger | Repo setup (init/maintenance) |
+| `ConfigChange` | source | Configuration file changes |
+| `InstructionsLoaded` | load_reason | Instruction file loaded |
+| `WorktreeCreate` | — | Create worktree |
+| `WorktreeRemove` | — | Remove worktree |
+| `CwdChanged` | — | Working directory changes |
+| `FileChanged` | — | Watched file changes |
+| `TaskCreated` | — | Task being created |
+| `TaskCompleted` | — | Task being completed |
+| `TeammateIdle` | — | Teammate about to idle |
+| `Elicitation` | mcp_server_name | MCP elicitation request |
+| `ElicitationResult` | mcp_server_name | After user responds to elicitation |
+
+#### Hook Configuration Format
+
+Hooks use a matcher-based structure (aligned with Claude Code):
 
 ```json
 {
   "hooks": {
-    "PRE_TOOL_USE": [
+    "PreToolUse": [
       {
-        "type": "command",
-        "command": "echo 'Tool: $TOOL_NAME' >> /tmp/tool.log",
-        "timeout_seconds": 30,
-        "block_on_failure": false
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Tool: $ARGUMENTS' >> /tmp/tool.log",
+            "timeout": 30
+          }
+        ]
       }
     ],
-    "POST_TOOL_USE": [
+    "PostToolUse": [
       {
-        "type": "http",
-        "url": "https://hooks.example.com/tool-complete",
-        "headers": {"Authorization": "Bearer token"},
-        "timeout_seconds": 10
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "http",
+            "url": "https://hooks.example.com/tool-complete",
+            "headers": {"Authorization": "Bearer token"}
+          }
+        ]
       }
     ],
-    "USER_PROMPT_SUBMIT": [
+    "UserPromptSubmit": [
       {
-        "type": "prompt",
-        "prompt": "Check if user input contains sensitive information",
-        "block_on_failure": true
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Check if user input contains sensitive information"
+          }
+        ]
       }
     ]
   }
 }
 ```
 
-#### Hook Type Details
+#### Matcher Patterns
+
+The `matcher` field filters when hooks run:
+
+| Pattern | Example | Behavior |
+|---------|---------|----------|
+| Empty / `*` | `""` | Matches everything |
+| Exact match | `"Bash"` | Matches exact tool name |
+| Pipe-separated | `"Write\|Edit"` | Matches any in list |
+| Regex | `"^git .*"` | Regex match against tool name |
+
+#### Hook Types
 
-| Type | Required Fields | Optional Fields | Description |
-|------|-----------------|-----------------|-------------|
-| `command` | command | timeout_seconds, matcher, block_on_failure | Execute Shell command |
-| `prompt` | prompt | model, timeout_seconds, matcher, block_on_failure | Use LLM for verification |
-| `http` | url | headers, timeout_seconds, matcher, block_on_failure | Send HTTP request |
-| `agent` | prompt | model, timeout_seconds, matcher, block_on_failure | Use Agent for verification |
+| Type | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `command` | `command` | `if`, `shell`, `timeout`, `statusMessage`, `once`, `async`, `asyncRewake` | Execute Shell command |
+| `prompt` | `prompt` | `if`, `model`, `timeout`, `statusMessage`, `once` | Use LLM for verification |
+| `http` | `url` | `if`, `timeout`, `headers`, `allowedEnvVars`, `statusMessage`, `once` | Send HTTP POST request |
+| `agent` | `prompt` | `if`, `model`, `timeout`, `statusMessage`, `once` | Use Agent for verification |
+
+#### Common Hook Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `if` | string | Permission rule syntax filter (e.g. `"Bash(git *)"`) |
+| `timeout` | int | Timeout in seconds |
+| `once` | bool | If true, hook runs once then auto-removes |
+| `statusMessage` | string | Custom spinner message while hook runs |
+
+#### Command Hook Environment Variables
+
+Command hooks receive these environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDE_PROJECT_DIR` | Current working directory |
+| `CLAUDE_SESSION_ID` | Current session ID |
+| `CLAUDE_PLUGIN_ROOT` | Plugin installation directory (if from plugin) |
+| `CLAUDE_PLUGIN_DATA` | Plugin data directory |
+| `CLAUDE_ENV_FILE` | Write bash exports here to apply env to subsequent commands |
+
+Use `$ARGUMENTS` in the command string to inject the hook input JSON.
 
 ---
 
@@ -1129,46 +1215,307 @@ Supported environment variables:
 
 ### Sandbox Configuration
 
+The sandbox system provides OS-level isolation for shell commands, restricting filesystem and network access. Built with a Python-native runtime, it supports three platforms:
+
+| Platform | Isolation Mechanism | Dependencies |
+|----------|-------------------|--------------|
+| Linux / WSL | bubblewrap (bwrap) + optional seccomp | `bwrap`, `socat` (for network isolation) |
+| macOS | Apple Seatbelt (sandbox-exec) | Built-in |
+| Windows | Job Objects + Restricted Tokens + Low Integrity | `pywin32` |
+
+#### Basic Configuration
+
 ```json
 {
   "sandbox": {
     "enabled": true,
     "fail_if_unavailable": false,
-    "enabled_platforms": ["linux", "darwin"],
+    "auto_allow_bash_if_sandboxed": true,
+    "allow_unsandboxed_commands": true,
+    "enabled_platforms": [],
+    "excluded_commands": []
+  }
+}
+```
+
+#### Main Settings Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `bool` | `false` | Enable sandbox. When enabled, shell commands run in an isolated environment with filesystem and network access constrained by `filesystem` and `network` settings |
+| `fail_if_unavailable` | `bool` | `false` | Exit with error if sandbox cannot start. When `true`, the program exits if dependencies like `bwrap`/`sandbox-exec`/`pywin32` are missing, instead of running without sandbox |
+| `auto_allow_bash_if_sandboxed` | `bool` | `true` | Auto-allow bash commands when sandboxed. When `false`, each bash command requires manual user confirmation |
+| `allow_unsandboxed_commands` | `bool` | `true` | Allow LLM to use `dangerouslyDisableSandbox: true` to bypass sandbox. When `false`, the LLM cannot bypass sandbox restrictions |
+| `enabled_platforms` | `list[str]` | `[]` | Restrict sandbox to specific platforms (empty list = all platforms). Options: `linux`, `macos`, `windows`, `wsl`. Example: `["linux", "wsl"]` enables sandbox only on Linux and WSL |
+| `excluded_commands` | `list[str]` | `[]` | Command patterns to exclude from sandboxing. Matched commands skip sandbox wrapping and execute directly (see excluded commands section below) |
+| `ignore_violations` | `dict` | `{}` | Violation ignore rules. Format: `{"command_pattern": ["path1", "path2"]}`. Matching violations are not recorded or reported |
+| `enable_weaker_nested_sandbox` | `bool` | `false` | Set to `true` when running inside Docker containers to skip `--proc /proc` mount and avoid nested sandbox conflicts |
+| `mandatory_deny_search_depth` | `int` | `3` | Max directory depth for searching dangerous files (e.g., `.bashrc`, `.gitconfig`) in project subdirectories. Range 1-10, only effective when `deny_write`/`deny_read` are configured |
+| `allow_git_config` | `bool` | `false` | Allow writes to `.git/config` files. By default, `.git/config` is protected to prevent malicious git configuration changes |
+
+#### Network Configuration
+
+```json
+{
+  "sandbox": {
     "network": {
-      "allowed_domains": ["api.anthropic.com"],
-      "denied_domains": ["internal.company.com"]
-    },
+      "allowed_domains": ["api.anthropic.com", "*.github.com"],
+      "denied_domains": ["malicious.example.com"],
+      "allow_unix_sockets": [],
+      "allow_all_unix_sockets": false,
+      "allow_local_binding": false,
+      "http_proxy_port": null,
+      "socks_proxy_port": null
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `allowed_domains` | `list[str]` | `[]` | Allowed domains for network access (supports `*.example.com` wildcards). Unmatched domains trigger a confirmation prompt. On Linux, enforced via HTTP/SOCKS5 proxy + `--unshare-net`; on macOS via Seatbelt `allow network*` |
+| `denied_domains` | `list[str]` | `[]` | Denied domains for network access. Matched domains are blocked immediately without confirmation. Takes priority over `allowed_domains` |
+| `allow_unix_sockets` | `list[str]` | `[]` | macOS only: list of allowed Unix socket paths. Used to allow specific inter-process communication |
+| `allow_all_unix_sockets` | `bool` | `false` | Allow all Unix socket connections. Setting to `true` disables seccomp AF_UNIX blocking on Linux, allowing processes inside the sandbox to create Unix sockets freely |
+| `allow_local_binding` | `bool` | `false` | Allow processes inside the sandbox to bind to local ports. By default, sandbox blocks all port binding to prevent port conflicts and security risks |
+| `http_proxy_port` | `int?` | `null` | Use an external HTTP proxy port instead of starting a local proxy. Useful in environments with existing proxy infrastructure |
+| `socks_proxy_port` | `int?` | `null` | Use an external SOCKS5 proxy port instead of starting a local proxy |
+
+> **Domain validation rules**:
+> - Rejects overly broad patterns like `*` or `*.com`
+> - `*.example.com` requires at least 2 dot-separated parts after `*.`
+> - Rejects patterns containing `://`, `/`, or `:`
+> - `localhost` is always allowed
+
+#### Filesystem Configuration
+
+```json
+{
+  "sandbox": {
     "filesystem": {
-      "allow_read": ["./src", "./docs"],
+      "allow_write": [".", "./output"],
+      "deny_write": [".git/hooks", ".env"],
       "deny_read": ["./secrets"],
-      "allow_write": ["./output"],
-      "deny_write": ["./.git"]
+      "allow_read": ["./secrets/public"]
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `allow_write` | `list[str]` | `["."]` | Paths allowed for writing. On Linux/macOS, enforced at OS level via bwrap `--bind`/Seatbelt `allow file-write*`; on Windows, only checked at application layer |
+| `deny_write` | `list[str]` | `[]` | Paths denied for writing, takes priority over `allow_write`. Shows three-option confirmation dialog on match. On Linux, blocked via `--ro-bind /dev/null` mount; on macOS, blocked via Seatbelt `deny file-write*` |
+| `deny_read` | `list[str]` | `[]` | Paths denied for reading. Shows three-option confirmation dialog (Allow / Allow for session / Deny) on match. Affects `read_file`, `grep`, `glob`, `lsp` and other tools |
+| `allow_read` | `list[str]` | `[]` | Paths re-allowed for reading within denied regions. Example: `deny_read: ["~/.ssh"]` + `allow_read: ["~/.ssh/known_hosts"]` allows reading the known_hosts file |
+
+#### Excluded Commands
+
+`excluded_commands` supports three matching patterns:
+
+```json
+{
+  "sandbox": {
+    "excluded_commands": [
+      "npm test",
+      "make:*",
+      "git status"
+    ]
+  }
+}
+```
+
+| Pattern | Example | Matches |
+|---------|---------|---------|
+| Exact match | `"npm test"` | `npm test` |
+| Wildcard | `"make:*"` | `make:build`, `make:clean` |
+| Prefix match | `"git push"` | `git push origin main` |
+
+The system automatically splits compound commands (`&&`, `||`, `;`, `|`) and strips environment variable prefixes (`FOO=bar cmd` → `cmd`) and safe wrappers (`sudo`, `env`, `time`) to prevent bypass via `safe_cmd && evil_cmd`.
+
+#### Sandbox Blocking Behavior
+
+When an LLM operation triggers a sandbox restriction (e.g., reading a file in `deny_read`), the system shows a three-option confirmation dialog:
+
+```
+┌─────────────────────────────────────────────┐
+│ Allow access to 'E:\PyCode\API.txt'?       │
+│                                             │
+│  1. Allow              (single operation)   │
+│  2. Allow for session  (resets on restart)  │
+│  3. Deny               (block operation)    │
+└─────────────────────────────────────────────┘
+```
+
+| Option | Effect | Persistence |
+|--------|--------|-------------|
+| Allow | Allow this single operation | One-time only |
+| Allow for session | Allow this path for the current session | Resets on restart |
+| Deny | Block the operation, return error to LLM | None |
+
+> **Difference from `permission.denied_tools`**:
+> - `sandbox.filesystem.deny_read` → Shows three-option confirmation dialog, user can choose to allow
+> - `permission.denied_tools` → Hard deny, terminates operation immediately with no confirmation
+
+#### Filesystem Restriction Effects
+
+| Field | Affected Tools | Enforcement Level |
+|-------|---------------|-------------------|
+| `deny_read` | `read_file`, `grep`, `glob`, `lsp` | Permission checker (application layer) |
+| `deny_write` | `edit`, `write`, `bash` (write ops) | Permission checker + OS-level sandbox |
+| `allow_write` | `bash` (write ops) | OS-level sandbox (bwrap/Seatbelt) |
+
+- **Linux/macOS**: `deny_write` is enforced at both application layer and OS level (bwrap `--ro-bind`, Seatbelt `deny file-write*`)
+- **Windows**: Only enforced at application layer (Job Objects don't provide filesystem isolation)
+
+#### Full Example
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "fail_if_unavailable": true,
+    "auto_allow_bash_if_sandboxed": true,
+    "allow_unsandboxed_commands": true,
+    "excluded_commands": ["git status", "git log", "git diff"],
+    "network": {
+      "allowed_domains": ["*.github.com", "*.npmjs.org", "pypi.org", "*.pypi.org"]
+    },
+    "filesystem": {
+      "allow_write": ["."],
+      "deny_write": [".git/hooks", ".env", ".env.*"],
+      "deny_read": ["~/.ssh", "~/.gnupg"]
     }
   }
 }
 ```
 
+#### Environment Variable Overrides
+
+| Environment Variable | Overrides |
+|---------------------|-----------|
+| `ILLUSION_SANDBOX_ENABLED` | `sandbox.enabled` (`1`/`true`/`yes`/`on` = true) |
+| `ILLUSION_SANDBOX_FAIL_IF_UNAVAILABLE` | `sandbox.fail_if_unavailable` |
+
+#### /sandbox Command
+
+| Command | Description |
+|---------|-------------|
+| `/sandbox` or `/sandbox status` | Show current sandbox status |
+| `/sandbox exclude <pattern>` | Add an excluded command pattern |
+
 ---
 
 ## 🔌 Extension Development
 
-### Hook System
+### Plugin System
 
-Supports multiple hook types:
+Plugins extend IllusionCode with skills, hooks, commands, and MCP servers. Plugin format is fully aligned with Claude Code.
 
-- `PRE_TOOL_USE` - Before tool execution
-- `POST_TOOL_USE` - After tool execution
-- `USER_PROMPT_SUBMIT` - After user prompt submission
+#### Plugin Directory Structure
 
-### Plugin System
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin manifest
+├── skills/                  # Skills (subdirs with SKILL.md)
+│   ├── my-skill/
+│   │   └── SKILL.md
+│   └── another-skill.md
+├── commands/                # Slash commands (.md files)
+├── agents/                  # Agent definitions (.md files)
+├── hooks/
+│   └── hooks.json           # Hook definitions
+├── .mcp.json                # MCP server configuration
+└── settings.json            # Plugin default settings
+```
+
+#### Plugin Manifest (plugin.json)
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "My custom plugin",
+  "enabled_by_default": true,
+  "skills_dir": "skills",
+  "hooks_file": "hooks.json"
+}
+```
+
+#### Plugin Installation
+
+```bash
+# Install from local path
+illusion plugin install /path/to/my-plugin
+
+# List installed plugins
+illusion plugin list
+
+# Enable/disable
+illusion plugin enable my-plugin
+illusion plugin disable my-plugin
+
+# Uninstall
+illusion plugin uninstall my-plugin
+```
+
+Plugins are installed to `~/.illusion/plugins/` (user-level) or `.illusion/plugins/` (project-level).
+
+#### Plugin Hooks (hooks/hooks.json)
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/init.cmd\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Plugin hooks support `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}` variable substitution.
+
+#### Skill Frontmatter
 
-Defined through `plugin.json` manifest:
+Skills defined in SKILL.md files support these frontmatter fields:
+
+```yaml
+---
+description: What this skill does
+allowed-tools: Bash, Read, Write
+model: claude-sonnet-4-6
+context: fork
+effort: high
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: echo check
+---
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | string | Skill description (shown in skill list) |
+| `allowed-tools` | string | Comma-separated list of allowed tools |
+| `model` | string | Model override for this skill |
+| `context` | string | `inline` (expand into conversation) or `fork` (sub-agent) |
+| `effort` | string | Reasoning effort override |
+| `hooks` | object | Hooks to register when skill is invoked |
+
+### Hook System
 
-- Skills
-- Commands
-- Hooks
-- MCP Servers
+See [Hook Configuration](#hook-configuration) for the full hook documentation with 27 events and matcher-based format.
 
 ## 🧪 Development & Testing