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

# Tools, results and artifacts

> QitOS public API: tools

Legacy host `Read` uses a zero-based offset and a positive line limit: offset 2,
limit 2 selects only lines 3/4. Empty files and EOF return empty output; negative
or non-integer windows fail. Selection metadata reports truncation and more lines.
`Edit` requires a unique match unless `replace_all=True`; no match, ambiguous match,
permission denial and explicit `expected_sha256` conflicts leave the file unchanged.
These two aliases now return canonical `ToolResult` (read numbered text in `.output`,
status/error in their named fields), rather than successful strings containing errors.
Direct callers expecting strings should use `.output` after checking `.status`.
The existing validation/permission pipeline remains authoritative. Host compatibility
remains host execution; Env `read_file`/`edit_file` keep their Env-only operations and
one-based `line_offset` interface. No fallback to host or new isolation guarantee is implied.

Register tools before running. execute(args, runtime\_context) is the class-tool contract; run is compatibility only. Inspect ToolResult status, error\_code, output, artifact\_refs, outcome\_unknown and worker\_still\_running. Successful text alone is insufficient. Parallel execution requires truthful concurrency declarations. Completion and declaration order differ. Publication is opt-in and platform/file-shape limited; cleanup never publishes. SandboxPublicationTool is an advanced, explicitly registered adapter despite its internal module name, not a default tool.

[完整可运行教程 / Complete tutorial](/concepts/tools-and-registry) · [API index](/reference/api)

Signatures and fields below are extracted from the pinned source. Signatures are reference material, not standalone programs. Source links bind the same runtime baseline. Any does not imply arbitrary objects are supported; use the behavioral contract above and the linked tutorial.

<span id="qitos-toolregistry" />

## ToolRegistry

```python theme={null}
from qitos import ToolRegistry
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/tool_registry.py#L20)

[Usage and executable example](/concepts/tools-and-registry)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
registry = ToolRegistry()
registry.register(summarize_note)
```

```text theme={null}
Registry for function tools, bound methods, tool objects, and ToolSets.
```

```text theme={null}
ToolRegistry(*, auto_short_aliases: bool=True) -> Any (see behavior contract)
```

| Parameter            | Type   | Default |
| -------------------- | ------ | ------- |
| `auto_short_aliases` | `bool` | `True`  |

<span id="qitos-toolregistry-register" />

### ToolRegistry.register

```text theme={null}
register(item: Any, name: Optional[str]=None, meta: Optional[ToolMeta]=None) -> 'ToolRegistry'
```

| Parameter | Type                 | Default    |
| --------- | -------------------- | ---------- |
| `item`    | `Any`                | `required` |
| `name`    | `Optional[str]`      | `None`     |
| `meta`    | `Optional[ToolMeta]` | `None`     |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/tool_registry.py#L32)

<span id="qitos-core-function_tool_decorator-function_tool" />

## function\_tool

```python theme={null}
from qitos.core.function_tool_decorator import function_tool
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/function_tool_decorator.py#L11)

[Usage and executable example](/concepts/tools-and-registry)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
@function_tool(read_only=True, concurrency_safe=True)
def title(text: str) -> str:
    return text.split(":", 1)[0]
```

```text theme={null}
Decorator that creates a :class:`FunctionTool` from a plain function.

Can be used with or without parentheses::

    @function_tool
    def greet(name: str) -> str: ...

    @function_tool(name="custom", needs_approval=True)
    def greet(name: str) -> str: ...

Returns a :class:`FunctionTool` instance.
```

```text theme={null}
function_tool(func: Optional[Callable[..., Any]]=None, *, name: Optional[str]=None, description: Optional[str]=None, timeout_s: Optional[float]=None, max_retries: int=0, retry_policy: Optional[RetryPolicy]=None, on_failure: Optional[Callable]=None, read_only: bool=False, concurrency_safe: Optional[bool]=None, needs_approval: bool=False, **extra_meta: Any) -> Any
```

