agent-orchestration-process 0.2.0__tar.gz → 0.2.2__tar.gz

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-orchestration-process
-Version: 0.2.0
+Version: 0.2.2
 Summary: Run bounded, non-interactive jobs across agent harnesses with isolation, exact resume, and provenance
 Keywords: agent-orchestration,ai-agents,autoresearch,coding-agents,git-worktrees
 Author: AOP contributors

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agent-orchestration-process"
-version = "0.2.0"
+version = "0.2.2"
 description = "Run bounded, non-interactive jobs across agent harnesses with isolation, exact resume, and provenance"
 readme = "README.md"
 requires-python = ">=3.11"

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "agent-orchestration-process"
-version = "0.2.0"
+version = "0.2.2"
 description = "Run bounded, non-interactive jobs across agent harnesses with isolation, exact resume, and provenance"
 readme = "README.md"
 requires-python = ">=3.11"

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/src/agent_orchestration_process/cli.py

@@ -22,8 +22,14 @@ from .isolation import PROFILES, explain_profile, resolve_policy
 from .locks import exclusive_lock, task_lock_path
 from .model_catalog import ModelCatalog, ensure_catalog_fresh
 from .model_listing import AGENTS, AvailableModel, list_models
-from .models import RunRequest, RunResult
-from .runner import AgentRunner, RunStore, adapter_for, provider_runtime_record
+from .models import PromptPart, RunRequest, RunResult
+from .runner import (
+    AgentRunner,
+    RunStore,
+    adapter_for,
+    plan_inputs,
+    provider_runtime_record,
+)
 from .migration import migrate_runs, migration_roots, print_counts
 from .worktrees import (
     AOPError,
@@ -396,6 +402,25 @@ def main(argv: Sequence[str] | None = None) -> int:
                 input_names=tuple(Path(path).name for path in args.input_paths),
             ).to_dict()
             preview["provider"] = args.agent
+            planned = plan_inputs(
+                args.input_paths,
+                excludes=args.input_excludes,
+                skip_external_links=args.skip_external_links,
+                protected=(manager.state_dir, manager.sealed_runtime_dir),
+            )
+            preview["inputs"]["planned"] = [
+                {
+                    "name": plan.alias,
+                    "source": os.fspath(plan.source),
+                    "files": len(plan.entries) if plan.entries else 1,
+                    "size_bytes": sum(path.stat().st_size for _, path in plan.entries)
+                    if plan.source.is_dir()
+                    else plan.source.stat().st_size,
+                    "excluded": list(plan.excluded),
+                    "links": list(plan.links),
+                }
+                for plan in planned
+            ]
             preview["provider_runtime"] = provider_runtime_record(
                 adapter_for(args.agent)
             )
@@ -409,9 +434,11 @@ def main(argv: Sequence[str] | None = None) -> int:
                     prefix="aop: ",
                     stream=sys.stderr,
                 )
