# How OpenMontage Ensures Tools Write Outputs to the Correct Project Workspace Paths

> Discover how OpenMontage guarantees tools write outputs to correct workspace paths. Learn about mandatory workspace_path validation for organized project directories and artifact management.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: how-to-guide
- Published: 2026-08-29

---

**OpenMontage enforces a mandatory `workspace_path` property in every tool's input schema and validates it through the centralized `_require_workspace` helper, which resolves absolute paths and raises `ValueError` on missing inputs to guarantee all artifacts are written to the designated project directory.**

The `calesthio/OpenMontage` repository implements a strict workspace contract to ensure reproducible builds and prevent artifacts from leaking outside project boundaries. By treating the workspace directory as the single source of truth for all tool-generated outputs, OpenMontage eliminates path ambiguity through schema validation, canonical path resolution, and runtime safety checks.

## Mandatory Workspace Declaration in Tool Schemas

Every tool in OpenMontage declares its workspace dependency explicitly through a **declarative input schema**. This contract forces the orchestrating pipeline to supply a concrete directory before any operation begins.

In [`tools/video/hyperframes_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/video/hyperframes_compose.py), the tool defines `workspace_path` as a required property in its input schema (lines 45-52). This schema-level requirement ensures that the pipeline cannot invoke the tool without explicitly specifying where outputs should be written. The validation occurs before execution, preventing any ambiguity about target locations for HTML, CSS, assets, or rendered video files.

## Canonical Path Resolution via `_require_workspace`

Once the pipeline supplies the `workspace_path` string, OpenMontage centralizes all path handling through the private helper `_require_workspace`. This method serves as the **single source of truth** for workspace directory resolution across all internal operations.

Located at lines 988-992 in [`hyperframes_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/hyperframes_compose.py), the helper extracts the raw input, validates its presence, and immediately resolves it to an absolute `Path` object:

```python
def _require_workspace(inputs: dict[str, Any]) -> Path:
    raw = inputs.get("workspace_path")
    if not raw:
        raise ValueError("workspace_path is required for this operation")
    return Path(raw).resolve()  # ← canonical absolute path

```

If the property is missing, the helper raises a clear `ValueError`, aborting the tool early. By using `.resolve()`, the method guarantees a canonical absolute path that lives inside the project tree, eliminating relative path traversal issues before any file operations occur.

## Enforcing Workspace Boundaries at Runtime

All internal file operations invoke `_require_workspace` to obtain the validated directory before reading or writing. For example, in the `_scaffold` method (line 339), the tool retrieves the workspace and immediately creates the target structure:

```python
def _scaffold(self, inputs: dict[str, Any]) -> ToolResult:
    workspace = self._require_workspace(inputs)   # ← same path everywhere

    workspace.mkdir(parents=True, exist_ok=True)  # create the target dir

    (workspace / "assets").mkdir(exist_ok=True)   # copy assets inside it

    (workspace / "index.html").write_text(html)   # write the HTML output

```

To prevent accidental escapes from the project boundary, OpenMontage implements the `_is_inside` helper (lines 1010-1014). This safety net verifies that any staged assets remain within the workspace directory:

```python
def _is_inside(path: Path, root: Path) -> bool:
    try:
        path.resolve().relative_to(root.resolve())
        return True
    except ValueError:
        return False

```

The runtime calls this check before copying files, ensuring that symbolic links or malicious relative paths cannot redirect outputs outside the designated project workspace.

## Explicit Side-Effect Documentation

Beyond runtime enforcement, OpenMontage requires tools to declare their intended side effects explicitly. The `side_effects` attribute (lines 229-232 in [`hyperframes_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/hyperframes_compose.py)) documents exactly which files will be written to the workspace_path, including copied assets and generated MP4 files.

This declaration enables the runtime to audit operations before execution and supports provenance tracking, giving downstream tooling visibility into exactly which paths will be modified during the tool's lifecycle.

## Implementation Across the Codebase

While [`tools/video/hyperframes_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/video/hyperframes_compose.py) implements the primary workspace contract, the pattern propagates through related modules:

- **[`tools/video/video_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/video/video_compose.py)**: Calls `hyperframes_compose` and forwards the same `workspace_path`, demonstrating end-to-end propagation of the workspace contract.
- **[`lib/paths.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/paths.py)** (if present): Centralizes path utilities used across the codebase for project-relative directory handling.

## Summary

- **Schema Enforcement**: Tools declare `workspace_path` as required in their input schemas, preventing invocation without a designated output directory.
- **Centralized Validation**: The `_require_workspace` helper is the sole authority for converting input strings to absolute `Path` objects, raising `ValueError` immediately if the path is missing.
- **Canonical Resolution**: All paths are resolved using `.resolve()` to eliminate relative traversal and ensure project-tree containment.
- **Boundary Safety**: The `_is_inside` helper verifies that all copied assets remain within the workspace directory, preventing path escape vulnerabilities.
- **Observable Contracts**: The `side_effects` attribute explicitly lists all files written to the workspace, enabling runtime auditing and provenance tracking.

## Frequently Asked Questions

### What happens if a tool receives inputs without a workspace_path?

OpenMontage aborts execution immediately. The `_require_workspace` helper checks for the presence of `workspace_path` in the input dictionary and raises a `ValueError` with the message *"workspace_path is required for this operation"* before any file operations occur (lines 988-992 in [`hyperframes_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/hyperframes_compose.py)).

### How does OpenMontage prevent tools from writing files outside the project workspace?

The framework uses a combination of **canonical path resolution** and **boundary checking**. First, `_require_workspace` resolves the path to an absolute canonical form using `Path.resolve()`. Second, when staging assets, the `_is_inside` helper verifies that the resolved path is actually contained within the workspace directory by attempting a `relative_to` operation (lines 1010-1014).

### Why does OpenMontage require absolute resolved paths instead of relative paths?

Absolute resolved paths eliminate ambiguity from symbolic links, parent directory references (`..`), and varying working directories. By calling `.resolve()` in `_require_workspace`, OpenMontage guarantees that all downstream operations reference the same canonical location on the filesystem, preventing race conditions and path traversal vulnerabilities during complex build pipelines.

### Where is the workspace contract formally defined for external tool consumers?

The contract is defined in the tool's JSON input schema within the Python source (lines 45-52 of [`hyperframes_compose.py`](https://github.com/calesthio/OpenMontage/blob/main/hyperframes_compose.py)), which specifies `workspace_path` as a required string property. Additionally, formal schema files such as [`schemas/tools/hyperframes_workspace.schema.json`](https://github.com/calesthio/OpenMontage/blob/main/schemas/tools/hyperframes_workspace.schema.json) (if present) provide external validation contracts for pipeline orchestrators integrating with OpenMontage tools.