> ## 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.

# PluginContext Reference

> The five properties available to tool handlers.

Every tool handler receives a `PluginContext` as its first argument. It provides authentication, authorization context, approval requests, and logging.

## Properties

### `ctx.userId`

```typescript theme={null}
userId: string
```

The authenticated user's ID. Use this to scope operations to the current user.

### `ctx.role`

```typescript theme={null}
role: Role  // { id: string, name: string, patterns: string[] }
```

The user's role, including the glob patterns that determine which tools they can access.

### `ctx.auth`

```typescript theme={null}
auth: AuthResolver  // { getToken(provider: string): Promise<string> }
```

Retrieve an OAuth access token for a provider. The token is automatically vended and refreshed by the server.

```typescript theme={null}
const token = await ctx.auth.getToken("github");
const res = await fetch("https://api.github.com/user", {
  headers: { Authorization: `Bearer ${token}` },
});
```

### `ctx.elicit`

```typescript theme={null}
elicit: (request: {
  toolPath: string;
  message: string;
  args?: Record<string, unknown>;
  type?: "approval" | "form";  // default: "approval"
}) => Promise<{
  executionId: string;
  approved: boolean;
  data?: Record<string, unknown>;
}>
```

Request user approval before performing a destructive action. See [Elicitation Guide](/guides/elicitation).

```typescript theme={null}
const approval = await ctx.elicit({
  toolPath: "github.issues.create",
  message: `Create issue "${input.title}"?`,
  args: input,
  type: "approval",
});

if (!approval.approved) {
  throw new Error("Denied by user");
}
```

### `ctx.logger`

```typescript theme={null}
logger: {
  info(message: string, meta?: Record<string, unknown>): void;
  warn(message: string, meta?: Record<string, unknown>): void;
  error(message: string, meta?: Record<string, unknown>): void;
}
```

Structured logging with optional metadata.

```typescript theme={null}
ctx.logger.info("Fetching issues", { owner: "org", repo: "repo" });
ctx.logger.error("GitHub API returned 403", { status: 403 });
```