connectry-architect-mcp 0.1.0 → 0.1.2

package/dist/data/curriculum.json

@@ -0,0 +1,74 @@
+{
+  "domains": [
+    {
+      "id": 1,
+      "title": "Agentic Architecture & Orchestration",
+      "weight": 27,
+      "mentalModel": "The model drives decisions, code enforces guardrails",
+      "taskStatements": [
+        { "id": "1.1", "domainId": 1, "title": "Design and implement agentic loops for autonomous task execution", "description": "Understanding the agentic loop lifecycle: sending requests, inspecting stop_reason, executing tools, and returning results.", "mentalModel": "The model drives decisions, code enforces guardrails" },
+        { "id": "1.2", "domainId": 1, "title": "Orchestrate multi-agent systems with coordinator-subagent patterns", "description": "Hub-and-spoke architecture, isolated context, task decomposition, and result aggregation.", "mentalModel": "The model drives decisions, code enforces guardrails" },
+        { "id": "1.3", "domainId": 1, "title": "Configure subagent invocation, context passing, and spawning", "description": "Task tool, allowedTools, explicit context passing, parallel subagent execution.", "mentalModel": "The model drives decisions, code enforces guardrails" },
+        { "id": "1.4", "domainId": 1, "title": "Implement multi-step workflows with enforcement and handoff patterns", "description": "Programmatic enforcement vs prompt-based guidance, structured handoff protocols.", "mentalModel": "The model drives decisions, code enforces guardrails" },
+        { "id": "1.5", "domainId": 1, "title": "Apply Agent SDK hooks for tool call interception and data normalization", "description": "PostToolUse hooks, tool call interception, deterministic vs probabilistic compliance.", "mentalModel": "The model drives decisions, code enforces guardrails" },
+        { "id": "1.6", "domainId": 1, "title": "Design task decomposition strategies for complex workflows", "description": "Prompt chaining vs dynamic decomposition, per-file analysis vs cross-file integration.", "mentalModel": "The model drives decisions, code enforces guardrails" },
+        { "id": "1.7", "domainId": 1, "title": "Manage session state, resumption, and forking", "description": "Named sessions, fork_session, structured summaries vs stale context.", "mentalModel": "The model drives decisions, code enforces guardrails" }
+      ]
+    },
+    {
+      "id": 2,
+      "title": "Tool Design & MCP Integration",
+      "weight": 18,
+      "mentalModel": "Tool descriptions are the LLM's only guide — design them like API docs",
+      "taskStatements": [
+        { "id": "2.1", "domainId": 2, "title": "Design effective tool interfaces with clear descriptions and boundaries", "description": "Tool descriptions as selection mechanism, disambiguation, splitting vs consolidating.", "mentalModel": "Tool descriptions are the LLM's only guide — design them like API docs" },
+        { "id": "2.2", "domainId": 2, "title": "Implement structured error responses for MCP tools", "description": "isError flag, error categories, retryable vs non-retryable, structured metadata.", "mentalModel": "Tool descriptions are the LLM's only guide — design them like API docs" },
+        { "id": "2.3", "domainId": 2, "title": "Distribute tools appropriately across agents and configure tool choice", "description": "Scoped tool access, tool_choice options, forced selection patterns.", "mentalModel": "Tool descriptions are the LLM's only guide — design them like API docs" },
+        { "id": "2.4", "domainId": 2, "title": "Integrate MCP servers into Claude Code and agent workflows", "description": "Project vs user scope, .mcp.json, environment variable expansion, MCP resources.", "mentalModel": "Tool descriptions are the LLM's only guide — design them like API docs" },
+        { "id": "2.5", "domainId": 2, "title": "Select and apply built-in tools effectively", "description": "Grep vs Glob vs Read/Write/Edit, incremental codebase understanding.", "mentalModel": "Tool descriptions are the LLM's only guide — design them like API docs" }
+      ]
+    },
+    {
+      "id": 3,
+      "title": "Claude Code Configuration & Workflows",
+      "weight": 20,
+      "mentalModel": "Hierarchy of instructions: user → project → directory, each scoped to its audience",
+      "taskStatements": [
+        { "id": "3.1", "domainId": 3, "title": "Configure CLAUDE.md files with appropriate hierarchy and scoping", "description": "User-level, project-level, directory-level, @import syntax, .claude/rules/.", "mentalModel": "Hierarchy of instructions: user → project → directory, each scoped to its audience" },
+        { "id": "3.2", "domainId": 3, "title": "Create and configure custom slash commands and skills", "description": "Project vs user scope, context: fork, allowed-tools, argument-hint frontmatter.", "mentalModel": "Hierarchy of instructions: user → project → directory, each scoped to its audience" },
+        { "id": "3.3", "domainId": 3, "title": "Apply path-specific rules for conditional convention loading", "description": "YAML frontmatter paths, glob patterns, conditional activation.", "mentalModel": "Hierarchy of instructions: user → project → directory, each scoped to its audience" },
+        { "id": "3.4", "domainId": 3, "title": "Determine when to use plan mode vs direct execution", "description": "Complexity assessment, architectural decisions, Explore subagent.", "mentalModel": "Hierarchy of instructions: user → project → directory, each scoped to its audience" },
+        { "id": "3.5", "domainId": 3, "title": "Apply iterative refinement techniques for progressive improvement", "description": "Input/output examples, test-driven iteration, interview pattern.", "mentalModel": "Hierarchy of instructions: user → project → directory, each scoped to its audience" },
+        { "id": "3.6", "domainId": 3, "title": "Integrate Claude Code into CI/CD pipelines", "description": "-p flag, --output-format json, --json-schema, session context isolation.", "mentalModel": "Hierarchy of instructions: user → project → directory, each scoped to its audience" }
+      ]
+    },
+    {
+      "id": 4,
+      "title": "Prompt Engineering & Structured Output",
+      "weight": 20,
+      "mentalModel": "Specificity beats vagueness. Examples beat instructions. Schemas beat parsing.",
+      "taskStatements": [
+        { "id": "4.1", "domainId": 4, "title": "Design prompts with explicit criteria to improve precision", "description": "Explicit criteria vs vague instructions, false positive management.", "mentalModel": "Specificity beats vagueness. Examples beat instructions. Schemas beat parsing." },
+        { "id": "4.2", "domainId": 4, "title": "Apply few-shot prompting to improve output consistency", "description": "Targeted examples, ambiguous case handling, format demonstration.", "mentalModel": "Specificity beats vagueness. Examples beat instructions. Schemas beat parsing." },
+        { "id": "4.3", "domainId": 4, "title": "Enforce structured output using tool use and JSON schemas", "description": "tool_use with schemas, tool_choice options, nullable fields, enum patterns.", "mentalModel": "Specificity beats vagueness. Examples beat instructions. Schemas beat parsing." },
+        { "id": "4.4", "domainId": 4, "title": "Implement validation, retry, and feedback loops", "description": "Retry-with-error-feedback, limits of retry, detected_pattern tracking.", "mentalModel": "Specificity beats vagueness. Examples beat instructions. Schemas beat parsing." },
+        { "id": "4.5", "domainId": 4, "title": "Design efficient batch processing strategies", "description": "Message Batches API, latency tolerance, custom_id, failure handling.", "mentalModel": "Specificity beats vagueness. Examples beat instructions. Schemas beat parsing." },
+        { "id": "4.6", "domainId": 4, "title": "Design multi-instance and multi-pass review architectures", "description": "Self-review limitations, independent review instances, per-file + cross-file passes.", "mentalModel": "Specificity beats vagueness. Examples beat instructions. Schemas beat parsing." }
+      ]
+    },
+    {
+      "id": 5,
+      "title": "Context Management & Reliability",
+      "weight": 15,
+      "mentalModel": "Context is finite and degrades — extract facts, trim noise, verify provenance",
+      "taskStatements": [
+        { "id": "5.1", "domainId": 5, "title": "Manage conversation context to preserve critical information", "description": "Progressive summarization risks, lost-in-the-middle, tool output trimming.", "mentalModel": "Context is finite and degrades — extract facts, trim noise, verify provenance" },
+        { "id": "5.2", "domainId": 5, "title": "Design effective escalation and ambiguity resolution patterns", "description": "Escalation triggers, customer preferences, sentiment unreliability.", "mentalModel": "Context is finite and degrades — extract facts, trim noise, verify provenance" },
+        { "id": "5.3", "domainId": 5, "title": "Implement error propagation strategies across multi-agent systems", "description": "Structured error context, access failures vs empty results, partial results.", "mentalModel": "Context is finite and degrades — extract facts, trim noise, verify provenance" },
+        { "id": "5.4", "domainId": 5, "title": "Manage context effectively in large codebase exploration", "description": "Context degradation, scratchpad files, subagent delegation, /compact.", "mentalModel": "Context is finite and degrades — extract facts, trim noise, verify provenance" },
+        { "id": "5.5", "domainId": 5, "title": "Design human review workflows and confidence calibration", "description": "Stratified sampling, field-level confidence, accuracy by document type.", "mentalModel": "Context is finite and degrades — extract facts, trim noise, verify provenance" },
+        { "id": "5.6", "domainId": 5, "title": "Preserve information provenance and handle uncertainty in synthesis", "description": "Claim-source mappings, conflict annotation, temporal data handling.", "mentalModel": "Context is finite and degrades — extract facts, trim noise, verify provenance" }
+      ]
+    }
+  ]
+}

