@opengroundplan/core 0.1.1

package/templates/agent-kits/core/files/specs/README.md

@@ -0,0 +1,32 @@
+# Specs
+
+Feature work is spec-driven. Each feature gets a numbered folder:
+
+```
+specs/001-user-invites/
+├── spec.md      what and why — deliberately no tech stack
+├── plan.md      technical strategy
+└── tasks.md     actionable breakdown
+```
+
+Copy [`000-template/`](000-template/) to start one.
+
+## Why this order
+
+Writing `spec.md` first — with the tech stack deliberately excluded — forces the *problem* to
+be settled before the *solution*. An agent handed a spec that already assumes an
+implementation will faithfully build the wrong thing.
+
+Each artifact feeds the next, which gives an agent structured context instead of an ad-hoc
+prompt.
+
+## When to skip it
+
+A one-line fix, a typo, a dependency bump. Ceremony on a trivial change is waste. The
+threshold is roughly: *would a reviewer ask "why did we do it this way?"* If yes, write the
+spec.
+
+## Numbering
+
+Sequential, zero-padded, never reused. The number is a stable reference — `specs/007` should
+mean the same thing in a commit message a year from now.

package/templates/architectures/agentic-tool-loop/blueprint.yaml

@@ -0,0 +1,137 @@
+# Agentic tool loop — folder overlay plus the enforcement that keeps it bounded.
+#
+# The layout is worthless without the caps: an agent loop with no turn or token ceiling is
+# the top cause of runaway spend, so every cap is a config field and a numeric cap literal
+# outside the config module fails a command.
+id: agentic-tool-loop
+kind: architecture
+name: Agentic Tool Loop
+description: >-
+  Folder overlay for a single-model agent loop: one registry that owns every tool schema, a
+  loop with hard turn and token caps read from config, a structured trace of every turn and
+  tool call, a sandbox seam that gates irreversible effects, and a per-stack check that fails
+  when a tool is unregistered, the model is called outside the one client, or a cap is
+  written as a literal.
+
+tags:
+  - agent
+  - agentic
+  - tool-use
+  - llm
+  - ai
+  - tool-registry
+  - turn-cap
+  - token-cap
+  - tracing
+  - sandbox
+  - boundaries
+
+requires: []
+conflicts: []
+provides:
+  - agent-loop
+  - tool-registry
+  - loop-budget-caps
+  - agent-tracing
+  - sandbox-seam
+  - boundary-enforcement
+
+# An overlay is chosen through the architecture question, never listed as a supported target.
+supportsArchitectures: []
+
+variables:
+  # Role name, not a model id. The model and key are resolved from the environment by role
+  # so no call site ever names a model — see the generated docs/architecture doc.
+  - name: agentRole
+    prompt: Role name the loop resolves its model and key under (e.g. "agent", "planner")
+    type: string
+    default: agent
+    required: true
+
+  # The three caps below are the point of this architecture. They are template inputs so a
+  # team can set its own ceiling at generation time, and config fields so it stays one edit.
+  - name: maxTurns
+    prompt: Hard ceiling on model round trips in one loop run
+    type: number
+    default: 12
+    required: true
+
+  - name: maxTotalTokens
+    prompt: Hard ceiling on cumulative input + output tokens across one loop run
+    type: number
+    default: 200000
+    required: true
+
+  - name: maxOutputTokens
+    prompt: Per-turn output token ceiling passed to the model
+    type: number
+    default: 4096
+    required: true
+
+  - name: toolTimeoutSeconds
+    prompt: Wall-clock ceiling for a single tool call
+    type: number
+    default: 30
+    required: true
+
+  # Irreversible effects need a decision, never a default yes. `deny` makes the seam visible
+  # on the first run instead of the first incident.
+  - name: sandboxMode
+    prompt: Policy for tools that declare an irreversible (write) effect
+    type: select
+    default: deny
+    required: true
+    choices:
+      - { value: deny, label: 'deny — refuse every write-effect tool until a policy is wired' }
+      - { value: dry-run, label: 'dry-run — report what would happen, change nothing' }
+      - { value: allow, label: 'allow — execute, and record every call in the trace' }
+
+files:
+  # ── python ──────────────────────────────────────────────────────────────────
+  # Both python bases place their package at src/<snake>/, so one rule serves either.
+  - from: files/src/__solutionName.snake__/**/*.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/tests/architecture/test_agent_loop.py
+    to: .
+    when: "stack == 'python'"
+  # The standard-tool half: import-linter proves the layering that the pytest file cannot
+  # express as cheaply (external package imports).
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+  - from: files/docs/architecture/agentic-tool-loop.python.md
+    to: .
+    when: "stack == 'python'"
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  # One layout serves both: the agent package sits at src/agent/ whether the base is Hono,
+  # Nest, Next.js or Vite. The doc is named for `node` and covers both, matching how the
+  # other overlays in this repo name a shared JS/TS document.
+  - from: files/src/agent/**/*.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/scripts/check-agent-loop.mjs
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  # The loop imports the SDK and the schemas; a manifest that never installs them does not build.
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/docs/architecture/agentic-tool-loop.node.md
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # Declared, not installed by a post-apply step: a package added after generation is
+  # missing from the first install (ADR 0005, spec 003).
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+postApply:
+  # Manifest-only, matching the other overlays: no install runs here.
+  - run: npm pkg set "scripts.check:agent"="node scripts/check-agent-loop.mjs"
+    when: "stack == 'typescript' || stack == 'node'"
+    optional: true