+            prompt, prompt_parts = _read_prompt(args)
             result = AgentRunner(manager, adapter_for(args.agent)).run(
                 task=task,
-                prompt=_read_prompt(args),
+                prompt=prompt,
+                prompt_parts=prompt_parts,
                 base=args.base,
                 model=args.model,
                 inference_provider=args.inference_provider,
@@ -422,6 +449,8 @@ def main(argv: Sequence[str] | None = None) -> int:
                 timeout_seconds=args.timeout,
                 artifacts=args.artifact,
                 input_paths=args.input_paths,
+                input_excludes=args.input_excludes,
+                skip_external_links=args.skip_external_links,
                 system_prompt=_read_system_prompt(args),
                 tools=args.tools,
                 provider_base_url=args.provider_base_url,
@@ -432,9 +461,11 @@ def main(argv: Sequence[str] | None = None) -> int:
             return _report_run(result, manager, json_output=args.json)
 
         if args.command == "resume":
+            prompt, prompt_parts = _read_prompt(args)
             result = AgentRunner(manager).resume(
                 run_id=args.run_id,
-                prompt=_read_prompt(args),
+                prompt=prompt,
+                prompt_parts=prompt_parts,
                 timeout_seconds=args.timeout,
                 artifacts=args.artifact,
                 input_paths=args.input_paths,
@@ -461,7 +492,11 @@ def main(argv: Sequence[str] | None = None) -> int:
         print(f"aop: {error}", file=sys.stderr)
         return 2
     except FileNotFoundError as error:
-        print(f"aop: command not found: {error.filename}", file=sys.stderr)
+        print(
+            f"aop: command not found: {error.filename} "
+            f"(PATH={os.environ.get('PATH', '')})",
+            file=sys.stderr,
+        )
         return 127
     except KeyboardInterrupt:
         print("aop: interrupted", file=sys.stderr)
@@ -472,6 +507,13 @@ def _add_prompt_arguments(parser: argparse.ArgumentParser) -> None:
     prompts = parser.add_mutually_exclusive_group(required=True)
     prompts.add_argument("--prompt")
     prompts.add_argument("--prompt-file", type=Path)
+    prompts.add_argument(
+        "--prompt-parts",
+        type=Path,
+        metavar="PATH",
+        help='JSON list of prompt blocks, each {"text": ..., "cache": true|false}; '
+        "Claude caches the prompt through the one cached block (claude only)",
+    )
 
 
 def _add_artifact_arguments(parser: argparse.ArgumentParser) -> None:
@@ -503,6 +545,25 @@ def _add_input_arguments(
         metavar="PATH",
         help=help_text,
     )
+    if resume:
+        return
+    parser.add_argument(
+        "--input-exclude",
+        action="append",
+        default=[],
+        dest="input_excludes",
+        metavar="GLOB",
+        help="leave matching paths out of every input directory; a pattern "
+        "without '/' matches names at any depth, one with '/' matches paths "
+        "from the input's root; repeat for more",
+    )
+    parser.add_argument(
+        "--skip-external-links",
+        action="store_true",
+        help="leave out symlinks that point outside their input instead of "
+        "failing; links that stay inside an input are always copied as their "
+        "targets",
+    )
 
 
 def _tool_list(value: str) -> tuple[str, ...]:
@@ -520,15 +581,36 @@ def _read_system_prompt(args: argparse.Namespace) -> str | None:
         ) from error
 
 
-def _read_prompt(args: argparse.Namespace) -> str:
+def _read_prompt(args: argparse.Namespace) -> tuple[str, tuple[PromptPart, ...] | None]:
     if args.prompt is not None:
-        return args.prompt
+        return args.prompt, None
+    path = args.prompt_file or args.prompt_parts
     try:
-        return args.prompt_file.read_text()
+        text = path.read_text()
     except OSError as error:
+        raise AOPError(f"could not read prompt file {path}: {error}") from error
+    if args.prompt_file is not None:
+        return text, None
+    try:
+        blocks = json.loads(text)
+    except json.JSONDecodeError as error:
+        raise AOPError(f"prompt parts file {path} is not JSON: {error}") from error
+    if not isinstance(blocks, list) or not all(
+        isinstance(block, dict)
+        and set(block) <= {"text", "cache"}
+        and isinstance(block.get("text"), str)
+        and isinstance(block.get("cache", False), bool)
+        for block in blocks
+    ):
         raise AOPError(
-            f"could not read prompt file {args.prompt_file}: {error}"
-        ) from error
+            f"prompt parts file {path} must be a list of "
+            '{"text": string, "cache": boolean} objects'
+        )
+    parts = tuple(
+        PromptPart(chars=len(block["text"]), cache=block.get("cache", False))
+        for block in blocks
+    )
+    return "".join(block["text"] for block in blocks), parts
 
 
 def _report_policy(
@@ -574,6 +656,15 @@ def _report_policy(
         f"{prefix}inputs: {inputs['mode']} ({len(inputs.get('names', []))} declared)",
         file=stream,
     )
+    for item in inputs.get("planned", []):
+        skipped = sum(link["action"] == "skipped" for link in item["links"])
+        print(
+            f"{prefix}  {item['name']}: {item['files']} files, "
+            f"{item['size_bytes'] / 1e6:.1f} MB; {len(item['excluded'])} paths "
+            f"excluded; {len(item['links']) - skipped} symlinks followed, "
+            f"{skipped} skipped",
+            file=stream,
+        )
     print(
         f"{prefix}inherited local instructions: {instructions['inherited_local']}; "
         f"provider built-in prompt: {instructions['provider_builtin']}; "

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/src/agent_orchestration_process/isolation.py

@@ -157,7 +157,7 @@ def resolve_policy(
         host={
             "access": selected.host_access,
             "runtime_paths": (
-                ["/usr", "/bin", "/lib", "/lib64", "/etc runtime files"]
+                ["/usr", "/bin", "/sbin", "/lib", "/lib64", "/etc runtime files"]
                 if selected.host_access == "runtime-only"
                 else ["/"]
             ),

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/src/agent_orchestration_process/models.py

@@ -28,11 +28,19 @@ class InputSnapshot:
     size_bytes: int
     sha256: str
     files: tuple[InputFile, ...]
+    # Paths left out of the snapshot, relative to the input: matches of the
+    # run's input excludes and AOP's own state directories.
+    excluded: tuple[str, ...] = ()
+    # Symlinks found in the input: {"path", "target", "action"}, where action
+    # is "followed" for a target inside the input and "skipped" otherwise.
+    links: tuple[dict[str, str], ...] = ()
 
     @classmethod
     def from_dict(cls, value: dict[str, Any]) -> InputSnapshot:
         fields = dict(value)
         fields["files"] = tuple(InputFile(**item) for item in fields.get("files", ()))
+        fields["excluded"] = tuple(fields.get("excluded", ()))
+        fields["links"] = tuple(fields.get("links", ()))
         return cls(**fields)
 
 
@@ -57,6 +65,15 @@ class InferenceRoute:
         return cls(**fields)
 
 
+@dataclass(frozen=True)
+class PromptPart:
+    """One content block of a prompt; `cache` asks Claude to cache the prompt
+    up to and including this block. The text itself stays in RunRequest.prompt."""
+
+    chars: int
+    cache: bool = False
+
+
 @dataclass(frozen=True)
 class RunRequest:
     run_id: str
@@ -90,6 +107,13 @@ class RunRequest:
     allowed_urls: tuple[str, ...] = ()
     # A sealed run's private, initially empty /workspace is writable.
     writable_workspace: bool = False
+    # The prompt split into content blocks, in order; their lengths add up to
+    # len(prompt). None sends the prompt as one block.
+    prompt_parts: tuple[PromptPart, ...] | None = None
+    # Glob patterns left out of every input directory, and whether symlinks
+    # that leave their input are skipped instead of failing the run.
+    input_excludes: tuple[str, ...] = ()
+    skip_external_links: bool = False
     # How `aop migrate-results` converted an older record, if it did.
     migration: dict[str, Any] | None = None
 
@@ -106,6 +130,11 @@ class RunRequest:
         if fields.get("tools") is not None:
             fields["tools"] = tuple(fields["tools"])
         fields["allowed_urls"] = tuple(fields.get("allowed_urls", ()))
+        fields["input_excludes"] = tuple(fields.get("input_excludes", ()))
+        if fields.get("prompt_parts") is not None:
+            fields["prompt_parts"] = tuple(
+                PromptPart(**part) for part in fields["prompt_parts"]
+            )
         fields["inputs"] = tuple(
             InputSnapshot.from_dict(item) for item in fields["inputs"]
         )

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/src/agent_orchestration_process/prompt_transport.py

@@ -1,11 +1,14 @@
 """Prompt transport independent of the OS argument and environment limits."""
 
+from collections.abc import Sequence
 from contextlib import contextmanager
 import json
 import os
 from pathlib import Path
 import tempfile
 
+from .models import PromptPart
+
 
 # Native protocols remain in their adapters. Runtime-file is only for CLIs
 # whose one-shot parser accepts text exclusively as an argument.
@@ -47,6 +50,28 @@ def stdin_prompt(provider: str, prompt: str) -> str | None:
     return None
 
 
+def claude_message(prompt: str, parts: Sequence[PromptPart]) -> str:
+    """A stream-json user message whose content blocks follow `parts`.
+
+    Claude Code marks its own system blocks and the context it appends after
+    the prompt with one-hour cache marks, and a five-minute mark must not
+    precede a one-hour one, so a caller's mark uses one hour too.
+    """
+    content = []
+    start = 0
+    for part in parts:
+        block: dict[str, object] = {
+            "type": "text",
+            "text": prompt[start : start + part.chars],
+        }
+        if part.cache:
+            block["cache_control"] = {"type": "ephemeral", "ttl": "1h"}
+        content.append(block)
+        start += part.chars
+    message = {"type": "user", "message": {"role": "user", "content": content}}
+    return json.dumps(message) + "\n"
+
+
 @contextmanager
 def prompt_stream(prompt: str | None):
     """A seekable stdin avoids blocking on pipe writes before the timeout starts."""

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/src/agent_orchestration_process/provider_versions.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import re
 import subprocess
 
@@ -24,6 +25,11 @@ def require_supported_agy(binary: str) -> str:
             capture_output=True,
             timeout=5,
         )
+    except FileNotFoundError as error:
+        raise AOPError(
+            f"{binary} not found on PATH ({os.environ.get('PATH', '')}); set "
+            "AOP_AGY_BIN to its absolute path"
+        ) from error
     except OSError as error:
         raise AOPError(f"could not query Agy version: {error}") from error
     except subprocess.TimeoutExpired as error:

{agent_orchestration_process-0.2.0 → agent_orchestration_process-0.2.2}/src/agent_orchestration_process/runner.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import ast
 import contextlib
+import fnmatch
 import hashlib
 import json
 import os
@@ -39,6 +40,7 @@ from .models import (
     InputFile,
     InputSnapshot,
     InferenceRoute,
+    PromptPart,
     RunArtifact,
     RunRequest,
     RunResult,
@@ -1074,7 +1076,10 @@ def _capture_process(
     prompt: str | None,
     timeout_seconds: float | None,
     is_response: Callable[[str], bool],
+    live_dir: Path | None = None,
 ) -> _ProcessCapture:
+    """Run a harness to completion; with `live_dir`, its stdout and stderr also
+    grow in live_dir/events.jsonl and live_dir/stderr.log while it runs."""
     started = time.monotonic()
     timed_out = False
     first_event_seconds = None
@@ -1105,6 +1110,11 @@ def _capture_process(
 
     stdout_parts: list[str] = []
     stderr_parts: list[str] = []
+    live = contextlib.ExitStack()
+    live_stdout = live_stderr = None
+    if live_dir is not None:
+        live_stdout = live.enter_context((live_dir / "events.jsonl").open("w"))
+        live_stderr = live.enter_context((live_dir / "stderr.log").open("w"))
 
     def read_stdout() -> None:
         nonlocal first_event_seconds, first_response_seconds
@@ -1116,10 +1126,17 @@ def _capture_process(
             if first_response_seconds is None and is_response(line):
                 first_response_seconds = elapsed
             stdout_parts.append(line)
+            if live_stdout is not None:
+                live_stdout.write(line)
+                live_stdout.flush()
 
     def read_stderr() -> None:
         assert process.stderr is not None
-        stderr_parts.extend(process.stderr)
+        for line in process.stderr:
+            stderr_parts.append(line)
+            if live_stderr is not None:
+                live_stderr.write(line)
+                live_stderr.flush()
 
     stdout_reader = threading.Thread(target=read_stdout, daemon=True)
     stderr_reader = threading.Thread(target=read_stderr, daemon=True)
@@ -1149,6 +1166,8 @@ def _capture_process(
         _close_finished_streams(
             (stdout_reader, process.stdout), (stderr_reader, process.stderr)
         )
+        if not (stdout_reader.is_alive() or stderr_reader.is_alive()):
+            live.close()
     return _ProcessCapture(
         stdout="".join(stdout_parts),
         stderr="".join(stderr_parts),
@@ -1221,9 +1240,14 @@ class ClaudeAdapter:
             command,
             cwd=worktree.path,
             environment=environment,
-            prompt=prompt_transport.stdin_prompt(self.provider, request.prompt),
+            prompt=(
+                prompt_transport.claude_message(request.prompt, request.prompt_parts)
+                if request.prompt_parts is not None
+                else prompt_transport.stdin_prompt(self.provider, request.prompt)
+            ),
             timeout_seconds=request.timeout_seconds,
             is_response=self._is_response,
+            live_dir=run_dir,
         )
         _atomic_write(run_dir / "events.jsonl", capture.stdout)
         _atomic_write(run_dir / "stderr.log", capture.stderr)
@@ -1396,6 +1420,8 @@ class ClaudeAdapter:
             command.extend(["--system-prompt", request.system_prompt])
         if request.thinking_display is not None:
             command.extend(["--thinking-display", request.thinking_display])
+        if request.prompt_parts is not None:
+            command.extend(["--input-format", "stream-json"])
         if request.session_id:
             command.extend(["--resume", request.session_id])
         else:
@@ -1861,6 +1887,7 @@ class GrokAdapter:
             prompt=None,
             timeout_seconds=request.timeout_seconds,
             is_response=self._is_response,
+            live_dir=run_dir,
         )
         _atomic_write(run_dir / "events.jsonl", capture.stdout)
         _atomic_write(run_dir / "stderr.log", capture.stderr)
@@ -2194,6 +2221,7 @@ class CursorAdapter:
             prompt=prompt_transport.stdin_prompt(self.provider, request.prompt),
             timeout_seconds=request.timeout_seconds,
             is_response=self._is_response,
+            live_dir=run_dir,
         )
         _atomic_write(run_dir / "events.jsonl", capture.stdout)
         _atomic_write(run_dir / "stderr.log", capture.stderr)
@@ -2412,6 +2440,7 @@ class DevinAdapter:
             prompt=None,
             timeout_seconds=request.timeout_seconds,
             is_response=lambda line: bool(line.strip()),
+            live_dir=run_dir,
         )
         _atomic_write(run_dir / "events.jsonl", capture.stdout)
         _atomic_write(run_dir / "stderr.log", capture.stderr)
@@ -2673,6 +2702,7 @@ class OpenCodeAdapter:
             prompt=prompt_transport.stdin_prompt(self.provider, request.prompt),
             timeout_seconds=request.timeout_seconds,
             is_response=self._is_response,
+            live_dir=run_dir,
         )
         _atomic_write(run_dir / "events.jsonl", capture.stdout)
         _atomic_write(run_dir / "stderr.log", capture.stderr)
@@ -3033,6 +3063,7 @@ class AgyAdapter:
             prompt=prompt_transport.stdin_prompt(self.provider, request.prompt),
             timeout_seconds=request.timeout_seconds,
             is_response=self._is_response,
+            live_dir=run_dir,
         )
         _atomic_write(run_dir / "events.jsonl", capture.stdout)
         _atomic_write(run_dir / "stderr.log", capture.stderr)
@@ -3317,6 +3348,7 @@ class HermesAdapter:
             prompt=None,
             timeout_seconds=request.timeout_seconds,
             is_response=lambda line: bool(line.strip()),
+            live_dir=run_dir,
         )
         _atomic_write(run_dir / "events.jsonl", capture.stdout)
         _atomic_write(run_dir / "stderr.log", capture.stderr)
@@ -3765,6 +3797,7 @@ class DeepSeekHarnessAdapter:
             prompt=None,
             timeout_seconds=request.timeout_seconds,
             is_response=self._is_response,
+            live_dir=run_dir,
         )
         _atomic_write(run_dir / "events.jsonl", capture.stdout)
         _atomic_write(run_dir / "stderr.log", capture.stderr)