package/dist/data/handouts/1.1-design-and-implement-agentic-loops-for-autonomous-task-execution.md

@@ -0,0 +1,36 @@
+# 1.1 — Agentic Loops for Autonomous Task Execution
+
+## Concept
+
+When Claude uses tools, it follows a cycle: send a message → Claude decides to call a tool → execute the tool → return the result → Claude decides what to do next. This is the **agentic loop**.
+
+The key mechanism is `stop_reason`:
+- `"tool_use"` → Claude wants to use another tool. Keep the loop going.
+- `"end_turn"` → Claude is done. Present the response.
+
+## Code Example
+
+```typescript
+while (true) {
+  const response = await client.messages.create({ /* ... */ });
+
+  if (response.stop_reason === 'end_turn') {
+    return response; // Done — present to user
+  }
+
+  // Execute requested tools
+  const toolResults = await executeTools(response.content);
+  messages.push({ role: 'assistant', content: response.content });
+  messages.push({ role: 'user', content: toolResults });
+}
+```
+
+## Common Mistakes
+
+1. **Parsing text to detect completion** — Don't check if the assistant said "I'm done." Use `stop_reason`.
+2. **Arbitrary iteration caps** — Don't set `maxIterations = 5` as the primary stopping mechanism.
+3. **Checking for text content** — Don't assume the loop is done because the response contains text.
+
+## References
+
+- [Anthropic Agent SDK Documentation](https://docs.anthropic.com/en/docs/agents)

package/dist/data/handouts/1.2-orchestrate-multi-agent-systems-with-coordinator-subagent-patterns.md

@@ -0,0 +1,125 @@
+# 1.2 — Orchestrate Multi-Agent Systems with Coordinator-Subagent Patterns
+
+## Concept
+
+Multi-agent systems follow a **hub-and-spoke** (coordinator-subagent) pattern. A single coordinator agent receives a complex task, decomposes it into well-scoped subtasks, delegates each subtask to a specialized subagent, and then aggregates the results into a final response. The coordinator never tries to do everything itself — it drives decisions, while each subagent operates within guardrails enforced in code.
+
+The critical design principle is **isolated context**: every subagent runs in its own independent conversation. It has no memory of what other subagents said, and it cannot read the coordinator's full conversation history. This isolation prevents context contamination, keeps each subagent focused, and makes the system easier to reason about. The coordinator is the only node that holds the full picture — it receives outputs from each spoke and synthesizes them.
+
+Task decomposition is where the model earns its role. The coordinator's system prompt instructs Claude to analyze the incoming request and produce a structured breakdown of subtasks before any subagent is spawned. Each subtask has a clear scope, a defined output format, and a minimal `allowedTools` list. Result aggregation happens after all subagents complete: the coordinator receives their outputs as tool results, reasons across them, and produces a coherent final answer. The mental model is: **the model drives decisions, code enforces guardrails** — Claude decides which subagents to invoke and how to interpret their outputs; your application code controls which tools each subagent may access and what data it can see.
+
+## Code Example
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic();
+
+// Coordinator: receives a complex task and delegates to subagents
+async function coordinator(userTask: string): Promise<string> {
+  const messages: Anthropic.MessageParam[] = [
+    { role: "user", content: userTask },
+  ];
+
+  // Agentic loop — coordinator decides which subagents to invoke
+  while (true) {
+    const response = await client.messages.create({
+      model: "claude-opus-4-5",
+      max_tokens: 4096,
+      system:
+        "You are a coordinator. Break complex tasks into subtasks and delegate each to a specialized subagent using the available tools. Synthesize their outputs into a final answer.",
+      tools: [
+        {
+          name: "run_research_agent",
+          description: "Spawn a subagent that researches a specific topic.",
+          input_schema: {
+            type: "object" as const,
+            properties: {
+              query: {
+                type: "string",
+                description: "The focused research question.",
+              },
+            },
+            required: ["query"],
+          },
+        },
+        {
+          name: "run_analysis_agent",
+          description: "Spawn a subagent that analyzes provided data.",
+          input_schema: {
+            type: "object" as const,
+            properties: {
+              data: { type: "string", description: "Raw data to analyze." },
+            },
+            required: ["data"],
+          },
+        },
+      ],
+      messages,
+    });
+
+    if (response.stop_reason === "end_turn") {
+      const textBlock = response.content.find((b) => b.type === "text");
+      return textBlock ? textBlock.text : "";
+    }
+
+    // Execute tool calls — each spawns an isolated subagent conversation
+    const toolResults: Anthropic.ToolResultBlockParam[] = [];
+    for (const block of response.content) {
+      if (block.type !== "tool_use") continue;
+
+      let result: string;
+      if (block.name === "run_research_agent") {
+        const input = block.input as { query: string };
+        result = await researchSubagent(input.query); // isolated context
+      } else {
+        const input = block.input as { data: string };
+        result = await analysisSubagent(input.data); // isolated context
+      }
+
+      toolResults.push({ type: "tool_result", tool_use_id: block.id, content: result });
+    }
+
+    messages.push({ role: "assistant", content: response.content });
+    messages.push({ role: "user", content: toolResults });
+  }
+}
+
+// Subagent: isolated conversation, restricted tools
+async function researchSubagent(query: string): Promise<string> {
+  const response = await client.messages.create({
+    model: "claude-haiku-4-5",
+    max_tokens: 1024,
+    system: "You are a research specialist. Answer only the question asked.",
+    messages: [{ role: "user", content: query }],
+    // No tools — this subagent only reasons, does not act
+  });
+
+  const textBlock = response.content.find((b) => b.type === "text");
+  return textBlock?.text ?? "";
+}
+
+async function analysisSubagent(data: string): Promise<string> {
+  const response = await client.messages.create({
+    model: "claude-haiku-4-5",
+    max_tokens: 1024,
+    system: "You are a data analyst. Summarize key insights from the data.",
+    messages: [{ role: "user", content: `Analyze this data:\n\n${data}` }],
+  });
+
+  const textBlock = response.content.find((b) => b.type === "text");
+  return textBlock?.text ?? "";
+}
+```
+
+## Common Mistakes
+
+1. **Sharing the full conversation history with subagents** — Each subagent should receive only the context it needs for its specific subtask. Passing the coordinator's entire message history bloats the context window, leaks unrelated information, and produces worse-focused outputs.
+2. **Letting subagents call other subagents directly** — In a hub-and-spoke topology, only the coordinator routes work. Allowing subagents to spawn their own subagents creates uncontrolled fan-out, makes aggregation logic unpredictable, and breaks the single-point-of-synthesis guarantee.
+3. **Skipping task decomposition and going straight to subagent invocation** — Without a structured decomposition step, the coordinator tends to spawn overlapping or redundant subagents. Always instruct the coordinator to plan subtasks first; the decomposition itself is where the model earns its role.
+
+## References
+
+- [Anthropic: Build multi-agent systems](https://docs.anthropic.com/en/docs/agents/multi-agent-systems)
+- [Anthropic: Tool use overview](https://docs.anthropic.com/en/docs/tool-use)
+- [Anthropic: Model overview (choosing Haiku vs Sonnet vs Opus)](https://docs.anthropic.com/en/docs/about-claude/models)

package/dist/data/handouts/1.3-configure-subagent-invocation-context-passing-and-spawning.md

@@ -0,0 +1,109 @@
+# 1.3 — Configure Subagent Invocation, Context Passing, and Spawning
+
+## Concept
+
+In multi-agent systems, an orchestrator agent spawns subagents to handle discrete subtasks. The **Task tool** in the Claude Agent SDK is the primary mechanism for this: the orchestrator calls `Task` with a description of the work, an optional set of allowed tools, and any context the subagent needs to execute independently. The SDK handles launching a fresh agent loop for that subagent, running it to completion, and returning the result to the orchestrator.
+
+Tool scoping via `allowedTools` is critical for security and predictability. Each subagent should only have access to the tools it actually needs. A subagent responsible for reading files should not have write or shell execution tools. This principle of least privilege prevents runaway agents from taking destructive actions and makes the system easier to reason about. If `allowedTools` is omitted, the subagent inherits all tools available in the environment — a common source of unintended side effects.
+
+Context isolation is the other essential discipline. Subagents do not share memory or conversation state with the orchestrator or with each other. Any information a subagent needs — user intent, prior results, relevant file contents, configuration — must be passed explicitly in the task prompt. Relying on shared global state or assuming a subagent "remembers" something from the parent conversation is a design error that produces silent, hard-to-debug failures. When you need to run multiple subagents over the same data, pass that data explicitly to each one. Parallel execution with `Promise.all` is both safe and efficient when subagents are truly independent, since each runs in its own isolated context.
+
+## Code Example
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic();
+
+// Orchestrator spawns two parallel subagents with scoped tools and explicit context
+async function analyzeRepository(repoSummary: string): Promise<void> {
+  const [securityReport, qualityReport] = await Promise.all([
+    // Subagent 1: security review — read-only file access only
+    client.beta.messages.create({
+      model: "claude-sonnet-4-6",
+      max_tokens: 4096,
+      tools: [
+        {
+          type: "computer_20241022",
+          name: "Task",
+          description: "Spawn a subagent for security review",
+        },
+      ],
+      messages: [
+        {
+          role: "user",
+          content: `You are a security reviewer. Analyze this repository summary for vulnerabilities.
+
+Repository context:
+${repoSummary}
+
+Use only read_file to inspect individual files. Do not write or execute anything.
+Return a structured JSON report with findings.`,
+        },
+      ],
+      betas: ["computer-use-2024-10-22"],
+    }),
+
+    // Subagent 2: code quality — read-only, no security concerns
+    client.beta.messages.create({
+      model: "claude-sonnet-4-6",
+      max_tokens: 4096,
+      messages: [
+        {
+          role: "user",
+          content: `You are a code quality reviewer. Analyze this repository summary for maintainability issues.
+
+Repository context:
+${repoSummary}
+
+Focus on: naming conventions, file size, cyclomatic complexity, dead code.
+Return a structured JSON report with findings.`,
+        },
+      ],
+    }),
+  ]);
+
+  // Aggregate results from both isolated subagents
+  console.log("Security findings:", securityReport.content);
+  console.log("Quality findings:", qualityReport.content);
+}
+
+// Explicit context passing — never rely on shared state
+async function processChunks(chunks: string[]): Promise<string[]> {
+  return Promise.all(
+    chunks.map((chunk, index) =>
+      client.messages
+        .create({
+          model: "claude-haiku-4-5",
+          max_tokens: 1024,
+          messages: [
+            {
+              role: "user",
+              // Each subagent receives its full context explicitly
+              content: `Process chunk ${index + 1} of ${chunks.length}:
+
+${chunk}
+
+Return a one-paragraph summary.`,
+            },
+          ],
+        })
+        .then((r) => r.content[0].type === "text" ? r.content[0].text : "")
+    )
+  );
+}
+```
+
+## Common Mistakes
+
+1. **Omitting `allowedTools` on subagents** — Without explicit scoping, subagents inherit all available tools. A summarization subagent that accidentally has shell execution access can cause unintended side effects. Always declare the minimal set of tools each subagent requires.
+
+2. **Passing context by reference or shared state** — Subagents run in isolated loops with no access to the orchestrator's conversation history. Storing shared context in a global variable and expecting subagents to read it silently fails. Every piece of information a subagent needs must appear in its initial `messages` array.
+
+3. **Running independent subagents sequentially** — Using `await` in a loop when subagents do not depend on each other's results wastes wall-clock time proportional to the number of agents. Use `Promise.all` (or `Promise.allSettled` when partial failures are acceptable) to run truly independent subagents concurrently.
+
+## References
+
+- [Anthropic: Build multi-agent systems](https://docs.anthropic.com/en/docs/build-with-claude/agents)
+- [Anthropic: Tool use overview](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)
+- [Anthropic: Model context and memory](https://docs.anthropic.com/en/docs/build-with-claude/memory-and-storage)

package/dist/data/handouts/1.4-implement-multi-step-workflows-with-enforcement-and-handoff-patterns.md

@@ -0,0 +1,120 @@
+# 1.4 — Implement Multi-Step Workflows with Enforcement and Handoff Patterns
+
+## Concept
+
+Multi-step agentic workflows require more than just chaining prompts together. Each stage may produce output that the next stage depends on, and the correctness of that handoff determines whether the entire pipeline succeeds. There are two fundamentally different ways to ensure a workflow progresses correctly: **prompt-based guidance** and **programmatic enforcement**.
+
+Prompt-based guidance relies on instructions in the system or user prompt to steer the model — telling it to "always return valid JSON" or "only proceed if the previous step succeeded." This is convenient but fragile: the model may deviate under long context pressure, unexpected input, or ambiguous situations. The prompt provides no hard guarantees. Programmatic enforcement, by contrast, validates outputs in code after each model response before passing them to the next stage. If the output fails validation, the workflow halts or retries — the model's good intentions are irrelevant.
+
+The structured handoff pattern bridges these stages: each step produces a typed, validated payload that the next step receives as its input. Rather than passing raw text between steps, you define an interface for what each stage emits and parse the model's output against that schema. This creates a clear contract at every boundary. The general rule is: use deterministic code for anything that must be correct (schema validation, precondition checks, routing logic), and use model flexibility for anything that requires judgment (summarization, classification, generation). Mixing the two — trusting the model to enforce its own constraints — is the most common source of silent workflow failures.
+
+## Code Example
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { z } from "zod";
+
+const client = new Anthropic();
+
+// --- Stage schemas define the handoff contract ---
+
+const ResearchOutputSchema = z.object({
+  topic: z.string(),
+  keyFindings: z.array(z.string()).min(1),
+  confidence: z.enum(["low", "medium", "high"]),
+});
+
+const DraftOutputSchema = z.object({
+  title: z.string(),
+  body: z.string().min(100),
+  wordCount: z.number().int().positive(),
+});
+
+type ResearchOutput = z.infer<typeof ResearchOutputSchema>;
+type DraftOutput = z.infer<typeof DraftOutputSchema>;
+
+// --- Programmatic enforcement via a typed step runner ---
+
+async function runStep<T>(
+  systemPrompt: string,
+  userMessage: string,
+  schema: z.ZodType<T>,
+  maxRetries = 2
+): Promise<T> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const response = await client.messages.create({
+      model: "claude-sonnet-4-5",
+      max_tokens: 1024,
+      system: systemPrompt,
+      messages: [{ role: "user", content: userMessage }],
+    });
+
+    const text = response.content
+      .filter((b) => b.type === "text")
+      .map((b) => b.text)
+      .join("");
+
+    // Programmatic enforcement: parse and validate before proceeding
+    try {
+      const parsed = JSON.parse(text);
+      return schema.parse(parsed); // throws ZodError if schema not satisfied
+    } catch (err) {
+      if (attempt === maxRetries) {
+        throw new Error(
+          `Step failed schema validation after ${maxRetries + 1} attempts: ${err}`
+        );
+      }
+      // Could inject the validation error back into the next attempt here
+    }
+  }
+  throw new Error("Unreachable");
+}
+
+// --- Structured handoff: each stage receives the previous stage's validated output ---
+
+async function researchStage(topic: string): Promise<ResearchOutput> {
+  return runStep(
+    'You are a research assistant. Respond ONLY with a JSON object matching: { "topic": string, "keyFindings": string[], "confidence": "low"|"medium"|"high" }',
+    `Research this topic and return structured findings: ${topic}`,
+    ResearchOutputSchema
+  );
+}
+
+async function draftStage(research: ResearchOutput): Promise<DraftOutput> {
+  // The handoff: structured context from stage 1 becomes the input for stage 2
+  const handoffContext = JSON.stringify(research, null, 2);
+
+  return runStep(
+    'You are a technical writer. Respond ONLY with a JSON object matching: { "title": string, "body": string, "wordCount": number }',
+    `Using this research, write a short article:\n\n${handoffContext}`,
+    DraftOutputSchema
+  );
+}
+
+// --- Orchestrator: deterministic routing, not prompt-guided ---
+
+async function runWorkflow(topic: string): Promise<DraftOutput> {
+  const research = await researchStage(topic);
+
+  // Deterministic gate: model judgment not trusted for routing decisions
+  if (research.confidence === "low") {
+    throw new Error(
+      `Research confidence too low for topic "${topic}". Aborting draft stage.`
+    );
+  }
+
+  return draftStage(research);
+}
+```
+
+## Common Mistakes
+
+1. **Trusting the model to self-validate** — Adding "ensure your output is valid JSON" to a prompt is not enforcement. Parse and validate in code; if the schema check fails, the step failed regardless of what the model intended.
+2. **Passing raw text between stages** — Handing the raw string output of one step directly into the next prompt makes the pipeline brittle. A single unexpected phrase or formatting quirk in stage one breaks stage two. Always parse into a typed structure at each boundary.
+3. **Using model output for routing decisions** — Letting the model decide whether to proceed to the next stage (e.g., "if you think the data is ready, say PROCEED") mixes concerns incorrectly. Routing logic belongs in deterministic code; use schema-validated fields like `confidence` or `status` to drive control flow.
+
+## References
+
+- [Anthropic: Build with Claude — Workflows and orchestration](https://docs.anthropic.com/en/docs/build-with-claude/workflows)
+- [Anthropic: Tool use overview](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview)
+- [Zod schema validation](https://zod.dev/)

package/dist/data/handouts/1.5-apply-agent-sdk-hooks-for-tool-call-interception-and-data-normalization.md

@@ -0,0 +1,155 @@
+# 1.5 — Apply Agent SDK Hooks for Tool Call Interception and Data Normalization
+
+## Concept
+
+The Agent SDK exposes a hook system that lets you attach callbacks at key points in the agentic loop without modifying the core execution logic. Two hooks are central to this: **`beforeToolCall`** fires immediately after Claude requests a tool but before the tool executes, and **`afterToolCall`** fires after the tool returns but before the result is sent back to the model. These hooks receive the full tool call context — name, input arguments, and (in the case of `afterToolCall`) the raw output — giving you a structured intercept point for validation, transformation, and logging.
+
+This architecture matters because it separates cross-cutting concerns from tool implementation. A tool that queries a database should not need to know about audit logging, input sanitization, or output schema normalization. Hooks handle those responsibilities once, centrally, and consistently. Every tool call passes through the same pipeline regardless of which tool is invoked or which part of your codebase registered it.
+
+The distinction between **deterministic compliance** and **probabilistic compliance** is critical here. Probabilistic compliance means adding instructions to the system prompt such as "always return dates in ISO 8601 format" and hoping the model follows them. This works most of the time but fails silently when it doesn't. Deterministic compliance means enforcing the rule in code — in an `afterToolCall` hook that parses and reformats every date field in every tool output before the model ever sees it. The hook runs every time, unconditionally. For anything that must be reliably true — sanitized inputs, normalized schemas, redacted PII, validated ranges — deterministic enforcement via hooks is the correct approach.
+
+## Code Example
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic();
+
+// --- Hook definitions ---
+
+function beforeToolCall(toolName: string, toolInput: Record<string, unknown>): Record<string, unknown> {
+  // Validate that required fields are present
+  if (toolName === "query_database" && typeof toolInput.table !== "string") {
+    throw new Error(`beforeToolCall: 'table' must be a string, got ${typeof toolInput.table}`);
+  }
+
+  // Normalize inputs deterministically — no model instruction needed
+  const normalized = { ...toolInput };
+  if (typeof normalized.limit === "number") {
+    normalized.limit = Math.min(normalized.limit, 100); // enforce hard cap
+  }
+
+  return normalized;
+}
+
+function afterToolCall(
+  toolName: string,
+  rawOutput: unknown
+): Record<string, unknown> {
+  if (typeof rawOutput !== "object" || rawOutput === null) {
+    return { result: rawOutput };
+  }
+
+  const output = rawOutput as Record<string, unknown>;
+
+  // Normalize date fields to ISO 8601 — deterministic, not instructional
+  const normalized = Object.fromEntries(
+    Object.entries(output).map(([key, value]) => {
+      if (key.endsWith("_at") || key.endsWith("_date")) {
+        const parsed = new Date(value as string);
+        return [key, isNaN(parsed.getTime()) ? value : parsed.toISOString()];
+      }
+      return [key, value];
+    })
+  );
+
+  // Redact sensitive fields before they reach the model context
+  const { password, secret, api_key, ...safe } = normalized as Record<string, unknown>;
+  void password; void secret; void api_key; // explicitly discarded
+
+  return safe;
+}
+
+// --- Tool executor that applies hooks ---
+
+async function executeToolWithHooks(
+  toolName: string,
+  rawInput: Record<string, unknown>,
+  tools: Record<string, (input: Record<string, unknown>) => Promise<unknown>>
+): Promise<Record<string, unknown>> {
+  const validatedInput = beforeToolCall(toolName, rawInput);
+
+  const tool = tools[toolName];
+  if (!tool) throw new Error(`Unknown tool: ${toolName}`);
+
+  const rawOutput = await tool(validatedInput);
+  return afterToolCall(toolName, rawOutput);
+}
+
+// --- Usage in the agentic loop ---
+
+async function runAgentWithHooks(userMessage: string) {
+  const tools: Anthropic.Tool[] = [
+    {
+      name: "query_database",
+      description: "Query a database table",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          table: { type: "string" },
+          limit: { type: "number" },
+        },
+        required: ["table"],
+      },
+    },
+  ];
+
+  const toolImpls: Record<string, (input: Record<string, unknown>) => Promise<unknown>> = {
+    query_database: async (input) => ({
+      rows: [{ id: 1, created_at: "2024-01-15", password: "hunter2" }],
+      table: input.table,
+    }),
+  };
+
+  const messages: Anthropic.MessageParam[] = [
+    { role: "user", content: userMessage },
+  ];
+
+  while (true) {
+    const response = await client.messages.create({
+      model: "claude-sonnet-4-5",
+      max_tokens: 1024,
+      tools,
+      messages,
+    });
+
+    if (response.stop_reason === "end_turn") {
+      return response;
+    }
+
+    const toolResults: Anthropic.ToolResultBlockParam[] = [];
+
+    for (const block of response.content) {
+      if (block.type === "tool_use") {
+        const normalizedOutput = await executeToolWithHooks(
+          block.name,
+          block.input as Record<string, unknown>,
+          toolImpls
+        );
+        toolResults.push({
+          type: "tool_result",
+          tool_use_id: block.id,
+          content: JSON.stringify(normalizedOutput),
+        });
+      }
+    }
+
+    messages.push({ role: "assistant", content: response.content });
+    messages.push({ role: "user", content: toolResults });
+  }
+}
+```
+
+## Common Mistakes
+
+1. **Using system prompt instructions instead of hooks for data contracts.** Writing "always return dates as ISO 8601" in the system prompt is probabilistic — the model may comply, but it is not guaranteed. If downstream systems depend on date format consistency, enforce it in `afterToolCall` where the transformation is unconditional.
+
+2. **Mutating the input object passed to `beforeToolCall`.** Modifying the original input in-place creates hidden side effects and makes debugging difficult. Always return a new object (`{ ...toolInput, limit: cap }`) rather than reassigning properties on the argument directly.
+
+3. **Swallowing hook errors silently.** A `beforeToolCall` hook that catches a validation failure and returns a default value instead of throwing allows invalid tool calls to proceed undetected. Throw explicitly with a descriptive message so the failure surfaces in logs and halts execution at the correct point.
+
+## References
+
+- [Anthropic Agent SDK — Hooks](https://docs.anthropic.com/en/docs/agents-and-tools/agent-sdk/hooks)
+- [Tool Use Overview](https://docs.anthropic.com/en/docs/tool-use)
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)