| Parameter          | Type                           | Default |
| ------------------ | ------------------------------ | ------- |
| `func`             | `Optional[Callable[..., Any]]` | `None`  |
| `name`             | `Optional[str]`                | `None`  |
| `description`      | `Optional[str]`                | `None`  |
| `timeout_s`        | `Optional[float]`              | `None`  |
| `max_retries`      | `int`                          | `0`     |
| `retry_policy`     | `Optional[RetryPolicy]`        | `None`  |
| `on_failure`       | `Optional[Callable]`           | `None`  |
| `read_only`        | `bool`                         | `False` |
| `concurrency_safe` | `Optional[bool]`               | `None`  |
| `needs_approval`   | `bool`                         | `False` |

<span id="qitos-core-tool-basetool" />

## BaseTool

```python theme={null}
from qitos.core.tool import BaseTool
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/tool.py#L611)

[Usage and executable example](/concepts/tools-and-registry)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
# Class tools implement execute, not the compatibility run method.
class EchoTool(BaseTool):
    name = "echo"
    description = "Return a trusted input"
    def execute(self, args, runtime_context=None):
        return ToolResult(output=args)
```

```text theme={null}
Base abstraction for callable tools.
```

```text theme={null}
BaseTool(spec: ToolSpec) -> Any (see behavior contract)
```

| Parameter | Type       | Default    |
| --------- | ---------- | ---------- |
| `spec`    | `ToolSpec` | `required` |

<span id="qitos-core-tool-basetool-execute" />

### BaseTool.execute

```text theme={null}
execute(args: Dict[str, Any], runtime_context: Optional[Dict[str, Any]]=None) -> Any
```

| Parameter         | Type                       | Default    |
| ----------------- | -------------------------- | ---------- |
| `args`            | `Dict[str, Any]`           | `required` |
| `runtime_context` | `Optional[Dict[str, Any]]` | `None`     |

```text theme={null}
Execute tool with optional runtime context.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/tool.py#L706)

<span id="qitos-core-tool_result-toolresult" />

## ToolResult

```python theme={null}
from qitos.core.tool_result import ToolResult
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/tool_result.py#L547)

[Usage and executable example](/concepts/tools-and-registry)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
result = ToolResult(output={"title": "Session"})
print(result.status, result.output, result.outcome_unknown)
```

```text theme={null}
Lossless terminal outcome for one declared action/tool slot.
```

| Field                     | Type                      | Default                       |
| ------------------------- | ------------------------- | ----------------------------- |
| `status`                  | `ToolResultStatus`        | `'success'`                   |
| `output`                  | `Any`                     | `None`                        |
| `error`                   | `str \| None`             | `None`                        |
| `metadata`                | `Dict[str, Any]`          | `field(default_factory=dict)` |
| `tool_name`               | `str \| None`             | `None`                        |
| `action_id`               | `str \| None`             | `None`                        |
| `model_output`            | `Any`                     | `None`                        |
| `error_kind`              | `ToolErrorKind \| None`   | `None`                        |
| `error_code`              | `str \| None`             | `None`                        |
| `recoverable`             | `bool`                    | `False`                       |
| `recovery_hint`           | `str \| None`             | `None`                        |
| `next_action`             | `Dict[str, Any] \| None`  | `None`                        |
| `complete`                | `bool`                    | `True`                        |
| `truncated`               | `bool`                    | `False`                       |
| `omitted`                 | `Dict[str, int]`          | `field(default_factory=dict)` |
| `attempts`                | `int`                     | `1`                           |
| `latency_ms`              | `float`                   | `0.0`                         |
| `declared_effects`        | `list[Dict[str, Any]]`    | `field(default_factory=list)` |
| `filesystem_changes`      | `list[Dict[str, Any]]`    | `field(default_factory=list)` |
| `artifact_refs`           | `tuple[ArtifactRef, ...]` | `()`                          |
| `normalized_request`      | `Dict[str, Any]`          | `field(default_factory=dict)` |
| `provenance`              | `Dict[str, Any]`          | `field(default_factory=dict)` |
| `worker_still_running`    | `bool`                    | `False`                       |
| `attempt_id`              | `AttemptIdentity \| None` | `None`                        |
| `effect_ref`              | `str \| None`             | `None`                        |
| `effect_state`            | `EffectState`             | `'no_effect_declared'`        |
| `idempotency_ref`         | `str \| None`             | `None`                        |
| `retry_disposition`       | `RetryDisposition`        | `'not_evaluated'`             |
| `reconciliation_required` | `bool`                    | `False`                       |
| `outcome_unknown`         | `bool`                    | `False`                       |
| `late_result`             | `bool`                    | `False`                       |
| `owner_generation`        | `int \| None`             | `None`                        |
| `stale_owner`             | `bool`                    | `False`                       |
| `batch_closure`           | `Dict[str, Any]`          | `field(default_factory=dict)` |
| `schema_version`          | `str`                     | `TOOL_RESULT_SCHEMA_VERSION`  |

<span id="qitos-core-artifact-artifactref" />

## ArtifactRef

```python theme={null}
from qitos.core.artifact import ArtifactRef
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/artifact.py#L78)

