Merge pull request #2 from iamjacobjia/master

fix(agents): isolate repo-local instructions in agent runs

Author: shouc

.gitignore

@@ -10,3 +10,4 @@ test-results/
 .e2e-flaky
 dist/
 *.egg-info/
+.worktrees/

agentflow/agents/claude.py

@@ -7,7 +7,7 @@
 from agentflow.agents.base import AgentAdapter
 from agentflow.env import merge_env_layers
 from agentflow.prepared import ExecutionPaths, PreparedExecution
-from agentflow.specs import NodeSpec, ToolAccess
+from agentflow.specs import NodeSpec, RepoInstructionsMode, ToolAccess
 
 
 _CLAUDE_READ_ONLY_TOOLS = [
@@ -37,6 +37,7 @@ class ClaudeAdapter(AgentAdapter):
     def prepare(self, node: NodeSpec, prompt: str, paths: ExecutionPaths) -> PreparedExecution:
         provider = self.provider_config(node.provider, node.agent)
         executable = node.executable or "claude"
+        repo_instructions_ignored = node.repo_instructions_mode == RepoInstructionsMode.IGNORE
         command = [
             executable,
             "-p",
@@ -47,6 +48,8 @@ def prepare(self, node: NodeSpec, prompt: str, paths: ExecutionPaths) -> Prepare
             "--permission-mode",
             "bypassPermissions",
         ]
+        if repo_instructions_ignored:
+            command.extend(["--bare", "--add-dir", paths.target_workdir])
         if node.model:
             command.extend(["--model", node.model])
         allowed_tools = _CLAUDE_READ_ONLY_TOOLS if node.tools == ToolAccess.READ_ONLY else _CLAUDE_READ_WRITE_TOOLS
@@ -87,10 +90,13 @@ def prepare(self, node: NodeSpec, prompt: str, paths: ExecutionPaths) -> Prepare
                 if api_key is not None:
                     env.setdefault("ANTHROPIC_API_KEY", api_key)
         command.extend(node.extra_args)
+        cwd = paths.target_workdir
+        if repo_instructions_ignored:
+            cwd = str(Path(paths.target_runtime_dir))
         return PreparedExecution(
             command=command,
             env=env,
-            cwd=paths.target_workdir,
+            cwd=cwd,
             trace_kind="claude",
             runtime_files=runtime_files,
         )

agentflow/agents/codex.py

@@ -5,7 +5,7 @@
 from agentflow.agents.base import AgentAdapter
 from agentflow.env import merge_env_layers
 from agentflow.prepared import ExecutionPaths, PreparedExecution
-from agentflow.specs import NodeSpec, ProviderConfig, ToolAccess
+from agentflow.specs import NodeSpec, ProviderConfig, RepoInstructionsMode, ToolAccess
 
 
 class CodexAdapter(AgentAdapter):
@@ -68,6 +68,7 @@ def prepare(self, node: NodeSpec, prompt: str, paths: ExecutionPaths) -> Prepare
         provider = self.provider_config(node.provider, node.agent)
         executable = node.executable or "codex"
         sandbox = "read-only" if node.tools == ToolAccess.READ_ONLY else "workspace-write"
+        repo_instructions_ignored = node.repo_instructions_mode == RepoInstructionsMode.IGNORE
         command = [
             executable,
             "exec",
@@ -84,18 +85,26 @@ def prepare(self, node: NodeSpec, prompt: str, paths: ExecutionPaths) -> Prepare
             command.extend(["--model", node.model])
         if provider:
             command.extend(["--profile", "agentflow"])
+        if repo_instructions_ignored:
+            command.extend(["--disable", "plugins"])
+            command.extend(["--add-dir", paths.target_workdir])
         command.extend(node.extra_args)
         command.append(prompt)
 
         env = merge_env_layers(getattr(provider, "env", None), node.env)
         runtime_files: dict[str, str] = {}
-        if provider or node.mcps:
+        if provider or node.mcps or repo_instructions_ignored:
+            codex_home = str(Path(paths.target_runtime_dir) / "codex_home")
             runtime_files[self.relative_runtime_file("codex_home", "config.toml")] = self._render_config(node, provider)
-            env["CODEX_HOME"] = str(Path(paths.target_runtime_dir) / "codex_home")
+            env["CODEX_HOME"] = codex_home
+            env["HOME"] = codex_home
+        cwd = paths.target_workdir
+        if repo_instructions_ignored:
+            cwd = str(Path(paths.target_runtime_dir))
         return PreparedExecution(
             command=command,
             env=env,
-            cwd=paths.target_workdir,
+            cwd=cwd,
             trace_kind="codex",
             runtime_files=runtime_files,
         )

agentflow/agents/kimi.py

@@ -7,13 +7,14 @@
 from agentflow.agents.base import AgentAdapter
 from agentflow.env import merge_env_layers
 from agentflow.prepared import ExecutionPaths, PreparedExecution
-from agentflow.specs import NodeSpec
+from agentflow.specs import NodeSpec, RepoInstructionsMode
 
 
 class KimiAdapter(AgentAdapter):
     def prepare(self, node: NodeSpec, prompt: str, paths: ExecutionPaths) -> PreparedExecution:
         provider = self.provider_config(node.provider, node.agent)
         executable = node.executable or "kimi"
+        repo_instructions_ignored = node.repo_instructions_mode == RepoInstructionsMode.IGNORE
         command = [
             executable,
             "--print",
@@ -23,9 +24,14 @@ def prepare(self, node: NodeSpec, prompt: str, paths: ExecutionPaths) -> Prepare
             "-p",
             prompt,
         ]
+        if repo_instructions_ignored:
+            empty_skills_dir = Path(paths.target_runtime_dir) / "empty-skills"
+            command.extend(["--add-dir", paths.target_workdir, "--skills-dir", str(empty_skills_dir)])
         if node.model:
             command.extend(["--model", node.model])
         runtime_files: dict[str, str] = {}
+        if repo_instructions_ignored:
+            runtime_files[self.relative_runtime_file("empty-skills", ".gitkeep")] = ""
         if node.mcps:
             mcp_payload: dict[str, object] = {"mcpServers": {}}
             for mcp in node.mcps:
@@ -57,10 +63,13 @@ def prepare(self, node: NodeSpec, prompt: str, paths: ExecutionPaths) -> Prepare
                     api_key = os.getenv(provider.api_key_env)
                 if api_key is not None:
                     env.setdefault("KIMI_API_KEY", api_key)
+        cwd = paths.target_workdir
+        if repo_instructions_ignored:
+            cwd = str(Path(paths.target_runtime_dir))
         return PreparedExecution(
             command=command,
             env=env,
-            cwd=paths.target_workdir,
+            cwd=cwd,
             trace_kind="kimi",
             runtime_files=runtime_files,
         )

agentflow/specs.py

@@ -46,6 +46,11 @@ class CaptureMode(StrEnum):
     TRACE = "trace"
 
 
+class RepoInstructionsMode(StrEnum):
+    INHERIT = "inherit"
+    IGNORE = "ignore"
+
+
 class PeriodicActuationMode(StrEnum):
     NONE = "none"
     OUTPUT_JSON = "output_json"
@@ -728,6 +733,7 @@ class NodeSpec(BaseModel):
     skills: list[str] = Field(default_factory=list)
     target: TargetSpec = Field(default_factory=LocalTarget)
     capture: CaptureMode = CaptureMode.FINAL
+    repo_instructions_mode: RepoInstructionsMode = RepoInstructionsMode.INHERIT
     output_key: str | None = None
     timeout_seconds: int = Field(default=1800, gt=0)
     env: dict[str, str] = Field(default_factory=dict)

docs/pipelines.md

@@ -46,6 +46,7 @@ Each node supports:
 - `model`: any model string understood by the backend
 - `provider`: a string or a structured provider config with `base_url`, `api_key_env`, headers, and env
 - `tools`: `read_only` or `read_write`
+- `repo_instructions_mode`: `inherit` (default) or `ignore` for agent CLIs that should not absorb repo-local instruction files such as `AGENTS.md`, `CLAUDE.md`, or project skills
 - `mcps`: a list of MCP server definitions
 - `skills`: a list of local skill paths or names
 - `target`: `local`, `container`, `ssh`, `ec2`, or `ecs`
@@ -217,6 +218,8 @@ Runtime numeric settings are validated up front: `concurrency` must be at least
 
 MCP definitions are also validated before launch: `stdio` servers require `command` and reject HTTP-only fields such as `url`, `streamable_http` servers require `url` and reject stdio-only fields such as `command`, and MCP server names must be unique within a node.
 
+`repo_instructions_mode: ignore` is a generic AgentFlow switch with agent-specific implementations. The current adapters use the same high-level pattern: start the agent from an isolated runtime directory, keep the target repo accessible via an explicit allowlist flag such as `--add-dir`, and disable or override repo-local instruction discovery where the underlying CLI supports it. When you enable this mode, write prompts that use absolute paths or explicitly tell the agent to `cd` into the repository before running shell commands.
+
 Built-in provider shorthands:
 
 - `codex`: `openai`

tests/test_agents.py

@@ -123,6 +123,53 @@ def test_codex_adapter_uses_runtime_codex_home_for_mcp_config(tmp_path):
     assert 'command = "npx"' in prepared.runtime_files["codex_home/config.toml"]
 
 
+def test_codex_adapter_isolates_home_when_runtime_codex_home_is_used(tmp_path):
+    node = NodeSpec.model_validate(
+        {
+            "id": "plan",
+            "agent": "codex",
+            "prompt": "Plan",
+            "provider": {
+                "name": "openai-pinned",
+                "base_url": "http://example.test/v1",
+                "api_key_env": "OPENAI_API_KEY",
+                "wire_api": "responses",
+            },
+        }
+    )
+
+    prepared = CodexAdapter().prepare(node, "Plan", _paths(tmp_path))
+
+    expected_home = str(tmp_path / ".runtime" / "codex_home")
+    assert prepared.env["CODEX_HOME"] == expected_home
+    assert prepared.env["HOME"] == expected_home
+    assert prepared.runtime_files.keys() == {"codex_home/config.toml"}
+
+
+def test_codex_adapter_can_ignore_repo_instructions_with_isolated_runtime_cwd(tmp_path):
+    node = NodeSpec.model_validate(
+        {
+            "id": "plan",
+            "agent": "codex",
+            "prompt": "Plan",
+            "repo_instructions_mode": "ignore",
+        }
+    )
+
+    prepared = CodexAdapter().prepare(node, "Plan", _paths(tmp_path))
+
+    expected_home = str(tmp_path / ".runtime" / "codex_home")
+    assert prepared.env["CODEX_HOME"] == expected_home
+    assert prepared.env["HOME"] == expected_home
+    assert prepared.cwd == str(tmp_path / ".runtime")
+    assert "--disable" in prepared.command
+    disable_index = prepared.command.index("--disable")
+    assert prepared.command[disable_index + 1] == "plugins"
+    assert "--add-dir" in prepared.command
+    add_dir_index = prepared.command.index("--add-dir")
+    assert prepared.command[add_dir_index + 1] == str(tmp_path)
+
+
 def test_claude_adapter_uses_tools_flag_for_read_only_access(tmp_path):
     node = NodeSpec.model_validate(
         {
@@ -156,6 +203,25 @@ def test_claude_adapter_uses_tools_flag_for_read_write_access(tmp_path):
     assert "Write" in prepared.command[index + 1].split(",")
 
 
+def test_claude_adapter_can_ignore_repo_instructions_with_bare_runtime_cwd(tmp_path):
+    node = NodeSpec.model_validate(
+        {
+            "id": "review",
+            "agent": "claude",
+            "prompt": "Review",
+            "repo_instructions_mode": "ignore",
+        }
+    )
+
+    prepared = ClaudeAdapter().prepare(node, "Review", _paths(tmp_path))
+
+    assert "--bare" in prepared.command
+    assert "--add-dir" in prepared.command
+    add_dir_index = prepared.command.index("--add-dir")
+    assert prepared.command[add_dir_index + 1] == str(tmp_path)
+    assert prepared.cwd == str(tmp_path / ".runtime")
+
+
 def test_claude_adapter_supports_kimi_provider_alias(tmp_path, monkeypatch):
     monkeypatch.setenv("ANTHROPIC_API_KEY", "test-kimi-secret")
     node = NodeSpec.model_validate(
@@ -225,6 +291,28 @@ def test_kimi_adapter_respects_custom_executable(tmp_path):
     assert prepared.command[0] == "/usr/local/bin/kimi"
 
 
+def test_kimi_adapter_can_ignore_repo_instructions_with_isolated_runtime_cwd(tmp_path):
+    node = NodeSpec.model_validate(
+        {
+            "id": "review",
+            "agent": "kimi",
+            "prompt": "Review",
+            "repo_instructions_mode": "ignore",
+        }
+    )
+
+    prepared = KimiAdapter().prepare(node, "Review", _paths(tmp_path))
+
+    assert "--add-dir" in prepared.command
+    add_dir_index = prepared.command.index("--add-dir")
+    assert prepared.command[add_dir_index + 1] == str(tmp_path)
+    assert "--skills-dir" in prepared.command
+    skills_dir_index = prepared.command.index("--skills-dir")
+    assert prepared.command[skills_dir_index + 1] == str(tmp_path / ".runtime" / "empty-skills")
+    assert prepared.cwd == str(tmp_path / ".runtime")
+    assert prepared.runtime_files.keys() == {"empty-skills/.gitkeep"}
+
+
 def test_claude_adapter_prefers_node_env_over_provider_env(tmp_path):
     node = NodeSpec.model_validate(
         {