docs: address documentation gaps vs official Claude Code docs

Add missing features, fix inaccuracies, and expand coverage across all
skills to match the official Claude Code documentation.

Agent development: add maxTurns, memory, mcpServers, hooks fields;
execution modes; agent teams; new advanced-agent-fields.md reference.

Hook development: add TeammateIdle/TaskCompleted events; once and
statusMessage handler fields; event-specific matchers; decision control
output schemas; async hooks; two new patterns.

Marketplace: add enterprise features (strictKnownMarketplaces, private
repo auth, reserved names); ref/sha pinning; hostPattern source type.

Plugin structure: fix outputStyles from inline JSON to path-based field;
add plugin validation commands; add npm/pip source types.

Skill development: add visual output generators; Skill() permission
syntax; update context budget to 2%/16KB.

MCP integration: fix allowedServers/blockedServers to correct
allowedMcpServers/deniedMcpServers with matcher types; add claude mcp
serve, list_changed, output limits.

LSP integration: add socket transport example; initializationOptions
example; full config with all optional fields.

Component patterns: add new agent fields, hook events, agent hook type.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sjnims

docs/component-patterns.md

@@ -14,6 +14,10 @@ Agents require YAML frontmatter with:
 - `disallowedTools`: Comma-separated list of blocked tools (optional, denylist — use one or the other)
 - `skills`: Comma-separated list of skills the agent can load (optional)
 - `permissionMode`: acceptEdits/dontAsk/bypassPermissions/plan (optional)
+- `maxTurns`: Number limiting agentic turns (optional)
+- `memory`: user/project/local for persistent memory (optional)
+- `mcpServers`: Scoped MCP server access (optional)
+- `hooks`: Lifecycle hooks scoped to agent (optional)
 
 ## Skills
 
@@ -65,8 +69,8 @@ disallowedTools: Bash, Write # Denylist
 
 Hooks defined in `hooks/hooks.json`:
 
-- Events: PreToolUse, PermissionRequest, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification
-- Types: `prompt` (LLM-driven) or `command` (bash scripts)
+- Events: PreToolUse, PermissionRequest, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, TeammateIdle, TaskCompleted
+- Types: `prompt` (LLM-driven), `command` (bash scripts), or `agent` (multi-step with tools)
 - Use matchers for tool filtering (e.g., "Write|Edit", "\*")
 
 ### Plugin hooks.json Format

plugins/plugin-dev/skills/agent-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-development
-description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", "disallowedTools", "block tools", "agent denylist", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
+description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", "disallowedTools", "block tools", "agent denylist", "maxTurns", "agent memory", "mcpServers in agent", "agent hooks", "background agent", "resume agent", "agent teams", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
 ---
 
 # Agent Development for Claude Code Plugins
@@ -310,6 +310,60 @@ permissionMode: acceptEdits
 
 **Security note:** Use restrictive modes (`plan`, `acceptEdits`) for untrusted agents. `bypassPermissions` should only be used for fully trusted agents.
 
