# pkg/tools

> Sistema de tools (function calling) con JSON Schema, sandbox, y permisos.

## Responsabilidad

Permitir que el LLM invoque funciones definidas en Go, con validación de schema y sandboxing.

## API pública

```go
type Tool struct {
    Name        string
    Description string
    InputSchema json.RawMessage  // JSON Schema draft-07+
    Handler     Handler          // func(ctx, args json.RawMessage) (Result, error)
    Permission  Permission       // Allow | Ask | Deny
    Examples    []Example        // few-shot para el LLM
}

type Registry interface {
    Register(tool Tool) error
    Get(name string) (Tool, bool)
    List() []Tool
    Filter(policy Policy) []Tool
}

type Call struct {
    ID        string
    Name      string
    Arguments json.RawMessage
    Thought   string           // opcional: chain-of-thought del LLM
}

type Result struct {
    Content   string
    IsError   bool
    Metadata  map[string]string
    Artifacts []Artifact
}

type Permission int

const (
    Allow Permission = iota
    Ask
    Deny
)
```

## Sandbox integrado

`pkg/tools` usa `os.Root` (Go 1.24+) para sandbox de filesystem:

```go
sandbox := tools.NewSandbox("./workspace")
sandbox.Register(myReadTool)  // solo puede leer dentro del workspace
```

Ver [pkg/tools/sandbox/](sandbox/) para detalles.

## Tools genéricos incluidos

- `http_fetch` — GET a URL con HTML→markdown
- `json_parse` — Parse JSON arbitrario
- `datetime_now` — Current timestamp

Las tools específicas de cada producto (ej. `read_file`, `bash` para software dev) las define cada consumidor en su propio `internal/tools/`.

## Ver también

- [pkg/agent](../agent/README.md) — Ejecuta tool calls
- [pkg/llm](../llm/README.md) — Las tools se envían al LLM