@redue/cli 0.1.0-alpha.25 → 0.1.0-alpha.26

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.1.0-alpha.26 — 2026-10-31
+
+Typecheck and lint checks run inside an OS sandbox, so REDUE can reuse them
+for native tools and for Python. Python projects are supported for the first
+time.
+
+- **Sandboxed recipe.** On macOS (Seatbelt) and Linux 6.7+ (Landlock), a
+  root typecheck or lint script runs in a sandbox that sees only the
+  project, its installed packages and the toolchain, the way CI does. Its
+  inputs are the whole checkout, git-ignored files included, plus the
+  installed packages and a fingerprint of the environment it was given. A
+  result holds for a run that sees only those. `init` tries the precise
+  TypeScript recipes first, then the sandbox, then the general recipe. See
+  [sandboxed recipe](docs/user/sandbox.md).
+- **Python.** `redue setup claude` and `init` find mypy, pyright, ty and
+  ruff in the project's `.venv`, from its CI workflows, Makefile, justfile,
+  tox, nox and scripts. The Claude Code hook recognizes `uv run`,
+  `poetry run`, `python -m` and `.venv/bin` forms.
+- **What the sandbox changes.** Network is off. HOME and the temp folder
+  are private to the check; HOME is kept between runs so caches persist.
+  Tools can read `.git`, but git commands find no repository. A background
+  process the check leaves running is stopped when the run ends.
+- **Checked at init.** `init` runs each check plainly and sandboxed, and
+  proposes the sandbox only when exit status and output (timings and paths
+  aside) match. Otherwise the general recipe applies. A failing run whose
+  output looks like a sandbox refusal is rerun plainly; if the plain run
+  exits differently, the result is UNVERIFIED. Other failures run once.
+- **Coverage.** In a census of 120 public TypeScript repositories (86
+  installed on macOS), 35 have a qualifying check (alpha.24 census: 30):
+  typecheck 22, lint 25, tests 2. Of 120 Python repositories, 23 of the 75
+  that installed on Linux have one (typecheck 15, lint 22); 20 of 64 on
+  macOS. On Linux, every sandboxed run was traced with strace: each file
+  it read in the checkout was a recorded input, a cache or its own output.
+- **Measured with Claude Code.** On starlette, graphon and
+  claude-agent-sdk-python, sessions took 58 s with REDUE and 125 s without.
+  REDUE skipped 10 typechecks and every one matched a plain rerun.
+- Known limits: inside Claude Code's own macOS sandbox and on Windows, the
+  sandbox can't start and the general recipe applies. On Linux before 6.7,
+  sandboxed runs are UNVERIFIED.
+  A build or test run that writes into the checkout (`dist/`, `.next/`,
+  coverage files) makes a sandboxed check STALE, as it does a
+  general-recipe check: about 1 in 4 TypeScript and 2 in 3 Python checks
+  stayed CURRENT through the project's build and tests.
+
 ## 0.1.0-alpha.25 — 2026-10-29
 
 Running your tests no longer makes a typecheck STALE, and `status --sync`

package/README.md

@@ -10,9 +10,11 @@ check that still holds is not run again and one that is stale is.
 
 ## Quickstart (about 5 minutes)
 