@@ -4205,7 +4238,7 @@ def _isolated_root_command(bwrap: str) -> list[str]:
         "--tmpfs",
         "/tmp",
     ]
-    for path in ("/usr", "/bin", "/lib", "/lib64"):
+    for path in ("/usr", "/bin", "/sbin", "/lib", "/lib64"):
         source = Path(path)
         if source.exists():
             command.extend(["--ro-bind", path, path])
@@ -4214,6 +4247,9 @@ def _isolated_root_command(bwrap: str) -> list[str]:
         "/etc/ca-certificates",
         "/etc/crypto-policies",
         "/etc/hosts",
+        # The dynamic linker finds libraries in folders registered under
+        # /etc/ld.so.conf.d only through this cache.
+        "/etc/ld.so.cache",
         "/etc/localtime",
         "/etc/nsswitch.conf",
         "/etc/pki",
@@ -5775,8 +5811,20 @@ class AgentRunner:
         allowed_urls: Sequence[str] = (),
         writable_workspace: bool = False,
         thinking_display: str | None = None,
+        prompt_parts: Sequence[PromptPart] | None = None,
+        input_excludes: Sequence[str] = (),
+        skip_external_links: bool = False,
     ) -> RunResult:
         self._validate_mode(mode)
+        prompt_parts = self._validated_prompt_parts(prompt, prompt_parts)
+        input_excludes = tuple(input_excludes)
+        # Every input problem fails here, before any state is created.
+        plan_inputs(
+            input_paths,
+            excludes=input_excludes,
+            skip_external_links=skip_external_links,
+            protected=self._state_roots(),
+        )
         if writable_workspace and profile != "sealed":
             raise AOPError("--writable-workspace applies only to the sealed profile")
         if thinking_display is not None:
