---
title: "Stack Integration Contracts"
---
import RepoFile from '../../../../components/RepoFile.astro'

**Status**: Open — design proposal (Containment track, [Agent Orchestrator Research Program](/reference/roadmap/agent-orchestrator-research/))

## Problem

Jackin roles define the agent environment, but real engineering projects still
have local stack details that are awkward to encode in every role:

- read-only toolchain paths or caches that live on the operator machine
- safe selector environment variables such as `JAVA_HOME`, `GOPATH`, or
  `VIRTUAL_ENV`
- generated directories that should be excluded from future snapshots
- project-specific warnings and command hints

The unsafe version of this feature is "let the repo define whatever mounts and
environment it wants." That would turn project files into policy authority and
undermine jackin's host-protection rules.

The useful version is narrower: integrations are data-only hints that improve
ergonomics without widening the trust boundary.

## Inspiration

Hazmat's session integrations are a good shape. They can add read-only
directories, snapshot excludes, a small safe env passthrough set, warnings, and
command hints. They cannot widen project write scope, bypass credential denies,
change network policy, inject arbitrary runtime flags, or reconfigure the
agent runtime.

That "can help but cannot weaken containment" rule maps well to jackin.

## Proposal

Add stack integration contracts as a complement to role repos, not a
replacement for them.

An integration can propose:

- extra read-only mounts for toolchains or caches
- safe env selectors from a jackin-owned allowlist
- snapshot exclude globs for generated artifacts
- warnings shown in the session contract
- informational command hints for humans and future operator tools

An integration cannot:

- widen trust compared with the resolved workspace/role policy
- add write mounts
- change sandbox backend
- change network policy
- expose credentials or credential-shaped env vars
- convert a denied credential into an env var, file mount, command output, or
  helper socket
- request env names matching credential-shaped patterns such as `*_TOKEN`,
  `*_KEY`, `*_SECRET`, `*_PASSWORD`, `AWS_*`, `GITHUB_*`, `GH_*`, `OPENAI_*`,
  or `ANTHROPIC_*` unless a jackin-owned credential source explicitly grants
  them
- run hooks or shell commands
- override agent runtime configuration
- mutate host files

## Suggested shape

```toml
[integrations.rust]
detect_files = ["Cargo.toml"]
read_only = ["${env.RUSTUP_HOME}", "${env.CARGO_HOME}"]
safe_env = ["RUSTUP_HOME", "CARGO_HOME", "CARGO_TARGET_DIR"]
snapshot_excludes = ["target/"]
warnings = ["Cargo target caches can be large; prefer isolated target dirs for untrusted repos."]
```

Repo recommendations should reference existing integration names only:

```toml
[workspace.integrations]
recommended = ["rust", "node"]
```

The repo should not be able to define custom paths inline. If a repo
recommendation is accepted, store the approval outside the repo keyed by
canonical path plus file hash, so changes prompt again.

## Phases

### Phase 1 — Built-in readonly hints

- Define the integration schema and validation rules.
- Add a small built-in set for common stacks (`rust`, `node`, `python-uv`,
  `go`) with read-only mounts and excludes only.
- Surface active integrations in
  [session contract and explain mode](/reference/roadmap/session-contract-explain-mode/).

### Phase 2 — Repo recommendations with approval

- Let repos recommend existing integration names.
- Prompt the operator once per canonical repo path plus recommendation hash.
- Show recommendation source and diff in the contract before launch.

### Phase 3 — User-authored integration manifests

- Load user manifests from a jackin-owned config directory.
- Reject unknown fields, unsafe env names, paths that resolve into sensitive
  credential zones, and oversized manifests.
- Add validation commands for contribution-friendly PRs.
- Add `jackin integration validate <path>` output that prints accepted fields,
  rejected fields, resolved paths, sensitive-zone hits, safe-env decisions, and
  the exact contract diff a reviewer should inspect.

## Host-side effects

Activating an integration may add read-only container mounts and may store an
operator approval outside the project tree. It must not repair host
permissions, edit shell files, create toolchain directories, or install
packages unless a future design adds an explicit host-action approval flow.

## Related files

- <RepoFile path="src/config/workspaces.rs" /> — workspace configuration
- <RepoFile path="src/config/mounts.rs" /> — mount schema
- <RepoFile path="src/workspace/mounts.rs" /> — mount resolution behavior
- <RepoFile path="src/workspace/sensitive.rs" /> — sensitive path detection

## Source materials

- [Hazmat integrations](https://github.com/dredozubov/hazmat/blob/master/docs/integrations.md) —
  capability limits, repo recommendations, validation, and built-in stack list
- [Session contract and explain mode](/reference/roadmap/session-contract-explain-mode/)
- [Agent Orchestrator Research Program](/reference/roadmap/agent-orchestrator-research/)