+### maxTurns (optional)
+
+Limit the maximum number of agentic turns before the agent stops:
+
+```yaml
+maxTurns: 50
+```
+
+**Use cases:**
+
+- Prevent runaway agents from consuming excessive resources
+- Set reasonable bounds for task complexity
+- Higher values (50-100) for complex multi-file tasks; lower values (10-20) for focused checks
+
+If omitted, the agent runs until it completes or the user interrupts.
+
+### memory (optional)
+
+Enable persistent memory across sessions:
+
+```yaml
+memory: user
+```
+
+**Scopes:** `user` (~/.claude/agent-memory/), `project` (.claude/agent-memory/), `local` (.claude/agent-memory-local/)
+
+When enabled, the agent's first 200 lines of `MEMORY.md` are auto-injected into its system prompt. The agent can read/write its memory directory to learn across sessions. See `references/advanced-agent-fields.md` for details.
+
+### mcpServers (optional)
+
+Scope MCP servers to this agent:
+
+```yaml
+mcpServers:
+  slack:
+```
+
+Reference an already-configured server by name, or provide inline config. Restricts which MCP servers the agent can access. See `references/advanced-agent-fields.md` for configuration examples.
+
+### hooks (optional)
+
+Define lifecycle hooks scoped to this agent:
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bash.sh"
+```
+
+Supports all hook events. Note: `Stop` hooks in agent frontmatter are auto-converted to `SubagentStop` at runtime. Hooks activate when the agent starts and deactivate when it finishes. See `references/advanced-agent-fields.md` for full details.
+
 ### Fields NOT Available for Agents
 
 Some frontmatter fields are specific to skills and do not apply to agents:
@@ -501,6 +555,10 @@ Ensure system prompt is complete:
 | disallowedTools | No       | Comma-separated tool names | Bash, Write              |
 | skills          | No       | Array of skill names       | [testing, security]      |
 | permissionMode  | No       | Permission mode string     | acceptEdits              |
+| maxTurns        | No       | Number                     | 50                       |
+| memory          | No       | user/project/local         | user                     |
+| mcpServers      | No       | Object or server names     | { "slack": {} }          |
+| hooks           | No       | Hook event config          | { PreToolUse: [...] }    |
 
 > **Note:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. The field names differ between component types.
 
@@ -524,12 +582,36 @@ Ensure system prompt is complete:
 - ❌ Write vague system prompts
 - ❌ Skip testing
 
+## Execution Modes
+
+Agents can run in foreground (blocking) or background (concurrent) mode:
+
+- **Foreground** (default): Blocks the main conversation until the agent completes
+- **Background**: Runs concurrently; permissions must be pre-approved at spawn time since the user can't be prompted
+
+Background agents that need an unapproved permission will fail. Plan tool restrictions accordingly.
+
+**Resuming agents:** Each Task invocation creates a fresh agent. To continue with full prior context, ask Claude to "resume that agent" — it will restore the previous transcript.
+
+**Restricting spawnable agents:** Use `Task(agent_type1, agent_type2)` syntax in settings.json allow rules to control which agent types can be spawned. Omitting `Task` entirely prevents subagent spawning.
+
+**Built-in agent types:** Explore (read-only, Haiku), Plan (read-only research), general-purpose (all tools), Bash (terminal commands), statusline-setup (Haiku), Claude Code Guide (Haiku).
+
+## Agent Teams (Experimental)
+
+Agent teams enable multi-agent coordination where a team lead spawns and manages multiple independent Claude Code sessions as teammates. Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
+
+Teams provide shared task lists, inter-agent messaging, and parallel execution. Use `permissionMode: delegate` to restrict a lead to coordination-only tools.
+
+This is an advanced feature — see the [official agent teams documentation](https://code.claude.com/docs/en/agent-teams) for details.
+
 ## Additional Resources
 
 ### Reference Files
 
 For detailed guidance, consult:
 
+- **`references/advanced-agent-fields.md`** - Detailed docs for maxTurns, memory, mcpServers, hooks, execution modes, and agent teams
 - **`references/system-prompt-design.md`** - Four system prompt patterns (Analysis, Generation, Validation, Orchestration) with complete templates and common pitfalls
 - **`references/triggering-examples.md`** - Example block anatomy, four example types, template library, and debugging guide
 - **`references/agent-creation-system-prompt.md`** - The exact prompt used by Claude Code's agent generation feature with usage patterns

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

@@ -0,0 +1,187 @@
+# 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
+
+### Delegate Mode
+
+Use `permissionMode: delegate` to restrict a team lead to coordination-only tools (spawn, message, shut down teammates, manage tasks). This prevents the lead from implementing tasks itself.
+
+### Quality Gates
+
+Use `TeammateIdle` and `TaskCompleted` hooks to enforce quality standards in team workflows.
+
+For complete documentation, see the [official agent teams guide](https://code.claude.com/docs/en/agent-teams).

plugins/plugin-dev/skills/hook-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hook-development
-description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", "scoped hooks", "frontmatter hooks", "hook in skill", "hook in agent", "agent hook type", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStop, SubagentStart, Setup, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
+description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", "scoped hooks", "frontmatter hooks", "hook in skill", "hook in agent", "agent hook type", "async hooks", "once handler", "statusMessage", "hook decision control", "TeammateIdle hook", "TaskCompleted hook", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStop, SubagentStart, Setup, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, TeammateIdle, TaskCompleted). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
 ---
 
 # Hook Development for Claude Code Plugins
@@ -772,6 +772,17 @@ echo "$output" | jq .
 | SessionEnd         | Session ends       | Cleanup, logging         |
 | PreCompact         | Before compact     | Preserve context         |
 | Notification       | User notified      | Logging, reactions       |
+| TeammateIdle       | Teammate goes idle | Quality gates in teams   |
+| TaskCompleted      | Task marked done   | Completion verification  |
+
+### Handler Configuration Fields
+
+Beyond `type`, `timeout`, and `matcher`, hook handlers support:
+
+- **`once`** (boolean): Run only once per session, then auto-removed. Useful for one-time initialization in scoped hooks.
+- **`statusMessage`** (string): Display text shown in the UI while the hook runs.
+
+See `references/advanced.md` for detailed decision control output schemas and event-specific matchers.
 
 ### Best Practices