@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/extensions/plugin-dev/skills/agent-development/references/advanced-agent-fields.md

@@ -0,0 +1,246 @@
+# Advanced Agent Fields
+
+This reference covers agent frontmatter fields beyond the core fields (name, description, model, color, tools, disallowedTools, skills, permissionMode). These enable turn limits, persistent memory, scoped MCP access, lifecycle hooks, and advanced execution patterns.
+
+## maxTurns
+
+Limit the maximum number of agentic turns (API round-trips) before the agent stops.
+
+```yaml
+maxTurns: 50
+```
+
+### Choosing Values
+
+| Task Type                     | Suggested Range | Rationale                       |
+| ----------------------------- | --------------- | ------------------------------- |
+| Quick checks, linting         | 5-15            | Focused, fast completion        |
+| Code review, analysis         | 20-40           | Needs to read multiple files    |
+| Complex refactoring, creation | 50-100          | Multi-file changes with testing |
+
+If omitted, the agent runs until it completes or is interrupted. Set `maxTurns` to prevent runaway agents from consuming excessive resources, especially for background agents where there's no user to interrupt.
+
+## memory
+
+Enable persistent memory that survives across sessions.
+
+```yaml
+memory: user
+```
+
+### Scopes
+
+| Scope     | Directory                                  | Use When                         |
+| --------- | ------------------------------------------ | -------------------------------- |
+| `user`    | `~/.claude/agent-memory/<agent-name>/`     | Personal preferences, defaults   |
+| `project` | `.claude/agent-memory/<agent-name>/`       | Codebase-specific knowledge      |
+| `local`   | `.claude/agent-memory-local/<agent-name>/` | Gitignored project-specific data |
+
+### How It Works
+
+When `memory` is set:
+
+1. System prompt includes instructions for reading/writing the memory directory
+2. First 200 lines of `MEMORY.md` are auto-injected into the agent's system prompt
+3. Read, Write, and Edit tools are automatically enabled (even if not in `tools` list)
+4. Agent should curate `MEMORY.md` if it exceeds 200 lines
+
+### Best Practices
+
+- Use `user` scope as the default for most agents
+- Use `project` or `local` for codebase-specific learning
+- Include memory management instructions in the agent's system prompt (e.g., "After completing a task, update your MEMORY.md with key learnings")
+
+## mcpServers
+
+Scope MCP servers to the agent, controlling which external services it can access.
+
+### Reference by Name
+
+Reference an already-configured MCP server:
+
+```yaml
+mcpServers:
+  slack:
+```
+
+The agent inherits the full configuration of the named server from the project/user MCP settings.
+
+### Inline Configuration
+
+Provide full server config scoped to the agent:
+
+```yaml
+mcpServers:
+  custom-api:
+    command: "${CLAUDE_PLUGIN_ROOT}/servers/api-server"
+    args: ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
+    env:
+      API_KEY: "${API_KEY}"
+```
+
+### Use Cases
+
+- Restrict a code review agent to only read-only MCP tools
+- Give a deployment agent access to CI/CD servers but not database servers
+- Provide agent-specific server configuration
+
+## hooks
+
+Define lifecycle hooks scoped to the agent. These hooks activate when the agent starts and deactivate when it finishes.
+
+### Format
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: Write
+      hooks:
+        - type: command
+          command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh"
+          timeout: 10
+  Stop:
+    - hooks:
+        - type: prompt
+          prompt: "Verify all tasks are complete before stopping."
+```
+
+### Supported Events
+
+All hook events are supported in agent frontmatter. Key behavior difference:
+
+- **`Stop`** hooks are automatically converted to **`SubagentStop`** at runtime, since agents are subprocesses
+- Hooks only run while the agent is active and are cleaned up when the agent finishes
+
+### Comparison with hooks.json
+
+| Aspect   | `hooks.json`                               | Agent frontmatter `hooks`                       |
+| -------- | ------------------------------------------ | ----------------------------------------------- |
+| Scope    | Global (always active when plugin enabled) | Agent-specific (active only during agent run)   |
+| Events   | All hook events                            | All events (Stop auto-converts to SubagentStop) |
+| Location | `hooks/hooks.json` file                    | YAML frontmatter in agent .md file              |
+| Use case | Plugin-wide validation                     | Agent-specific safety checks                    |
+
+## Execution Modes
+
+### Background vs Foreground
+
+- **Foreground** (default): Blocks the main conversation until the agent completes. User can interact if the agent requests permission.
+- **Background**: Runs concurrently with the main conversation. All permissions must be pre-approved at spawn time since the user cannot be prompted.
+
+Background agents that encounter an unapproved permission request will fail. Design tool restrictions (`tools`, `permissionMode`) accordingly when agents may run in background.
+
+### Resuming Agents
+
+Each Task tool invocation creates a new agent instance with a fresh context. To continue with the full prior context preserved, ask Claude to "resume that agent" or "continue that subagent" — it will restore the previous transcript.
+
+Agent transcripts are stored at `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl`.
+
+### Restricting Spawnable Agent Types
+
+Use `Task(agent_type1, agent_type2)` syntax in settings.json allow rules to control which agent types can be spawned:
+
+```json
+{
+  "permissions": {
+    "allow": ["Task(code-reviewer, test-runner)"]
+  }
+}
+```
+
+- `Task(type1, type2)` — only these agent types can be spawned
+- `Task` (no parentheses) — allow any subagent
+- Omitting `Task` entirely — cannot spawn any subagents
+
+## Built-in Agent Types
+
+Claude Code includes several built-in agent types that can be referenced in the `agent` field of skills or used as targets for `Task()` restrictions:
+
+| Agent Type          | Model   | Tools     | Purpose                             |
+| ------------------- | ------- | --------- | ----------------------------------- |
+| `Explore`           | Haiku   | Read-only | Fast codebase exploration/search    |
+| `Plan`              | Inherit | Read-only | Codebase research during planning   |
+| `general-purpose`   | Inherit | All       | Complex multi-step tasks            |
+| `Bash`              | Inherit | Bash      | Terminal commands in isolation      |
+| `statusline-setup`  | Haiku   | Read/Edit | Status line configuration           |
+| `Claude Code Guide` | Haiku   | Read-only | Documentation and feature questions |
+
+## Agent Teams (Experimental)
+
+Agent teams enable multi-agent coordination where a team lead spawns and manages multiple independent Claude Code sessions as teammates. This is an experimental feature requiring `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
+
+### Key Concepts
+
+- **Team lead**: Main session that creates the team, spawns teammates, and coordinates work
+- **Teammates**: Independent Claude Code instances with their own context windows
+- **Shared task list**: Coordinated work items that teammates claim and complete
+- **Messaging**: Direct messages and broadcasts between team members
+
+### Designing Team Lead Agents
+
+Team leads coordinate work across multiple teammates. Key design considerations:
+
+- **Use `permissionMode: delegate`** to restrict the lead to coordination-only tools (spawn, message, shut down teammates, manage tasks). This prevents the lead from implementing tasks directly.
+- **System prompt focus**: Task decomposition, work assignment, progress monitoring, quality review
+- **Tools**: Team leads automatically get access to `TeamCreate`, `TaskCreate`, `TaskUpdate`, `TaskList`, `SendMessage`, and `Task` (for spawning)
+
+```yaml
+# Example team lead agent
+permissionMode: delegate
+```
+
+### Permission Inheritance
+
+Teammates inherit the team lead's permission settings. If the lead runs with `--dangerously-skip-permissions`, all teammates inherit that too. Plan permission modes accordingly — a permissive lead creates permissive teammates.
+
+### Context Isolation
+
+Teammates load CLAUDE.md, MCP servers, and skills from the project, but do NOT inherit the lead's conversation history. Each teammate starts with a fresh context window; the spawn prompt provides initial task context.
+
+### Token Cost
+
+Each teammate is a separate Claude Code session with its own context window. Token costs scale linearly with team size. Worth the extra cost for genuinely parallel work, but avoid spawning teammates for tasks that could be done sequentially.
+
+### Designing Teammate Agents
+
+Teammates are spawned by the team lead and work independently on assigned tasks:
+
+- **Self-contained context**: Each teammate has its own context window; don't assume shared state
+- **Task-focused prompts**: System prompt should focus on a specific type of work (e.g., "you are a test writer")
+- **Tool restrictions**: Use `tools` to limit what each teammate can do based on their role
+- **Plan mode for review**: Use `permissionMode: plan` for teammates that should propose changes for lead approval
+
+### Display Modes
+
+The `teammateMode` setting controls how agent teams display in the terminal:
+
+| Mode         | Behavior                                                  |
+| ------------ | --------------------------------------------------------- |
+| `in-process` | All teammates in main terminal; Shift+Up/Down to navigate |
+| `tmux`       | Split panes, each teammate in its own pane                |
+| `auto`       | Split panes if in tmux, in-process otherwise (default)    |
+
+### Team Hooks
+
+Use hook events to enforce quality standards in team workflows:
+
+| Event           | Fires When                   | Use Case                                      |
+| --------------- | ---------------------------- | --------------------------------------------- |
+| `TeammateIdle`  | A teammate finishes its turn | Trigger code review, run tests on changes     |
+| `TaskCompleted` | A task is marked complete    | Validate deliverables, update documentation   |
+| `SubagentStart` | A teammate spawns            | Log team activity, enforce naming conventions |
+| `SubagentStop`  | A teammate finishes          | Clean up resources, collect metrics           |
+
+### Plan Approval Mode
+
+Teammates can be configured to require plan approval from the team lead before implementing:
+
+1. Teammate uses `permissionMode: plan`
+2. Teammate explores codebase and creates a plan
+3. Teammate calls `ExitPlanMode`, which sends plan to team lead
+4. Team lead reviews and approves/rejects via `SendMessage` with `plan_approval_response`
+5. On approval, teammate exits plan mode and proceeds with implementation
+
+This pattern is useful for complex tasks where the lead wants to review approach before execution.
+
+For complete documentation, see the [official agent teams guide](https://code.claude.com/docs/en/agent-teams).

package/extensions/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md

@@ -0,0 +1,216 @@
+# Agent Creation System Prompt
+
+This is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use.
+
+## The Prompt
+
+```
+You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.
+
+**Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.
+
+When a user describes what they want an agent to do, you will:
+
+1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.
+
+2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.
+
+3. **Architect Comprehensive Instructions**: Develop a system prompt that:
+   - Establishes clear behavioral boundaries and operational parameters
+   - Provides specific methodologies and best practices for task execution
+   - Anticipates edge cases and provides guidance for handling them
+   - Incorporates any specific requirements or preferences mentioned by the user
+   - Defines output format expectations when relevant
+   - Aligns with project-specific coding standards and patterns from CLAUDE.md
+
+4. **Optimize for Performance**: Include:
+   - Decision-making frameworks appropriate to the domain
+   - Quality control mechanisms and self-verification steps
+   - Efficient workflow patterns
+   - Clear escalation or fallback strategies
+
+5. **Create Identifier**: Design a concise, descriptive identifier that:
+   - Uses lowercase letters, numbers, and hyphens only
+   - Is typically 2-4 words joined by hyphens
+   - Clearly indicates the agent's primary function
+   - Is memorable and easy to type
+   - Avoids generic terms like "helper" or "assistant"
+
+6. **Example agent descriptions**:
+   - In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.
+   - Examples should be of the form:
+     <example>
+     Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.
+     user: "Please write a function that checks if a number is prime"
+     assistant: "Here is the relevant function: "
+     <function call omitted for brevity only for this example>
+     <commentary>
+     Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code.
+     </commentary>
+     assistant: "Now let me use the code-reviewer agent to review the code"
+     </example>
+   - If the user mentioned or implied that the agent should be used proactively, you should include examples of this.
+   - NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.
+
+Your output must be a valid JSON object with exactly these fields:
+{
+  "identifier": "A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')",
+  "whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.",
+  "systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness"
+}
+
+Key principles for your system prompts:
+- Be specific rather than generic - avoid vague instructions
+- Include concrete examples when they would clarify behavior
+- Balance comprehensiveness with clarity - every instruction should add value
+- Ensure the agent has enough context to handle variations of the core task
+- Make the agent proactive in seeking clarification when needed
+- Build in quality assurance and self-correction mechanisms
+
+Remember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.
+```
+
+## Usage Pattern
+
+Use this prompt to generate agent configurations:
+
+```markdown
+**User input:** "I need an agent that reviews pull requests for code quality issues"
+
+**You send to Claude with the system prompt above:**
+Create an agent configuration based on this request: "I need an agent that reviews pull requests for code quality issues"
+
+**Claude returns JSON:**
+{
+"identifier": "pr-quality-reviewer",
+"whenToUse": "Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n<example>\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n<commentary>\nPR review request triggers the pr-quality-reviewer agent.\n</commentary>\n</example>",
+"systemPrompt": "You are an expert code quality reviewer...\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n..."
+}
+```
+
+## Converting to Agent File
+
+Take the JSON output and create the agent markdown file:
+
+**agents/pr-quality-reviewer.md:**
+
+```markdown
+---
+name: pr-quality-reviewer
+description: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:
+
+<example>
+Context: User has created a PR and wants quality review
+user: "Can you review PR #123 for code quality?"
+assistant: "I'll use the pr-quality-reviewer agent to analyze the PR."
+<commentary>
+PR review request triggers the pr-quality-reviewer agent.
+</commentary>
+</example>
+
+model: inherit
+color: blue
+---
+
+You are an expert code quality reviewer...
+
+**Your Core Responsibilities:**
+
+1. Analyze code changes for quality issues
+2. Check adherence to best practices
+   ...
+```
+
+## Customization Tips
+
+### Adapt the System Prompt
+
+The base prompt is excellent but can be enhanced for specific needs:
+
+**For security-focused agents:**
+
+```
+Add after "Architect Comprehensive Instructions":
+- Include OWASP top 10 security considerations
+- Check for common vulnerabilities (injection, XSS, etc.)
+- Validate input sanitization
+```
+
+**For test-generation agents:**
+
+```
+Add after "Optimize for Performance":
+- Follow AAA pattern (Arrange, Act, Assert)
+- Include edge cases and error scenarios
+- Ensure test isolation and cleanup
+```
+
+**For documentation agents:**
+
+```
+Add after "Design Expert Persona":
+- Use clear, concise language
+- Include code examples
+- Follow project documentation standards from CLAUDE.md
+```
+
+## Best Practices from Internal Implementation
+
+### 1. Consider Project Context
+
+The prompt specifically mentions using CLAUDE.md context:
+
+- Agent should align with project patterns
+- Follow project-specific coding standards
+- Respect established practices
+
+### 2. Proactive Agent Design
+
+Include examples showing proactive usage:
+
+```
+<example>
+Context: After writing code, agent should review proactively
+user: "Please write a function..."
+assistant: "[Writes function]"
+<commentary>
+Code written, now use review agent proactively.
+</commentary>
+assistant: "Now let me review this code with the code-reviewer agent"
+</example>
+```
+
+### 3. Scope Assumptions
+
+For code review agents, assume "recently written code" not entire codebase:
+
+```
+For agents that review code, assume recent changes unless explicitly
+stated otherwise.
+```
+
+### 4. Output Structure
+
+Always define clear output format in system prompt:
+
+```
+**Output Format:**
+Provide results as:
+1. Summary (2-3 sentences)
+2. Detailed findings (bullet points)
+3. Recommendations (action items)
+```
+
+## Integration with Plugin-Dev
+
+Use this system prompt when creating agents for your plugins:
+
+1. Take user request for agent functionality
+2. Feed to Claude with this system prompt
+3. Get JSON output (identifier, whenToUse, systemPrompt)
+4. Convert to agent markdown file with frontmatter
+5. Validate with agent validation rules
+6. Test triggering conditions
+7. Add to plugin's `agents/` directory
+
+This provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation.

package/extensions/plugin-dev/skills/agent-development/references/permission-modes-rules.md

@@ -0,0 +1,226 @@
+# Permission Modes & Rules Reference
+
+This reference covers the complete permission system for Claude Code agents, including all permission modes and the permission rule syntax for fine-grained access control.
+
+## Permission Modes
+
+Agents can specify a `permissionMode` in frontmatter to control how permission requests are handled:
+
+```yaml
+permissionMode: acceptEdits
+```
+
+### All Permission Modes
+
+| Mode                | Behavior                                                     | Use Case                                            |
+| ------------------- | ------------------------------------------------------------ | --------------------------------------------------- |
+| `default`           | Standard permission model — prompts user for each action     | General-purpose agents, untrusted contexts          |
+| `acceptEdits`       | Auto-accept file edit operations (Write, Edit, NotebookEdit) | Code generation agents that need to write files     |
+| `dontAsk`           | Skip all permission dialogs                                  | Trusted automation agents, CI/CD agents             |
+| `bypassPermissions` | Full bypass of all permission checks                         | Fully trusted agents only                           |
+| `plan`              | Planning mode — propose changes without executing            | Architecture/design agents, review agents           |
+| `delegate`          | Coordination-only — restricted to team management tools      | Team lead agents that should not implement directly |
+
+### Mode Details
+
+#### default
+
+The standard interactive permission model. Claude asks the user before performing actions that require permission. This is the implicit mode when `permissionMode` is not specified.
+
+**When to use:** General-purpose agents, agents handling sensitive operations, agents in untrusted contexts.
+
+#### acceptEdits
+
+Auto-accepts file writing operations (Write, Edit, NotebookEdit) without prompting. Other operations (Bash, etc.) still require user permission.
+
+**When to use:** Code generation agents, refactoring agents, documentation generators.
+
+#### dontAsk
+
+Skips all permission dialogs. The agent proceeds without user confirmation for any action.
+
+**When to use:** Trusted automation, background agents, CI/CD pipelines where no user is present.
+
+#### bypassPermissions
+
+Full permission bypass with no restrictions. More permissive than `dontAsk` as it bypasses even system-level restrictions.
+
+**When to use:** Only for fully trusted agents in controlled environments. Never for plugins distributed to unknown users.
+
+#### plan
+
+Planning mode restricts the agent to read-only operations. The agent can explore the codebase and propose changes but cannot execute them. Requires user approval before any modifications.
+
+**When to use:** Architecture planning, design review, impact analysis agents.
+
+#### delegate
+
+Restricts the agent to team coordination tools only: spawning teammates, sending messages, managing tasks, and shutting down teammates. The agent cannot use implementation tools (Edit, Write, Bash, etc.) directly.
+
+**When to use:** Team lead agents that should coordinate work across teammates without implementing tasks themselves.
+
+```yaml
+# Team lead agent that only coordinates
+permissionMode: delegate
+```
+
+## Permission Specifier Syntax
+
+Permission specifiers define exactly which tool invocations a rule matches. Each tool type has its own pattern syntax.
+
+### Bash Patterns
+
+| Pattern          | Behavior                     | Example Match             | Non-Match          |
+| ---------------- | ---------------------------- | ------------------------- | ------------------ |
+| `Bash(npm test)` | Exact match                  | `npm test`                | `npm test --watch` |
+| `Bash(npm *)`    | Prefix with word boundary    | `npm test`, `npm install` | `npmx build`       |
+| `Bash(git*)`     | Prefix without word boundary | `git`, `git push`, `gitk` | —                  |
+
+Space before `*` means word boundary: `Bash(ls *)` matches `ls -la` but NOT `lsof`. No space means substring: `Bash(git*)` matches both `git push` and `gitk`.
+
+### Path Patterns for Edit/Read/Write
+
+Path specifiers follow the gitignore specification:
+
+| Pattern  | Meaning                                      | Example                |
+| -------- | -------------------------------------------- | ---------------------- |
+| `//path` | Absolute from filesystem root                | `Edit(//etc/config)`   |
+| `~/path` | Relative to home directory                   | `Read(~/Documents/**)` |
+| `/path`  | Relative to settings file location           | `Edit(/src/**)`        |
+| `./path` | Relative to current directory                | `Write(./output/*)`    |
+| `path`   | Relative to current directory (same as `./`) | `Edit(src/**)`         |
+| `*`      | Single directory level wildcard              | `Read(src/*)`          |
+| `**`     | Recursive directory wildcard                 | `Edit(src/**)`         |
+
+### WebFetch Patterns
+
+Restrict by domain:
+
+```
+WebFetch(domain:example.com)
+```
+
+### MCP Tool Patterns
+
+| Pattern             | Matches                   |
+| ------------------- | ------------------------- |
+| `mcp__server`       | All tools from server     |
+| `mcp__server__*`    | All tools from server     |
+| `mcp__server__tool` | Specific tool from server |
+
+### Task (Agent) Patterns
+
+| Pattern              | Matches                      |
+| -------------------- | ---------------------------- |
+| `Task(agent-name)`   | Only the named agent type    |
+| `Task(name1, name2)` | Only listed agent types      |
+| `Task`               | All subagent types           |
+| _(omit entirely)_    | No subagent spawning allowed |
+
+### Skill Patterns
+
+| Pattern         | Matches                     |
+| --------------- | --------------------------- |
+| `Skill(name)`   | Exact skill name match      |
+| `Skill(name *)` | Prefix match with arguments |
+
+### Evaluation Order
+
+Rules are evaluated in a strict order — first match wins within each tier:
+
+1. **Deny** rules checked first
+2. **Ask** rules checked second
+3. **Allow** rules checked last
+
+### Default Permission Tiers
+
+Tools fall into three default permission tiers:
+
+| Tier              | Tools                     | Behavior                                           |
+| ----------------- | ------------------------- | -------------------------------------------------- |
+| Read-only         | Read, Glob, Grep          | No approval needed                                 |
+| Bash commands     | Bash                      | Manual approval on first use per directory/command |
+| File modification | Write, Edit, NotebookEdit | Approval required per session                      |
+
+## Permission Rules
+
+Permission rules provide fine-grained control over specific tool access. They are configured in settings files (not agent frontmatter) and apply based on precedence.
+
+### Rule Syntax
+
+Rules are specified in `settings.json` under `permissions`:
+
+```json
+{
+  "permissions": {
+    "allow": ["Read", "Bash(npm test)", "Edit(src/**)"],
+    "deny": ["Bash(rm *)", "Bash(git push --force*)"]
+  }
+}
+```
+
+### Tool Specifiers
+
+| Pattern              | Matches                         | Example                              |
+| -------------------- | ------------------------------- | ------------------------------------ |
+| `ToolName`           | Any use of that tool            | `Read` — all file reads              |
+| `ToolName(argument)` | Tool with specific argument     | `Bash(npm test)` — only this command |
+| `ToolName(pattern*)` | Tool with wildcard argument     | `Bash(npm *)` — any npm command      |
+| `Edit(path)`         | Edit with gitignore-style path  | `Edit(src/**)` — edits in src/       |
+| `Write(path)`        | Write with gitignore-style path | `Write(tests/**)` — writes in tests/ |
+
+### MCP Tool Patterns
+
+```json
+{
+  "permissions": {
+    "allow": ["mcp__servername__toolname", "mcp__servername__*"]
+  }
+}
+```
+
+- `mcp__server__tool` — specific MCP tool
+- `mcp__server__*` — all tools from a server
+- `mcp__*` — all MCP tools (use sparingly)
+
+### Task (Agent) Patterns
+
+Control which agent types can be spawned:
+
+```json
+{
+  "permissions": {
+    "allow": ["Task(code-reviewer, test-runner)"]
+  }
+}
+```
+
+- `Task(type1, type2)` — only listed agent types
+- `Task` — allow any subagent
+- Omitting `Task` — no subagent spawning
+
+### Rule Precedence
+
+When multiple rules match:
+
+1. **deny** rules always take precedence over **allow** rules
+2. More specific rules take precedence over general ones
+3. Explicit rules override `permissionMode` settings
+
+### Plugin Developer Guidance
+
+**Document required permissions:** If your plugin's agents need specific tool access, document the minimum required permissions in your README:
+
+```markdown
+## Required Permissions
+
+This plugin's agents need:
+
+- `Edit(src/**)` — to modify source files
+- `Bash(npm test)` — to run tests
+- `mcp__plugin_myserver__*` — for MCP tool access
+```
+
+**Configure agent permissions:** Use `permissionMode` in agent frontmatter for broad access control. For fine-grained restrictions, document the settings users should configure.
+
+**Principle of least privilege:** Request only the permissions your agent actually needs. Use `acceptEdits` over `dontAsk` when only file writes are needed.