cleveragents-core/docs/adr/ADR-008-resource-system.md

adr_number, title, status_history, tier, authors, superseded_by, related_adrs, acceptance

adr_number	title	status_history	tier	authors	superseded_by	related_adrs	acceptance
8	Resource System	2026-02-16 Proposed Jeffrey Phillips Freeman 2026-02-16 Accepted Jeffrey Phillips Freeman	2	Jeffrey Phillips Freeman	null	number title relationship 2 Namespace System Resources are identified and resolved via the universal naming convention number title relationship 9 Project Model Projects aggregate and scope the resources available to plans number title relationship 11 Tool System Tools declare resource bindings that determine which resources they operate on number title relationship 15 Sandbox and Checkpoint Per-resource-type sandbox strategies isolate resource modifications number title relationship 36 Resource DAG Operational Semantics Defines the operational semantics (sandbox boundary algebra, reachability, change propagation) that build on the DAG structure number title relationship 37 Tool Reachability and Access Projection Formalizes transitive tool reachability through DAG containment edges number title relationship 38 Cross-Mechanism Sandbox Coordination Defines coherence and coordination across equivalent physical resources in different sandbox domains number title relationship 39 Container and Execution Environment Resource Types Extends the built-in type registry with container and execution environment types number title relationship 40 LSP Resource Types Extends the built-in type registry with LSP server, workspace, and document types	votes_for votes_against abstentions voter comment Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> Typed resources with DAG relationships and per-type sandbox strategies provide the right abstraction for safe manipulation

Context

CleverAgents must operate on a wide variety of artifacts — git repositories, filesystem directories, databases, APIs, configuration files, documentation, and more. Each resource type has different read/write semantics, different sandboxing strategies, and different merge behaviors. The system needs a uniform abstraction that makes resources discoverable, linkable to projects, bindable to tools, and sandboxable — while accommodating the inherent diversity of resource types.

Decision Drivers

• Must operate on diverse artifact types (git repos, filesystems, databases, APIs, config files) with different read/write semantics
• Each resource type requires a different sandboxing strategy and merge behavior
• Resources must be discoverable, linkable to projects, and bindable to tools through a uniform abstraction
• Need DAG-based relationships between resources for correct sandbox creation and cleanup ordering
• Resources must be independently registered and shareable across multiple projects
• Per-type sandbox strategies must ensure appropriate isolation without per-resource manual configuration

Decision

CleverAgents uses a typed resource system with a resource registry, independently registered resource types, and per-type sandbox strategies. Resources are first-class entities with namespaced names, ULID identifiers, and DAG-based relationships. Resource types define the schema, sandbox strategy, and merge behavior for each category of artifact.

Design

Resource Model

Each resource is an independently registered entity with:

• Identity: resource_id (ULID), name (namespaced, e.g., local/api-service-repo), resource_type (reference to a registered type).
• Location: uri or path pointing to the physical artifact.
• Metadata: description, tags, custom key-value properties.
• Access control: read_only flag (can be overridden at the project level).
• Relationships: DAG edges to other resources (e.g., a git checkout depends on a git repository).

Resource Types

Resource types are independently registered entities that define the schema and behavior for a category of resources. Built-in types include:

Type	Sandbox Strategy	Description
git-checkout	git_worktree	A checked-out git working tree
git	none	A bare or remote git repository
fs-directory	copy_on_write	A filesystem directory
fs-mount	copy_on_write or overlay	A mounted filesystem
Database types	transaction_rollback	Custom database resource types
API types	none	Custom API endpoint types

Resource types are registered via YAML configuration and managed through the agents resource-type CLI commands.

Resource Registry

The resource registry is a persistent catalog of all registered resources. Resources are registered via agents resource add --config <FILE> and linked to projects via agents project link. A resource can be linked to multiple projects.

DAG Relationships

Resources form a directed acyclic graph. For example, a git-checkout resource depends on a git resource. The DAG is used for:

• Determining sandbox creation order (dependencies sandboxed first).
• Resolving resource discovery queries ("what resources does this project provide?").
• Ensuring cleanup happens in the correct order.

Resource Bindings

Tools declare resource slots specifying what types of resources they need and how they access them. At tool activation time, slots are bound to concrete resources through one of three modes:

• Contextual binding (default): Resolved from the plan's project context.
• Static binding: Hardcoded to a specific resource by name.
• Parameter binding: Passed as an argument at invocation time.

Sandbox Strategies Per Resource Type

Each resource type defines its default sandbox strategy. Per-resource overrides are possible. The five strategies are:

1. git_worktree: Creates a git worktree with a plan-specific branch. Rollback via git reset.
2. filesystem_copy (copy_on_write): Copies the directory. Rollback via restoring snapshot.
3. overlay: Overlay filesystem mount. Rollback via discarding overlay.
4. transaction_rollback: Database transaction with rollback capability.
5. none: No isolation. Used for read-only resources or resources that cannot be sandboxed.

Constraints

• Every resource must have a registered resource type. Untyped resources are not permitted.
• Resource names follow the namespace system ([[server:]namespace/]name).
• Resources are independently registered and exist outside of any project. Projects link to resources; they do not define them inline.
• A resource linked to a project with project_read_only: true must not be modified by any tool invoked within that project, even in sandbox.
• DAG relationships must be acyclic. Circular dependencies are rejected at registration time.

Consequences

Positive

• A uniform abstraction handles diverse artifact types (git repos, filesystems, databases, APIs) through the same management interface.
• Per-type sandbox strategies ensure appropriate isolation without requiring per-resource configuration.
• Independent registration enables resource sharing across multiple projects.
• DAG relationships enable correct ordering of sandbox creation and cleanup.

Negative

• The type registration system adds setup overhead before resources can be used.
• Custom resource types (databases, APIs) require implementing sandbox strategy adapters.
• The DAG tracking adds complexity to resource management.

Risks

• Resource types that cannot be sandboxed (none strategy) create a safety gap for plans that assume isolation.
• The resource registry could become stale if physical artifacts move or are deleted without updating registrations.

Alternatives Considered

None — specification-driven requirement. The typed resource system with registry, DAG relationships, and per-type sandbox strategies is prescribed by the specification as the foundation for tool resource bindings and sandboxed execution.

Compliance

• Type validation: Registration commands reject resources without a valid registered type.
• DAG cycle detection: Registration and linking operations validate that no cycles are introduced.
• Sandbox strategy tests: Each sandbox strategy has integration tests verifying isolation, modification, rollback, and cleanup.
• Binding resolution tests: Unit tests verify that all three binding modes (contextual, static, parameter) resolve correctly for each resource type.
• BDD scenarios: Behave features exercise multi-resource, multi-type plan execution including sandbox creation, tool binding, and result merging.