https://futurewithml.netlify.app
|
This is a web feed, also known as an Atom feed. Subscribe by copying the URL from the address bar into your newsreader. Visit About Feeds to learn more and get started. It's free.
Visit website
Recent posts
Updated on $DATE
date
Agent Architecture
Future With ML - Agent Architecture
Machine Learning Design Patterns, MLOps, and AI Engineering insights by Christian Picon Calderon
Zola2026-01-06T12:00:00+00:00https://futurewithml.netlify.app/tags/agent-architecture/atom.xml
The Inheritance Paradox: Tool Scoping in Multi-Agent Systems
2026-01-06T12:00:00+00:00
2026-01-06T12:00:00+00:00
Christian Picon Calderon
https://futurewithml.netlify.app/posts/claude-code-plugin-journey-part2/
<h1 id="the-inheritance-paradox-tool-scoping-in-multi-agent-systems">The Inheritance Paradox: Tool Scoping in Multi-Agent Systems</h1>
<blockquote>
<p><em>This is Part 2 of a three-part series. See <a href="/posts/claude-code-plugin-journey-part0/">Part 0</a> for the plugin overview and installation, or <a href="/posts/claude-code-plugin-journey-part1/">Part 1</a> for the development journey.</em></p>
</blockquote>
<p><strong>Abstract</strong>: This article presents empirical observations from developing a Claude Code plugin, revealing fundamental patterns in multi-agent AI system design. Through documented development sessions, we identify three key findings: (1) implicit tool inheritance models consistently fail in practice, requiring explicit scope contracts; (2) platform-enforced topology constraints drive the emergence of specific architectural patterns; and (3) agent naming conventions become functional requirements in AI systems. These findings have implications for the design of agent frameworks beyond the specific platform studied.</p>
<span id="continue-reading"></span>
<hr />
<h2 id="1-introduction">1. Introduction</h2>
<p>Agent-based development platforms represent an emerging paradigm in software engineering, where AI instances collaborate on complex tasks through structured orchestration. These platforms offer extension mechanisms—plugins, commands, agents—that allow developers to customize behavior for specific domains.</p>
<p>This article examines Claude Code as a case study in agent framework design. Claude Code enables developers to build custom plugins with commands (user-invoked shortcuts), agents (specialized Claude instances), skills (context providers), hooks (event handlers), and MCP integrations (external service connections).</p>
<p>During the development of <code>agent-team-creator</code>, a plugin for generating project-specific AI agents, we documented systematic observations about platform behavior. These observations reveal patterns relevant to multi-agent system design more broadly.</p>
<h3 id="research-questions">Research Questions</h3>
<ol>
<li>How do tool inheritance models behave in practice versus documentation?</li>
<li>What architectural patterns emerge from platform topology constraints?</li>
<li>How do naming conventions influence agent behavior in AI systems?</li>
</ol>
<hr />
<h2 id="2-platform-architecture-analysis">2. Platform Architecture Analysis</h2>
<h3 id="2-1-component-type-taxonomy">2.1 Component Type Taxonomy</h3>
<p>Claude Code plugins support five distinct extension types, each with different triggering mechanisms and scope:</p>
<table><thead><tr><th>Component</th><th>Trigger</th><th>Invocation</th><th>Scope</th></tr></thead><tbody>
<tr><td>Skills</td><td>Auto (Claude decides)</td><td>Implicit</td><td>Cross-product</td></tr>
<tr><td>Commands</td><td>User (<code>/syntax</code>)</td><td>Explicit</td><td>Claude Code</td></tr>
<tr><td>Agents</td><td>Spawn (Task tool)</td><td>Explicit/Implicit</td><td>Claude Code</td></tr>
<tr><td>Hooks</td><td>Events</td><td>Automatic</td><td>Claude Code</td></tr>
<tr><td>MCPs</td><td>Tool calls</td><td>Explicit</td><td>Claude Code</td></tr>
</tbody></table>
<p><strong>Key Observation</strong>: Skills are unique in being cross-product (functional in web UI, API, and CLI), while all other components are Claude Code-specific. This suggests different inheritance models may apply to different component types.</p>
<h3 id="2-2-tool-inventory">2.2 Tool Inventory</h3>
<p>The platform provides 15 built-in tools available to agents:</p>
<ol>
<li>Read, Write, Edit, MultiEdit (file operations)</li>
<li>Glob, Grep, LS (search operations)</li>
<li>Bash (system commands)</li>
<li>WebFetch, WebSearch (web access)</li>
<li>NotebookRead, NotebookEdit (Jupyter support)</li>
<li>TodoRead, TodoWrite (task tracking)</li>
<li>exit_plan_mode (workflow control)</li>
</ol>
<p>Additionally, MCP (Model Context Protocol) servers provide external service integrations—database access, API connections, third-party services.</p>
<h3 id="2-3-lifecycle-events">2.3 Lifecycle Events</h3>
<p>Nine hook events define the agent lifecycle:</p>
<table><thead><tr><th>Event</th><th>Trigger</th></tr></thead><tbody>
<tr><td>PreToolUse</td><td>Before any tool execution</td></tr>
<tr><td>PostToolUse</td><td>After tool execution</td></tr>
<tr><td>UserPromptSubmit</td><td>User message received</td></tr>
<tr><td>Stop</td><td>Agent completion</td></tr>
<tr><td>SubagentStop</td><td>Subagent completion</td></tr>
<tr><td>SessionStart</td><td>Session initialization</td></tr>
<tr><td>SessionEnd</td><td>Session termination</td></tr>
<tr><td>PreCompact</td><td>Before context compaction</td></tr>
<tr><td>Notification</td><td>System notification</td></tr>
</tbody></table>
<p>Hook exit codes follow Unix conventions: 0 for success, 2 for blocking errors (Claude processes stderr), other codes for non-blocking errors.</p>
<hr />
<h2 id="3-key-findings">3. Key Findings</h2>
<h3 id="3-1-the-inheritance-paradox">3.1 The Inheritance Paradox</h3>
<p><strong>Documentation Claim</strong>:</p>
<blockquote>
<p>“MCP Tools: Subagents can access MCP tools from configured MCP servers. When the tools field is omitted, subagents inherit all MCP tools available to the main thread.”</p>
</blockquote>
<p><strong>Observed Behavior</strong>: Plugin-defined subagents cannot access MCP tools under any tested configuration.</p>
<p>This discrepancy is documented across four GitHub issues (#13605, #15810, #14496, #7296), each describing a different manifestation of scope inheritance failure:</p>
<table><thead><tr><th>Issue</th><th>Failure Mode</th><th>Scope Context</th></tr></thead><tbody>
<tr><td>#13605</td><td>Plugin agents can’t access MCP</td><td>Plugin vs built-in</td></tr>
<tr><td>#15810</td><td>Subagents don’t inherit MCP</td><td>Parent-child hierarchy</td></tr>
<tr><td>#14496</td><td>Complex prompts break MCP access</td><td>Prompt complexity</td></tr>
<tr><td>#7296</td><td>Task-launched agents lack MCP</td><td>User-scoped inheritance</td></tr>
</tbody></table>
<p><strong>Analysis</strong>: The pattern suggests a fundamental architectural issue rather than isolated bugs. Tool inheritance operates differently across scope boundaries:</p>
<ol>
<li><strong>Built-in agents</strong> inherit MCP tools correctly</li>
<li><strong>Plugin-defined agents</strong> do not inherit MCP tools</li>
<li><strong>Task-launched agents</strong> receive a fresh scope without user-level configurations</li>
</ol>
<p><strong>Implication for Framework Design</strong>: Implicit tool inheritance models require explicit contracts at scope boundaries. Assuming tools propagate through agent hierarchies creates fragile dependencies. Explicit tool declarations at each scope level, while verbose, produce predictable behavior.</p>
<h3 id="3-2-topology-constraints-and-emergent-patterns">3.2 Topology Constraints and Emergent Patterns</h3>
<p><strong>Discovery</strong>: The platform enforces a single-level nesting limit for agent spawning.</p>
<div class="blocked-flow-container" id="blocked-">
<canvas class="blocked-flow-canvas" aria-label="Flow diagram with blocked step"></canvas>
</div>
<script>
(function() {
const containerId = 'blocked-';
const nodeNames = ['Agent', 'Subagent'];
const blockedName = 'Subsubagent';
function initBlockedFlow() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.blocked-flow-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
let pulsePhase = 0;
const colors = {
nodes: ['#ff0080', '#00d4ff', '#00ff88', '#8b5cf6'],
blocked: '#ff4444',
blockedBg: '#442222',
particle: '#00ff88',
connection: 'rgba(0, 212, 255, 0.4)',
blockedConnection: 'rgba(255, 68, 68, 0.5)',
text: '#e0e0e4'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 180;
}
resize();
window.addEventListener('resize', resize);
function getNodePositions() {
const allNodes = [...nodeNames, blockedName];
const margin = 60;
const spacing = (canvas.width - margin * 2) / (allNodes.length - 1);
const y = canvas.height / 2;
return allNodes.map((name, i) => ({
label: name,
x: margin + i * spacing,
y: y,
radius: 26,
isBlocked: i === allNodes.length - 1,
color: i < nodeNames.length ? colors.nodes[i % colors.nodes.length] : colors.blockedBg
}));
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const nodes = getNodePositions();
pulsePhase += 0.05;
// Draw connections
for (let i = 0; i < nodes.length - 1; i++) {
const from = nodes[i];
const to = nodes[i + 1];
const isBlockedConnection = to.isBlocked;
ctx.beginPath();
ctx.moveTo(from.x + from.radius, from.y);
ctx.lineTo(to.x - to.radius, to.y);
if (isBlockedConnection) {
ctx.strokeStyle = colors.blockedConnection;
ctx.setLineDash([8, 4]);
} else {
ctx.strokeStyle = colors.connection;
ctx.setLineDash([]);
}
ctx.lineWidth = 3;
ctx.stroke();
ctx.setLineDash([]);
// Arrow
if (!isBlockedConnection) {
const midX = (from.x + to.x) / 2;
ctx.fillStyle = colors.connection;
ctx.beginPath();
ctx.moveTo(midX - 5, from.y - 6);
ctx.lineTo(midX + 8, from.y);
ctx.lineTo(midX - 5, from.y + 6);
ctx.closePath();
ctx.fill();
}
}
// Draw "BLOCKED" label on the blocked connection
const lastNormal = nodes[nodes.length - 2];
const blocked = nodes[nodes.length - 1];
const midX = (lastNormal.x + blocked.x) / 2;
ctx.save();
ctx.fillStyle = colors.blocked;
ctx.font = 'bold 11px JetBrains Mono';
ctx.textAlign = 'center';
// Pulsing X
const pulse = Math.sin(pulsePhase) * 0.3 + 1;
ctx.font = `bold ${14 * pulse}px JetBrains Mono`;
ctx.fillText('❌', midX, nodes[0].y - 20);
ctx.font = 'bold 10px JetBrains Mono';
ctx.fillText('BLOCKED', midX, nodes[0].y + 32);
ctx.restore();
// Draw nodes
nodes.forEach((node, i) => {
if (node.isBlocked) {
// Blocked node - pulsing red border
ctx.shadowColor = colors.blocked;
ctx.shadowBlur = 10 + Math.sin(pulsePhase) * 5;
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.strokeStyle = colors.blocked;
ctx.lineWidth = 3;
ctx.setLineDash([4, 4]);
ctx.stroke();
ctx.setLineDash([]);
ctx.shadowBlur = 0;
// Strikethrough effect
ctx.strokeStyle = colors.blocked;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.moveTo(node.x - node.radius + 5, node.y - node.radius + 5);
ctx.lineTo(node.x + node.radius - 5, node.y + node.radius - 5);
ctx.stroke();
} else {
// Normal node
ctx.shadowColor = node.color;
ctx.shadowBlur = 15;
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
ctx.strokeStyle = '#00ff88';
ctx.lineWidth = 2;
ctx.stroke();
}
// Label
ctx.fillStyle = node.isBlocked ? '#666' : '#0a0a0f';
ctx.font = 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
// Wrap text if needed
const words = node.label.split(/(?=[A-Z])/);
if (words.length > 1 && node.label.length > 8) {
ctx.fillText(words[0], node.x, node.y - 6);
ctx.fillText(words.slice(1).join(''), node.x, node.y + 6);
} else {
ctx.fillText(node.label, node.x, node.y);
}
});
// Particles (only on valid connections)
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.segmentIndex++;
p.progress = 0;
if (p.segmentIndex >= nodes.length - 2) {
p.segmentIndex = 0;
}
}
const from = nodes[p.segmentIndex];
const to = nodes[p.segmentIndex + 1];
if (from && to && !to.isBlocked) {
const ease = p.progress * p.progress * (3 - 2 * p.progress);
const x = from.x + (to.x - from.x) * ease;
const y = from.y + (to.y - from.y) * ease;
ctx.fillStyle = colors.particle;
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(x, y, 4, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
}
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
for (let i = 0; i < 2; i++) {
particles.push({
segmentIndex: i,
progress: 0,
speed: 0.015
});
}
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const nodes = getNodePositions();
nodes.forEach(node => {
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = node.isBlocked ? '#666' : '#0a0a0f';
ctx.font = 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.fillText(node.label, node.x, node.y);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initBlockedFlow);
} else {
initBlockedFlow();
}
})();
</script>
<style>
.blocked-flow-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.blocked-flow-canvas {
width: 100%;
height: 180px;
display: block;
}
@media (max-width: 768px) {
.blocked-flow-container {
overflow-x: auto;
}
.blocked-flow-canvas {
min-width: 500px;
}
}
</style>
<p>When an agent attempts to spawn a nested subagent, the platform returns:</p>
<pre class="z-code"><code><span class="z-text z-plain">Error: Subagents cannot spawn subagents
</span></code></pre>
<p><strong>Design Rationale (Inferred)</strong>:</p>
<ul>
<li>Prevents infinite recursion in autonomous systems</li>
<li>Maintains bounded resource consumption</li>
<li>Ensures predictable execution topology</li>
<li>Simplifies debugging and monitoring</li>
</ul>
<p><strong>Emergent Architecture: Hub-and-Spoke</strong></p>
<div class="hub-spoke-container" id="hub-spok">
<canvas class="hub-spoke-canvas" aria-label="Hub-and-spoke agent topology visualization"></canvas>
<div class="hub-spoke-info">
<span class="info-label">Topology</span>
<span class="info-value">Hub-and-Spoke</span>
</div>
</div>
<script>
(function() {
const containerId = 'hub-spok';
// Decode HTML entities (Tera encodes / as /)
function decodeHTML(str) {
const textarea = document.createElement('textarea');
textarea.innerHTML = str;
return textarea.value;
}
const hubName = decodeHTML('Main Agent');
const spokeNames = [decodeHTML('Agent 1'), decodeHTML('Agent 2'), decodeHTML('Agent 3')];
const showUser = true;
const showCommand = true;
function initHubSpoke() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.hub-spoke-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
// Colors
const colors = {
user: '#ff0080',
command: '#ff8800',
hub: '#00d4ff',
spoke: '#8b5cf6',
particle: '#00ff88',
connection: 'rgba(0, 212, 255, 0.3)'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 300;
}
resize();
window.addEventListener('resize', resize);
// Get node positions
function getNodes() {
const centerX = canvas.width / 2;
const centerY = canvas.height / 2 + 20;
const spokeRadius = Math.min(canvas.width * 0.35, 120);
const nodes = [];
// User node
if (showUser) {
nodes.push({
type: 'user',
label: 'User',
x: centerX,
y: 40,
radius: 20,
color: colors.user
});
}
// Command node
if (showCommand) {
nodes.push({
type: 'command',
label: 'Command',
x: centerX,
y: showUser ? 100 : 50,
radius: 22,
color: colors.command
});
}
// Hub node
const hubY = showUser && showCommand ? centerY : centerY - 30;
nodes.push({
type: 'hub',
label: hubName,
x: centerX,
y: hubY,
radius: 32,
color: colors.hub
});
// Spoke nodes
const spokeCount = spokeNames.length;
const angleStep = Math.PI / (spokeCount + 1);
const startAngle = Math.PI;
spokeNames.forEach((name, i) => {
const angle = startAngle - angleStep * (i + 1);
nodes.push({
type: 'spoke',
label: name,
x: centerX + Math.cos(angle) * spokeRadius,
y: hubY + Math.sin(angle) * spokeRadius * 0.7,
radius: 24,
color: colors.spoke
});
});
return nodes;
}
function createParticle(from, to) {
return {
fromX: from.x,
fromY: from.y,
toX: to.x,
toY: to.y,
progress: Math.random(),
speed: 0.005 + Math.random() * 0.003,
x: from.x,
y: from.y
};
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
const command = nodes.find(n => n.type === 'command');
const user = nodes.find(n => n.type === 'user');
// Draw connections
ctx.lineWidth = 2;
ctx.strokeStyle = colors.connection;
// User -> Command
if (user && command) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(command.x, command.y - command.radius);
ctx.stroke();
}
// Command -> Hub
if (command && hub) {
ctx.beginPath();
ctx.moveTo(command.x, command.y + command.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
} else if (user && hub) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
}
// Hub -> Spokes
spokes.forEach(spoke => {
ctx.beginPath();
ctx.moveTo(hub.x, hub.y);
ctx.lineTo(spoke.x, spoke.y);
ctx.stroke();
});
// Draw nodes
nodes.forEach(node => {
// Glow
const gradient = ctx.createRadialGradient(
node.x, node.y, 0,
node.x, node.y, node.radius * 2
);
gradient.addColorStop(0, node.color.replace(')', ', 0.3)').replace('#', 'rgba(').replace(/^rgba\(([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})/, (m, r, g, b) => `rgba(${parseInt(r, 16)}, ${parseInt(g, 16)}, ${parseInt(b, 16)}`));
gradient.addColorStop(1, 'transparent');
// Simpler glow approach
ctx.shadowColor = node.color;
ctx.shadowBlur = 15;
// Node circle
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
// Border
ctx.strokeStyle = node.color;
ctx.lineWidth = 2;
ctx.stroke();
// Label
ctx.fillStyle = '#e0e0e4';
ctx.font = node.type === 'hub' ? 'bold 11px JetBrains Mono' : '10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
// Wrap long labels
const maxWidth = node.radius * 1.8;
const words = node.label.split(' ');
if (words.length > 1 && ctx.measureText(node.label).width > maxWidth) {
ctx.fillText(words[0], node.x, node.y - 6);
ctx.fillText(words.slice(1).join(' '), node.x, node.y + 6);
} else {
ctx.fillText(node.label, node.x, node.y);
}
// Type indicator below node
if (node.type === 'hub') {
ctx.fillStyle = '#8888a0';
ctx.font = '9px JetBrains Mono';
ctx.fillText('(Hub)', node.x, node.y + node.radius + 14);
}
});
// Update and draw particles
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.progress = 0;
// Reverse direction
[p.fromX, p.toX] = [p.toX, p.fromX];
[p.fromY, p.toY] = [p.toY, p.fromY];
}
const ease = p.progress * p.progress * (3 - 2 * p.progress);
p.x = p.fromX + (p.toX - p.fromX) * ease;
p.y = p.fromY + (p.toY - p.fromY) * ease;
ctx.fillStyle = colors.particle;
ctx.beginPath();
ctx.arc(p.x, p.y, 3, 0, Math.PI * 2);
ctx.fill();
// Glow
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(p.x, p.y, 3, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
spokes.forEach(spoke => {
particles.push(createParticle(hub, spoke));
});
// Respect reduced motion
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
const command = nodes.find(n => n.type === 'command');
const user = nodes.find(n => n.type === 'user');
ctx.lineWidth = 2;
ctx.strokeStyle = colors.connection;
if (user && command) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(command.x, command.y - command.radius);
ctx.stroke();
}
if (command && hub) {
ctx.beginPath();
ctx.moveTo(command.x, command.y + command.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
}
spokes.forEach(spoke => {
ctx.beginPath();
ctx.moveTo(hub.x, hub.y);
ctx.lineTo(spoke.x, spoke.y);
ctx.stroke();
});
nodes.forEach(node => {
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = '#e0e0e4';
ctx.font = node.type === 'hub' ? 'bold 11px JetBrains Mono' : '10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(node.label, node.x, node.y);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initHubSpoke);
} else {
initHubSpoke();
}
})();
</script>
<style>
.hub-spoke-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.hub-spoke-canvas {
width: 100%;
height: 300px;
display: block;
}
.hub-spoke-info {
position: absolute;
bottom: 1rem;
right: 1rem;
background: rgba(0, 0, 0, 0.6);
padding: 0.5rem 0.75rem;
border-radius: 6px;
font-family: 'JetBrains Mono', monospace;
font-size: 0.75rem;
}
.hub-spoke-info .info-label {
color: var(--meta-color);
display: block;
margin-bottom: 0.25rem;
}
.hub-spoke-info .info-value {
color: #00d4ff;
}
@media (max-width: 768px) {
.hub-spoke-canvas {
height: 250px;
}
}
</style>
<p>This constraint eliminates tree-structured agent hierarchies in favor of flat, hub-coordinated topologies. The “hub” agent coordinates parallel execution of “spoke” agents. No spoke can spawn additional agents.</p>
<p><strong>Observed Trade-off</strong>:</p>
<table><thead><tr><th>Lost Capability</th><th>Gained Property</th></tr></thead><tbody>
<tr><td>Recursive decomposition</td><td>Bounded execution depth</td></tr>
<tr><td>Dynamic hierarchy</td><td>Predictable topology</td></tr>
<tr><td>Arbitrary nesting</td><td>Simplified resource management</td></tr>
</tbody></table>
<p><strong>Implication for Framework Design</strong>: Topology constraints are design decisions, not merely limitations. The hub-and-spoke pattern that emerges from single-level nesting produces systems that are easier to reason about, debug, and monitor than arbitrary recursive structures.</p>
<h3 id="3-3-naming-as-behavior">3.3 Naming as Behavior</h3>
<p><strong>Discovery</strong>: Claude Code infers agent behavior from agent names.</p>
<p>An agent named <code>code-reviewer</code> triggers built-in review behaviors that may override custom system prompt instructions. The platform applies heuristics based on naming conventions.</p>
<p><strong>Observed Pattern</strong>:</p>
<table><thead><tr><th>Agent Name</th><th>Inferred Behavior</th></tr></thead><tbody>
<tr><td><code>code-reviewer</code></td><td>Generic code review patterns</td></tr>
<tr><td><code>test-writer</code></td><td>Test generation patterns</td></tr>
<tr><td><code>implementation-planner</code></td><td>Less inference, more custom control</td></tr>
</tbody></table>
<p><strong>Analysis</strong>: This represents a “convention over configuration” paradigm applied to AI agent systems. The platform assumes semantically meaningful names carry behavioral intent.</p>
<p><strong>Implications</strong>:</p>
<ol>
<li>Naming conventions become functional requirements</li>
<li>Distinctive, non-generic names preserve custom behavior</li>
<li>Agent system design must consider name-based inference</li>
</ol>
<hr />
<h2 id="4-emergent-patterns">4. Emergent Patterns</h2>
<h3 id="4-1-i-o-separation-hybrid-architecture">4.1 I/O Separation (Hybrid Architecture)</h3>
<p>In response to MCP access limitations, a clear architectural pattern emerged: separating I/O operations from intelligence operations.</p>
<p><strong>Layer Model</strong>:</p>
<table><thead><tr><th>Layer</th><th>Responsibilities</th><th>Components</th></tr></thead><tbody>
<tr><td>I/O</td><td>MCP access, file ops, user interaction, caching</td><td>Commands</td></tr>
<tr><td>Intelligence</td><td>Reasoning, analysis, formatting, decisions</td><td>Agents</td></tr>
</tbody></table>
<p><strong>6-Phase Pipeline Example</strong>:</p>
<div class="pipeline-container" id="pipeline">
<canvas class="pipeline-canvas" aria-label="Pipeline flow visualization"></canvas>
<div class="pipeline-legend">
<span class="legend-item"><span class="legend-dot command"></span> Command (I/O)</span>
<span class="legend-item"><span class="legend-dot agent"></span> Agent (Intelligence)</span>
</div>
</div>
<script>
(function() {
const containerId = 'pipeline';
const phasesData = [
{"phase": 0, "owner": "Command", "label": "Availability", "io": "external"},
{"phase": 1, "owner": "Command", "label": "Data Resolve", "io": "external"},
{"phase": 2, "owner": "Command", "label": "Load Content", "io": "local"},
{"phase": 3, "owner": "Command", "label": "Validation", "io": "external"},
{"phase": 4, "owner": "Agent", "label": "Reasoning", "io": "none"},
{"phase": 5, "owner": "Agent", "label": "Formatting", "io": "none"},
{"phase": 6, "owner": "Command", "label": "Delivery", "io": "external"}
];
function initPipeline() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.pipeline-canvas');
const ctx = canvas.getContext('2d');
// Responsive sizing
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 180;
}
resize();
window.addEventListener('resize', resize);
// Colors
const colors = {
command: '#00d4ff',
agent: '#00ff88',
external: '#8b5cf6',
local: '#ff8800',
none: '#444466',
particle: '#00ff88',
bg: 'rgba(10, 10, 15, 0.8)'
};
// Animation state
let particles = [];
let time = 0;
// Get phase positions
function getPhasePositions() {
const phases = phasesData;
const margin = 60;
const spacing = (canvas.width - margin * 2) / (phases.length - 1);
return phases.map((p, i) => ({
...p,
x: margin + i * spacing,
y: canvas.height / 2,
radius: 24
}));
}
// Create particle
function createParticle(positions) {
return {
phaseIndex: 0,
progress: 0,
speed: 0.01 + Math.random() * 0.01,
x: positions[0].x,
y: positions[0].y
};
}
// Draw
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const positions = getPhasePositions();
// Draw connections
ctx.lineWidth = 2;
ctx.strokeStyle = 'rgba(0, 212, 255, 0.3)';
ctx.beginPath();
positions.forEach((pos, i) => {
if (i === 0) ctx.moveTo(pos.x, pos.y);
else ctx.lineTo(pos.x, pos.y);
});
ctx.stroke();
// Draw arrows
for (let i = 0; i < positions.length - 1; i++) {
const from = positions[i];
const to = positions[i + 1];
const midX = (from.x + to.x) / 2;
const midY = (from.y + to.y) / 2;
ctx.fillStyle = 'rgba(0, 212, 255, 0.5)';
ctx.beginPath();
ctx.moveTo(midX - 6, midY - 4);
ctx.lineTo(midX + 6, midY);
ctx.lineTo(midX - 6, midY + 4);
ctx.closePath();
ctx.fill();
}
// Draw phase nodes
positions.forEach((pos, i) => {
const isCommand = pos.owner === 'Command';
const color = isCommand ? colors.command : colors.agent;
// Glow
const gradient = ctx.createRadialGradient(pos.x, pos.y, 0, pos.x, pos.y, pos.radius * 2);
gradient.addColorStop(0, color.replace(')', ', 0.3)').replace('rgb', 'rgba'));
gradient.addColorStop(1, 'transparent');
ctx.fillStyle = gradient;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius * 2, 0, Math.PI * 2);
ctx.fill();
// Node
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius, 0, Math.PI * 2);
ctx.fill();
// Phase number
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 14px JetBrains Mono, monospace';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(pos.phase, pos.x, pos.y);
// Label
ctx.fillStyle = '#e0e0e4';
ctx.font = '11px JetBrains Mono, monospace';
ctx.fillText(pos.label, pos.x, pos.y + pos.radius + 16);
// I/O indicator
if (pos.io !== 'none') {
ctx.fillStyle = pos.io === 'external' ? colors.external : colors.local;
ctx.font = '9px JetBrains Mono, monospace';
ctx.fillText(pos.io.toUpperCase(), pos.x, pos.y - pos.radius - 10);
}
});
// Update and draw particles
particles.forEach(p => {
if (p.phaseIndex >= positions.length - 1) {
p.phaseIndex = 0;
p.progress = 0;
}
const from = positions[p.phaseIndex];
const to = positions[p.phaseIndex + 1];
p.progress += p.speed;
if (p.progress >= 1) {
p.phaseIndex++;
p.progress = 0;
}
if (to) {
p.x = from.x + (to.x - from.x) * p.progress;
p.y = from.y + (to.y - from.y) * p.progress;
}
// Draw particle
ctx.fillStyle = colors.particle;
ctx.beginPath();
ctx.arc(p.x, p.y, 4, 0, Math.PI * 2);
ctx.fill();
// Particle glow
const pGrad = ctx.createRadialGradient(p.x, p.y, 0, p.x, p.y, 12);
pGrad.addColorStop(0, 'rgba(0, 255, 136, 0.4)');
pGrad.addColorStop(1, 'transparent');
ctx.fillStyle = pGrad;
ctx.beginPath();
ctx.arc(p.x, p.y, 12, 0, Math.PI * 2);
ctx.fill();
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
const positions = getPhasePositions();
for (let i = 0; i < 3; i++) {
const p = createParticle(positions);
p.phaseIndex = i * 2;
particles.push(p);
}
// Respect reduced motion
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const positions = getPhasePositions();
ctx.clearRect(0, 0, canvas.width, canvas.height);
ctx.lineWidth = 2;
ctx.strokeStyle = 'rgba(0, 212, 255, 0.5)';
ctx.beginPath();
positions.forEach((pos, i) => {
if (i === 0) ctx.moveTo(pos.x, pos.y);
else ctx.lineTo(pos.x, pos.y);
});
ctx.stroke();
positions.forEach((pos) => {
const color = pos.owner === 'Command' ? colors.command : colors.agent;
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 14px JetBrains Mono, monospace';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(pos.phase, pos.x, pos.y);
ctx.fillStyle = '#e0e0e4';
ctx.font = '11px JetBrains Mono, monospace';
ctx.fillText(pos.label, pos.x, pos.y + pos.radius + 16);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initPipeline);
} else {
initPipeline();
}
})();
</script>
<style>
.pipeline-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1.5rem 1rem 1rem;
margin: 1.5rem 0;
position: relative;
}
.pipeline-canvas {
width: 100%;
height: 180px;
display: block;
}
.pipeline-legend {
display: flex;
justify-content: center;
gap: 2rem;
margin-top: 0.5rem;
font-family: 'JetBrains Mono', monospace;
font-size: 0.8rem;
color: var(--meta-color);
}
.legend-item {
display: flex;
align-items: center;
gap: 0.5rem;
}
.legend-dot {
width: 12px;
height: 12px;
border-radius: 50%;
}
.legend-dot.command {
background: #00d4ff;
}
.legend-dot.agent {
background: #00ff88;
}
@media (max-width: 768px) {
.pipeline-container {
overflow-x: auto;
}
.pipeline-canvas {
min-width: 600px;
}
}
</style>
<p><strong>Generalizability</strong>: This separation applies to any framework where tool access constraints exist. The intelligence layer becomes portable and testable in isolation. The I/O layer becomes the platform-specific adapter.</p>
<h3 id="4-2-phase-based-validation">4.2 Phase-Based Validation</h3>
<p>Each phase transition represents a validation checkpoint:</p>
<table><thead><tr><th>Checkpoint</th><th>Validation</th></tr></thead><tbody>
<tr><td>Pre-phase</td><td>Input contract verification</td></tr>
<tr><td>Mid-phase</td><td>Progress checkpoint</td></tr>
<tr><td>Post-phase</td><td>Output contract enforcement</td></tr>
<tr><td>Inter-phase</td><td>Data transformation validation</td></tr>
</tbody></table>
<p><strong>Error Recovery Strategies</strong>:</p>
<ol>
<li>Rollback to last valid state</li>
<li>Retry with modified parameters</li>
<li>Escalate to fallback mode</li>
<li>Preserve partial results</li>
</ol>
<h3 id="4-3-graceful-degradation">4.3 Graceful Degradation</h3>
<p><strong>FALLBACK_MODE Pattern</strong>:</p>
<p>When external services become unavailable, the system degrades gracefully:</p>
<div class="comparison-container" id="comparis">
<canvas class="comparison-canvas" aria-label="Mode comparison visualization"></canvas>
</div>
<script>
(function() {
const containerId = 'comparis';
const mode1Title = 'Normal Mode';
const mode1Steps = ['Phase 1: MCP Resolve', 'Phase 3: Dup Check', 'Phase 6: Create Issue'];
const mode2Title = 'Fallback Mode';
const mode2Steps = ['Phase 1: Skip', 'Phase 3: Skip', 'Phase 6: Local File'];
const sharedTitle = 'Intelligence Layer (Always Active)';
const sharedSteps = ['Phase 4: Reasoning', 'Phase 5: Formatting'];
function initComparison() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.comparison-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
const colors = {
mode1: '#00d4ff',
mode2: '#ff8800',
shared: '#00ff88',
skip: '#444466',
particle: '#00ff88',
connection: 'rgba(255, 255, 255, 0.2)',
text: '#e0e0e4',
subtext: '#8888a0'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 320;
}
resize();
window.addEventListener('resize', resize);
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const leftX = canvas.width * 0.25;
const rightX = canvas.width * 0.75;
const centerX = canvas.width / 2;
const headerY = 35;
const stepsStartY = 80;
const stepSpacing = 45;
const sharedY = 240;
// Draw mode headers
function drawHeader(x, title, color) {
ctx.fillStyle = color;
ctx.font = 'bold 14px JetBrains Mono';
ctx.textAlign = 'center';
ctx.shadowColor = color;
ctx.shadowBlur = 10;
ctx.fillText(title, x, headerY);
ctx.shadowBlur = 0;
// Underline
ctx.strokeStyle = color;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.moveTo(x - 60, headerY + 8);
ctx.lineTo(x + 60, headerY + 8);
ctx.stroke();
}
drawHeader(leftX, mode1Title, colors.mode1);
drawHeader(rightX, mode2Title, colors.mode2);
// Draw steps for each mode
function drawStep(x, y, text, color, isSkip) {
const width = 130;
const height = 32;
ctx.shadowColor = color;
ctx.shadowBlur = isSkip ? 0 : 12;
ctx.fillStyle = isSkip ? colors.skip : color;
ctx.beginPath();
ctx.roundRect(x - width/2, y - height/2, width, height, 6);
ctx.fill();
ctx.shadowBlur = 0;
if (!isSkip) {
ctx.strokeStyle = '#00ff88';
ctx.lineWidth = 1;
ctx.stroke();
} else {
ctx.setLineDash([4, 4]);
ctx.strokeStyle = '#666';
ctx.lineWidth = 1;
ctx.stroke();
ctx.setLineDash([]);
}
ctx.fillStyle = isSkip ? '#666' : '#0a0a0f';
ctx.font = isSkip ? '10px JetBrains Mono' : 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(text, x, y);
return { x, y, width, height };
}
// Mode 1 steps
const mode1Nodes = [];
mode1Steps.forEach((step, i) => {
const y = stepsStartY + i * stepSpacing;
mode1Nodes.push(drawStep(leftX, y, step, colors.mode1, false));
});
// Mode 2 steps
const mode2Nodes = [];
mode2Steps.forEach((step, i) => {
const y = stepsStartY + i * stepSpacing;
const isSkip = step.toLowerCase().includes('skip');
mode2Nodes.push(drawStep(rightX, y, step, colors.mode2, isSkip));
});
// Connections between steps
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 1;
for (let i = 0; i < mode1Nodes.length - 1; i++) {
const from = mode1Nodes[i];
const to = mode1Nodes[i + 1];
ctx.beginPath();
ctx.moveTo(from.x, from.y + from.height/2);
ctx.lineTo(to.x, to.y - to.height/2);
ctx.stroke();
}
for (let i = 0; i < mode2Nodes.length - 1; i++) {
const from = mode2Nodes[i];
const to = mode2Nodes[i + 1];
ctx.beginPath();
ctx.moveTo(from.x, from.y + from.height/2);
ctx.lineTo(to.x, to.y - to.height/2);
ctx.stroke();
}
// Shared section
ctx.fillStyle = colors.shared;
ctx.font = 'bold 13px JetBrains Mono';
ctx.textAlign = 'center';
ctx.shadowColor = colors.shared;
ctx.shadowBlur = 10;
ctx.fillText(sharedTitle, centerX, sharedY - 25);
ctx.shadowBlur = 0;
// Shared steps box
const sharedWidth = 200;
const sharedHeight = 50;
ctx.fillStyle = 'rgba(0, 255, 136, 0.15)';
ctx.strokeStyle = colors.shared;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.roundRect(centerX - sharedWidth/2, sharedY - 10, sharedWidth, sharedHeight, 8);
ctx.fill();
ctx.stroke();
// Shared step text
ctx.fillStyle = colors.text;
ctx.font = '11px JetBrains Mono';
sharedSteps.forEach((step, i) => {
ctx.fillText(step, centerX, sharedY + 8 + i * 16);
});
// Arrows from both modes to shared
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 2;
// Left arrow
const lastMode1 = mode1Nodes[mode1Nodes.length - 1];
ctx.beginPath();
ctx.moveTo(lastMode1.x, lastMode1.y + lastMode1.height/2);
ctx.quadraticCurveTo(lastMode1.x, sharedY - 30, centerX - sharedWidth/2, sharedY + 15);
ctx.stroke();
// Right arrow
const lastMode2 = mode2Nodes[mode2Nodes.length - 1];
ctx.beginPath();
ctx.moveTo(lastMode2.x, lastMode2.y + lastMode2.height/2);
ctx.quadraticCurveTo(lastMode2.x, sharedY - 30, centerX + sharedWidth/2, sharedY + 15);
ctx.stroke();
// "Always Active" badge
ctx.fillStyle = colors.shared;
ctx.font = 'bold 9px JetBrains Mono';
ctx.fillText('✓ ALWAYS ACTIVE', centerX, sharedY + sharedHeight + 8);
// Animate particles
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.progress = 0;
p.side = p.side === 'left' ? 'right' : 'left';
}
const nodes = p.side === 'left' ? mode1Nodes : mode2Nodes;
const segmentIndex = Math.floor(p.progress * nodes.length);
const segmentProgress = (p.progress * nodes.length) % 1;
if (segmentIndex < nodes.length - 1) {
const from = nodes[segmentIndex];
const to = nodes[segmentIndex + 1];
const x = from.x + (to.x - from.x) * segmentProgress;
const y = from.y + (to.y - from.y) * segmentProgress;
ctx.fillStyle = colors.particle;
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(x, y, 4, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
}
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
particles.push({ side: 'left', progress: 0, speed: 0.008 });
particles.push({ side: 'right', progress: 0.5, speed: 0.008 });
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
draw();
// Just draw once for static
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initComparison);
} else {
initComparison();
}
})();
</script>
<style>
.comparison-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.comparison-canvas {
width: 100%;
height: 320px;
display: block;
}
@media (max-width: 768px) {
.comparison-container {
overflow-x: auto;
}
.comparison-canvas {
min-width: 500px;
}
}
</style>
<p>The intelligence layers (Phases 4-5) function identically in both modes. Core reasoning is preserved even when I/O capabilities are reduced.</p>
<hr />
<h2 id="5-framework-design-implications">5. Framework Design Implications</h2>
<h3 id="5-1-tool-access-philosophy">5.1 Tool Access Philosophy</h3>
<p><strong>Recommendation</strong>: Prefer explicit tool declarations over implicit inheritance.</p>
<p>The inheritance paradox demonstrates that implicit models create unexpected scope boundaries. Explicit declarations, while verbose, produce predictable behavior:</p>
<pre data-lang="yaml" class="language-yaml z-code"><code class="language-yaml" data-lang="yaml"><span class="z-source z-yaml"><span class="z-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Explicit (recommended)
</span></span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">tools</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Read</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Write</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Grep</span>
</span><span class="z-source z-yaml">
</span><span class="z-source z-yaml"><span class="z-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Implicit (problematic)
</span></span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">tools</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">inherit</span> <span class="z-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Behavior varies by context
</span></span></code></pre>
<h3 id="5-2-documentation-fidelity">5.2 Documentation Fidelity</h3>
<p><strong>Requirement</strong>: Implementation must match documentation.</p>
<p>The gap between documented and actual MCP behavior consumed significant debugging effort. Automated testing of documented behaviors would catch such discrepancies before they reach users.</p>
<h3 id="5-3-testing-in-real-contexts">5.3 Testing in Real Contexts</h3>
<p><strong>Requirement</strong>: Test with actual platform constraints.</p>
<p>MCP access works in isolation testing but fails in plugin contexts. Integration tests must execute in production-like environments with actual scope boundaries.</p>
<h3 id="5-4-developer-experience-considerations">5.4 Developer Experience Considerations</h3>
<p><strong>Observation</strong>: Complex deployment requirements discourage experimentation.</p>
<p>The three-location sync requirement, lack of hot reload, and strict schema validation add friction to the development cycle. Each constraint adds approximately 2-5 minutes per change cycle versus seconds for hot-reload systems.</p>
<p><strong>Trade-off Analysis</strong>:</p>
<table><thead><tr><th>Constraint</th><th>Benefit</th><th>Cost</th></tr></thead><tbody>
<tr><td>Three-location sync</td><td>Version consistency</td><td>Manual sync overhead</td></tr>
<tr><td>No hot reload</td><td>State predictability</td><td>Restart delay</td></tr>
<tr><td>Strict schema</td><td>Early error detection</td><td>Debugging difficulty</td></tr>
</tbody></table>
<hr />
<h2 id="6-conclusion">6. Conclusion</h2>
<h3 id="summary-of-contributions">Summary of Contributions</h3>
<p>This empirical study of Claude Code plugin development reveals patterns applicable to multi-agent AI system design:</p>
<ol>
<li>
<p><strong>The Inheritance Paradox</strong>: Tool access inheritance models documented in specifications may not function across all scope boundaries. Explicit contracts prevent unexpected behavior.</p>
</li>
<li>
<p><strong>Topology-Driven Architecture</strong>: Platform-enforced constraints (like single-level nesting) drive the emergence of specific patterns (hub-and-spoke) that may be superior to unconstrained designs.</p>
</li>
<li>
<p><strong>Naming as Behavior</strong>: In AI agent systems, naming conventions carry functional implications beyond labeling.</p>
</li>
<li>
<p><strong>I/O Separation</strong>: Separating I/O from intelligence creates portable, testable, gracefully-degrading systems.</p>
</li>
</ol>
<h3 id="limitations">Limitations</h3>
<p>This study is based on observations from a single platform (Claude Code) during a specific development period. Findings may not generalize to all agent frameworks. Additionally, platform behavior may change as bugs are resolved.</p>
<h3 id="future-research-directions">Future Research Directions</h3>
<ol>
<li>Comparative analysis of tool inheritance models across agent platforms</li>
<li>Formal specification of scope contracts for multi-agent systems</li>
<li>Empirical studies of naming-behavior coupling in other AI systems</li>
<li>Framework design patterns that explicitly leverage topology constraints</li>
</ol>
<hr />
<h2 id="appendix-evidence-summary">Appendix: Evidence Summary</h2>
<h3 id="github-issues-referenced">GitHub Issues Referenced</h3>
<table><thead><tr><th>Issue</th><th>Description</th></tr></thead><tbody>
<tr><td>#13605</td><td>Custom plugin agents can’t access MCP</td></tr>
<tr><td>#15810</td><td>Subagents don’t inherit MCP from plugin-defined agents</td></tr>
<tr><td>#14496</td><td>Inconsistent MCP access with complex prompts</td></tr>
<tr><td>#7296</td><td>Scope inheritance failure for Task-launched agents</td></tr>
</tbody></table>
<h3 id="research-metrics">Research Metrics</h3>
<ul>
<li><strong>Observation Period</strong>: January 3-4, 2026</li>
<li><strong>Token Investment</strong>: ~265,000 tokens across sessions</li>
<li><strong>Distinct Observations</strong>: 13 documented findings</li>
<li><strong>Finding Types</strong>: 4 Decisions, 8 Discoveries, 1 Change</li>
</ul>
<h3 id="methodology">Methodology</h3>
<p>Observations were collected through development sessions using the claude-mem persistent memory system. Each finding was cross-referenced against documentation and, where applicable, GitHub issue reports. Workarounds were developed through iterative experimentation.</p>
<hr />
<h2 id="get-the-plugin">Get the Plugin</h2>
<p>The plugin discussed in this research is open source: <a href="https://github.com/Cpicon/claude-code-plugins">Cpicon/claude-code-plugins</a></p>
<p>Use the <a href="https://github.com/Cpicon/claude-code-plugins/issues">GitHub Issues</a> tab to request features, report bugs, or discuss improvements.</p>
<hr />
<p><strong>Series Navigation:</strong></p>
<ul>
<li><strong>Part 0</strong>: <a href="/posts/claude-code-plugin-journey-part0/">Agent Team Creator</a> — What the plugin does and how to use it</li>
<li><strong>Part 1</strong>: <a href="/posts/claude-code-plugin-journey-part1/">The Hybrid Architecture Pattern</a> — Building the plugin, lessons learned</li>
<li><strong>Part 2</strong> (You are here): Research insights, patterns</li>
</ul>
<hr />
<p><em>This article is based on empirical observations from developing the agent-team-creator Claude Code plugin. For practical implementation guidance, see Part 1.</em></p>
The Inheritance Paradox: Tool Scoping in Multi-Agent Systems
This is Part 2 of a three-part series. See Part 0 for the plugin overview and installation, or Part 1 for the development journey.
Abstract: This article presents empirical observations from developing a Claude Code plugin, revealing fundamental patterns in multi-agent AI system design. Through documented development sessions, we identify three key findings: (1) implicit tool inheritance models consistently fail in practice, requiring explicit scope contracts; (2) platform-enforced topology constraints drive the emergence of specific architectural patterns; and (3) agent naming conventions become functional requirements in AI systems. These findings have implications for the design of agent frameworks beyond the specific platform studied.
…