package/templates/architectures/agentic-tool-loop/files/.importlinter

@@ -0,0 +1,47 @@
+# import-linter contracts — the standard-tool half of the boundary enforcement.
+# `lint-imports` fails the build; wire it into CI next to pytest and ruff.
+# The registry, cap-literal, and environment rules live in
+# tests/architecture/test_agent_loop.py, which needs no per-tool upkeep.
+[importlinter]
+root_package = {{ solutionName | snake }}
+# Required so the vendor SDK appears in the graph and can be forbidden below.
+include_external_packages = True
+
+# One model call site. A second one is a second set of caps nobody is enforcing.
+# Direct imports only: the loop reaches the SDK *through* agent.model by design, and a
+# transitive contract would flag exactly the layering this architecture prescribes.
+[importlinter:contract:one-model-call-site]
+name = Only agent.model may import the Anthropic SDK
+type = forbidden
+allow_indirect_imports = True
+source_modules =
+    {{ solutionName | snake }}.agent.loop
+    {{ solutionName | snake }}.agent.tools
+    {{ solutionName | snake }}.agent.trace
+    {{ solutionName | snake }}.agent.sandbox
+    {{ solutionName | snake }}.agent.settings
+forbidden_modules =
+    anthropic
+
+# Tools are leaves. A tool that re-enters the loop is an unbounded loop with extra steps.
+[importlinter:contract:tools-are-leaves]
+name = Tools never re-enter the loop
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.agent.tools
+forbidden_modules =
+    {{ solutionName | snake }}.agent.loop
+    {{ solutionName | snake }}.agent.model
+
+# Settings sits below everything; if it imports upward the typed default table is not the root.
+[importlinter:contract:settings-is-the-floor]
+name = Settings depends on nothing in the agent package
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.agent.settings
+forbidden_modules =
+    {{ solutionName | snake }}.agent.loop
+    {{ solutionName | snake }}.agent.model
+    {{ solutionName | snake }}.agent.tools
+    {{ solutionName | snake }}.agent.sandbox
+    {{ solutionName | snake }}.agent.trace

package/templates/architectures/agentic-tool-loop/files/docs/architecture/agentic-tool-loop.node.md

