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

agent_dispatch-0.2.0/.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.0}/.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.0}/.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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.1.0
+Version: 0.2.0
 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.0}/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.0/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.0/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.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.1.0"
+version = "0.2.0"
 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.0}/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.0"

{agent_dispatch-0.1.0 → agent_dispatch-0.2.0}/src/agent_dispatch/cli.py

@@ -10,7 +10,7 @@ from pathlib import Path
 import click
 
 from .config import auto_describe, config_path, load_config, save_config
-from .models import AgentConfig, DispatchConfig, validate_agent_name
+from .models import AgentConfig, DispatchConfig, check_permission_mode, validate_agent_name
 
 
 @click.group()
@@ -76,12 +76,29 @@ def init() -> None:
 @click.option("-d", "--description", default=None, help="Agent description. Auto-generated if omitted.")
 @click.option("--timeout", default=300, help="Timeout in seconds (default: 300).")
 @click.option("--model", default=None, help="Model override for this agent.")
+@click.option("--max-budget", default=None, type=float, help="Max cost in USD per dispatch.")
+@click.option(
+    "--permission-mode", default=None,
+    help="Permission mode for claude CLI (e.g. default, plan, bypassPermissions).",
+)
+@click.option(
+    "--allowed-tools", default=None,
+    help="Comma-separated list of allowed tools (e.g. Bash,Read,Edit).",
+)
+@click.option(
+    "--disallowed-tools", default=None,
+    help="Comma-separated list of disallowed tools.",
+)
 def add(
     name: str,
     directory: str,
     description: str | None,
     timeout: int,
     model: str | None,
+    max_budget: float | None,
+    permission_mode: str | None,
+    allowed_tools: str | None,
+    disallowed_tools: str | None,
 ) -> None:
     """Add an agent. Auto-generates description from project files if omitted."""
     try:
@@ -106,7 +123,16 @@ def add(
         description=description,
         timeout=timeout,
         model=model,
+        max_budget_usd=max_budget,
+        permission_mode=permission_mode,
+        allowed_tools=[t.strip() for t in allowed_tools.split(",") if t.strip()]
+        if allowed_tools else [],
+        disallowed_tools=[t.strip() for t in disallowed_tools.split(",") if t.strip()]
+        if disallowed_tools else [],
     )
+    if warning := check_permission_mode(permission_mode):
+        click.echo(click.style(f"Warning: {warning}", fg="yellow"))
+
     save_config(config)
     click.echo(f"Added agent '{name}' -> {dir_path}")
 
@@ -139,9 +165,104 @@ def list_agents() -> None:
         click.echo(f"  {name} [{status}]")
         click.echo(f"    dir:  {agent.directory}")
         click.echo(f"    desc: {agent.description}")
+        extras: list[str] = []
+        if agent.timeout != 300:
+            extras.append(f"timeout={agent.timeout}s")
+        if agent.model:
+            extras.append(f"model={agent.model}")
+        if agent.max_budget_usd:
+            extras.append(f"budget=${agent.max_budget_usd}")
+        if extras:
+            click.echo(f"    config: {', '.join(extras)}")
+        if agent.permission_mode:
+            click.echo(f"    permission_mode: {agent.permission_mode}")
+        if agent.allowed_tools:
+            click.echo(f"    allowed_tools: {', '.join(agent.allowed_tools)}")
+        if agent.disallowed_tools:
+            click.echo(f"    disallowed_tools: {', '.join(agent.disallowed_tools)}")
         click.echo()
 
 