@@ -5822,6 +5870,9 @@ class AgentRunner:
             allowed_urls=allowed_urls,
             writable_workspace=writable_workspace,
             thinking_display=thinking_display,
+            prompt_parts=prompt_parts,
+            input_excludes=input_excludes,
+            skip_external_links=skip_external_links,
         )
         worktree = (
             self._create_sealed_workspace(request.run_id)
@@ -5854,6 +5905,7 @@ class AgentRunner:
         timeout_seconds: float | None = None,
         artifacts: Sequence[str] = (),
         input_paths: Sequence[str | os.PathLike[str]] | None = None,
+        prompt_parts: Sequence[PromptPart] | None = None,
         _task_lock_held: bool = False,
     ) -> RunResult:
         parent_request = self.store.load_request(run_id)
@@ -5865,6 +5917,7 @@ class AgentRunner:
                 )
             self.adapter = adapter_for(parent_request.provider)
         self._validate_mode(parent_request.mode)
+        prompt_parts = self._validated_prompt_parts(prompt, prompt_parts)
         self._validate_no_web(
             parent_request.no_web, parent_request.mode, parent_request.profile
         )
@@ -5952,6 +6005,9 @@ class AgentRunner:
             allowed_urls=parent_request.allowed_urls,
             writable_workspace=parent_request.writable_workspace,
             thinking_display=parent_request.thinking_display,
