@inneranimalmedia/agentsam-sdk 2.4.0 → 2.5.0

package/README.md

@@ -2,13 +2,13 @@
 
 A deterministic-first application and agent toolkit: reusable repository, knowledge, integrity,
 security, identity, scaffolding, and delivery capabilities with optional AgentSam/LLM composition.
-CLI/TUI surfaces make those same primitives easy to use without making a model part of the implementation.
+The interactive CLI makes those same primitives easy to use without making a model part of the implementation.
 
 **npm:** `@inneranimalmedia/agentsam-sdk` · **Source:** [GitHub](https://github.com/SamPrimeaux/agentsam-sdk)
 
 Node 22.5+ is required. Docker is optional for container commands. Python 3.10+ is required
-for the bundled Python repository tools; Rich is optional for the richer terminal UI.
-See the [2.0 release guide](docs/sdk-2.0-release.md) for publication status and migration notes.
+for the bundled Python repository tools. Rich is optional for the contributor-only terminal renderer lab.
+See [release receipts](docs/RELEASES.md) for publication status.
 
 ## Install
 
@@ -71,17 +71,18 @@ read-only `repository.snapshot` composition primitive. See [Capabilities and pre
 | Capability | Entry point | Guide |
 | --- | --- | --- |
 | Capability registry + presets | `agentsam capabilities`, `/capabilities`, `/presets` | [Capabilities](docs/CAPABILITIES.md) |
+| Portable AgentSam skills | `agentsam skills`; `/skills` | [Skills](skills/README.md) |
 | Canonical repository snapshot | `agentsam inspect --json`; `/repository` | [Capabilities](docs/CAPABILITIES.md) |
 | Git context and bridge client | `agentsam context --json`; `/git-context`, `/bridge-client` | [Portable context](docs/PORTABLE_CONTEXT.md) |
 | Identity contracts and adapters | `/identity`; `agentsam identity init` | [Identity](packages/identity/README.md) |
 | Repository knowledge | `agentsam index`, `search`, `repo`; `/knowledge` | [Knowledge](docs/portable-knowledge.md) |
 | File integrity | `agentsam merkle`; `/merkle` | [Merkle](docs/MERKLE.md) |
-| Dependency health and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
+| Security, trust-boundary scan, and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
 | Mini prototypes | `agentsam mini`; `/mini` | [Mini](docs/MINI.md) |
 | Recon bounded-worker packets | `agentsam recon pack\|validate` | [Recon](docs/RECON.md) |
 | Local containers | `agentsam dockerize`; `/dockerize` | [Dockerize](docs/DOCKERIZE.md) |
 | Background indexing service | Docker `knowledge_service`; `/knowledge-service-client` | [Knowledge service](docs/knowledge-service.md) |
-| Local status, DB, terminal UI | `agentsam status`, `db`, `tui`, `start-local` | [Terminal UI](docs/CLI_SHELL.md) |
+| Interactive Agent Sam + local runtime | `agentsam`, `agentsam status`, `db`, `models`, `start-local` | [CLI shell](docs/CLI_SHELL.md) |
 
 Export suffixes such as `/identity` mean imports from
 `@inneranimalmedia/agentsam-sdk/identity`. Use `agentsam <command> --help` where supported.
@@ -123,7 +124,7 @@ npm run verify:release
 
 Release verification runs Node/identity tests, bootstrap and package checks, installed
 tarball fixtures in unrelated repositories, Python tests, and a complete dependency scan.
-[Development](DEVELOPMENT.md) · [Release guide](docs/sdk-2.0-release.md) ·
+[Development](DEVELOPMENT.md) · [Release receipts](docs/RELEASES.md) ·
 [Branch archive](docs/branch-archive-2026-09-02.md).
 
 License: MIT. Optional visual experiments and host-specific integrations retain their

package/docs/AGENTSAM_WORKBENCH.md

@@ -0,0 +1,30 @@
+# AgentSam shared workbench boundary
+
+The SDK has one shared AgentSam interaction layer for product applications:
+
+```text
+packages/agentsam-contracts       pure TypeScript, no React
+            ↑
+packages/agentsam-workbench       reusable React/browser workbench
+            ↑
+    ┌───────┼────────┐
+    │       │        │
+ Local    CAD      CMS
+ Studio   Studio    Studio
+```
+
+`apps/*` are development products and remain independent workspace roots. They may consume the shared packages, but shared packages must never import an app.
+
+## Contracts
+
+`@inneranimalmedia/agentsam-contracts` owns messages, runs, events, tools/capabilities, artifacts/attachments, model options, explicit context, and runtime adapter interfaces. Context is supplied by the host through an explicit `AgentContextProvider`; the workbench does not scrape app state implicitly.
+
+## Workbench
+
+`@inneranimalmedia/agentsam-workbench` owns reusable controlled UI primitives. Product-specific state stores, route trees, auth implementations, repo/CAD/CMS schemas, and deployment wiring remain outside it.
+
+Local Studio is the first proof consumer. CAD and CMS should consume this layer through domain adapters rather than cloning Local Studio components.
+
+## Authentication and execution
+
+The workbench does not own identity authority. Identity establishes an authenticated principal first; application authorization then creates any optional browser/container/terminal execution session. Cache and execution bindings are never account/session authority.

package/docs/AUTH_IDENTITY_CONTRACT.md

@@ -0,0 +1,52 @@
+# AgentSam identity/auth configuration contract
+
+The `agentsam-sdk` package owns the portable public configuration contract. Consuming applications implement storage, authorization, and host routes against this contract instead of defining competing environment names.
+
+## Canonical variables
+
+| Variable | Meaning |
+| --- | --- |
+| `IAM_ORIGIN` | Canonical IAM authority and browser/OAuth/API origin. |
+| `IAM_CLIENT_ID` | OAuth client id for an application using IAM identity. |
+| `IAM_CLIENT_SECRET` | OAuth client secret. Keep it server-side. |
+| `AGENTSAM_SDK_KEY` | Account/delegated SDK bearer. Raw values use the `sdk_` prefix and are sent as `Authorization: Bearer …`. |
+| `AGENTSAM_BRIDGE_KEY` | Machine/integration credential. It is never a substitute for user SDK authentication. |
+
+The host-side durable verifier for SDK credentials is `agentsam_sdk_tokens`. The SDK defines the public credential semantics; the host owns the database and authorization implementation.
+
+`AGENTSAM_BRIDGE_KEY` remains the direct machine-secret environment variable. A host may additionally resolve a hashed credential from `agentsam_sdk_tokens` when that row has `token_type='integration'`. That does not turn the bridge credential into user authentication.
+
+## Migration compatibility
+
+The current migration window accepts two deprecated read fallbacks:
+
+```text
+IAM_ORIGIN
+  fallback: IAM_OAUTH_ISSUER
+
+AGENTSAM_SDK_KEY
+  fallback: AGENTSAM_SDK_TOKEN
+```
+
+Canonical names always win when both are present. New scaffolds, docs, and writes emit only the canonical names. Compatibility aliases are intentionally not a permanent parallel configuration surface.
+
+Older platform-base aliases (`IAM_CORE_URL`, `AGENTSAM_CORE_URL`, `AGENTSAM_BASE_URL`) are compatibility-only. SDK clients prefer `IAM_ORIGIN`.
+
+## Credential boundaries
+
+```text
+human/account SDK lane
+  AGENTSAM_SDK_KEY
+    -> sdk_* bearer
+    -> Authorization: Bearer <sdk_*>
+    -> account/delegated authority
+    -> agentsam_sdk_tokens
+
+machine/integration lane
+  AGENTSAM_BRIDGE_KEY
+    -> machine principal
+    -> no user/workspace identity injection
+    -> host env secret OR agentsam_sdk_tokens(token_type='integration')
+```
+
+Browser OAuth uses `IAM_ORIGIN` together with `IAM_CLIENT_ID` and `IAM_CLIENT_SECRET`. Repository identity, workspace labels, or machine trust do not prove account authority.

package/docs/CAPABILITIES.md

@@ -18,7 +18,7 @@ agentsam capabilities
 agentsam capabilities repository.snapshot --json
 ```
 
-This registry is intended to drive CLI/TUI discovery, AgentSam/MCP tool selection, docs, verification, and workflow capability resolution. It is deliberately not a second hosted tools database.
+This registry is intended to drive CLI/terminal UI discovery, AgentSam/MCP tool selection, docs, verification, and workflow capability resolution. It is deliberately not a second hosted tools database.
 
 ## repository.snapshot
 
@@ -26,7 +26,8 @@ This registry is intended to drive CLI/TUI discovery, AgentSam/MCP tool selectio
 
 - Git resource identity and revision
 - Python repository intelligence
-- Merkle root and tree statistics
+- Merkle root, semantic metadata root, execution-domain facts, and tree statistics
+- deterministic client/server trust-boundary contradictions derived from the Merkle-bound AST graph
 - package/manifests
 - local knowledge/index generation when configured
 - last trusted local deployment receipt when available
@@ -36,6 +37,7 @@ It does **not** call an LLM, mutate source, index the repository, provision clou
 
 ```sh
 agentsam inspect --json
+agentsam inspect --execution-domain browser --view files --json
 ```
 
 ```js
@@ -43,7 +45,7 @@ import { repositorySnapshot } from '@inneranimalmedia/agentsam-sdk/repository';
 const snapshot = await repositorySnapshot({ cwd: process.cwd() });
 ```
 
-The timestamp is not included in the content hash, so unchanged evidence produces the same `content_hash` and `snapshot_id`.
+The timestamp is not included in the content hash, so unchanged evidence produces the same `content_hash` and `snapshot_id`. The default bounded index view carries a compact `analysis.trust_boundary` summary (up to 20 contradiction cards) while the canonical full snapshot retains all deterministic findings. `agentsam security scan` consumes the same analyzer rather than maintaining a separate architecture model.
 
 ## Optional AgentSam/LLM composition
 

package/docs/CLI_SHELL.md

@@ -1,129 +1,106 @@
 # Agent Sam SDK — terminal experience
 
-The Agent Sam terminal is a presentation layer over real local capabilities. It is not a second execution engine and it is not tied to Gorilla, Cloudflare, or a particular model provider.
+`agentsam` is the product entrypoint. Users do not choose a renderer or need to know whether a screen is implemented with ANSI, Rich, Clack, or another terminal library.
 
-## Default experience
+## Product entrypoint
 
 ```bash
-agentsam tui
+agentsam
 ```
 
-Runs the bundled zero-dependency Node/ANSI renderer. This is the default because it is available anywhere the npm CLI runs.
+On the first run for a project, Agent Sam opens keyboard-driven setup for the project, runtime, terminal, and model preference. On later runs it shows a short project-aware boot transition and enters the Agent Sam prompt.
 
-```bash
-agentsam tui rich
-agentsam tui rich --install
-```
+```text
+$ agentsam
 
-Runs the optional Python Rich renderer. `--install` creates an isolated `.agentsam/tui-venv` and installs Rich there; system Python is left alone.
+  Agent Sam
+  my-project · main · qwen2.5-coder
 
-```bash
-agentsam shell
+  ✓ project
+  ✓ runtime
+  ✓ model
+
+  username ~/path/to/project >
 ```
 
-Starts the interactive Agent Sam slash-command shell. Once the `agentsam>` prompt is visible, commands such as `/help`, `/status`, `/pwd`, and `/git` are handled by Agent Sam instead of the host shell (PowerShell, bash, or zsh). Use `/exit` to return to the host terminal.
+The model stored by the CLI is a **preference only**. It does not replace the connected host/runtime as model-routing authority.
+
+Live terminal scenes are automatic product behavior. When Agent Sam is actively handling an `/agent` request, the installed CLI renders the compact thinking/activity panel itself; users never run a renderer or preview command. The same shipped activity seam accepts model, tool, and context-compaction lifecycle events from richer hosts. Pipes and CI remain plain/deterministic.
+
+Use `/settings` inside Agent Sam to revisit the keyboard choices and `/models` to inspect providers and locally available models.
 
-Do not type `/help` directly at a PowerShell/bash prompt; enter `agentsam shell` first.
+## One-shot commands
 
-For scripts and regression tests, a single slash command can be dispatched without opening the REPL:
+Normal commands remain deterministic and scriptable:
 
 ```bash
-agentsam shell --command /help
+agentsam status
+agentsam models
+agentsam inspect --json
+agentsam deploy
+agentsam --help
 ```
 
-## Architecture
+`agentsam shell` remains an explicit/secondary way to enter the slash-command shell. Bare `agentsam` is the normal interactive entrypoint.
 
-```text
-CLI command / execution state
-        |
-        +--> Node ANSI renderer        default, zero extra dependencies
-        |
-        +--> Python Rich renderer      optional high-fidelity live presentation
-        |
-        +--> browser shell-kit         reusable React components, separate surface
-
-Capabilities underneath presentation:
+For regression tests, one slash command can still be dispatched without opening an interactive terminal:
 
-Git context
-Local SQLite
-Local PTY
-Agent/tool execution
-Logs/events
-Deploy adapters
+```bash
+agentsam shell --command /help
 ```
 
-Presentation consumes state. It does not authorize tools, decide policy, own databases, or execute cloud operations by itself.
-
-## Local project contract
+## Internal UI engine
 
-`agentsam init` creates:
+The renderer is implementation detail:
 
 ```text
-.git/
-.env
-.env.example
-agentsam.config.js
-.agentsam/config.json
-.agentsam/data/agentsam.sqlite
-db/schema.sql
-src/agent.js
-src/dev-server.js
-scripts/smoke.mjs
+Agent Sam lifecycle/state
+        |
+        +--> ANSI / picocolors       semantic color + cursor control
+        +--> Rich renderer           high-fidelity live render experiments
+        +--> Clack prompts           arrow-key selects / confirms / text input
+        +--> node-pty                real shell/process/filesystem
 ```
 
-There is no Worker requirement in this contract.
+SDK developers can preview render experiments from this repository without exposing renderer names as product commands:
 
-`src/agent.js` is runtime-neutral. The Node development adapter injects local SQLite. A cloud adapter may later inject D1 or another compatible store.
-
-## TUI ownership
-
-| Surface | Location | Role |
-|---|---|---|
-| ANSI | `examples/agentsam-tui-ansi.mjs` | npm-native default terminal renderer |
-| Rich | `python/agentsam_sdk/tui/` | optional richer cards, progress, events, logs |
-| shell-kit | `packages/agentsam-shell-kit/` | reusable React/browser work-surface components |
-| Gorilla | `templates/gorilla-shell/` | visual/theme experiment only |
+```bash
+npm run ui:preview -- tour
+npm run ui:preview -- boot
+npm run ui:preview -- setup
+npm run ui:preview -- thinking
+npm run ui:preview -- ready
+npm run ui:preview -- ansi
+```
 
-Gorilla is intentionally not scaffolded by default.
+These preview commands are a design lab, not part of the installed user vocabulary.
 
-## Commands
+## Slash commands
 
 ```text
 /help       show commands
 /status     local project / DB / Git / PTY health
 /context    current repository + revision
 /pwd        working directory
-/cd         change directory
+/cd         change working directory
 /git        Git operations
 /db         local SQLite
 /agent      invoke configured Agent Sam
+/models     inspect available providers and local models
+/settings   choose project/runtime/terminal/model preference
 /logs       local execution events
-/tui        terminal presentation
 /deploy     intentionally add a cloud adapter
-/exit       exit Agent Sam shell and return to the host terminal
+/exit       exit Agent Sam and return to the host terminal
 ```
 
-Provider-specific commands such as `/claude` or `/codex` are not part of the generic shell contract. Model routing belongs behind Agent Sam.
-
-Workspace switching is not required for local tooling. Authenticated user/session identity is the security boundary; workspace/project labels are organizational metadata.
-
-## Cloud graduation
+Provider-specific commands such as `/claude` or `/codex` are not part of the generic shell contract. Model execution/routing belongs behind Agent Sam.
 
-Cloud infrastructure is generated when requested, not during local init.
+## Local project contract
 
-```text
-local project
-   |
-   +--> agentsam deploy --target cloudflare
-           |
-           +--> src/cloudflare-worker.js
-           +--> wrangler.toml
-           +--> migrations/0001_agentsam_core.sql
-           +--> provisioned account bindings
-```
+`agentsam init` creates a local project with Git, `.env`, `.agentsam/config.json`, a committed `.agentsamrules` project-instruction file, local SQLite, and the project runtime files. The setup wizard uses keyboard-driven Clack prompts in an interactive terminal; flags keep non-interactive creation deterministic.
 
-The same `src/agent.js` remains application authority.
+Local development requires no Worker or cloud account. Cloud infrastructure is added intentionally at deploy time.
 
 ## Design rule
 
-A CLI operation should be understandable in plain text first, then enhanced by ANSI/Rich presentation. CI and agent capture must always have a deterministic non-interactive path (`--check`, JSON receipts where applicable).
+A CLI operation must remain understandable in plain text and deterministic in CI/pipes. Interactive terminals may enhance that state with color, cursor redraw, prompts, progress, and animation. Presentation does not authorize tools, own execution policy, or silently become model-routing authority.

package/docs/CMS_STUDIO.md

@@ -0,0 +1,101 @@
+# AgentSam CMS Studio architecture
+
+The SDK treats CMS authoring and the public website as separate deployment products that share publication contracts.
+
+```text
+apps/client-cms-editor/                 authenticated authoring/control app
+        │
+        ├─ pages / sections / themes / assets
+        ├─ AgentSam workbench
+        ├─ preview
+        └─ publish
+                ↓
+        structured publication snapshot
+             ┌──┴──┐
+             │     │
+            D1     R2 WEBSITE_ASSETS
+        metadata   content/media/theme artifacts
+             │     │
+             └──┬──┘
+                ↓
+        small public CMS runtime
+```
+
+The public runtime must not inherit the full authoring dependency graph. Monaco, terminal, browser automation, authenticated admin UI, and the AgentSam workbench stay in the authoring application unless a public feature explicitly requires them.
+
+## Shared AgentSam platform
+
+CMS consumes `@inneranimalmedia/agentsam-contracts` and `@inneranimalmedia/agentsam-workbench`, the same product-neutral layer proven first by Local Studio. `CmsAgentSurface` supplies explicit CMS context to the shared `AgentWorkbenchAdapter`; it does not scrape editor state or invent a CMS-specific chat transport.
+
+Identity is resolved before AgentSam execution:
+
+```text
+IAM
+ ↓
+authenticated principal (accountId + authUserId)
+ ↓
+application authorization
+ ↓
+CMS context / capabilities
+ ↓
+optional browser or container runtime
+```
+
+`SESSION_CACHE` is an optional cache only. `MY_CONTAINER` and `MYBROWSER` are execution infrastructure only. None may become identity/session authority.
+
+## Cloudflare capability contract
+
+Baseline `cms-cloud` requires `DB` and `WEBSITE_ASSETS`. Other bindings are capability-driven:
+
+- `iam` → `IAM_CLIENT_ID`, `IAM_CLIENT_SECRET`, `IAM_ORIGIN`
+- `workers-ai` → `AGENTSAM_WAI`
+- `browser` → `MYBROWSER`
+- `container` → `MY_CONTAINER`
+- `encrypted-secrets` → `SECRETS_ENCRYPTION_KEY`
+- `acp` → `ACP_CLIENT_ID`, `ACP_CLIENT_SECRET`
+
+`IAM_ORIGIN` means the canonical IAM issuer/auth service. It must not silently mean the current website origin.
+
+## Routes
+
+The intended ownership boundary is:
+
+```text
+/*                    public CMS
+/auth/*                identity
+/dashboard/*           authenticated application
+/dashboard/agentsam    authenticated AgentSam product
+/dashboard/cms         authenticated CMS Studio
+/api/public/*          visitor-safe CMS APIs
+/api/auth/*            identity/session
+/api/cms/*             authenticated editor/publishing APIs
+/api/agentsam/*        authenticated AgentSam APIs
+```
+
+## Publication data
+
+Prefer versioned structured sections such as:
+
+```json
+{
+  "publicationId": "pub_example",
+  "route": "/about",
+  "revision": 18,
+  "theme": "iam-classy",
+  "sections": [
+    {
+      "type": "hero",
+      "props": {
+        "title": "About us",
+        "imageAsset": "asset_example"
+      }
+    }
+  ]
+}
+```
+
+The renderer may produce sanitized HTML/static snapshots from this data. Arbitrary executable HTML from the editor is not the public-content authority.
+
+## Current server authority
+
+The imported app contains only the portable CMS API/routing/preview bridge. The current full CMS domain remains in `inneranimalmedia/src/core/agentsam/cms/` at the import provenance revision. The next server-side extraction should create reusable `packages/agentsam-cms-*` packages rather than copy that domain into this app.

package/docs/CONTEXT.md

@@ -0,0 +1,170 @@
+# Agent Sam context contracts
+
+Agent Sam treats context as a bounded evidence pack, not as a place to dump every available index, tool, file, or prior message.
+
+## Project rules
+
+Generated projects include a committed `.agentsamrules` file. It is the repository-level instruction surface, similar in spirit to `.cursorrules`.
+
+```text
+repo/
+├── .agentsam/config.json   portable project identity/defaults
+├── .agentsamrules          committed project instructions
+└── .agentsam/cli.json      machine/user preferences; gitignored
+```
+
+`loadProjectRules()` searches upward from the active cwd, hashes the source, and bounds loaded content before it can enter system context. The portable default ceiling is 24,000 characters; a host may choose a lower ceiling through its context budget.
+
+`.agentsamrules` is for durable repository instructions and conventions. It is not a place for secrets, account IDs, active runs, task state, model history, terminal sessions, or Merkle roots.
+
+## Result policy
+
+Every result-producing capability should have a result policy. Absence of a custom policy means the bounded SDK default:
+
+```json
+{
+  "max_items": 8,
+  "max_chars": 24000,
+  "detail": "excerpt"
+}
+```
+
+A caller may request less. Asking for more items, more characters, or a higher detail class requires the explicit `higher-detail` operation.
+
+Progressive detail is ordered as:
+
+```text
+metadata
+  ↓
+card
+  ↓
+excerpt
+  ↓
+range
+  ↓
+full
+```
+
+`normalizeResultPolicy()` enforces the ceiling. Built-in SDK tool cards inherit the bounded default rather than silently behaving as unlimited.
+
+## Context budget
+
+`createContextBudget()` derives per-class ceilings from the selected model's context window. The default operating ratios are:
+
+```text
+target active input    60%
+emergency hard line    85%
+```
+
+The remaining window is deliberate headroom for additional retrieval, tool iterations, reasoning, user input, and output.
+
+A budget owns separate ceilings for:
+
+```text
+system / project rules
+tool schemas
+retrieved evidence
+single file reads
+cumulative file reads per turn
+tool results
+```
+
+For example:
+
+```js
+import { createContextBudget } from '@inneranimalmedia/agentsam-sdk/context';
+
+const budget = createContextBudget({
+  windowTokens: 250_000,
+});
+```
+
+The resulting budget tracks both tokens and deterministic character ceilings.
+
+## Context items
+
+Portable context evidence uses the following shape:
+
+```ts
+interface ContextItem {
+  ref: string;
+  kind: 'file' | 'symbol' | 'memory' | 'tool_result' | 'repo' | 'artifact';
+  chars: number;
+  hash?: string;
+  priority: number;
+  content?: string;
+}
+```
+
+`resolveContext()` sorts candidate evidence by priority, applies kind-specific and cumulative limits, and returns only the selected items.
+
+`resolveProjectContext()` does the same while automatically loading `.agentsamrules` within the system-context ceiling.
+
+Every resolved pack includes a receipt:
+
+```json
+{
+  "chars": 18422,
+  "evidence_chars": 17769,
+  "system_chars": 653,
+  "estimated_tokens": 4606,
+  "sources_considered": 73,
+  "sources_included": 6,
+  "sources_deferred": 67,
+  "deferred_refs": []
+}
+```
+
+The existing knowledge `ContextPack` now uses the same receipt vocabulary for retrieval hits.
+
+### Consumed tool results
+
+`compactConsumedToolResult()` defaults to 4,000 characters for evidence that has already had its high-fidelity pass. It preserves the item ref/hash/priority so later turns can expand the source again instead of replaying the original dump.
+
+## Index law
+
+> An index is a retrieval substrate, never prompt content.
+
+The active prompt should receive a compact repository/index status plus selected evidence references. It should not receive an entire repository tree, symbol graph, embedding set, tool catalog, or hundreds of search results.
+
+Prefer evidence in this order whenever possible:
+
+```text
+exact structural evidence
+        ↓
+bounded lexical/search evidence
+        ↓
+semantic retrieval
+        ↓
+explicit larger range/full object only when required
+```
+
+## Tool discovery
+
+`searchToolCards()` supports cards-first discovery. It accepts a host/tool catalog and returns compact cards without full input schemas:
+
+```json
+{
+  "tool": "code.retrieve",
+  "summary": "Find symbols, callers, and semantic code matches.",
+  "risk": "read",
+  "required": ["query"],
+  "result_class": "bounded_evidence"
+}
+```
+
+A host can hydrate the selected tool's full schema only after selection. This keeps the portable contract compatible with small local catalogs and large hosted catalogs without injecting all schemas at turn zero.
+
+## Subagent handoff law
+
+A child agent should return a compact work receipt rather than its entire prompt/tool history:
+
+```text
+conclusion
+evidence refs
+changed files
+commands/tests
+uncertainty
+```
+
+The parent can expand an evidence ref when needed.