+@cli.command()
+@click.argument("name")
+@click.option("-d", "--description", default=None, help="New description.")
+@click.option("--timeout", default=None, type=int, help="Timeout in seconds.")
+@click.option("--model", default=None, help="Model override.")
+@click.option("--max-budget", default=None, type=float, help="Max cost in USD. Use 0 to clear.")
+@click.option(
+    "--permission-mode", default=None,
+    help="Permission mode (default, plan, bypassPermissions). Use 'none' to clear.",
+)
+@click.option(
+    "--allowed-tools", default=None,
+    help="Comma-separated allowed tools. Use 'none' to clear.",
+)
+@click.option(
+    "--disallowed-tools", default=None,
+    help="Comma-separated disallowed tools. Use 'none' to clear.",
+)
+@click.pass_context
+def update(
+    ctx: click.Context,
+    name: str,
+    description: str | None,
+    timeout: int | None,
+    model: str | None,
+    max_budget: float | None,
+    permission_mode: str | None,
+    allowed_tools: str | None,
+    disallowed_tools: str | None,
+) -> None:
+    """Update an existing agent's configuration."""
+    config = load_config()
+    if name not in config.agents:
+        click.echo(f"Agent '{name}' not found. Run 'agent-dispatch list' to see agents.")
+        raise SystemExit(1)
+
+    agent = config.agents[name]
+    updated: list[str] = []
+
+    if description is not None:
+        agent.description = description
+        updated.append("description")
+    if timeout is not None:
+        agent.timeout = timeout
+        updated.append("timeout")
+    if model is not None:
+        agent.model = None if model.lower() == "none" else model
+        updated.append("model")
+    if max_budget is not None:
+        agent.max_budget_usd = None if max_budget == 0 else max_budget
+        updated.append("max_budget_usd")
+    if permission_mode is not None:
+        effective = None if permission_mode.lower() == "none" else permission_mode
+        agent.permission_mode = effective
+        if warning := check_permission_mode(effective):
+            click.echo(click.style(f"Warning: {warning}", fg="yellow"))
+        updated.append("permission_mode")
+    if allowed_tools is not None:
+        if allowed_tools.lower() == "none":
+            agent.allowed_tools = []
+        else:
+            agent.allowed_tools = [t.strip() for t in allowed_tools.split(",") if t.strip()]
+        updated.append("allowed_tools")
+    if disallowed_tools is not None:
+        if disallowed_tools.lower() == "none":
+            agent.disallowed_tools = []
+        else:
+            agent.disallowed_tools = [
+                t.strip() for t in disallowed_tools.split(",") if t.strip()
+            ]
+        updated.append("disallowed_tools")
+
+    if not updated:
+        click.echo("Nothing to update. Pass at least one option (see --help).")
+        raise SystemExit(1)
+
+    save_config(config)
+    click.echo(f"Updated agent '{name}': {', '.join(updated)}")
+
+
 @cli.command()
 @click.argument("name")
 @click.argument("task", default="What project is this? Describe in one sentence.")
@@ -167,6 +288,16 @@ def test(name: str, task: str) -> None:
             click.echo(f"\n--- Cost: ${result.cost_usd:.4f} | Turns: {result.num_turns}")
     else:
         click.echo(click.style(f"Error: {result.error}", fg="red"))
+        if result.error_type == "permission":
+            click.echo()
+            click.echo(click.style("Diagnosis: permission error", fg="yellow"))
+            click.echo("The agent was denied a tool or action. To fix:")
+            click.echo(f"  agent-dispatch update {name} --permission-mode bypassPermissions")
+            click.echo(f"  agent-dispatch update {name} --allowed-tools Bash,Read,Edit,Write")
+        elif result.error_type == "timeout":
+            click.echo()
+            click.echo(click.style("Diagnosis: timeout", fg="yellow"))
+            click.echo(f"  agent-dispatch update {name} --timeout 600")
         raise SystemExit(1)
 
 

{agent_dispatch-0.1.0 → agent_dispatch-0.2.0}/src/agent_dispatch/config.py

@@ -56,7 +56,7 @@ def _collect_mcp_servers(directory: Path) -> list[str]:
                 data = json.loads(path.read_text(encoding="utf-8"))
                 servers.extend(data.get("mcpServers", {}).keys())
             except (json.JSONDecodeError, KeyError):
-                pass
+                logger.debug("Failed to parse MCP config: %s", path)
     return list(dict.fromkeys(servers))  # deduplicate, preserve order
 
 
@@ -115,7 +115,7 @@ def auto_describe(directory: Path) -> str:
             if pkg.get("description"):
                 parts.append(pkg["description"])
         except (json.JSONDecodeError, KeyError):
-            pass
+            logger.debug("Failed to parse package.json: %s", pkg_json)
 
     # MCP servers — critical for understanding what tools this agent has
     servers = _collect_mcp_servers(directory)

{agent_dispatch-0.1.0 → agent_dispatch-0.2.0}/src/agent_dispatch/models.py

@@ -8,6 +8,18 @@ from pydantic import BaseModel, Field, field_validator
 
 _AGENT_NAME_PATTERN = r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$"
 
+KNOWN_PERMISSION_MODES = frozenset({
+    "default", "plan", "bypassPermissions",
+})
+
+
+def check_permission_mode(mode: str | None) -> str | None:
+    """Return a warning message if mode is unknown, else None."""
+    if mode and mode not in KNOWN_PERMISSION_MODES:
+        known = ", ".join(sorted(KNOWN_PERMISSION_MODES))
+        return f"Unknown permission_mode: {mode!r}. Known values: {known}"
+    return None
+
 
 class AgentConfig(BaseModel):
     """Configuration for a single agent."""
@@ -46,6 +58,9 @@ class Settings(BaseModel):
 
     default_timeout: int = 300
     default_max_budget_usd: float | None = None
+    default_permission_mode: str | None = None
+    default_allowed_tools: list[str] = Field(default_factory=list)
+    default_disallowed_tools: list[str] = Field(default_factory=list)
     max_dispatch_depth: int = Field(default=3, ge=1)
     max_concurrency: int = Field(default=5, ge=1)
     cache: CacheSettings = Field(default_factory=CacheSettings)
@@ -82,3 +97,4 @@ class DispatchResult(BaseModel):
     duration_ms: int | None = None
     num_turns: int | None = None
     error: str | None = None
+    error_type: str | None = None  # permission, timeout, recursion, not_found, cli_error