@@ -0,0 +1,83 @@
+# Architecture — Agentic Tool Loop
+
+A single model directing its own process: the loop repeats while the model's stop reason is
+`tool_use`. The layout below is ordinary. The **caps** are the architecture.
+
+## The one rule that matters
+
+> **Every cap is a config field, and the loop stops at it before the request that would breach
+> it.** A turn limit, a cumulative token limit, and a per-tool timeout live in
+> `src/agent/config.ts` and nowhere else. `scripts/check-agent-loop.mjs` fails the build the
+> moment a cap appears as a numeric literal anywhere under `src/agent/`.
+
+An unbounded agent loop is the top cause of runaway spend, and it fails in the direction of
+your bill rather than your tests. A ceiling checked *after* the call has already been paid
+for. That is why `run()` tests `AGENT_MAX_TURNS` and `AGENT_MAX_TOTAL_TOKENS` at the top of
+the loop body, not at the bottom.
+
+## Layout
+
+```
+src/agent/
+  config.ts        # THE typed default table — every cap, plus role -> model/key resolution
+  loop.ts          # the loop; the only place turns and tokens are counted
+  model.ts         # the ONLY import of @anthropic-ai/sdk and the only messages.create call
+  trace.ts         # one JSON line per turn, tool call, cap breach, sandbox decision
+  sandbox.ts       # approval seam for irreversible effects; wraps write-effect handlers
+  tools/
+    types.ts       # ToolDefinition — name, description, zod schema, effect, handler
+    registry.ts    # THE one place tools are registered; applies the sandbox guard
+    current-time.ts  #   read-effect example
+    write-note.ts    #   write-effect example (gated by the registry, not by itself)
+  index.ts         # public surface — callers never import loop or model directly
+scripts/
+  check-agent-loop.mjs   # the fitness test
+```
+
+Add a tool by writing one file under `tools/` and adding it to the array in `registry.ts`.
+Forget the second step and the check fails — an unregistered tool is a tool with no schema
+and no sandbox gate.
+
+## The four seams
+
+- **Tool registry.** One array, one place. Each entry carries a Zod schema that is both the
+  wire schema sent to the model (`z.toJSONSchema`) and the validator the handler's input must
+  pass. There is no second definition to drift.
+- **Caps.** `AGENT_MAX_TURNS`, `AGENT_MAX_TOTAL_TOKENS`, `AGENT_MAX_OUTPUT_TOKENS`,
+  `AGENT_TOOL_TIMEOUT_MS`. Set them per environment; the schema in `config.ts` is the only
+  default table.
+- **Tracing.** `trace()` emits one JSON object per line to stdout. `setTraceSink()` swaps in
+  OpenTelemetry, a database, or a test spy. The loop is non-deterministic between runs, so
+  the trace is the only way to answer "what did it actually do".
+- **Sandbox.** Every tool declares `effect: 'read' | 'write'`. The registry wraps every
+  `write` handler with the policy in `sandbox.ts`, so a tool author cannot forget the gate.
+  `AGENT_SANDBOX_MODE` defaults to **`deny`** — the example write tool refuses on the first
+  run. That is deliberate: wire your real approval policy into `decide()` before flipping it.
+
+## Model and key resolution
+
+No call site names a model. `modelFor(role)` reads `AGENT_MODEL_<ROLE>`, then
+`AGENT_MODEL_DEFAULT`, then the single typed default in `config.ts`. `apiKeyFor(role)` does
+the same for credentials and returns `undefined` so the SDK can read its own variable.
+Changing the model is one environment variable, never a code edit.
+
+## Enforcement
+
+`node scripts/check-agent-loop.mjs` (wire it into CI and `npm run check:agent`):
+
+1. every tool module under `src/agent/tools/` is imported by `registry.ts`,
+2. `@anthropic-ai/sdk`, `new Anthropic(`, and `.messages.create(` appear only in `model.ts`,
+3. no cap name is assigned a numeric literal outside `config.ts`,
+4. no module reads `process.env` outside `config.ts`.
+
+It reads source text and import specifiers as written and never resolves them on disk, so it
+is immune to bundler and TS resolution quirks; comments and string bodies are stripped first
+so prose never trips a rule. Run `--self-test` to prove the rules still fire.
+
+**What is not enforced mechanically:** nothing checks that your `decide()` implementation is
+a *correct* approval policy, that tool descriptions are good enough for the model to choose
+between them, or that the cap values you picked are affordable. Those are review questions.
+
+Sources: [Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) ·
+[How tool use works](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works) ·
+[Tool use overview](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview).

