# Shield Wrappers

Use `Shield` wrappers when you want guardrails to run automatically around your functions.

```typescript
import { Highflame, Shield } from "@highflame/sdk";

const client = new Highflame({ apiKey: "hf_sk_..." });
const shield = new Shield(client);
```

## `shield.prompt(fn, options?)`

Guards a prompt input before the function runs. If denied, `fn` is never called.

```typescript
const chat = shield.prompt(async (message: string) => llm.complete(message));

const guardedChat = shield.prompt(
  async (context: string, userMessage: string) => llm.complete(context, userMessage),
  { contentArg: 1 },
);

const monitoredChat = shield.prompt(async (msg: string) => llm.complete(msg), {
  mode: "monitor",
  sessionId: "sess_user_abc",
});
```

| Option       | Type                                | Default     | Description                               |
| ------------ | ----------------------------------- | ----------- | ----------------------------------------- |
| `mode`       | `"enforce" \| "monitor" \| "alert"` | `"enforce"` | Enforcement mode                          |
| `contentArg` | `number`                            | `0`         | Zero-based index of the argument to guard |
| `sessionId`  | `string`                            | —           | Session ID for cross-turn tracking        |

## `shield.tool(fn, options?)`

Guards a tool call before the function runs. If denied, `fn` is never called. All function arguments are forwarded as tool-call context.

```typescript
const shell = shield.tool(async function shell(cmd: string) {
  return exec(cmd);
});

const runQuery = shield.tool(async function runSql(query: string, db: string) {
  return database.query(query, db);
});

const deleteFile = shield.tool(async (path: string) => fs.unlink(path), {
  toolName: "delete_file",
});
```

| Option      | Type                                | Default     | Description            |
| ----------- | ----------------------------------- | ----------- | ---------------------- |
| `mode`      | `"enforce" \| "monitor" \| "alert"` | `"enforce"` | Enforcement mode       |
| `toolName`  | `string`                            | `fn.name`   | Override the tool name |
| `sessionId` | `string`                            | —           | Session ID             |

## `shield.toolResponse(fn, options?)`

Guards a tool's return value after the function runs. The function always executes first; the return value is blocked if denied.

```typescript
const fetchPage = shield.toolResponse(async function fetchPage(url: string) {
  return http.get(url);
});

const readRecord = shield.toolResponse(
  async function readRecord(id: string) {
    return db.find(id);
  },
  { mode: "alert", sessionId: "sess_abc" },
);
```

| Option      | Type                                | Default     | Description                       |
| ----------- | ----------------------------------- | ----------- | --------------------------------- |
| `mode`      | `"enforce" \| "monitor" \| "alert"` | `"enforce"` | Enforcement mode                  |
| `toolName`  | `string`                            | `fn.name`   | Tool name included in the request |
| `sessionId` | `string`                            | —           | Session ID                        |

## `shield.modelResponse(fn, options?)`

Guards a model's output before returning it to the caller. The function always executes first; its return value is blocked if denied.

```typescript
const generate = shield.modelResponse(async (prompt: string) => {
  return openai.chat.completions.create({ ... });
});

const trackedGenerate = shield.modelResponse(
  async (prompt: string) => llm.complete(prompt),
  { sessionId: "sess_user_xyz" },
);
```

| Option      | Type                                | Default     | Description      |
| ----------- | ----------------------------------- | ----------- | ---------------- |
| `mode`      | `"enforce" \| "monitor" \| "alert"` | `"enforce"` | Enforcement mode |
| `sessionId` | `string`                            | —           | Session ID       |

## `shield.wrap(options)`

Generic wrapper for content types and actions not covered by the named shorthands.

```typescript
const writeConfig = shield.wrap({
  contentType: "file",
  action: "write_file",
  contentArg: 1,
})(async (path: string, content: string) => fs.writeFile(path, content));

const fileGuard = shield.wrap({ contentType: "file", action: "read_file" });
const readKey = fileGuard(async (path: string) => fs.readFile(path, "utf8"));
const readCert = fileGuard(async (path: string) => fs.readFile(path, "utf8"));
```

| Option        | Type                                                                                 | Default     | Description                                 |
| ------------- | ------------------------------------------------------------------------------------ | ----------- | ------------------------------------------- |
| `contentType` | `"prompt" \| "response" \| "tool_call" \| "file"`                                    | required    | Content type                                |
| `action`      | `"process_prompt" \| "call_tool" \| "read_file" \| "write_file" \| "connect_server"` | required    | Cedar action                                |
| `contentArg`  | `number`                                                                             | `0`         | Zero-based argument index to use as content |
| `mode`        | `"enforce" \| "monitor" \| "alert"`                                                  | `"enforce"` | Enforcement mode                            |
| `sessionId`   | `string`                                                                             | —           | Session ID                                  |

## Related Topics

* [Low-Level Client](/api-reference/sdk/shield/typescript-sdk/client-api.md) for direct request and response control
* [Advanced Topics](/api-reference/sdk/shield/typescript-sdk/advanced-topics.md) for streaming, sessions, logging, and advanced request options


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/api-reference/sdk/shield/typescript-sdk/shield-wrappers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.