+            prompt_parts=prompt_parts,
+            input_excludes=parent_request.input_excludes,
+            skip_external_links=parent_request.skip_external_links,
         )
         return self._execute(
             request,
@@ -6068,7 +6124,12 @@ class AgentRunner:
             cache_dir = self.manager.cache_dir
             cache_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
         declared_inputs = _prepare_inputs(
-            input_paths,
+            plan_inputs(
+                input_paths,
+                excludes=request.input_excludes,
+                skip_external_links=request.skip_external_links,
+                protected=self._state_roots() if input_provenance is None else (),
+            ),
             input_dir,
             guest_paths=request.profile != "host",
             provenance=input_provenance,
@@ -6308,6 +6369,9 @@ class AgentRunner:
         allowed_urls: tuple[str, ...] = (),
         writable_workspace: bool = False,
         thinking_display: str | None = None,
+        prompt_parts: tuple[PromptPart, ...] | None = None,
+        input_excludes: tuple[str, ...] = (),
+        skip_external_links: bool = False,
     ) -> RunRequest:
         return RunRequest(
             run_id=str(uuid.uuid4()),
@@ -6335,8 +6399,15 @@ class AgentRunner:
             allowed_urls=allowed_urls,
             writable_workspace=writable_workspace,
             thinking_display=thinking_display,
+            prompt_parts=prompt_parts,
+            input_excludes=input_excludes,
+            skip_external_links=skip_external_links,
         )
 
+    def _state_roots(self) -> tuple[Path, ...]:
+        """AOP's own state, which no input snapshot may copy into itself."""
+        return (self.manager.state_dir, self.manager.sealed_runtime_dir)
+
     def _validate_provider_base_url(self, url: str | None, profile: str) -> None:
         variable = PROVIDER_BASE_URL_VARIABLES.get(self.adapter.provider)
         if url is None:
@@ -6356,6 +6427,27 @@ class AgentRunner:
         if parsed.scheme not in {"http", "https"} or not parsed.hostname:
             raise AOPError(f"--provider-base-url must be an http(s) URL: {url!r}")
 
+    def _validated_prompt_parts(
+        self, prompt: str, parts: Sequence[PromptPart] | None
+    ) -> tuple[PromptPart, ...] | None:
+        if parts is None:
+            return None
+        if self.adapter.provider != "claude":
+            raise AOPError(f"{self.adapter.provider} does not support --prompt-parts")
+        parts = tuple(parts)
+        if not parts or any(part.chars <= 0 for part in parts):
+            raise AOPError("--prompt-parts needs at least one part, none of them empty")
+        if sum(part.chars for part in parts) != len(prompt):
+            raise AOPError("prompt parts do not add up to the prompt")
+        # Anthropic accepts four cache marks per request, and Claude Code
+        # places three: two on its system prompt and one on the context it
+        # appends after the prompt.
+        if sum(part.cache for part in parts) > 1:
+            raise AOPError(
+                "Claude allows one cached prompt part; Claude Code uses the other marks"
+            )
+        return parts
+
     def _validated_framing(
         self, system_prompt: str | None, tools: Sequence[str] | None, no_web: bool
     ) -> tuple[str, ...] | None:
@@ -6578,18 +6670,39 @@ def normalize_artifacts(artifacts: Sequence[str]) -> tuple[str, ...]:
     return tuple(normalized)
 
 
-def _prepare_inputs(
+@dataclass(frozen=True)
+class InputPlan:
+    """One declared input, checked and resolved before anything is copied."""
+
+    source: Path
+    alias: str
+    # (path relative to the input, host file to copy); empty for a file input.
+    entries: tuple[tuple[str, Path], ...]
+    excluded: tuple[str, ...]
+    links: tuple[dict[str, str], ...]
+
+
+def plan_inputs(
     values: Sequence[str | os.PathLike[str]],
-    input_dir: Path,
     *,
-    guest_paths: bool = True,
-    provenance: Sequence[str] | None = None,
-) -> tuple[InputSnapshot, ...]:
-    if provenance is not None and len(provenance) != len(values):
-        raise AOPError("input provenance does not match the input snapshot set")
-    prepared: list[InputSnapshot] = []
+    excludes: Sequence[str] = (),
+    skip_external_links: bool = False,
+    protected: Sequence[Path] = (),
+) -> tuple[InputPlan, ...]:
+    """Check every input as a run would, without copying.
+
+    Directories under `protected` (AOP's own state) are left out of any input
+    that contains them. A symlink whose target lies inside its input is copied
+    as the target's contents; one that leaves the input, or is dangling, fails
+    the run unless `skip_external_links` is set.
+    """
+    for pattern in excludes:
+        if not pattern or "\0" in pattern or pattern.startswith("/"):
+            raise AOPError(f"input exclude must be a relative glob pattern: {pattern!r}")
+    protected = tuple(path.resolve() for path in protected)
+    plans: list[InputPlan] = []
     aliases: set[str] = set()
-    for index, value in enumerate(values):
+    for value in values:
         raw = os.fspath(value)
         if not raw or "\0" in raw:
             raise AOPError("input path must be a non-empty filesystem path")
@@ -6609,46 +6722,136 @@ def _prepare_inputs(
         if alias in aliases:
             raise AOPError(f"input paths have the same basename: {alias}")
         aliases.add(alias)
-
-        mounted = input_dir / alias
+        if any(source == root or source.is_relative_to(root) for root in protected):
+            raise AOPError(f"input path is inside AOP's state directory: {source}")
         if source.is_dir():
-            _copy_input_directory(source, mounted)
+            plans.append(
+                _plan_directory(source, alias, excludes, skip_external_links, protected)
+            )
+        elif source.is_file():
+            plans.append(InputPlan(source, alias, (), (), ()))
         else:
-            shutil.copyfile(source, mounted)
+            raise AOPError(f"input path is not a regular file or directory: {source}")
+    return tuple(plans)
+
+
+def _plan_directory(
+    root: Path,
+    alias: str,
+    excludes: Sequence[str],
+    skip_external_links: bool,
+    protected: tuple[Path, ...],
+) -> InputPlan:
+    entries: list[tuple[str, Path]] = []
+    excluded: list[str] = []
+    links: list[dict[str, str]] = []
+
+    def is_excluded(relative: str) -> bool:
+        name = relative.rsplit("/", 1)[-1]
+        return any(
+            fnmatch.fnmatchcase(relative, pattern)
+            or ("/" not in pattern and fnmatch.fnmatchcase(name, pattern))
+            for pattern in excludes
+        )
+
+    def is_protected(path: Path) -> bool:
+        return any(path == item or path.is_relative_to(item) for item in protected)
+
+    def walk(directory: Path, relative: PurePosixPath, chain: tuple[Path, ...]) -> None:
+        try:
+            children = sorted(directory.iterdir(), key=lambda child: child.name)
+        except OSError as error:
+            raise AOPError(
+                f"could not read input directory {directory}: {error}"
+            ) from error
+        for child in children:
+            logical = (relative / child.name).as_posix()
+            if is_excluded(logical):
+                excluded.append(logical)
+                continue
+            status = child.lstat()
+            path = child
+            if stat.S_ISLNK(status.st_mode):
+                target = child.resolve()
+                inside = target.is_relative_to(root) and target.exists()
+                if not inside:
+                    if not skip_external_links:
+                        raise AOPError(
+                            f"input contains a symlink that leaves it: {child} -> "
+                            f"{os.readlink(child)}; pass --skip-external-links "
+                            "to leave such links out, or --input-exclude to "
+                            "exclude them"
+                        )
+                    links.append(
+                        {"path": logical, "target": os.readlink(child), "action": "skipped"}
+                    )
+                    continue
+                if target in chain:
+                    raise AOPError(f"input contains a symlink loop: {child}")
+                links.append(
+                    {"path": logical, "target": os.readlink(child), "action": "followed"}
+                )
+                path = target
+                status = target.stat()
+            if stat.S_ISDIR(status.st_mode):
+                resolved = path.resolve()
+                if is_protected(resolved):
+                    excluded.append(logical)
+                elif resolved in chain:
+                    raise AOPError(f"input contains a symlink loop: {child}")
+                else:
+                    walk(path, PurePosixPath(logical), (*chain, resolved))
+            elif stat.S_ISREG(status.st_mode):
+                entries.append((logical, path))
+            else:
+                raise AOPError(f"read path contains a special file: {child}")
+
+    walk(root, PurePosixPath(), (root,))
+    return InputPlan(root, alias, tuple(entries), tuple(excluded), tuple(links))
+
+
+def _prepare_inputs(
+    plans: Sequence[InputPlan],
+    input_dir: Path,
+    *,
+    guest_paths: bool = True,
+    provenance: Sequence[str] | None = None,
+) -> tuple[InputSnapshot, ...]:
+    if provenance is not None and len(provenance) != len(plans):
+        raise AOPError("input provenance does not match the input snapshot set")
+    prepared: list[InputSnapshot] = []
+    for index, plan in enumerate(plans):
+        mounted = input_dir / plan.alias
+        if plan.source.is_dir():
+            mounted.mkdir()
+            for relative, path in plan.entries:
+                target = mounted / relative
+                target.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copyfile(path, target)
+        else:
+            shutil.copyfile(plan.source, mounted)
         kind, files = _inspect_read_path(mounted)
-        size_bytes = sum(item.size_bytes for item in files)
         prepared.append(
             InputSnapshot(
                 source_path=(
-                    provenance[index] if provenance is not None else os.fspath(source)
+                    provenance[index]
+                    if provenance is not None
+                    else os.fspath(plan.source)
                 ),
                 mounted_path=(
-                    f"/inputs/{alias}" if guest_paths else os.fspath(mounted)
+                    f"/inputs/{plan.alias}" if guest_paths else os.fspath(mounted)
                 ),
                 kind=kind,
-                size_bytes=size_bytes,
+                size_bytes=sum(item.size_bytes for item in files),
                 sha256=_read_path_digest(kind, files),
                 files=files,
+                excluded=plan.excluded,
+                links=plan.links,
             )
         )
     return tuple(prepared)
 
 
-def _copy_input_directory(source: Path, destination: Path) -> None:
-    destination.mkdir()
-    for child in sorted(source.iterdir(), key=lambda item: item.name):
-        status = child.lstat()
-        target = destination / child.name
-        if stat.S_ISLNK(status.st_mode):
-            raise AOPError(f"read path contains a symlink: {child}")
-        if stat.S_ISDIR(status.st_mode):
-            _copy_input_directory(child, target)
-        elif stat.S_ISREG(status.st_mode):
-            shutil.copyfile(child, target)
-        else:
-            raise AOPError(f"read path contains a special file: {child}")
-
-
 def _make_snapshot_private(root: Path) -> None:
     for directory, names, files in os.walk(root):
         path = Path(directory)