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

# harnest.agent.approval

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Approval request inputs

| Input | Rule | Example |
| - | - | - |
| `action` | Stable and non-sensitive | `typescript.execute` |
| `arguments` | Serializable values identifying the operation | Source hash and capabilities |
| `message` | Public text shown to the approver | `Execute TypeScript with network access?` |

## Exports

| Name | Kind |
| - | - |
| [`ApprovalDenied`](#approvaldenied) | Class |
| [`ApprovalEnforcementError`](#approvalenforcementerror) | Class |
| [`ApprovalError`](#approvalerror) | Class |
| [`ApprovalExecution`](#approvalexecution) | Class |
| [`ApprovalExpired`](#approvalexpired) | Class |
| [`ApprovalPolicy`](#approvalpolicy) | Class |
| [`ApprovalRequired`](#approvalrequired) | Class |
| [`ApprovalRun`](#approvalrun) | Class |
| [`InMemoryApprovalStore`](#inmemoryapprovalstore) | Class |
| [`PendingApproval`](#pendingapproval) | Class |
| [`approval_execution`](#approval_execution) | Function |
| [`approval_policy`](#approval_policy) | Function |
| [`authorize_mcp`](#authorize_mcp) | Function |
| [`bind_tool_arguments`](#bind_tool_arguments) | Function |
| [`record_approved_execution`](#record_approved_execution) | Function |
| [`record_approved_failure`](#record_approved_failure) | Function |
| [`request_human_approval`](#request_human_approval) | Function |
| [`require_human_approval`](#require_human_approval) | Function |
| [`wrap_approved_tool`](#wrap_approved_tool) | Function |

## ApprovalDenied

Raised inside a suspended execution when its principal denies the call.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalDenied
>
> try:
>     ...
> except ApprovalDenied as error:
>     ...
> ```

## ApprovalEnforcementError

Raised when protected work lacks a managed approval boundary.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalEnforcementError
>
> try:
>     ...
> except ApprovalEnforcementError as error:
>     ...
> ```

## ApprovalError

Base error for approval policy and state transitions.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalError
>
> try:
>     ...
> except ApprovalError as error:
>     ...
> ```

## ApprovalExecution

Invocation identity and optional grant visible to protected callables.

```python theme={null}
ApprovalExecution(
    user_id: str,
    session_id: str,
    call_id: str,
    grant: PendingApproval | None = None,
    store: 'InMemoryApprovalStore | None' = None,
    run: 'ApprovalRun | None' = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `user_id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `call_id` | `str` | `—` |
| `grant` | `PendingApproval \| None` | `None` |
| `store` | `'InMemoryApprovalStore \| None'` | `None` |
| `run` | `'ApprovalRun \| None'` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `call_id` | `str` | Required |
> | `grant` | `PendingApproval \| None` | `None` |
> | `store` | `'InMemoryApprovalStore \| None'` | `None` |
> | `run` | `'ApprovalRun \| None'` | `None` |
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalExecution
>
> execution = ApprovalExecution(user_id=..., session_id=..., call_id=...)
> ```

### ApprovalExecution.authorize

```python theme={null}
async ApprovalExecution.authorize(challenge: ApprovalChallenge) -> PendingApproval | None
```

Authorize a challenge through a live store or supplied one-time grant.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `challenge` | `ApprovalChallenge` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalExecution
>
> execution: ApprovalExecution
> approval = await execution.authorize(challenge=...)
> ```

## ApprovalExpired

Raised inside a suspended execution when its decision deadline passes.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalExpired
>
> try:
>     ...
> except ApprovalExpired as error:
>     ...
> ```

## ApprovalPolicy

Immutable policy attached to a local tool or MCP client factory.

```python theme={null}
ApprovalPolicy(
    message: str,
    timeout_seconds: int = 900,
    on_timeout: Literal['deny'] = 'deny',
    tools: tuple[str, ...] | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `message` | `str` | `—` |
| `timeout_seconds` | `int` | `900` |
| `on_timeout` | `Literal['deny']` | `'deny'` |
| `tools` | `tuple[str, ...] \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `message` | `str` | Required |
> | `timeout_seconds` | `int` | `900` |
> | `on_timeout` | `Literal['deny']` | `'deny'` |
> | `tools` | `tuple[str, ...] \| None` | `None` |
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalPolicy
>
> policy = ApprovalPolicy(message=...)
> ```

### ApprovalPolicy.applies\_to

```python theme={null}
ApprovalPolicy.applies_to(name: str) -> bool
```

Report whether this policy protects the named remote tool.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalPolicy
>
> policy: ApprovalPolicy
> result = policy.applies_to(name=...)
> ```

## ApprovalRequired

Stop managed execution before a protected action is called.

```python theme={null}
ApprovalRequired(challenge: ApprovalChallenge) -> None
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalRequired
>
> try:
>     ...
> except ApprovalRequired as error:
>     ...
> ```

## ApprovalRun

One live invocation whose Python task may suspend at protected calls.

Obtain this object from the owning Harnest API; its constructor includes runtime bindings.

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `id` | `str` | `—` |
| `user_id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `call_id` | `str` | `—` |
| `notifications` | `asyncio.Queue[tuple[str, Any]]` | `Queue()` |
| `activation` | `asyncio.Event` | `Event()` |
| `task` | `asyncio.Task[Any] \| None` | `None` |

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import ApprovalRun
>
> run: ApprovalRun  # returned by Harnest, not constructed directly
> ```

## InMemoryApprovalStore

Development approval store with atomic one-time transitions.

```python theme={null}
InMemoryApprovalStore(
    *,
    clock: Callable[[], float] = time,
    max_pending: int = 1024,
    tombstone_seconds: float = 60,
) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `clock` | `Callable[[], float]` | `time` |
> | `max_pending` | `int` | `1024` |
> | `tombstone_seconds` | `float` | `60` |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store = InMemoryApprovalStore()
> ```

### InMemoryApprovalStore.create\_run

```python theme={null}
InMemoryApprovalStore.create_run(*, user_id: str, session_id: str, call_id: str) -> ApprovalRun
```

Create an invocation-scoped approval suspension channel.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `call_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> run = store.create_run(user_id=..., session_id=..., call_id=...)
> ```

### InMemoryApprovalStore.request

```python theme={null}
InMemoryApprovalStore.request(
    challenge: ApprovalChallenge,
    *,
    user_id: str,
    session_id: str,
    call_id: str,
    invocation: Any = None,
) -> PendingApproval
```

Register a bounded one-time approval challenge.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `challenge` | `ApprovalChallenge` | Required |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `call_id` | `str` | Required |
> | `invocation` | `Any` | `None` |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> approval = store.request(challenge=..., user_id=..., session_id=..., call_id=...)
> ```

### InMemoryApprovalStore.suspend

```python theme={null}
async InMemoryApprovalStore.suspend(run: ApprovalRun, challenge: ApprovalChallenge) -> PendingApproval
```

Suspend an invocation until its challenge is approved or rejected.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `run` | `ApprovalRun` | Required |
> | `challenge` | `ApprovalChallenge` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> approval = await store.suspend(run=..., challenge=...)
> ```

### InMemoryApprovalStore.decide

```python theme={null}
InMemoryApprovalStore.decide(
    approval_id: str,
    *,
    user_id: str,
    decision: Decision,
    deliver: bool = True,
) -> PendingApproval
```

Commit an approval decision for the matching user-owned challenge.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `approval_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `decision` | `Decision` | Required |
> | `deliver` | `bool` | `True` |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> approval = store.decide(approval_id=..., user_id=..., decision=...)
> ```

### InMemoryApprovalStore.deliver\_decision

```python theme={null}
InMemoryApprovalStore.deliver_decision(pending: PendingApproval, decision: Decision) -> None
```

Deliver a committed decision to its suspended invocation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `pending` | `PendingApproval` | Required |
> | `decision` | `Decision` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> store.deliver_decision(pending=..., decision=...)
> ```

### InMemoryApprovalStore.run\_for

```python theme={null}
InMemoryApprovalStore.run_for(pending: PendingApproval) -> ApprovalRun | None
```

Return the live invocation associated with a pending challenge.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `pending` | `PendingApproval` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> run = store.run_for(pending=...)
> ```

### InMemoryApprovalStore.pending\_for

```python theme={null}
InMemoryApprovalStore.pending_for(*, user_id: str, session_id: str) -> list[PendingApproval]
```

Expose only live challenges owned by this principal and session.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> result = store.pending_for(user_id=..., session_id=...)
> ```

### InMemoryApprovalStore.assert\_consumed

```python theme={null}
InMemoryApprovalStore.assert_consumed(pending: PendingApproval) -> None
```

Require resumed execution to have reached the approved action.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `pending` | `PendingApproval` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> store.assert_consumed(pending=...)
> ```

### InMemoryApprovalStore.executed

```python theme={null}
InMemoryApprovalStore.executed(pending: PendingApproval) -> None
```

Mark an approved action as successfully executed.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `pending` | `PendingApproval` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> store.executed(pending=...)
> ```

### InMemoryApprovalStore.failed

```python theme={null}
InMemoryApprovalStore.failed(pending: PendingApproval) -> None
```

Mark an approved action as failed during execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `pending` | `PendingApproval` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> store.failed(pending=...)
> ```

### InMemoryApprovalStore.cancel\_run

```python theme={null}
InMemoryApprovalStore.cancel_run(run: ApprovalRun) -> None
```

Cancel all unresolved challenges and work for one invocation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `run` | `ApprovalRun` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> store.cancel_run(run=...)
> ```

### InMemoryApprovalStore.retained\_count

Return the number of live challenges and retained tombstones.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import InMemoryApprovalStore
>
> store: InMemoryApprovalStore
> value = store.retained_count
> ```

## PendingApproval

One principal-scoped invocation awaiting a one-time decision.

Obtain this object from the owning Harnest API; its constructor includes runtime bindings.

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `id` | `str` | `—` |
| `user_id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `call_id` | `str` | `—` |
| `action` | `str` | `—` |
| `argument_hash` | `str` | `—` |
| `message` | `str` | `—` |
| `expires_at` | `float` | `—` |
| `status` | `str` | `'pending'` |
| `consumed` | `bool` | `False` |
| `finished_at` | `float \| None` | `None` |

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import PendingApproval
>
> approval: PendingApproval  # returned by Harnest, not constructed directly
> ```

### PendingApproval.public

```python theme={null}
PendingApproval.public() -> dict[str, Any]
```

Return the client-safe fields needed to present an approval prompt.

> [accordion] Example
>
> ```python theme={null}
> from harnest.agent.approval import PendingApproval
>
> approval: PendingApproval
> result = approval.public()
> ```

## approval\_execution

Activate approval authority for protected work in this context.

```python theme={null}
approval_execution(execution: ApprovalExecution) -> Iterator[None]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `execution` | `ApprovalExecution` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import approval_execution
>
> with approval_execution(execution=...):
>     ...
> ```

## approval\_policy

Read the Harnest approval policy attached to a callable, if present.

```python theme={null}
approval_policy(value: Any) -> ApprovalPolicy | None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `value` | `Any` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import approval_policy
>
> policy = approval_policy(value=...)
> ```

## authorize\_mcp

Authorize one MCP tool call when the client policy selects it.

```python theme={null}
async authorize_mcp(
    client_name: str,
    tool_name: str,
    arguments: Mapping[str, Any],
    policy: ApprovalPolicy,
) -> PendingApproval | None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `client_name` | `str` | Required |
> | `tool_name` | `str` | Required |
> | `arguments` | `Mapping[str, Any]` | Required |
> | `policy` | `ApprovalPolicy` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import authorize_mcp
>
> approval = await authorize_mcp(
>     client_name=...,
>     tool_name=...,
>     arguments=...,
>     policy=...,
> )
> ```

## bind\_tool\_arguments

Bind a tool call to canonical approval-safe argument values.

```python theme={null}
bind_tool_arguments(function: Callable[..., Any], args: tuple[Any, ...], kwargs: Mapping[str, Any]) -> dict[str, Any]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `Callable[..., Any]` | Required |
> | `args` | `tuple[Any, ...]` | Required |
> | `kwargs` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import bind_tool_arguments
>
> result = bind_tool_arguments(function=..., args=..., kwargs=...)
> ```

## record\_approved\_execution

Record successful completion for an optional one-time approval grant.

```python theme={null}
record_approved_execution(grant: PendingApproval | None) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `grant` | `PendingApproval \| None` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import record_approved_execution
>
> record_approved_execution(grant=...)
> ```

## record\_approved\_failure

Record failed execution for an optional one-time approval grant.

```python theme={null}
record_approved_failure(grant: PendingApproval | None) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `grant` | `PendingApproval \| None` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import record_approved_failure
>
> record_approved_failure(grant=...)
> ```

## request\_human\_approval

Protect only the dynamic operation inside this asynchronous block.

Callers may evaluate policy or risk before entering the block. The approval
is bound to a stable action name and canonical arguments, while the block
boundary lets Harnest audit whether the approved operation completed.

```python theme={null}
request_human_approval(
    *,
    action: str,
    message: str,
    arguments: Mapping[str, Any] | None = None,
    timeout_seconds: int = 900,
    on_timeout: Literal['deny'] = 'deny',
) -> AsyncIterator[None]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `action` | `str` | Required |
> | `message` | `str` | Required |
> | `arguments` | `Mapping[str, Any] \| None` | `None` |
> | `timeout_seconds` | `int` | `900` |
> | `on_timeout` | `Literal['deny']` | `'deny'` |
>
> ```python theme={null}
> from harnest.agent.approval import request_human_approval
>
> async with request_human_approval(action=..., message=...):
>     ...
> ```

## require\_human\_approval

Declare that a tool or MCP `client()` factory requires approval.

```python theme={null}
require_human_approval(
    *,
    message: str,
    timeout_seconds: int = 900,
    on_timeout: Literal['deny'] = 'deny',
    tools: Sequence[str] | None = None,
) -> Callable[[F], F]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `message` | `str` | Required |
> | `timeout_seconds` | `int` | `900` |
> | `on_timeout` | `Literal['deny']` | `'deny'` |
> | `tools` | `Sequence[str] \| None` | `None` |
>
> ```python theme={null}
> from harnest.agent.approval import require_human_approval
>
> @require_human_approval(message=...)
> def my_function():
>     ...
> ```

## wrap\_approved\_tool

Install an execution gate after both decorator orders are known.

```python theme={null}
wrap_approved_tool(function: F) -> F
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `F` | Required |
>
> ```python theme={null}
> from harnest.agent.approval import wrap_approved_tool
>
> result = wrap_approved_tool(function=...)
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.