---
title: "tools"
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# tools

```go
import "github.com/goppydae/sharur/internal/tools"
```

Package tools provides the universal tool interface and registry.

## Index

- [func NormalizePath\(path string\) string](<#NormalizePath>)
- [type Bash](<#Bash>)
  - [func \(Bash\) Description\(\) string](<#Bash.Description>)
  - [func \(t Bash\) Execute\(ctx context.Context, args json.RawMessage, update ToolUpdate\) \(\*ToolResult, error\)](<#Bash.Execute>)
  - [func \(Bash\) IsReadOnly\(\) bool](<#Bash.IsReadOnly>)
  - [func \(Bash\) Name\(\) string](<#Bash.Name>)
  - [func \(Bash\) Schema\(\) json.RawMessage](<#Bash.Schema>)
- [type Edit](<#Edit>)
  - [func \(Edit\) Description\(\) string](<#Edit.Description>)
  - [func \(Edit\) Execute\(ctx context.Context, args json.RawMessage, update ToolUpdate\) \(\*ToolResult, error\)](<#Edit.Execute>)
  - [func \(Edit\) IsReadOnly\(\) bool](<#Edit.IsReadOnly>)
  - [func \(Edit\) Name\(\) string](<#Edit.Name>)
  - [func \(Edit\) Schema\(\) json.RawMessage](<#Edit.Schema>)
- [type Find](<#Find>)
  - [func \(Find\) Description\(\) string](<#Find.Description>)
  - [func \(Find\) Execute\(ctx context.Context, args json.RawMessage, update ToolUpdate\) \(\*ToolResult, error\)](<#Find.Execute>)
  - [func \(Find\) IsReadOnly\(\) bool](<#Find.IsReadOnly>)
  - [func \(Find\) Name\(\) string](<#Find.Name>)
  - [func \(Find\) Schema\(\) json.RawMessage](<#Find.Schema>)
- [type Grep](<#Grep>)
  - [func \(Grep\) Description\(\) string](<#Grep.Description>)
  - [func \(Grep\) Execute\(ctx context.Context, args json.RawMessage, update ToolUpdate\) \(\*ToolResult, error\)](<#Grep.Execute>)
  - [func \(Grep\) IsReadOnly\(\) bool](<#Grep.IsReadOnly>)
  - [func \(Grep\) Name\(\) string](<#Grep.Name>)
  - [func \(Grep\) Schema\(\) json.RawMessage](<#Grep.Schema>)
- [type Ls](<#Ls>)
  - [func \(Ls\) Description\(\) string](<#Ls.Description>)
  - [func \(Ls\) Execute\(ctx context.Context, args json.RawMessage, update ToolUpdate\) \(\*ToolResult, error\)](<#Ls.Execute>)
  - [func \(Ls\) IsReadOnly\(\) bool](<#Ls.IsReadOnly>)
  - [func \(Ls\) Name\(\) string](<#Ls.Name>)
  - [func \(Ls\) Schema\(\) json.RawMessage](<#Ls.Schema>)
- [type Read](<#Read>)
  - [func \(Read\) Description\(\) string](<#Read.Description>)
  - [func \(Read\) Execute\(ctx context.Context, args json.RawMessage, update ToolUpdate\) \(\*ToolResult, error\)](<#Read.Execute>)
  - [func \(Read\) IsReadOnly\(\) bool](<#Read.IsReadOnly>)
  - [func \(Read\) Name\(\) string](<#Read.Name>)
  - [func \(Read\) Schema\(\) json.RawMessage](<#Read.Schema>)
- [type Tool](<#Tool>)
- [type ToolCall](<#ToolCall>)
- [type ToolRegistry](<#ToolRegistry>)
  - [func NewToolRegistry\(\) \*ToolRegistry](<#NewToolRegistry>)
  - [func \(r \*ToolRegistry\) All\(\) \[\]Tool](<#ToolRegistry.All>)
  - [func \(r \*ToolRegistry\) Get\(name string\) \(Tool, bool\)](<#ToolRegistry.Get>)
  - [func \(r \*ToolRegistry\) Has\(name string\) bool](<#ToolRegistry.Has>)
  - [func \(r \*ToolRegistry\) Register\(t Tool\)](<#ToolRegistry.Register>)
- [type ToolResult](<#ToolResult>)
- [type ToolUpdate](<#ToolUpdate>)
- [type Write](<#Write>)
  - [func \(Write\) Description\(\) string](<#Write.Description>)
  - [func \(Write\) Execute\(ctx context.Context, args json.RawMessage, update ToolUpdate\) \(\*ToolResult, error\)](<#Write.Execute>)
  - [func \(Write\) IsReadOnly\(\) bool](<#Write.IsReadOnly>)
  - [func \(Write\) Name\(\) string](<#Write.Name>)
  - [func \(Write\) Schema\(\) json.RawMessage](<#Write.Schema>)


<a name="NormalizePath"></a>
## func NormalizePath

```go
func NormalizePath(path string) string
```

NormalizePath strips a leading '@' from a path if present.

<a name="Bash"></a>
## type Bash

Bash is a tool for executing shell commands.

Security note: commands are executed as\-is via \`bash \-c\`. The subprocess runs in an isolated environment containing only an explicit allowlist of variables \(PATH, HOME, LANG, TERM, TMPDIR, USER, SHELL\). Extra variables can be injected via EnvAllowlist. DenyPatterns blocks commands by substring match before execution.

```go
type Bash struct {
    // Cwd is the working directory for commands.
    Cwd string
    // Timeout for command execution.
    Timeout time.Duration
    // DenyPatterns is an optional list of substrings that, if found in the
    // command, will cause execution to be rejected. Checked case-insensitively.
    // Example: []string{"rm -rf /", "dd if=", "> /dev/sd"}
    DenyPatterns []string
    // EnvAllowlist is an optional list of KEY=VALUE pairs to inject into the
    // subprocess environment in addition to the default allowlist.
    EnvAllowlist []string
}
```

<a name="Bash.Description"></a>
### func \(Bash\) Description

```go
func (Bash) Description() string
```



<a name="Bash.Execute"></a>
### func \(Bash\) Execute

```go
func (t Bash) Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
```



<a name="Bash.IsReadOnly"></a>
### func \(Bash\) IsReadOnly

```go
func (Bash) IsReadOnly() bool
```



<a name="Bash.Name"></a>
### func \(Bash\) Name

```go
func (Bash) Name() string
```



<a name="Bash.Schema"></a>
### func \(Bash\) Schema

```go
func (Bash) Schema() json.RawMessage
```



<a name="Edit"></a>
## type Edit

Edit is a tool for performing search\-replace edits on files.

```go
type Edit struct{}
```

<a name="Edit.Description"></a>
### func \(Edit\) Description

```go
func (Edit) Description() string
```



<a name="Edit.Execute"></a>
### func \(Edit\) Execute

```go
func (Edit) Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
```



<a name="Edit.IsReadOnly"></a>
### func \(Edit\) IsReadOnly

```go
func (Edit) IsReadOnly() bool
```



<a name="Edit.Name"></a>
### func \(Edit\) Name

```go
func (Edit) Name() string
```



<a name="Edit.Schema"></a>
### func \(Edit\) Schema

```go
func (Edit) Schema() json.RawMessage
```



<a name="Find"></a>
## type Find

Find is a tool for finding files by glob pattern.

```go
type Find struct{}
```

<a name="Find.Description"></a>
### func \(Find\) Description

```go
func (Find) Description() string
```



<a name="Find.Execute"></a>
### func \(Find\) Execute

```go
func (Find) Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
```



<a name="Find.IsReadOnly"></a>
### func \(Find\) IsReadOnly

```go
func (Find) IsReadOnly() bool
```



<a name="Find.Name"></a>
### func \(Find\) Name

```go
func (Find) Name() string
```



<a name="Find.Schema"></a>
### func \(Find\) Schema

```go
func (Find) Schema() json.RawMessage
```



<a name="Grep"></a>
## type Grep

Grep is a tool for searching file contents with regex.

```go
type Grep struct{}
```

<a name="Grep.Description"></a>
### func \(Grep\) Description

```go
func (Grep) Description() string
```



<a name="Grep.Execute"></a>
### func \(Grep\) Execute

```go
func (Grep) Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
```



<a name="Grep.IsReadOnly"></a>
### func \(Grep\) IsReadOnly

```go
func (Grep) IsReadOnly() bool
```



<a name="Grep.Name"></a>
### func \(Grep\) Name

```go
func (Grep) Name() string
```



<a name="Grep.Schema"></a>
### func \(Grep\) Schema

```go
func (Grep) Schema() json.RawMessage
```



<a name="Ls"></a>
## type Ls

Ls is a tool for listing directory contents.

```go
type Ls struct{}
```

<a name="Ls.Description"></a>
### func \(Ls\) Description

```go
func (Ls) Description() string
```



<a name="Ls.Execute"></a>
### func \(Ls\) Execute

```go
func (Ls) Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
```



<a name="Ls.IsReadOnly"></a>
### func \(Ls\) IsReadOnly

```go
func (Ls) IsReadOnly() bool
```



<a name="Ls.Name"></a>
### func \(Ls\) Name

```go
func (Ls) Name() string
```



<a name="Ls.Schema"></a>
### func \(Ls\) Schema

```go
func (Ls) Schema() json.RawMessage
```



<a name="Read"></a>
## type Read

Read is a tool for reading file contents.

```go
type Read struct{}
```

<a name="Read.Description"></a>
### func \(Read\) Description

```go
func (Read) Description() string
```



<a name="Read.Execute"></a>
### func \(Read\) Execute

```go
func (Read) Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
```



<a name="Read.IsReadOnly"></a>
### func \(Read\) IsReadOnly

```go
func (Read) IsReadOnly() bool
```



<a name="Read.Name"></a>
### func \(Read\) Name

```go
func (Read) Name() string
```



<a name="Read.Schema"></a>
### func \(Read\) Schema

```go
func (Read) Schema() json.RawMessage
```



<a name="Tool"></a>
## type Tool

Tool is the universal tool interface — anything the agent can do.

```go
type Tool interface {
    Name() string
    Description() string
    Schema() json.RawMessage // JSON Schema for parameters
    Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
    IsReadOnly() bool
}
```

<a name="ToolCall"></a>
## type ToolCall

ToolCall represents a tool invocation from the LLM.

```go
type ToolCall struct {
    ID       string          `json:"id"`
    Name     string          `json:"name"`
    Args     json.RawMessage `json:"args"`
    Position int             `json:"position,omitempty"`
}
```

<a name="ToolRegistry"></a>
## type ToolRegistry

ToolRegistry manages registered tools.

```go
type ToolRegistry struct {
    // contains filtered or unexported fields
}
```

<a name="NewToolRegistry"></a>
### func NewToolRegistry

```go
func NewToolRegistry() *ToolRegistry
```

NewToolRegistry creates an empty tool registry.

<a name="ToolRegistry.All"></a>
### func \(\*ToolRegistry\) All

```go
func (r *ToolRegistry) All() []Tool
```

All returns all registered tools.

<a name="ToolRegistry.Get"></a>
### func \(\*ToolRegistry\) Get

```go
func (r *ToolRegistry) Get(name string) (Tool, bool)
```

Get retrieves a tool by name.

<a name="ToolRegistry.Has"></a>
### func \(\*ToolRegistry\) Has

```go
func (r *ToolRegistry) Has(name string) bool
```

Has checks if a tool is registered.

<a name="ToolRegistry.Register"></a>
### func \(\*ToolRegistry\) Register

```go
func (r *ToolRegistry) Register(t Tool)
```

Register adds a tool to the registry.

<a name="ToolResult"></a>
## type ToolResult

ToolResult represents the output of a tool execution.

```go
type ToolResult struct {
    Content  string         `json:"content"`
    IsError  bool           `json:"isError,omitempty"`
    Metadata map[string]any `json:"metadata,omitempty"`
}
```

<a name="ToolUpdate"></a>
## type ToolUpdate

ToolUpdate is a callback for streaming partial results.

```go
type ToolUpdate func(partial *ToolResult)
```

<a name="Write"></a>
## type Write

Write is a tool for creating or overwriting files.

```go
type Write struct{}
```

<a name="Write.Description"></a>
### func \(Write\) Description

```go
func (Write) Description() string
```



<a name="Write.Execute"></a>
### func \(Write\) Execute

```go
func (Write) Execute(ctx context.Context, args json.RawMessage, update ToolUpdate) (*ToolResult, error)
```



<a name="Write.IsReadOnly"></a>
### func \(Write\) IsReadOnly

```go
func (Write) IsReadOnly() bool
```



<a name="Write.Name"></a>
### func \(Write\) Name

```go
func (Write) Name() string
```



<a name="Write.Schema"></a>
### func \(Write\) Schema

```go
func (Write) Schema() json.RawMessage
```



Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)