[Usage and executable example](/concepts/tools-and-registry)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
# ref is an ArtifactRef obtained from a tool result.
print(ref.sha256)
body = composition.agent.config["artifact_resolver"].resolve(ref).body
```

```text theme={null}
Portable content-addressed pointer; never an artifact body or host path.
```

| Field               | Type            | Default                       |
| ------------------- | --------------- | ----------------------------- |
| `artifact_id`       | `str`           | `required`                    |
| `resolver_key`      | `str`           | `required`                    |
| `sha256`            | `str`           | `required`                    |
| `media_type`        | `str`           | `required`                    |
| `byte_length`       | `int`           | `required`                    |
| `encoding`          | `str`           | `'binary'`                    |
| `sensitivity`       | `str`           | `'internal'`                  |
| `provenance_digest` | `Optional[str]` | `None`                        |
| `model_summary`     | `Optional[str]` | `None`                        |
| `required`          | `bool`          | `True`                        |
| `schema_version`    | `str`           | `ARTIFACT_REF_SCHEMA_VERSION` |

<span id="qitos-core-artifact-artifactref-from-dict" />

### ArtifactRef.from\_dict

```text theme={null}
from_dict(value: Any) -> 'ArtifactRef'
```

| Parameter | Type  | Default    |
| --------- | ----- | ---------- |
| `value`   | `Any` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/artifact.py#L159)

<span id="qitos-engine-action_executor-actionexecutionpolicy" />

## ActionExecutionPolicy

```python theme={null}
from qitos.engine.action_executor import ActionExecutionPolicy
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/core/action.py#L145)

[Usage and executable example](/concepts/tools-and-registry)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
policy = ActionExecutionPolicy(mode="parallel", max_concurrency=2)
engine = Engine(NotesAgent(), runtime=RuntimeComposition(), action_execution_policy=policy)
```

```text theme={null}
Executor policy for action batches.
```

| Field                 | Type                     | Default    |
| --------------------- | ------------------------ | ---------- |
| `mode`                | `str`                    | `'serial'` |
| `fail_fast`           | `bool`                   | `False`    |
| `max_concurrency`     | `int`                    | `4`        |
| `parallel_tool_names` | `FrozenSet[str] \| None` | `None`     |

<span id="qitos-kit-tool-internal-publication-sandboxpublicationtool" />

## SandboxPublicationTool

```python theme={null}
from qitos.kit.tool.internal.publication import SandboxPublicationTool
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/kit/tool/internal/publication.py#L15)

[Usage and executable example](/concepts/tools-and-registry)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
# Only after sandbox execution, with explicit publication authority:
publication = SandboxPublicationTool(
    composition.env, paths=["report.txt"],
    expected_input_digest=composition.env.input_digest,
)
composition.tool_registry.register(publication)
```

```text theme={null}
Opt-in tool restricted to paths and input digest approved by its caller.
```

```text theme={null}
SandboxPublicationTool(env: Any, *, paths: Iterable[str], expected_input_digest: str) -> Any (see behavior contract)
```

| Parameter               | Type            | Default    |
| ----------------------- | --------------- | ---------- |
| `env`                   | `Any`           | `required` |
| `paths`                 | `Iterable[str]` | `required` |
| `expected_input_digest` | `str`           | `required` |

<span id="qitos-kit-tool-internal-publication-sandboxpublicationtool-execute" />

### SandboxPublicationTool.execute

```text theme={null}
execute(args: Any, runtime_context: Any=None) -> ToolResult
```

| Parameter         | Type  | Default    |
| ----------------- | ----- | ---------- |
| `args`            | `Any` | `required` |
| `runtime_context` | `Any` | `None`     |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/kit/tool/internal/publication.py#L33)