> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# @toolshed/policy

> Authorization, role-based filtering, and annotation resolution.

The policy package provides the authorization layer for Toolshed -- filtering tools by role and resolving whether tools require approval.

## filterToolsByRole(tools, role)

Returns only the tools whose paths match at least one pattern in the role:

```typescript theme={null}
import { filterToolsByRole } from "@toolshed/policy";

const visibleTools = filterToolsByRole(allTools, {
  id: "developer",
  name: "Developer",
  patterns: ["github.**", "slack.channels.list"],
});
```

## matchPattern(toolPath, pattern)

Tests whether a tool path matches a glob pattern:

```typescript theme={null}
import { matchPattern } from "@toolshed/policy";

matchPattern("github.issues.create", "github.issues.*");  // true
matchPattern("github.issues.create", "github.**");         // true
matchPattern("github.issues.create", "linear.**");         // false
matchPattern("github.issues.create", "*");                 // true
```

Algorithm: recursive segment-by-segment matching.

* `*` matches exactly one segment
* `**` matches zero or more segments

## resolveAnnotations(tool)

Derives whether a tool requires user approval based on its metadata:

```typescript theme={null}
import { resolveAnnotations } from "@toolshed/policy";

const annotations = resolveAnnotations(tool);
// { requiresApproval: true, reason: "HTTP method POST is not safe" }
```

**Resolution priority** (first match wins):

| Source  | Logic                                                                     |
| ------- | ------------------------------------------------------------------------- |
| OpenAPI | `metadata.httpMethod` -- GET, HEAD, OPTIONS are safe                      |
| GraphQL | `metadata.operationType` -- `query` is safe, `mutation` requires approval |
| MCP     | `metadata.mcpAnnotations.destructiveHint`                                 |
| Plugin  | Falls back to `tool.destructive` field                                    |

### Return type

```typescript theme={null}
interface ToolAnnotations {
  requiresApproval: boolean;
  reason?: string;
}
```