Part 5 · Extend Agent Behavior

This part has two axes: the capability plane gives the agent business capabilities, knowledge, and rules; the control plane lets you intervene at lifecycle points the agent already passes through. Sections 5.1–5.6 are capability-plane extensions; 5.7 is the control plane.

Key terms in this Part

• Tool subclass — the canonical way to expose a business capability: name / description / parameters / execute() · §5.1, G.2
• requires_confirmation — Tool flag → triggers the ask_confirmation UI for side-effecting calls · §5.1, §5.4
• PermissionEngine — Tier 0 hard guards + presets + custom rules; the rule-based defense layer · §5.4, G.5
• Skill — SKILL.md + YAML front-matter, dynamically discovered from skills/; LLM-side instructions · §5.2, G.2
• MemoryManager — SQLite-backed dual-scope (project + user) persistent + session memory · §5.5, G.1
• Plugin Hook — hooks.json rules aligned with Claude Code; intercept / inject / continue at lifecycle points · §5.7

Coverage

Capability plane

• 5.1 Custom Tools & Host Injection — write tools, inject/select the tool surface, and avoid common pitfalls
• 5.2 Skills — Markdown instructions for the LLM
• 5.3 MCP Server Integration — reuse the community / official tool ecosystem
• 5.4 Permission Engine — the first rule-based defense, layered with confirm_tool
• 5.5 Memory System — cross-session persistence and compliance
• 5.6 System Prompt Customization — the 3 of 11 prompt blocks you actually own

Control plane

• 5.7 Plugin Hooks — hooks.json rules; injection and interception at UserPromptSubmit / PreToolUse / Stop / PreCompact and other lifecycle points

Read by task

What you are building	Recommended path	You should be able to
Let the agent call your business API	5.1 → 5.4	Write and inject a Tool, then add confirmation or permission boundaries for side effects
Select / shrink the tool surface from the host	5.1	Inject, replace, or prune tools at construction or runtime — and know it's not a security boundary
Make the agent follow team conventions	5.2 → 5.6	Separate on-demand Skills from project-wide prompt instructions
Integrate an existing service ecosystem	5.3 → 5.4	Connect MCP while constraining tool visibility and execution scope
Remember long-term facts or user preferences	5.5 → 6.4	Design memory scope, cleanup, and tenant boundaries
Intercept, inject, or continue at lifecycle points	5.7 → 4.7	Write hooks.json and know when stable event streams are the right audit surface
Choose between Tool, Skill, MCP, and Hook	5.1 → 5.2 → 5.3 → 5.7	Decide by capability, instruction, external ecosystem, and lifecycle intervention

Three pragmatic rules

1. Start with 5.4: write permission rules before deployment — avoid "we'll add safety later" tech debt
2. Don't duplicate 5.1 and 5.3: the same capability should be either a Tool or an MCP server, never both — the LLM gets confused
3. Skills: small and specific: one skill, one job, concrete trigger description; many small skills beat one monster skill

→ Start with 5.1 →