No env var inference in strict mode.

cli/internal/graph/graph.go

@@ -83,7 +83,7 @@ func (g *CompleteGraph) GetPackageTaskVisitor(
 		useOldTaskHashable := false
 		if taskEnvMode == util.Infer {
 			if taskDefinition.PassthroughEnv != nil {
-				taskEnvMode = util.Strict
+				taskEnvMode = util.StrictIncludeFrameworkVars
 			} else {
 				// If we're in infer mode we have just detected non-usage of strict env vars.
 				// Since we haven't stabilized this we don't want to break their cache.

cli/internal/run/global_hash.go

@@ -90,7 +90,7 @@ func calculateGlobalHashFromHashableInputs(full GlobalHashableInputs) (string, e
 			// In infer mode, if there is any passThru config (even if it is an empty array)
 			// we'll hash the whole object, so we can detect changes to that config
 			// Further, resolve the envMode to the concrete value.
-			full.envMode = util.Strict
+			full.envMode = util.StrictIncludeFrameworkVars
 			return newGlobalHash(full)
 		}
 
@@ -102,6 +102,8 @@ func calculateGlobalHashFromHashableInputs(full GlobalHashableInputs) (string, e
 		// Remove the passthroughs from hash consideration if we're explicitly loose.
 		full.envVarPassthroughs = nil
 		return newGlobalHash(full)
+	case util.StrictIncludeFrameworkVars:
+		fallthrough
 	case util.Strict:
 		// Collapse `nil` and `[]` in strict mode.
 		if full.envVarPassthroughs == nil {

cli/internal/run/real_run.go

@@ -293,7 +293,7 @@ func (ec *execContext) exec(ctx gocontext.Context, packageTask *nodes.PackageTas
 	currentState := env.GetEnvMap()
 	passthroughEnv := env.EnvironmentVariableMap{}
 
-	if packageTask.EnvMode == util.Strict {
+	if packageTask.EnvMode.IsStrict() {
 		defaultPassthrough := []string{
 			"PATH",
 			"SHELL",

cli/internal/run/run.go

@@ -356,7 +356,7 @@ func (r *run) run(ctx gocontext.Context, targets []string) error {
 
 	globalEnvMode := rs.Opts.runOpts.EnvMode
 	if globalEnvMode == util.Infer && turboJSON.GlobalPassthroughEnv != nil {
-		globalEnvMode = util.Strict
+		globalEnvMode = util.StrictIncludeFrameworkVars
 	}
 
 	// RunSummary contains information that is statically analyzable about

cli/internal/taskhash/taskhash.go

@@ -325,6 +325,8 @@ func calculateTaskHashFromHashable(full *taskHashable, useOldTaskHashable bool)
 		// Remove the passthroughs from hash consideration if we're explicitly loose.
 		full.passthroughEnv = nil
 		return fs.HashObject(full)
+	case util.StrictIncludeFrameworkVars:
+		fallthrough
 	case util.Strict:
 		// Collapse `nil` and `[]` in strict mode.
 		if full.passthroughEnv == nil {
@@ -379,17 +381,30 @@ func (th *Tracker) CalculateTaskHash(packageTask *nodes.PackageTask, dependencyS
 	}
 
 	var keyMatchers []string
-	framework := inference.InferFramework(packageTask.Pkg)
-	if framework != nil && framework.EnvMatcher != "" {
-		// log auto detected framework and env prefix
-		logger.Debug(fmt.Sprintf("auto detected framework for %s", packageTask.PackageName), "framework", framework.Slug, "env_prefix", framework.EnvMatcher)
-		keyMatchers = append(keyMatchers, framework.EnvMatcher)
+	var framework *inference.Framework
+	envVarContainingExcludePrefix := ""
+
+	// In Strict environment variable mode we don't do framework env var inference.
+	// You must instead:
+	// - Specify all environment variables that you want available in your build environment.
+	// - Specify whether you want those considered for the hash or merely passed through.
+	//
+	// This allows advanced users to improve both cache hit ratio _and_ correctness with
+	// the tradeoff of increased configuration verbosity.
+	if packageTask.EnvMode != util.Strict {
+		envVarContainingExcludePrefix = "TURBO_CI_VENDOR_ENV_KEY"
+		framework := inference.InferFramework(packageTask.Pkg)
+		if framework != nil && framework.EnvMatcher != "" {
+			// log auto detected framework and env prefix
+			logger.Debug(fmt.Sprintf("auto detected framework for %s", packageTask.PackageName), "framework", framework.Slug, "env_prefix", framework.EnvMatcher)
+			keyMatchers = append(keyMatchers, framework.EnvMatcher)
+		}
 	}
 
 	envVars, err := env.GetHashableEnvVars(
 		packageTask.TaskDefinition.EnvVarDependencies,
 		keyMatchers,
-		"TURBO_CI_VENDOR_ENV_KEY",
+		envVarContainingExcludePrefix,
 	)
 	if err != nil {
 		return "", err

cli/internal/util/run_opts.go

@@ -10,13 +10,24 @@ const (
 	Infer EnvMode = "Infer"
 	// Loose - environment variables are unconstrained
 	Loose EnvMode = "Loose"
+	// StrictIncludeFrameworkVars - environment variables are limited.
+	// They include vars from detected frameworks.
+	StrictIncludeFrameworkVars EnvMode = "StrictIncludeFrameworkVars"
 	// Strict - environment variables are limited
 	Strict EnvMode = "Strict"
 )
 
 // MarshalText implements TextMarshaler for the struct.
-func (s EnvMode) MarshalText() (text []byte, err error) {
-	return []byte(strings.ToLower(string(s))), nil
+func (em EnvMode) MarshalText() (text []byte, err error) {
+	if em == StrictIncludeFrameworkVars {
+		return []byte("strict-include-framework-vars"), nil
+	}
+	return []byte(strings.ToLower(string(em))), nil
+}
+
+// IsStrict collapses the two Strict variants.
+func (em EnvMode) IsStrict() bool {
+	return em == Strict || em == StrictIncludeFrameworkVars
 }
 
 // RunOpts holds the options that control the execution of a turbo run

crates/turborepo-lib/src/cli.rs

@@ -56,6 +56,7 @@ pub enum DryRunMode {
 pub enum EnvMode {
     Infer,
     Loose,
+    StrictIncludeFrameworkVars,
     Strict,
 }
 
@@ -728,6 +729,26 @@ mod test {
             "env_mode: specified strict"
         );
 
+        assert_eq!(
+            Args::try_parse_from([
+                "turbo",
+                "run",
+                "build",
+                "--experimental-env-mode",
+                "strict-include-framework-vars"
+            ])
+            .unwrap(),
+            Args {
+                command: Some(Command::Run(Box::new(RunArgs {
+                    tasks: vec!["build".to_string()],
+                    env_mode: EnvMode::StrictIncludeFrameworkVars,
+                    ..get_default_run_args()
+                }))),
+                ..Args::default()
+            },
+            "env_mode: specified strict-include-framework-vars"
+        );
+
         assert_eq!(
             Args::try_parse_from(["turbo", "run", "build", "lint", "test"]).unwrap(),
             Args {

docs/pages/repo/docs/core-concepts/caching.mdx

@@ -261,6 +261,10 @@ To alter the cache for _all_ tasks, you can declare environment variables in the
 
 ### Automatic environment variable inclusion
 
+<Callout type="info">
+  Turborepo does automatic environment variable inclusion unless you pass `--env-mode=strict` in order to disable this behavior. In `strict` environment variable mode you must specify every environment variable you want available in your execution environment via `env` or `globalEnv` if you want them considered for the hash and `experimentalPassThroughEnv` or `experimentalGlobalPassThroughEnv` if not.
+</Callout>
+
 To help ensure correct caching across environments, Turborepo automatically infers and includes public environment variables when calculating cache keys for apps built with detected frameworks. You can safely omit framework-specific public environment variables from `turbo.json`:
 
 ```diff filename="turbo.json"

docs/pages/repo/docs/reference/command-line-reference.mdx

@@ -188,20 +188,21 @@ Task details include:
 
 Controls the available environment variables to your tasks.
 
-| option | description                                                |
-| ------ | ---------------------------------------------------------- |
-| infer  | infers strict mode or loose mode based on allowlist config |
-| loose  | allows all environment variables                           |
-| strict | only allow declared variables                              |
+| option                        | description                                                                                              |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
+| infer                         | infers loose or strict-include-framework-vars mode based upon existence of configuration                 |
+| loose                         | allows all environment variables                                                                         |
+| strict-include-framework-vars | allows only environment variables detected from your framework and those specified by your configuration |
+| strict                        | allows only environment variables specified by your configuration                                        |
 
 `PATH`, `SHELL`, and `SYSTEMROOT` are always available to all tasks.
 
 ##### `infer`
 
 In infer mode, Turborepo will look for [`experimentalPassThroughEnv`][1] for
 each task config, and [`experimentalGlobalPassThroughEnv`][2] in the root of the
-`turbo.json` config. If either is defined, "strict" mode is inferred. If
-neither is defined, then `loose` mode is inferred.
+`turbo.json` config. If either is defined, "strict-include-framework-vars" mode
+is inferred. If neither is defined, then `loose` mode is inferred.
 
 In this mode, the value of `experimentalGlobalPassThroughEnv` and the flag's
 value ("infer") will only be incorporated into the global hash if
@@ -210,9 +211,25 @@ value ("infer") will only be incorporated into the global hash if
 ##### `loose`
 
 In loose mode, all environment variables are made available to the task.
-The value of `experimentalGlobalPassThroughEnv` and the flag's value ("loose")
+The flag's value ("loose") itself will be incorporated into the global hash.
+
+##### `strict-include-framework-vars`
+
+In strict-include-framework-vars mode, environment variables specified in the following keys are
+available to the task:
+
+- `env` and `experimentalPassThroughEnv` in each task configuration
+- `globalEnv` and `experimentalGlobalPassThroughEnv` in the root of your config
+
+In addition, values detected by [automatic environment variable inclusion](../caching#automatic-environment-variable-inclusion)
+will also be available to the task.
+
+The value of `experimentalGlobalPassThroughEnv` and the flag's value ("strict-include-framework-vars")
 itself will be incorporated into the global hash.
 
+If strict-include-framework-vars mode is specified or inferred _all_ tasks are run in
+strict-include-framework-vars mode regardless of their configuration.
+
 ##### `strict`
 
 In strict mode, only environment variables specified in the following keys are
@@ -224,7 +241,7 @@ available to the task:
 The value of `experimentalGlobalPassThroughEnv` and the flag's value ("strict")
 itself will be incorporated into the global hash.
 
-If strict mode is specified or inferred, _all_ tasks are run in strict mode,
+If strict mode is specified or inferred _all_ tasks are run in strict mode,
 regardless of their configuration.
 
 #### `--filter`

turborepo-tests/integration/tests/_fixtures/framework_inference/apps/next/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "next-app",
+  "scripts": {
+    "build": "echo \"hello from $NEXT_PUBLIC_HELLO\""
+  },
+  "dependencies": {
+    "next": "latest"
+  }
+}

turborepo-tests/integration/tests/_fixtures/framework_inference/apps/vite/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "vite-app",
+  "scripts": {
+    "build": "echo \"hello from $VITE_HELLO\""
+  },
+  "dependencies": {
+    "vite": "latest"
+  }
+}

turborepo-tests/integration/tests/_fixtures/framework_inference/apps/vue/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "vue-app",
+  "scripts": {
+    "build": "echo \"hello from $VUE_APP_HELLO\""
+  },
+  "dependencies": {
+    "@vue/cli-service": "latest"
+  }
+}