agent-dispatch 0.1.0__tar.gz → 0.2.1__tar.gz

agent_dispatch-0.2.1/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

{agent_dispatch-0.1.0 → agent_dispatch-0.2.1}/.github/workflows/ci.yml

@@ -14,9 +14,9 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: ${{ matrix.python-version }}
 

{agent_dispatch-0.1.0 → agent_dispatch-0.2.1}/.github/workflows/publish.yml

@@ -11,9 +11,9 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: "3.12"
 
@@ -23,4 +23,4 @@ jobs:
           python -m build
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

{agent_dispatch-0.1.0 → agent_dispatch-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.1.0
+Version: 0.2.1
 Summary: MCP server that lets Claude Code agents delegate tasks to agents in other project directories
 Project-URL: Homepage, https://github.com/ginkida/agent-dispatch
 Project-URL: Repository, https://github.com/ginkida/agent-dispatch
@@ -30,8 +30,17 @@ Description-Content-Type: text/markdown
 
 # agent-dispatch
 
+[![PyPI](https://img.shields.io/pypi/v/agent-dispatch)](https://pypi.org/project/agent-dispatch/)
+[![CI](https://github.com/ginkida/agent-dispatch/actions/workflows/ci.yml/badge.svg)](https://github.com/ginkida/agent-dispatch/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/agent-dispatch)](https://pypi.org/project/agent-dispatch/)
+[![License](https://img.shields.io/github/license/ginkida/agent-dispatch)](LICENSE)
+
 **MCP server that lets Claude Code agents delegate tasks to agents in other project directories.**
 
+<p align="center">
+  <img src="assets/mascot.png" alt="agent-dispatch mascot" width="600">
+</p>
+
 Each agent runs as a separate `claude -p` session in its own project directory — inheriting that project's MCP servers, CLAUDE.md, and tools. The calling agent just gets the result back.
 
 Works with OAuth, API key, and Claude subscription authentication.
@@ -50,6 +59,9 @@ agent-dispatch add backend ~/projects/backend
 
 # Test it works
 agent-dispatch test infra
+
+# If agents hit permission errors, grant tool access:
+agent-dispatch update infra --permission-mode bypassPermissions
 ```
 
 Done. Every Claude Code session now has access to all dispatch tools.
@@ -70,7 +82,7 @@ Done. Every Claude Code session now has access to all dispatch tools.
 Lists all configured agents. **Call this first** to see what's available.
 
 ```json
-// Response
+// Response (permission fields shown only when configured)
 [
   {
     "name": "infra",
@@ -78,7 +90,9 @@ Lists all configured agents. **Call this first** to see what's available.
     "description": "Infrastructure agent. MCP: portainer. Stack: Python, Docker",
     "healthy": true,
     "has_claude_md": true,
-    "has_mcp_config": true
+    "has_mcp_config": true,
+    "permission_mode": "bypassPermissions",
+    "allowed_tools": ["Bash", "Read", "Grep"]
   }
 ]
 ```
@@ -96,7 +110,7 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `goal` | string | no | Broader objective — helps the agent make better trade-offs |
 
 ```json
-// Response
+// Response (success)
 {
   "agent": "infra",
   "success": true,
@@ -106,8 +120,19 @@ One-shot task delegation. Results are cached — identical requests within TTL r
   "duration_ms": 5000,
   "num_turns": 2
 }
+
+// Response (failure — error_type helps you handle programmatically)
+{
+  "agent": "infra",
+  "success": false,
+  "result": "",
+  "error": "Tool_use is not allowed in this permission mode\n\nHint: ...",
+  "error_type": "permission"
+}
 ```
 
+**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `cli_error` (other failures). Permission errors include an actionable hint.
+
 **Always pass `caller` and `goal`** — the dispatched agent sees a structured prompt:
 
 ```markdown
@@ -231,6 +256,24 @@ Register a new project directory as an agent. Description is auto-generated from
 | `name` | string | yes | Agent name (letters, digits, hyphens, underscores) |
 | `directory` | string | yes | Absolute path to project directory |
 | `description` | string | no | What this agent can do — auto-generated if empty |
+| `timeout` | int | no | Timeout in seconds (0 = use global default) |
+| `permission_mode` | string | no | Permission mode (e.g. `default`, `plan`, `bypassPermissions`) |
+| `allowed_tools` | string | no | Comma-separated allowed tools (e.g. `"Bash,Read,Edit"`) |
+| `disallowed_tools` | string | no | Comma-separated disallowed tools |
+
+### `update_agent`
+
+Update an existing agent's configuration. Only non-empty fields are changed. Pass `"none"` to clear a field.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | yes | Agent name to update |
+| `description` | string | no | New description |
+| `timeout` | int | no | New timeout (0 = don't change) |
+| `model` | string | no | Model override. `"none"` to clear |
+| `permission_mode` | string | no | Permission mode. `"none"` to clear |
+| `allowed_tools` | string | no | Comma-separated. `"none"` to clear |
+| `disallowed_tools` | string | no | Comma-separated. `"none"` to clear |
 
 ### `remove_agent`
 
@@ -284,6 +327,11 @@ agents:
 
 settings:
   default_timeout: 300
+  # default_permission_mode: bypassPermissions  # inherited by all agents
+  # default_allowed_tools:                      # inherited when agent has none
+  #   - Bash
+  #   - Read
+  #   - Edit
   max_dispatch_depth: 3     # recursion protection
   max_concurrency: 5        # max parallel claude -p processes
   cache:
@@ -338,8 +386,9 @@ agent-dispatch MCP server
 |---------|-------------|
 | `agent-dispatch init` | Create config + register MCP server with Claude Code |
 | `agent-dispatch add <name> <dir>` | Add an agent (auto-generates description) |
+| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, etc.) |
 | `agent-dispatch remove <name>` | Remove an agent |
-| `agent-dispatch list` | List agents with health status |
+| `agent-dispatch list` | List agents with health status and permissions |
 | `agent-dispatch test <name> [task]` | Test an agent with a dispatch |
 | `agent-dispatch serve` | Start MCP server (stdio, used by Claude Code) |
 

{agent_dispatch-0.1.0 → agent_dispatch-0.2.1}/README.md

@@ -1,7 +1,16 @@
 # agent-dispatch
 
+[![PyPI](https://img.shields.io/pypi/v/agent-dispatch)](https://pypi.org/project/agent-dispatch/)
+[![CI](https://github.com/ginkida/agent-dispatch/actions/workflows/ci.yml/badge.svg)](https://github.com/ginkida/agent-dispatch/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/agent-dispatch)](https://pypi.org/project/agent-dispatch/)
+[![License](https://img.shields.io/github/license/ginkida/agent-dispatch)](LICENSE)
+
 **MCP server that lets Claude Code agents delegate tasks to agents in other project directories.**
 
+<p align="center">
+  <img src="assets/mascot.png" alt="agent-dispatch mascot" width="600">
+</p>
+
 Each agent runs as a separate `claude -p` session in its own project directory — inheriting that project's MCP servers, CLAUDE.md, and tools. The calling agent just gets the result back.
 
 Works with OAuth, API key, and Claude subscription authentication.
@@ -20,6 +29,9 @@ agent-dispatch add backend ~/projects/backend
 
 # Test it works
 agent-dispatch test infra
+
+# If agents hit permission errors, grant tool access:
+agent-dispatch update infra --permission-mode bypassPermissions
 ```
 
 Done. Every Claude Code session now has access to all dispatch tools.
@@ -40,7 +52,7 @@ Done. Every Claude Code session now has access to all dispatch tools.
 Lists all configured agents. **Call this first** to see what's available.
 
 ```json
-// Response
+// Response (permission fields shown only when configured)
 [
   {
     "name": "infra",
@@ -48,7 +60,9 @@ Lists all configured agents. **Call this first** to see what's available.
     "description": "Infrastructure agent. MCP: portainer. Stack: Python, Docker",
     "healthy": true,
     "has_claude_md": true,
-    "has_mcp_config": true
+    "has_mcp_config": true,
+    "permission_mode": "bypassPermissions",
+    "allowed_tools": ["Bash", "Read", "Grep"]
   }
 ]
 ```
@@ -66,7 +80,7 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `goal` | string | no | Broader objective — helps the agent make better trade-offs |
 
 ```json
-// Response
+// Response (success)
 {
   "agent": "infra",
   "success": true,
@@ -76,8 +90,19 @@ One-shot task delegation. Results are cached — identical requests within TTL r
   "duration_ms": 5000,
   "num_turns": 2
 }
+
+// Response (failure — error_type helps you handle programmatically)
+{
+  "agent": "infra",
+  "success": false,
+  "result": "",
+  "error": "Tool_use is not allowed in this permission mode\n\nHint: ...",
+  "error_type": "permission"
+}
 ```
 
+**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `cli_error` (other failures). Permission errors include an actionable hint.
+
 **Always pass `caller` and `goal`** — the dispatched agent sees a structured prompt:
 
 ```markdown
@@ -201,6 +226,24 @@ Register a new project directory as an agent. Description is auto-generated from
 | `name` | string | yes | Agent name (letters, digits, hyphens, underscores) |
 | `directory` | string | yes | Absolute path to project directory |
 | `description` | string | no | What this agent can do — auto-generated if empty |
+| `timeout` | int | no | Timeout in seconds (0 = use global default) |
+| `permission_mode` | string | no | Permission mode (e.g. `default`, `plan`, `bypassPermissions`) |
+| `allowed_tools` | string | no | Comma-separated allowed tools (e.g. `"Bash,Read,Edit"`) |
+| `disallowed_tools` | string | no | Comma-separated disallowed tools |
+
+### `update_agent`
+
+Update an existing agent's configuration. Only non-empty fields are changed. Pass `"none"` to clear a field.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | yes | Agent name to update |
+| `description` | string | no | New description |
+| `timeout` | int | no | New timeout (0 = don't change) |
+| `model` | string | no | Model override. `"none"` to clear |
+| `permission_mode` | string | no | Permission mode. `"none"` to clear |
+| `allowed_tools` | string | no | Comma-separated. `"none"` to clear |
+| `disallowed_tools` | string | no | Comma-separated. `"none"` to clear |
 
 ### `remove_agent`
 
@@ -254,6 +297,11 @@ agents:
 
 settings:
   default_timeout: 300
+  # default_permission_mode: bypassPermissions  # inherited by all agents
+  # default_allowed_tools:                      # inherited when agent has none
+  #   - Bash
+  #   - Read
+  #   - Edit
   max_dispatch_depth: 3     # recursion protection
   max_concurrency: 5        # max parallel claude -p processes
   cache:
@@ -308,8 +356,9 @@ agent-dispatch MCP server
 |---------|-------------|
 | `agent-dispatch init` | Create config + register MCP server with Claude Code |
 | `agent-dispatch add <name> <dir>` | Add an agent (auto-generates description) |
+| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, etc.) |
 | `agent-dispatch remove <name>` | Remove an agent |
-| `agent-dispatch list` | List agents with health status |
+| `agent-dispatch list` | List agents with health status and permissions |
 | `agent-dispatch test <name> [task]` | Test an agent with a dispatch |
 | `agent-dispatch serve` | Start MCP server (stdio, used by Claude Code) |
 

agent_dispatch-0.2.1/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it via [GitHub Security Advisories](https://github.com/ginkida/agent-dispatch/security/advisories/new).
+
+**Do not** open a public issue for security vulnerabilities.
+
+## Scope
+
+`agent-dispatch` runs `claude -p` subprocesses in configured directories. Security-relevant areas:
+
+- **Command injection** — task/context strings are passed as CLI arguments, not shell-evaluated
+- **Directory traversal** — agent directories are resolved to absolute paths via `Path.resolve()`
+- **Recursion** — `AGENT_DISPATCH_DEPTH` env var prevents infinite dispatch loops
+- **Cost** — `max_budget_usd` limits spending per dispatch
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes       |

agent_dispatch-0.2.1/agents.example.yaml

@@ -0,0 +1,47 @@
+agents:
+  # Infrastructure agent — has Portainer MCP for container management
+  infra:
+    directory: ~/projects/infra
+    description: "Infrastructure agent. MCP servers: portainer. Can check container logs, restart services, inspect Docker state."
+    timeout: 300
+
+  # Backend agent — source code, tests, database
+  backend:
+    directory: ~/projects/backend
+    description: "Backend API agent. Python, FastAPI, PostgreSQL. Can modify code, run tests, check migrations."
+    timeout: 300
+    model: null  # use default model
+
+  # Agent with permission controls — useful when you want to restrict tool access
+  staging-db:
+    directory: ~/projects/staging-db
+    description: "Read-only database agent. Can query staging DB but not modify data."
+    timeout: 120
+    permission_mode: bypassPermissions  # skip permission prompts (agent runs non-interactively)
+    allowed_tools:                      # only these tools are available
+      - Read
+      - Grep
+      - Bash
+    # disallowed_tools:                 # alternatively, block specific tools
+    #   - Write
+    #   - Edit
+
+  # Frontend agent
+  # frontend:
+  #   directory: ~/projects/frontend
+  #   description: "Frontend React app. Can modify components, run build, check TypeScript errors."
+  #   timeout: 180
+
+settings:
+  default_timeout: 300
+  max_dispatch_depth: 3           # recursion protection: A -> B -> A
+  max_concurrency: 5              # max parallel claude -p processes
+  # default_max_budget_usd: 1.0   # cost limit per dispatch (all agents)
+  # default_permission_mode: bypassPermissions  # inherited by agents without override
+  # default_allowed_tools:         # inherited by agents without override
+  #   - Bash
+  #   - Read
+  #   - Edit
+  cache:
+    enabled: true
+    ttl: 300                       # seconds; identical (agent, task, context) requests are cached

{agent_dispatch-0.1.0 → agent_dispatch-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.1.0"
+version = "0.2.1"
 description = "MCP server that lets Claude Code agents delegate tasks to agents in other project directories"
 readme = "README.md"
 license = "MIT"

{agent_dispatch-0.1.0 → agent_dispatch-0.2.1}/src/agent_dispatch/__init__.py

@@ -1,3 +1,3 @@
 """agent-dispatch: Delegate tasks between Claude Code agents across projects."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"