Module permissions 

Permission enforcement shared by the path-touching hostlib builtins.

Two complementary layers live here:

• The per-thread “enabled features” registry plus gated_handler — the coarse “is this session allowed to touch the filesystem at all?” gate (see the module body below).
• enforce_path_scope — the granular “is this specific path inside the session’s workspace roots?” check, delegating to the VM-native sandbox so the hostlib surface and harness.fs.* agree.

harn-hostlib exposes the deterministic tool builtins on every VM that install_default runs against, but pipelines must explicitly opt in to their use by calling the hostlib_enable("tools:deterministic") builtin before any of the tool methods will execute. This keeps the surface sandbox-friendly: a script that doesn’t ask for the tools cannot poke the host filesystem or shell out to git even though the contract is registered.

State is held in a thread-local so that:

• Independent VM runs stay isolated when the embedder executes them on separate threads.
• Cargo test isolation works without extra ceremony.

Embedders can also call enable_for_test / reset from Rust if they need to bypass the builtin (for example, tests that don’t drive a live VM).

Constants

FEATURE_TOOLS_DETERMINISTIC

Feature key for the deterministic-tools surface.

Functions

disable

Mark feature as disabled on the current thread. Returns true if the feature was previously enabled. Mostly useful in tests that want to assert the gate works.

enable

Mark feature as enabled on the current thread. Returns true if the feature was newly enabled, false if it was already on.

enable_for_test

Convenience wrapper for tests: enable the deterministic tools in the current thread without needing to reach for the builtin.

enforce_path_scope

Reject path when it resolves outside the active execution policy’s workspace roots, under a restricted sandbox profile.

gated_handler

Wrap a builtin runner so it executes only when the deterministic-tools feature has been enabled on the current thread, returning a descriptive error otherwise.

is_enabled

Report whether feature is enabled on the current thread.

reset

Bulk-clear every enabled feature on the current thread. Tests use this to start from a known state.