Sandbox and Skills¶
tether.sandbox¶
Deterministic security sandbox for Tether (workspace jail, env scrubbing, Linux bwrap).
SandboxViolationError
¶
Bases: PermissionError
Raised when a tool call violates the deterministic SandboxPolicy.
ApprovalNeeded
¶
Bases: SandboxViolationError
The command needs to run outside the jail; only the session's caller can approve it.
SandboxUnavailableError
¶
Bases: RuntimeError
A write session needs bwrap and the caller did not opt out.
SandboxPolicy
dataclass
¶
Deterministic security envelope enforced by the harness (never by the LLM).
with_allow_file()
¶
A copy whose allow_outside also holds the project's .tether/allow.json entries.
attenuate(child_profile=None, child_network=None, child_web_allow=None, child_allow_unsandboxed=None, child_allow_outside=None, child_limits=None)
¶
Create a child SandboxPolicy that can only narrow (never escalate) privileges.
isolation_error()
¶
The refusal message when this policy needs bwrap and has no opt-out, else None.
require_isolation()
¶
Refuse before any model call; with the opt-out, print the notice once per process.
mode()
¶
What tether status shows for the session.
resolve_safe_path(raw_path, *, write=False)
¶
Resolve a path and enforce workspace confinement + sensitive-file protection.
scrub_env(base_env=None)
¶
Return a sanitized environment: allowlist only, so unknown secrets never leak.
validate_bash_command(cmd, *, text_rules=False)
¶
Deterministically validate a shell command against sandbox rules.
execute_bash_with_code(cmd, stdin=None)
async
¶
Execute a shell command in the deterministic sandbox and return (returncode, output).
execute_bash(cmd, stdin=None)
async
¶
Execute a shell command inside the deterministic sandbox.
approval_prefix(head)
¶
The prefix an approval grants: the first two words for git, the first word otherwise.
parse_limits(raw)
¶
Normalise resource limits from CLI K=V strings or a mapping; empty means no limits.
parse_web_allow(raw)
¶
Normalise a web_allow domain list; None means unset, () means deny every host.
parse_allow_outside(raw)
¶
Normalise allow_outside prefixes: single-spaced tokens, no duplicates, order kept.
load_allow_file(root)
¶
Entries of <root>/.tether/allow.json; a missing file allows nothing.
add_to_allow_file(root, prefix)
¶
Append prefix to <root>/.tether/allow.json, keeping existing entries and their order.
A malformed file stays a loud ValueError and is left untouched. The write goes through a
temp file and os.replace, so a concurrent reader never sees half a file.
tether.skills¶
Progressive Skill discovery, YAML frontmatter parser, and companion tools.py loader.
SkillLoader
¶
Discovers and loads skills from ./skills/ and ~/.tether/skills/.
parse_skill_markdown(raw_text, default_name, source_path=None)
¶
Parse a Markdown file with optional YAML frontmatter into a Skill object.
make_skill_tool(loader, mux)
¶
Create the progressive skill tool (skill list | load <name>).
tether.retro¶
Offline post-mortem (tether retro): distill session friction into tiny Skill rules.
parse_rules(text, existing='')
¶
Keep <=MAX_RULES bullets within the token cap, dropping ones already in existing.