package/templates/architectures/agentic-tool-loop/files/docs/architecture/agentic-tool-loop.python.md

@@ -0,0 +1,93 @@
+# Architecture — Agentic Tool Loop
+
+A single model directing its own process: the loop repeats while the model's stop reason is
+`tool_use`. The layout below is ordinary. The **caps** are the architecture.
+
+## The one rule that matters
+
+> **Every cap is a settings field, and the loop stops at it before the request that would
+> breach it.** A turn limit, a cumulative token limit, and a per-tool timeout live in
+> `agent/settings.py` and nowhere else. `tests/architecture/test_agent_loop.py` fails the
+> moment a cap appears as a numeric literal anywhere else in the package.
+
+An unbounded agent loop is the top cause of runaway spend, and it fails in the direction of
+your bill rather than your tests. A ceiling checked *after* the call has already been paid
+for. That is why `run()` tests `max_turns` and `max_total_tokens` at the top of the loop
+body, not at the bottom.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/agent/
+  settings.py      # THE typed default table — every cap, plus role -> model/key resolution
+  loop.py          # the loop; the only place turns and tokens are counted
+  model.py         # the ONLY import of `anthropic` and the only messages.create call
+  trace.py         # one JSON line per turn, tool call, cap breach, sandbox decision
+  sandbox.py       # approval seam for irreversible effects; wraps write-effect handlers
+  tools/
+    spec.py        # ToolSpec — name, description, pydantic schema, effect, handler
+    registry.py    # THE one place tools are registered; applies the sandbox guard
+    current_time.py  #   read-effect example
+    write_note.py    #   write-effect example (gated by the registry, not by itself)
+  __init__.py      # public surface — callers never import loop or model directly
+tests/architecture/
+  test_agent_loop.py     # the fitness test
+.importlinter            # the standard-tool half of the enforcement
+```
+
+Add a tool by writing one module under `tools/` and adding it to the tuple in `registry.py`.
+Forget the second step and the test fails — an unregistered tool is a tool with no schema and
+no sandbox gate.
+
+## The four seams
+
+- **Tool registry.** One tuple, one place. Each entry carries a pydantic model that is both
+  the wire schema sent to the model (`model_json_schema()`) and the validator the handler's
+  input must pass. There is no second definition to drift.
+- **Caps.** `max_turns`, `max_total_tokens`, `max_output_tokens`, `tool_timeout_seconds`.
+  Override any of them with `{{ solutionName | upperSnake }}_AGENT_<FIELD>`; the class in
+  `settings.py` is the only default table.
+- **Tracing.** `trace()` emits one JSON object per line to stderr. `set_trace_sink()` swaps in
+  OpenTelemetry, a database, or a test spy. The loop is non-deterministic between runs, so
+  the trace is the only way to answer "what did it actually do".
+- **Sandbox.** Every tool declares `effect: "read" | "write"`. The registry wraps every
+  `write` handler with the policy in `sandbox.py`, so a tool author cannot forget the gate.
+  `sandbox_mode` defaults to **`deny`** — the example write tool refuses on the first run.
+  That is deliberate: wire your real approval policy into `decide()` before flipping it.
+
+## Model and key resolution
+
+No call site names a model. `model_for(role)` reads
+`{{ solutionName | upperSnake }}_AGENT_MODEL_<ROLE>`, then `..._MODEL_DEFAULT`, then the
+single typed default in `settings.py`. `api_key_for(role)` does the same for credentials and
+returns `None` so the SDK can read its own variable. Changing the model is one environment
+variable, never a code edit.
+
+## Enforcement
+
+Two commands, and both fail the build:
+
+`pytest tests/architecture/test_agent_loop.py` (also runs standalone with
+`python tests/architecture/test_agent_loop.py`):
+
+1. every tool module under `agent/tools/` is imported by `registry.py`,
+2. no cap name is bound to a numeric literal outside `settings.py`,
+3. nothing reads `os.environ` / `os.getenv` outside `settings.py`.
+
+`lint-imports` reads `.importlinter`:
+
+4. only `agent.model` may import `anthropic` — a second call site is a second set of caps
+   nobody is enforcing,
+5. `agent.tools` never imports `agent.loop` or `agent.model` — tools are leaves,
+6. `agent.settings` imports nothing else in the package — the default table is the floor.
+
+Rules 1–3 walk the AST rather than matching text, so comments and docstrings never trip them.
+The test carries a self-test that proves each rule still detects a known violation.
+
+**What is not enforced mechanically:** nothing checks that your `decide()` implementation is
+a *correct* approval policy, that tool descriptions are good enough for the model to choose
+between them, or that the cap values you picked are affordable. Those are review questions.
+
+Sources: [Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) ·
+[How tool use works](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works) ·
+[Tool use overview](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview).

package/templates/architectures/agentic-tool-loop/files/package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.112.3",
+    "zod": "^4.4.3"
+  }
+}

package/templates/architectures/agentic-tool-loop/files/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+dependencies = ["anthropic>=0.117,<1", "pydantic-settings>=2.14,<3"]
+
+[dependency-groups]
+dev = ["import-linter==2.13"]

package/templates/architectures/agentic-tool-loop/files/scripts/check-agent-loop.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * Architecture fitness test for the agentic tool loop.
+ *
+ * Four rules, each one a defect this style produces when nobody checks:
+ *   1. a tool module the registry never imports  -> a tool with no schema and no sandbox gate
+ *   2. the model called outside the model module -> a second loop with nobody's caps on it
+ *   3. a cap written as a numeric literal        -> the ceiling drifts out of config
+ *   4. process.env read outside config           -> configuration with no typed default
+ *
+ * Exits non-zero on a violation, so it belongs in `lint` and in CI, not in a README.
+ * It reads source text and import specifiers as written and never resolves them on disk,
+ * so it is immune to TypeScript/bundler resolution differences.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+/** Every tunable lives here. Nothing below reads the environment directly. */
+const config = {
+  agentRoot: process.env.ARCH_AGENT_ROOT ?? 'src/agent',
+  toolsDir: 'tools',
+  /** The only module allowed to import the vendor SDK and call the model. */
+  modelModule: 'model',
+  /** The only module allowed to read process.env. */
+  configModule: 'config',
+  registryModule: 'registry',
+  /** Tool-directory files that are infrastructure, not tools. */
+  toolSupportModules: split(process.env.ARCH_TOOL_SUPPORT) ?? ['types', 'registry', 'index'],
+  extensions: ['.ts', '.tsx', '.mts', '.js', '.mjs'],
+  skipDirs: ['node_modules', 'dist', 'build', 'out', 'coverage', '.git', '.turbo', '.next'],
+};
+
+function split(value) {
+  return value
+    ? value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+    : undefined;
+}
+
+const SPECIFIER_PATTERNS = [
+  /(?:^|[\s;}])(?:import|export)[^;]*?\sfrom\s*['"]([^'"]+)['"]/g,
+  /(?:^|[\s;}])import\s*['"]([^'"]+)['"]/g,
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+
+/** Package whose import means "this module talks to the model". */
+const SDK_PACKAGE = '@anthropic-ai/sdk';
+/** Client construction or a Messages API call, matched on code with strings removed. */
+const MODEL_CALL = /new\s+Anthropic\s*\(|\.messages\s*\.\s*(?:create|stream)\s*\(/;
+
+/** A cap name assigned or keyed to a bare number: `maxTurns: 12`, `max_tokens = 4096`. */
+const CAP_LITERAL =
+  /\b(max_?turns|max_?tokens|max_?output_?tokens|max_?total_?tokens|max_?input_?tokens|tool_?timeout(?:_?ms)?|request_?timeout(?:_?ms)?)\b\s*[:=]\s*[\d_]+/i;
+
+const ENV_READ = /\bprocess\s*\.\s*env\b/;
+
+/** Strip comments and string bodies so prose and messages never trip a rule. */
+export function stripNoise(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1 ')
+    .replace(/'(?:\\.|[^'\\])*'/g, "''")
+    .replace(/"(?:\\.|[^"\\])*"/g, '""')
+    .replace(/`(?:\\.|[^`\\])*`/g, '``');
+}
+
+export function specifiersOf(source) {
+  const found = new Set();
+  for (const pattern of SPECIFIER_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const match of source.matchAll(pattern)) found.add(match[1]);
+  }
+  return [...found];
+}
+
+/** `src/agent/tools/write-note.ts` -> `write-note`; the identity the registry imports by. */
+export function moduleNameOf(filePath) {
+  return path.posix.basename(filePath).replace(/\.[^.]+$/, '');
+}
+
+/**
+ * The three per-file rules, isolated so `--self-test` can prove they still fire.
+ * Specifiers are read from the raw source; everything else from source with comments and
+ * string bodies removed, so prose and error messages never trip a rule.
+ */
+export function violationsOf(filePath, source) {
+  const found = [];
+  const name = moduleNameOf(filePath);
+  const code = stripNoise(source);
+  const importsSdk = specifiersOf(source).some(
+    (specifier) => specifier === SDK_PACKAGE || specifier.startsWith(SDK_PACKAGE + '/'),
+  );
+
+  if (name !== config.modelModule && (importsSdk || MODEL_CALL.test(code))) {
+    found.push(
+      `calls the model outside ${config.agentRoot}/${config.modelModule} — one call site, one set of caps`,
+    );
+  }
+  if (name !== config.configModule && CAP_LITERAL.test(code)) {
+    found.push(
+      `writes a cap as a literal — every ceiling belongs in ${config.agentRoot}/${config.configModule}`,
+    );
+  }
+  if (name !== config.configModule && ENV_READ.test(code)) {
+    found.push(
+      `reads process.env — configuration goes through ${config.agentRoot}/${config.configModule}`,
+    );
+  }
+  return found;
+}
+
+/** Rule 4: tool modules the registry never imports are unreachable and ungated. */
+export function orphanTools(toolFiles, registrySpecifiers) {
+  const imported = new Set(registrySpecifiers.map(moduleNameOf));
+  return toolFiles
+    .map(moduleNameOf)
+    .filter((name) => !config.toolSupportModules.includes(name) && !imported.has(name));
+}
+
+async function listFiles(root) {
+  const found = [];
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = path.posix.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!config.skipDirs.includes(entry.name)) await walk(child);
+      } else if (config.extensions.includes(path.extname(entry.name))) {
+        found.push(child);
+      }
+    }
+  };
+  await walk(root);
+  return found;
+}
+
+const SELF_TEST_CASES = [
+  ['src/agent/loop.ts', "import Anthropic from '@anthropic-ai/sdk';", true],
+  ['src/agent/model.ts', "import Anthropic from '@anthropic-ai/sdk';", false],
+  ['src/agent/loop.ts', 'const maxTurns = 12;', true],
+  ['src/agent/config.ts', 'AGENT_MAX_TURNS: z.coerce.number().default(12),', false],
+  ['src/agent/tools/registry.ts', 'const key = process.env.AGENT_API_KEY;', true],
+  ['src/agent/loop.ts', 'if (turns >= agentConfig.AGENT_MAX_TURNS) return;', false],
+  ['src/agent/loop.ts', '// bump max_turns to 99 later', false],
+];
+
+function selfTest() {
+  const wrong = SELF_TEST_CASES.filter(
+    ([file, source, expected]) => violationsOf(file, source).length > 0 !== expected,
+  );
+  for (const [file, source] of wrong) console.error(`self-test failed: ${file} <- ${source}`);
+
+  const orphans = orphanTools(
+    ['src/agent/tools/types.ts', 'src/agent/tools/registry.ts', 'src/agent/tools/rogue.ts'],
+    ['./types.js', '../sandbox.js'],
+  );
+  if (orphans.length !== 1 || orphans[0] !== 'rogue') {
+    console.error('self-test failed: orphan-tool rule no longer detects an unregistered tool');
+    return false;
+  }
+  return wrong.length === 0;
+}
+
+async function main() {
+  if (process.argv.includes('--self-test')) {
+    if (!selfTest()) process.exit(1);
+    console.log(`agent loop rules verified against ${SELF_TEST_CASES.length + 1} cases`);
+    return;
+  }
+
+  const files = await listFiles(config.agentRoot);
+  if (files.length === 0) {
+    // A silent pass over an empty file set is the failure mode this check exists to avoid.
+    console.error(`No agent sources found under ${config.agentRoot} — is ARCH_AGENT_ROOT right?`);
+    process.exit(1);
+  }
+
+  const violations = [];
+  const toolsRoot = path.posix.join(config.agentRoot, config.toolsDir);
+  const toolFiles = [];
+  let registrySpecifiers = null;
+
+  for (const file of files) {
+    const source = await readFile(file, 'utf8');
+    for (const violation of violationsOf(file, source)) violations.push(`${file}: ${violation}`);
+
+    if (file.startsWith(toolsRoot + '/')) {
+      toolFiles.push(file);
+      if (moduleNameOf(file) === config.registryModule) registrySpecifiers = specifiersOf(source);
+    }
+  }
+
+  if (registrySpecifiers === null) {
+    console.error(
+      `No ${config.registryModule} module under ${toolsRoot} — tools must be registered in one place.`,
+    );
+    process.exit(1);
+  }
+  for (const orphan of orphanTools(toolFiles, registrySpecifiers)) {
+    violations.push(
+      `${toolsRoot}/${orphan}: not imported by ${config.registryModule} — register it or delete it`,
+    );
+  }
+
+  if (violations.length > 0) {
+    console.error(`Agent loop violations (${violations.length}):\n` + violations.join('\n'));
+    process.exit(1);
+  }
+  console.log(
+    `Agent loop boundaries hold across ${files.length} file(s), ${toolFiles.length} in the tool registry.`,
+  );
+}
+
+if (!selfTest()) {
+  console.error('The agent loop rules no longer detect a known violation — fix violationsOf().');
+  process.exit(1);
+}
+await main();

package/templates/architectures/agentic-tool-loop/files/src/__solutionName.snake__/agent/__init__.py

@@ -0,0 +1,20 @@
+"""Public surface of the agent. Callers import from here, never from ``loop`` or ``model``."""
+
+from .loop import RunResult, StopReason, run
+from .sandbox import SandboxDecision, decide
+from .settings import get_settings, model_for
+from .tools.registry import TOOLS, tool_schemas
+from .trace import set_trace_sink
+
+__all__ = [
+    "TOOLS",
+    "RunResult",
+    "SandboxDecision",
+    "StopReason",
+    "decide",
+    "get_settings",
+    "model_for",
+    "run",
+    "set_trace_sink",
+    "tool_schemas",
+]