# Tool Resource Bindings

Tools in CleverAgents declare **resource slots** that describe which
resources they operate on.  At activation time the binding resolution
service maps each slot to a concrete resource from the registry.

## Binding Modes

### Contextual Binding (default)

The slot declares only a `resource_type` requirement.  The system
searches the plan's project for linked resources that match at
activation time.

**Resolution rules:**

1. Collect all linked resources whose type matches the slot's
   `resource_type` (including sub-types via `parent_types`).
2. If exactly **one** resource matches, it is automatically bound.
3. If **multiple** resources match, the slot `name` is used as a
   hint: the resource whose alias (or short name) equals the slot
   name is selected.  If no alias matches, a `ValidationError` is
   raised.
4. If **no** resource matches and the slot is `required`, a
   `ValidationError` is raised.

```yaml
resource_slots:
  - name: repo
    resource_type: git-checkout
    access: read_write
    binding: contextual       # default -- can be omitted
```

### Static Binding

The slot is hardcoded to a specific registered resource by name via
the `static_resource` field.  Validated at registration time.

```yaml
resource_slots:
  - name: config_dir
    resource_type: fs-directory
    access: read_only
    binding: static
    static_resource: local/shared-config
```

### Parameter Binding

The resource reference is passed as a tool argument at invocation
time.  Resolution is deferred until the tool is actually called.

```yaml
resource_slots:
  - name: target
    resource_type: fs-directory
    access: read_write
    binding: parameter
```

At invocation the caller supplies `target=<resource-name-or-id>`.

## Resolution Order

For each resource slot on the tool:

1. Determine the binding mode (`static`, `parameter`, or
   `contextual`).
2. **Static** -- look up the named resource in the registry;
   verify type compatibility.
3. **Parameter** -- if invocation params include the slot name,
   resolve eagerly; otherwise mark as *deferred*.
4. **Contextual** -- search the project's linked resources for
   type-compatible matches and apply disambiguation rules.

## Type Compatibility

A resource is *type-compatible* with a slot when:

- The resource's type **exactly matches** the slot's
  `resource_type`, **or**
- The resource's type declares the slot's `resource_type` in its
  `parent_types` list (sub-type relationship).

For example, `fs-directory` lists `git-checkout` in its
`parent_types`, so an `fs-directory` resource satisfies a slot
requiring `git-checkout`.

## Examples

### Single Contextual Resource

```python
from cleveragents.application.services.binding_resolution_service import (
    BindingResolutionService,
)

service = BindingResolutionService(resource_registry)
results = service.resolve(tool, project)
# results[0].binding_mode == "contextual"
# results[0].resource_id == "01HGZ..."
```

### Mixed Bindings

A tool may combine all three modes:

```yaml
resource_slots:
  - name: repo
    resource_type: git-checkout
    access: read_write
    binding: contextual
  - name: config
    resource_type: fs-directory
    access: read_only
    binding: static
    static_resource: local/shared-config
  - name: output
    resource_type: fs-directory
    access: write_only
    binding: parameter
```

## API Reference

See:

- [`BindingResolutionService`](cleveragents/application/services/binding_resolution_service.md)
- [`BindingResult`](cleveragents/domain/models/core/resource_slot.md)
- [`ResourceSlot`](cleveragents/domain/models/core/tool.md)