-You need macOS or Linux, Node 22 or 24, Git, Claude Code, and a JavaScript or
-TypeScript project with its dependencies installed (`npm install`,
-`pnpm install` or `yarn`). On Linux, also Python 3.
+You need macOS or Linux, Node 22 or 24, Git, Claude Code, and either a
+JavaScript or TypeScript project with its dependencies installed
+(`npm install`, `pnpm install` or `yarn`), or a Python project with a `.venv`
+in its root (`uv sync`, or Poetry with in-project virtualenvs). On Linux, also
+Python 3.
 
 ```sh
 npm install --global @redue/cli@alpha
@@ -62,21 +64,27 @@ To undo everything setup did: `redue remove`.
 ## What it covers today
 
 In a census of 120 active public TypeScript repositories (October 2026, REDUE
-at commit 0fcd19b, after 0.1.0-alpha.23), each installed as its users would,
-with dependencies' install scripts on, 86 installed cleanly. A check counts
-when two recorded runs on the same code both came out CURRENT on the same
-inputs. 30 repositories had at least one such check:
+at commit 046cd0e, before 0.1.0-alpha.26), each installed as its users would,
+with dependencies' install scripts on, 86 installed cleanly on a macOS runner.
+A check counts when two recorded runs on the same code both came out CURRENT
+on the same inputs. 35 repositories had at least one such check:
 
 | Check | Repositories | How |
 |---|---|---|
-| Typecheck | 21 | 15 by running the project's script with every Node process recorded ([general recipe](docs/user/node-script.md)); 6 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)) |
-| Lint | 18 | general recipe |
+| Typecheck | 22 | 15 by running the project's script in an OS sandbox ([sandboxed recipe](docs/user/sandbox.md)); 5 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)); 2 by running the script with every Node process recorded ([general recipe](docs/user/node-script.md)) |
+| Lint | 25 | 21 sandboxed recipe, 4 general recipe |
 | Tests | 2 | Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
 
+In a census of 120 Python repositories, 75 installed on a Linux runner
+and 23 had a qualifying check: typecheck (mypy, pyright, ty) 15, lint (ruff)
+22, all through the sandboxed recipe. On Linux, every sandboxed run was traced
+with strace: each file it read in the checkout was a recorded input, a cache
+or its own output.
+
 Everything else stays UNVERIFIED, with a reason you can read in
 `redue explain`. The usual ones: a script starts a program REDUE cannot see
-into (esbuild, turbo, nx, oxlint's tsgolint, TypeScript 7's native compiler),
-the project uses Bun, or a test suite writes into its own inputs.
+into and the sandbox can't run (inside Claude Code's macOS sandbox, on
+Windows), the project uses Bun, or a check writes into its own inputs.
 [Supported projects](docs/user/supported-projects.md) has the details.
 
 ## Measured with Claude Code

package/bin/redue.mjs

@@ -7,6 +7,7 @@ import {directCompiler,directQualification,directEnvironment,directInstalledInpu
 import {runArgv,tscRun} from '../src/typescript-invocation.mjs';
 import {testEnvironment,testRunnerAt,testsInterpretation,testsQualification} from '../src/test-direct.mjs';
 import {scriptEnvironment,scriptInterpretation,scriptKinds,scriptQualification} from '../src/node-script.mjs';
+import {pythonTool,sandboxEnvironment,sandboxInterpretation,sandboxKinds,sandboxQualification} from '../src/sandbox.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
@@ -31,7 +32,7 @@ Commands:
   setup claude [--yes] Set up REDUE and Claude Code in this project in one step:
                        init, agent setup claude, start, one recorded run per check
   remove [--yes]       Undo setup: integration, observer state, and the config setup created
-  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script]
+  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script|sandbox]
                        Discover existing scripts; optionally select one workspace/check
   agent setup codex|claude [--dry-run|--apply] [--json]
   agent doctor [codex|claude] [--json]
@@ -119,9 +120,28 @@ if(short&&(command!=='status'||json||sync))error('--short is a cached status opt
 if(dryRun&&command!=='init')error('--dry-run is for init');
 
 if(command==='init'){
-  const {discoverNodeProject}=await import('../src/node-onboarding.mjs');
-  let discovery;try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
-  catch(e){error(e.message);}
+  const {discoverNodeProject,sourceLinkIssue}=await import('../src/node-onboarding.mjs');
+  const {discoverPythonProject}=await import('../src/python-onboarding.mjs');
+  const {sandboxTrial}=await import('../src/sandbox.mjs');
+  // A Node project, a Python project, or both in one checkout.
+  const python=!recipeSelection||recipeSelection==='sandbox'?discoverPythonProject(process.cwd()):null;
+  let discovery;
+  if(fs.existsSync('package.json')||!python)try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
+    catch(e){error(e.message);}
+  else{const root=realObservedPath(process.cwd());
+    const git=spawnSync('git',['rev-parse','--show-toplevel'],{cwd:root,encoding:'utf8',timeout:3000,stdio:['ignore','pipe','ignore']});
+    discovery={schema:1,root,manager:{name:null,version:null,layout:null},observationIssue:git.status===0?sourceLinkIssue(root):
+      'Git checkout is unavailable; filesystem observation needs a checkout',workspaces:false,node:process.version,
+      checks:[],ambiguous:[],skipped:[],config:{schema:1,checks:[]}};}
+  if(python){
+    // A Python check takes its tool's name where the name is taken.
+    const taken=new Set(discovery.checks.map(row=>row.config.name));
+    for(const row of python.checks){if(taken.has(row.config.name))row.config.name=`${row.config.kind}:${row.config.command[0].split('/').at(-1)}`;
+      taken.add(row.config.name);}
+    if(!discovery.observationIssue)discovery.checks.push(...python.checks);
+    discovery.skipped.push(...python.skipped);
+    discovery.python=true;
+  }
   if(workspaceSelection||checkSelection){
     const chosen=discovery.checks.filter(row=>
       (!workspaceSelection||row.config.workspace===workspaceSelection||
@@ -130,6 +150,26 @@ if(command==='init'){
     if(!chosen.length)error('no discovered check matches the selected workspace and kind');
     discovery.checks=chosen;discovery.config.checks=chosen.map(row=>row.config);
   }
+  // A sandboxed check is proposed only when it gives the same exit status
+  // inside the sandbox as outside it. Otherwise init writes what it would
+  // have without the sandboxed recipe, with the reason.
+  let trials=0;
+  for(const [at,row] of [...discovery.checks.entries()]){
+    if(row.qualification!==sandboxQualification||row.level!=='ready')continue;
+    if(!json)console.error(`Running ${row.config.name} inside and outside the sandbox to confirm it...`);
+    const trial=await sandboxTrial(discovery.root,row.config);
+    if(!trial.issue)trials++;
+    const issue=trial.issue?`the sandbox cannot run here (${trial.issue})`:
+      // A failure both ways that shows a refusal cannot be told from a real one.
+      trial.same?null:trial.plain!==trial.sandboxed?`exit ${trial.sandboxed} inside the sandbox, ${trial.plain} outside it${trial.line?` (${trial.line})`:''}`:
+      trial.line?`it fails both ways (exit ${trial.plain}), with a sign of a refusal inside the sandbox (${trial.line})`:
+      `the output differs inside the sandbox: ${JSON.stringify(trial.output.sandboxed)} instead of ${JSON.stringify(trial.output.plain)}`;
+    if(!issue){row.reason+=`; ran both ways at init, exit ${trial.plain}`;continue;}
+    if(row.fallback)discovery.checks[at]={...row.fallback,reason:`Sandboxed recipe unavailable: ${issue}; ${row.fallback.reason}`};
+    else{discovery.checks[at]=null;discovery.skipped.push({kind:row.config.name,reason:`${row.config.name}: sandboxed recipe unavailable: ${issue}`});}
+  }
+  discovery.checks=discovery.checks.filter(Boolean).map(({fallback,...row})=>row);
+  discovery.config.checks=discovery.checks.map(row=>row.config);
   const configured=fs.existsSync(configFile),unsupported=Boolean(discovery.observationIssue||
     discovery.manager.issue&&!['npm','yarn','pnpm'].includes(discovery.manager.name)||
     discovery.manager.name==='yarn'&&!discovery.manager.version);
@@ -144,8 +184,9 @@ if(command==='init'){
       workspace:check.workspace||null,level,reason})),config:configFile,
     written:willWrite,existing:configured,writable:!configured&&!unsupported&&discovery.checks.length>0};
   if(!json) {
-    console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
+    if(summary.package_manager||!discovery.python)console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
       `${summary.version?' '+summary.version:''}; ${summary.installation_layout} installation.`);
+    if(discovery.python)console.log('Python project; tools run from .venv.');
     if(summary.issue)console.log(`Boundary: ${summary.issue}`);
     for(const row of summary.checks){
       console.log(`  ${row.name} (${row.script||row.command?.join(' ')}) — `+
@@ -167,7 +208,7 @@ if(command==='init'){
     if(!samePath(realObservedPath(path.dirname(configFile)),discovery.root))
       error('init writes only at the repository root; use --config there or --dry-run');
     fs.writeFileSync(configFile,JSON.stringify(discovery.config,null,2)+'\n',{flag:'wx'});
-    if(!json){console.log(`Created ${configFile}. No checks were executed.`);
+    if(!json){console.log(`Created ${configFile}. ${trials?'Sandboxed checks ran both ways to confirm them; no results were recorded.':'No checks were executed.'}`);
       console.log('Ready to qualify means the supported contract will be validated; it is not verification evidence.');
       console.log(`Next: review the config, then redue start and redue run ${JSON.stringify(discovery.checks[0].config.name)}.`);
       console.log('Connect your agent: redue agent setup codex (or claude). Preview with --dry-run.');
@@ -269,6 +310,7 @@ const checks=publicConfig.checks.map(check=>{
   const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
   const testsDirect=check.qualification===testsQualification;
   const generalScript=check.qualification===scriptQualification;
+  const sandboxed=check.qualification===sandboxQualification;
   if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect&&!testsDirect)
     error(`${check.name}: choose script or command, not both`);
   const manager=publicConfig.packageManager;
@@ -278,12 +320,16 @@ const checks=publicConfig.checks.map(check=>{
     [`@which:${manager}`,'run',check.script]:null;
   const npmAutomatic=check.qualification==='typescript-noemit-v1';
   const yarnWorkspace=check.qualification==='yarn-workspace-tsc-v1';
-  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect&&!generalScript)
+  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect&&!generalScript&&!sandboxed)
     error(`${check.name}: unknown qualification contract`);
   // The general recipe runs the root package script through the package manager.
   if(generalScript&&(!['npm','pnpm','yarn'].includes(manager)||!check.script||check.command||check.cwd&&check.cwd!=='.'||
     check.workspace||!scriptKinds.includes(check.kind)))
     error(`${check.name}: the general recipe needs a root typecheck, test or lint script, without command or cwd`);
+  // The sandboxed recipe runs a root package script, or a tool from the project's .venv.
+  if(sandboxed&&(check.cwd&&check.cwd!=='.'||check.workspace||!sandboxKinds.includes(check.kind)||
+    (check.script?!['npm','pnpm','yarn'].includes(manager):!pythonTool(check))))
+    error(`${check.name}: the sandboxed recipe needs a root ${sandboxKinds.join(' or ')} script, or a command that runs a tool from .venv/bin, without cwd`);
   if(npmDirect&&(manager!=='npm'||check.cwd&&check.cwd!=='.'||!Array.isArray(check.command)||
     check.command[0]!=='@node'||check.command[1]!=='@typescript-compiler:.'||
     !tscRun({},{script:null,args:check.command.slice(2)}).run?.noEmit))
@@ -324,7 +370,8 @@ const checks=publicConfig.checks.map(check=>{
       check.workspace||'.',...run]]:[];
   const windowsContext=process.platform==='win32'?
     ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
-  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:generalScript?scriptEnvironment(manager):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:generalScript?scriptEnvironment(manager):
+    sandboxed?sandboxEnvironment(Boolean(pythonTool(check)),check.script?manager:null):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
     'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
     pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
@@ -351,6 +398,7 @@ const checks=publicConfig.checks.map(check=>{
     ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
     ...(testsDirect?{qualificationInterpretation:testsInterpretation}:{}),
     ...(generalScript?{qualificationInterpretation:scriptInterpretation}:{}),
+    ...(sandboxed?{qualificationInterpretation:sandboxInterpretation}:{}),
     workspace:check.workspace||null,kind:check.kind||null};
 });
 const runtime={schema:1,provider:'declared-project@1',root,state,checks};

package/docs/README.md

@@ -5,6 +5,7 @@ For users:
 - [Install, initialize, run, and remove](user/getting-started.md)
 - [Fixed-build opt-in development pilot](user/pilot.md)
 - [Supported projects and conservative boundaries](user/supported-projects.md)
+- [Sandboxed recipe: typecheck and lint in any language, Python included](user/sandbox.md)
 - [Configuration](user/configuration.md)
 - [Connect coding agents and apply the decision policy](user/agents.md)
 - [JSON contract](user/json.md)

package/docs/user/node-script.md

@@ -4,10 +4,12 @@ The general recipe records a project's own typecheck or lint script, run
 through its package manager, and reports later whether that result still
 applies to the files you have. It is a lower tier than the strict recipes:
 `redue init` tries the [direct TypeScript recipe](direct-typescript.md), the
-pnpm and Yarn TypeScript recipes and the [direct test recipe](tests-direct.md)
-first, and uses the general recipe for a root typecheck or lint script none of
-them takes. Test scripts use the direct test recipe; `init` does not propose
-the general recipe for them.
+pnpm and Yarn TypeScript recipes, the [direct test recipe](tests-direct.md)
+and, on macOS and Linux, the [sandboxed recipe](sandbox.md) first. It uses
+the general recipe for a root typecheck or lint script none of them takes,
+and where the sandbox cannot run (at init, or at run time inside Claude
+Code's macOS sandbox). Test scripts use the direct test recipe; `init` does
+not propose the general recipe for them.
 
 It supports a project installed by npm, pnpm 9-12 (isolated or hoisted
 `node_modules`) or Yarn with the `node-modules` linker, with one lockfile kind
@@ -121,8 +123,10 @@ recording-only.
 Anything else makes the result UNVERIFIED and names the program: `git`,
 `sleep`, `find`, and native programs from installed packages such as esbuild,
 turbo, tsgo, tsgolint and biome, whose reads, writes and network use REDUE
-cannot see. `init` reads the script the same way and keeps a script that
-starts such a program recording-only, with the program in the reason.
+cannot see. `init` reads the script the same way. A typecheck or lint script
+gets the [sandboxed recipe](sandbox.md) first where it can run, which covers
+such programs; otherwise a script that starts one stays recording-only, with
+the program in the reason.
 
 A command line may use `&&`, `||`, `;`, `|`, quotes without expansions,
 globs in arguments and redirection to `/dev/null`. Variables, command

package/docs/user/sandbox.md

@@ -0,0 +1,169 @@
+# Sandboxed recipe (typecheck and lint, any language)
+
+The sandboxed recipe runs a typecheck or lint command inside an operating
+system sandbox and reports later whether that result still applies to the
+files you have. The sandbox holds for every process the command starts, so it
+covers programs REDUE cannot record: TypeScript 7's native compiler, esbuild,
+oxlint and tsgolint, biome, turbo, and Python tools such as mypy, pyright, ty
+and ruff.
+
+**The claim.** A sandboxed result holds for a run that sees only the project,
+its installed packages and the toolchain, the way CI does. It does not say
+that a run with your own configuration files, a service on your machine or the
+network would give the same result.
+
+## Where it applies
+
+- **Node projects:** a root `typecheck` or `lint` script (npm, pnpm, or Yarn
+  with the `node-modules` linker). `init` tries the
+  [direct TypeScript recipe](direct-typescript.md) and the pnpm and Yarn
+  TypeScript recipes first; they stay first where they apply. Then the
+  sandboxed recipe, before the [general recipe](node-script.md), since it
+  also covers the native programs a script starts. Where init's trial shows a
+  difference, or the sandbox cannot run, `init` writes the general recipe as
+  before. Where the sandbox cannot start at run time (inside Claude Code's
+  macOS sandbox), a script the general recipe takes is recorded as it records
+  it.
+- **Python projects:** mypy, pyright, ty and ruff installed in the project's
+  `.venv` (`uv sync` makes one; Poetry does with `virtualenvs.in-project`).
+  `init` uses the arguments your CI workflow, Makefile, tox, nox, justfile or
+  shell scripts in `scripts/` run the tool with, through `uv run`, `poetry run`,
+  `python -m` or `.venv/bin`. Without them it uses the tool's default:
+  `ruff check`, `ty check`, `pyright`, and `mypy` (with `.` when mypy's
+  configuration names no `files`).
+- **Platforms:** macOS (Seatbelt, `sandbox-exec`) and Linux 6.7 or later
+  (Landlock; the launcher needs Python 3).
+
+```sh
+redue init
+redue start
+redue run typecheck
+redue status --sync
+```
+
+A Python check in the config:
+
+```json
+{"name": "typecheck", "kind": "typecheck", "qualification": "sandbox-v1",
+ "command": [".venv/bin/mypy", "src"], "inputs": ["**", "..."], "installedInputs": [".venv/**", "..."]}
+```
+
+A Node check names its script, as the general recipe's do:
+`{"name": "lint", "script": "lint", "kind": "lint", "qualification": "sandbox-v1", ...}`.
+
+With the Claude Code hook, `uv run mypy src`, `poetry run mypy src`,
+`python -m mypy src`, `.venv/bin/mypy src` and `mypy src` are recognized as
+that check. The last two count only when PATH finds the tool or Python in the
+project's `.venv/bin` first. When the hook runs the check through REDUE, it
+keeps `uv run` or `poetry run` in front, so the environment still syncs first.
+
+## What the run sees
+
+It may read and execute only beneath:
+
+- the checkout;
+- the toolchain: Node's installation and the package managers' (with
+  Corepack's downloads), or the Python installation the `.venv` was made from;
+- system directories (`/usr`, `/bin`, `/etc` and the like on Linux; `/usr`,
+  `/System`, `/Library`, `/opt/homebrew` and the like on macOS);
+- a private home directory and a fresh temporary directory, in REDUE's state.
+
+It has no network: no TCP connection, loopback included. On macOS its only
+Unix sockets are in its own temporary directory, which is new for each run.
+On Linux 6.12 and later it cannot reach an abstract Unix socket outside the
+run.
+
+What the check leaves running is stopped when it exits, as at the end of a
+CI job: its process group gets SIGTERM, and SIGKILL a second later. On Linux
+the launcher also stops daemons that started their own session. On macOS
+such a daemon outlives the run, but no later run can reach it: its socket
+was in a temporary directory that is gone. The run gets no terminal input.
+
+The checkout's `.git` is not an input. Tools still see it, as they do in a CI
+checkout (a linter that applies `.gitignore` only inside a repository does),
+but git commands find no repository: `GIT_DIR` points nowhere. A script that
+runs git (`git diff --exit-code`) gives a different result inside the
+sandbox, and `init` leaves it to the other recipes.
+
+It gets a controlled environment, not yours:
+
+- the variables the check declares (`TZ`, `LANG`, `CI`, `USER`, `LC_*`,
+  `DYLD_*`, `LD_*`, and `NODE_*`, `npm_config_*`, `PNPM_*`, `YARN_*`,
+  `COREPACK_*` for Node, or `PYTHON*`, `MYPY*`, `RUFF_*`, `PYRIGHT*`, `TY_*`
+  for Python), with your values;
+- your PATH, without the project's `.venv/bin`, which a Python check gets
+  first instead, so `uv run` and an activated environment give the same PATH;
+- `HOME`, `TMPDIR` and the XDG directories in its private directories;
+  `VIRTUAL_ENV` for a Python check; Corepack's home where Corepack keeps it.
+
+## What REDUE claims
+
+CURRENT means the last sandboxed run's inputs are unchanged:
+
+- every file in the checkout, git-ignored files and git-ignored links to
+  files in it included, except `.git`, `node_modules` and `.venv` (observed
+  as installed files, by identity) and runner caches: the general recipe's,
+  plus `__pycache__`, `.mypy_cache`, `.ruff_cache` and `.pytest_cache`;
+- the environment the run gets (without display variables such as `TERM`
+  and `COLUMNS`), and the places it may read;
+- Node's and the package managers' executables, or the interpreter the
+  `.venv` was made from, by file identity;
+- every directory on PATH, by identity: installing, removing or upgrading a
+  program in one makes the result STALE;
+- `.git/info/exclude` and `.git/config`, by content: ruff and biome read the
+  ignore rules there.
+
+## Telling a refusal from a real failure
+
+A run the sandbox refused something fails like any other. REDUE does not run
+every failure twice to find out:
+
+- `init` runs each proposed check twice, plainly and sandboxed, and proposes
+  it only when both give the same exit status and the same output, and a
+  failure shows no sign of a refusal. The output is compared without colors,
+  timings, the temporary and home directories, and lines about caches.
+  Otherwise `init` writes what it would have without this recipe and says why.
+  These are the only runs `init` makes.
+- When a sandboxed run fails and its output has a line that looks like a
+  refusal ("Operation not permitted", "Permission denied", "Read-only file
+  system", a name lookup or a connection that failed), REDUE runs the check
+  again outside the sandbox. If that exits differently, the result is the
+  plain run's and UNVERIFIED: "the sandbox changed the result", with the
+  line. A failure without such a line is not run again.
+
+## The private home
+
+The run's home directory is kept between runs, per check, so caches tools
+build there (font caches, a type checker's cache) are not rebuilt every run.
+It starts empty: your configuration files are not in it. What a run leaves
+there can change a later run, and REDUE trusts it like a runner cache. Remove
+it with `redue remove-state`.
+
+## Limits
+
+- Inside Claude Code's own sandbox on macOS, `sandbox-exec` cannot start: the
+  run goes ahead unsandboxed and is UNVERIFIED ("the run was not sandboxed").
+  On Linux, Landlock works inside it.
+- Windows is not supported. The check stays recording-only there.
+- Linux before 6.7 (Landlock ABI below 4) cannot refuse TCP connections, so a
+  run there is UNVERIFIED. UDP is not refused on Linux.
+- System files (time zones, certificates, `/etc`) are not inputs: a change to
+  them does not make a result STALE.
+- A program that reads files in `.git` itself, without git (a commit hash for
+  a version string), reads something REDUE does not observe: a commit does
+  not make the result STALE.
+- Runner caches in the checkout are trusted as the general recipe trusts them.
+- On Linux, a run can still reach a daemon started outside it through a Unix
+  socket file (Landlock does not cover them), and what that daemon reads is
+  not seen. On macOS it cannot.
+- On Linux, uv hard-links `.venv` files to its cache. The cache is
+  toolchain: a file rewritten through the cache, not through the `.venv`, is
+  noticed only when the observer next reads the `.venv` (when it starts).
+- A `.venv` link that leads out of the checkout, other than the interpreter's,
+  keeps the check recording-only and names the link, and so does a `.venv`
+  that uses the system site-packages.
+- A git-ignored link to a directory, or out of the checkout, is not observed,
+  and neither is a `node_modules` directory outside the installed ones (a
+  nested example project's).
+- A script that changes files (`--fix`, `--write`) does not get this recipe:
+  `init` would run it twice.

package/docs/user/supported-projects.md

@@ -18,11 +18,14 @@ build scripts. It prefers familiar script names (for typecheck: `typecheck`,
 (`typecheck:test`, `tsc:build`; not a watch script), then unique recognizable
 `tsc`, Vitest/Jest, ESLint, or Vite commands under other names. Multiple
 matches are reported as ambiguous rather than guessed. It never creates a new
-project script. Without `--recipe`, `init` tries the strict recipes below first,
-then the [general recipe](node-script.md) for a root typecheck or lint
-script: the script run through the package manager with every Node process
-recorded and the whole checkout as its input. `--recipe typescript-direct`,
-`tests-direct` or `node-script` selects one recipe alone. The direct TypeScript recipe supports
+project script. Without `--recipe`, `init` tries the strict recipes below first, then,
+for a root typecheck or lint script, the [sandboxed recipe](sandbox.md) on
+macOS and Linux (the script run inside an OS sandbox, the whole checkout as
+its input), then the [general recipe](node-script.md): the script run
+through the package manager with every Node process recorded and the whole
+checkout as its input. Python projects get the sandboxed recipe for mypy,
+pyright, ty and ruff in their `.venv`. `--recipe typescript-direct`,
+`tests-direct`, `node-script` or `sandbox` selects one recipe alone. The direct TypeScript recipe supports
 a typecheck script of `tsc --noEmit` runs in any argument order, chained runs,
 or no typecheck script at all (a proposed `tsc --noEmit`; see
 [script forms](direct-typescript.md#script-forms)), in a single-package npm installation using

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.25",
+  "version": "0.1.0-alpha.26",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"

package/src/claude-hook.mjs

@@ -22,10 +22,41 @@ const typecheck=check=>check?.kind==='typecheck'||check?.name==='typecheck';
 const tests=check=>check?.qualification==='npm-tests-direct-v1'&&Array.isArray(check.command)&&
   /^@test-runner:(?:vitest|jest)$/.test(check.command[1]||'');
 // A general recipe check: a root typecheck, test or lint script run through the package manager.
-const general=check=>check?.qualification==='node-script-v1'&&['typecheck','test','lint'].includes(check.kind)&&
-  typeof check.script==='string';
-const eligibleCheck=check=>typecheck(check)||tests(check)||general(check);
-export const checkKind=check=>tests(check)?'test':general(check)?check.kind:'typecheck';
+const general=check=>(check?.qualification==='node-script-v1'&&['typecheck','test','lint'].includes(check.kind)||
+  sandboxed(check))&&typeof check.script==='string';
+// A sandboxed check: a root package script, or a tool from the project's .venv.
+const sandboxed=check=>check?.qualification==='sandbox-v1'&&['typecheck','lint'].includes(check.kind);
+const python=check=>sandboxed(check)&&Array.isArray(check.command)&&/^\.venv\/bin\/[A-Za-z0-9_.-]+$/.test(check.command[0]||'')&&
+  check.command.every(word=>typeof word==='string'&&safe.test(word));
+const eligibleCheck=check=>typecheck(check)||tests(check)||general(check)||python(check);
+export const checkKind=check=>tests(check)?'test':general(check)||python(check)?check.kind:'typecheck';
+// The ways an agent runs a Python check's tool: through uv or Poetry, with
+// `python -m`, from .venv/bin, or by name. A form that starts with `python`
+// or the tool's name depends on PATH, so the hook takes it only when PATH
+// finds that program in the project's .venv/bin first (pathForm).
+const wrappers=['uv run ','poetry run '];
+function pythonForms(check){
+  const [file,...args]=check.command,tool=file.split('/').at(-1),rest=args.length?' '+args.join(' '):'';
+  return [`.venv/bin/${tool}${rest}`,`./.venv/bin/${tool}${rest}`,`.venv/bin/python -m ${tool}${rest}`,
+    ...wrappers.flatMap(wrapper=>[`${wrapper}${tool}${rest}`,`${wrapper}python -m ${tool}${rest}`]),
+    `python -m ${tool}${rest}`,`python3 -m ${tool}${rest}`,`${tool}${rest}`];
+}
+// For a form that names a program PATH finds (`mypy .`, `python -m mypy .`),
+// whether PATH finds it first in the project's .venv/bin.
+export function pathForm(form,projectRoot,env=process.env){
+  const word=form.split(' ')[0];
+  if(word.includes('/')||wrappers.some(wrapper=>form.startsWith(wrapper)))return true;
+  if(!projectRoot)return false;
+  for(const dir of String(env.PATH??'').split(path.delimiter)){
+    if(!dir||!path.isAbsolute(dir))continue;
+    try{fs.accessSync(path.join(dir,word),fs.constants.X_OK);}catch{continue;}
+    try{return fs.realpathSync(dir)===fs.realpathSync(path.join(projectRoot,'.venv','bin'));}catch{return false;}
+  }
+  return false;
+}
+// The wrapper a matched form starts with, kept when the hook runs the check
+// through REDUE: `uv run` and `poetry run` sync the environment first.
+const wrapperOf=form=>wrappers.find(wrapper=>form.startsWith(wrapper))||'';
 
 export const defaultConfig='redue.config.json';
 // The `redue` prefix for a config beside the project root; null when the name
@@ -141,7 +172,8 @@ export function hookForms(config,configFile=defaultConfig,packageScripts=null){
     const forms=redue?[`${redue} run ${check.name}`]:[],local=[],dir=checkDir(check),key=groupOf(check),
       group=key?scripts.get(key):null,part=group?.length>1;
     const own=group?null:checkScript(check);
-    if(dir==='.'){
+    if(dir==='.'&&python(check))forms.push(...pythonForms(check));
+    else if(dir==='.'){
       forms.push(...scriptForms(pm,own),...toolForms(pm,toolText(check,packageScripts)));
       if(!tests(check)&&Array.isArray(check.command)&&check.command.length&&
         check.command.every(v=>typeof v==='string'&&safe.test(v)&&!v.startsWith('@')))
@@ -258,11 +290,16 @@ function split(command){
 // {check, rest}, or {fanout, rest} for a turbo/nx/`pnpm -r` command or a root
 // script that runs one; null when nothing matches. `dir` is where the command
 // runs, relative to the project root.
-function matched(command,config,configFile,dir='.',scripts={}){
+function matched(command,config,configFile,dir='.',scripts={},projectRoot=null){
   const parts=split(command);
   if(!parts)return null;
   const row=hookForms(config,configFile,dir==='.'?scripts:null).find(row=>dir==='.'?row.forms.includes(parts.base):
     row.dir===dir&&row.local.includes(parts.base));
+  // A Python check's form that depends on PATH matches only where PATH finds
+  // the project's .venv/bin.
+  const check=row&&config.checks.find(item=>item.name===row.check);
+  if(python(check)&&!parts.base.startsWith('redue'))
+    return pathForm(parts.base,projectRoot)?{check:row.check,rest:parts.rest,wrapper:wrapperOf(parts.base)}:null;
   // A root script that a general check runs is that check, even when the script fans out.
   if(dir==='.'&&row&&general(config.checks.find(check=>check.name===row.check)))return {check:row.check,rest:parts.rest};
   if(dir==='.'){
@@ -331,7 +368,7 @@ export function chainCommand(command,config,configFile,dir='.',scripts={},invoke
   const names=[];let plain=true;
   const text=parts.map(({separator,text})=>{
     const lead=text.match(/^\s*/)[0],trail=text.match(/\s*$/)[0],body=text.trim();
-    const match=matched(body,config,configFile,dir,scripts),split_=split(body);
+    const match=matched(body,config,configFile,dir,scripts,projectRoot),split_=split(body);
     // A compiler script is its checks in the order of its runs.
     const checks=match?.check?[match.check]:match?.row&&projectRoot?scriptChecks(match.row,config,projectRoot):null;
     if(!checks?.length||match.rest!==null||!split_||!checks.every(name=>safe.test(name))){
@@ -339,22 +376,23 @@ export function chainCommand(command,config,configFile,dir='.',scripts={},invoke
     if(!plain)return null;
     names.push(...checks);
     // Grouped, so a separator before it applies to all its runs.
-    const runs=checks.map(name=>`${redue} run ${name} --if-due`).join(' && ');
+    const runs=checks.map(name=>`${match.wrapper||''}${redue} run ${name} --if-due`).join(' && ');
     return `${separator}${lead}${checks.length>1?`{ ${runs}; }`:runs}${split_.suffix}${trail}`;
   });
   return names.length&&!text.includes(null)?{command:text.join(''),names}:null;
 }
-export function matchCheck(command,config,configFile,dir,scripts){
-  const match=matched(command,config,configFile,dir,scripts);
+export function matchCheck(command,config,configFile,dir,scripts,projectRoot=null){
+  const match=matched(command,config,configFile,dir,scripts,projectRoot);
   return match?.row?match.row.checks.join(' && '):match?.check||null;
 }
 // The same check (or checks, in order) through REDUE, keeping the output
 // suffix; null if it already is, or if more commands follow it.
-export function recordedCommand(command,name,configFile=defaultConfig,invoke='redue'){
+// A `uv run` or `poetry run` wrapper stays in front, so the environment syncs first.
+export function recordedCommand(command,name,configFile=defaultConfig,invoke='redue',wrapper=''){
   const names=Array.isArray(name)?name:[name];
   const parts=split(command),redue=redueFor(configFile)?.replace(/^redue/,()=>invoke);
   if(!parts||parts.rest!==null||!names.length||!names.every(value=>safe.test(value))||!redue)return null;
-  const run=names.map(value=>`${redue} run ${value}`).join(' && ');
+  const run=names.map(value=>`${wrapper}${redue} run ${value}`).join(' && ');
   return parts.base===run?null:names.length>1&&parts.suffix?`(${run})${parts.suffix}`:run+parts.suffix;
 }
 
@@ -488,7 +526,7 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
     return cached?.observation?.healthy===true&&chained.names.every(name=>cached.checks?.some(row=>row?.name===name))?
       {hookSpecificOutput:{hookEventName:'PreToolUse',updatedInput:{...input.tool_input,command:entered.prefix+chained.command}}}:null;
   }
-  const match=matched(entered.command,parsed,record.config,entered.dir,scripts);
+  const match=matched(entered.command,parsed,record.config,entered.dir,scripts,project.projectRoot);
   if(!match)return null;
   // A check followed by more than a simple chain runs untouched.
   if(match.rest!==null&&!match.fanout)return null;
@@ -530,7 +568,7 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
   // stays too: the rewrite returns "allow", which would also skip the prompt
   // for the rest of the chain.
   const rewritten=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)&&
-    status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,configPath,invoke??redueInvocation(entry)):null;
+    status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,configPath,invoke??redueInvocation(entry),match.wrapper):null;
   // updatedInput replaces the whole tool input. Deny and ask rules still apply
   // to the rewritten command; "allow" skips only the prompt.
   return rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',