Rectify: Shell Capture Filesystem Trust Anchor

docs/decisions/0005-output-budget-protocol.md

@@ -69,8 +69,10 @@ the selected decision without applying a second static shaping pass.
 
 The shell capture hook uses `shell_max_inline_bytes = 12_000` as the inline threshold:
 commands whose combined output fits within that budget are inlined in full (artifact
-deleted); larger outputs are captured losslessly to a mechanism-owned artifact with a
-bounded head/tail slice and provenance marker inlined.
+retained); larger outputs are captured losslessly to the same descriptor-owned artifact
+with a bounded head/tail slice and provenance marker inlined. SessionStart classifies
+stale artifacts but conservatively retains them on portable Python because pathname
+unlink cannot condition deletion on the validated inode.
 `small_file_max_bytes` was removed — it existed solely for the classifier's
 literal-small-JSONL exception, which is no longer needed.
 

docs/decisions/0006-output-containment.md

@@ -26,8 +26,11 @@ output-boundary bounding on measured bytes:
    oversized outputs are promoted in place with a contract (bytes, sha256,
    completeness).
 3. **Codex native shell** — PreToolUse input-rewrite hook wraps every shell
-   command in a capture harness: complete output to a mechanism-owned artifact,
-   bounded inline slice with provenance marker, exit code preserved. The
+   command in a minimal isolated runner invocation. The runner opens `cwd` first,
+   establishes descriptor-relative authority for policy and capture components,
+   creates the artifact exclusively without following symlinks, and drains child
+   output through its owned fd. The bounded inline slice includes a provenance
+   marker whose path is present only after marker-time identity verification. The
    ordinary outer-result limit remains the backstop for hook-failure paths. The
    separately configured `CODEX_HISTORY_RETENTION_TOKEN_LIMIT` governs later history.
 
@@ -66,10 +69,9 @@ hook can be retired in favor of that mechanism.
 1. `disown`ed/job-table-detached children are outside the `wait` drain guarantee.
    Their post-exit writes into the artifact are best-effort — mirrors native
    detached-output semantics.
-2. Fatal self-signals (e.g. `kill -TERM $$`) skip the slice-emission postlude.
-   Exit-code parity holds, the artifact persists as lossless evidence, but no inline
-   slice is emitted and the file is not deleted. SIGKILL is untrappable, so full
-   closure is impossible.
+2. Fatal self-signals (e.g. `kill -TERM $$`) are reported as the shell-compatible
+   `128 + signal` status by the runner. Output drained before termination remains
+   available inline and in the retained artifact. SIGKILL remains untrappable.
 3. Head/tail slices are byte-cut and may split multibyte UTF-8 at slice edges. The
    artifact is authoritative.
 4. Draining non-detached background jobs makes the harness synchronous for their
@@ -79,6 +81,18 @@ hook can be retired in favor of that mechanism.
 6. Vendored-tree version discrepancy: the checkout tag is `rust-v0.143.0-alpha.10`
    vs the 0.144.1 description in the issue/ADR. The hook contract must be re-verified
    against the deployed Codex version before shipping.
+7. A supplied symlink spelling of `cwd` is accepted only by opening it first as
+   the `ProjectAnchor`; `.autoskillit`, `temp`, and `shell_capture` symlinks are
+   rejected. Physical path strings are display hints, not filesystem authority.
+8. Same-user code inside the command can rename a verified directory entry after
+   it is opened. Output, hashing, and replay remain fd-bound; if the live pathname
+   chain no longer matches, the marker reports its path as `unavailable`.
+9. Portable Linux/macOS Python exposes descriptor-relative unlink but no
+   expected-inode conditional unlink. SessionStart therefore retains stale
+   candidates rather than making a security claim across a validation/deletion
+   race. Artifact quota and lifecycle reclamation remain follow-up work tracked
+   by [#4327](https://github.com/TalonT-Org/AutoSkillit/issues/4327) and
+   [#4320](https://github.com/TalonT-Org/AutoSkillit/issues/4320), respectively.
 
 ## Consequences
 
@@ -89,4 +103,5 @@ hook can be retired in favor of that mechanism.
   for the classifier's literal-small-JSONL exception).
 - `shell_max_inline_bytes` survives with its new capture-threshold meaning.
 - Complete Codex shell output is captured to mechanism-owned artifacts at
-  `<cwd>/.autoskillit/temp/shell_capture/shell_<uuid16>.log`.
+  the descriptor-anchored project capture root. A pathname is reported only
+  while it still binds to the opened project, directories, and artifact.

docs/safety/hooks.md

@@ -88,25 +88,36 @@ in `.hook_config.json` for future recipes that legitimately need these operation
 **Matched tool:** `Bash`
 **Scope:** Codex sessions only (#4286 / ADR-0006); Claude Code is unaffected.
 PreToolUse input-rewrite hook that wraps every native shell command on Codex in a
-capture harness. The original command runs unmodified in a subshell; its complete
-combined stdout+stderr goes to a mechanism-owned artifact at
-`<cwd>/.autoskillit/temp/shell_capture/shell_<uuid16>.log`. Only a bounded inline
-slice enters context: full content when small (artifact retained; reclaimed by SessionStart sweep), else head +
-provenance marker (bytes, sha256, path) + tail. Exit codes are preserved via a
-trap-EXIT postlude. Set `output_budget.guard_enabled: false` to disable;
-inline threshold controlled by `output_budget.shell_max_inline_bytes`.
+minimal isolated-Python runner. The runner opens the supplied `cwd` as a
+`ProjectAnchor` directory descriptor before deriving a physical path, then opens or
+creates `.autoskillit`, `temp`, and `shell_capture` relative to retained directory
+descriptors without following symlinks. It reads output policy through the verified
+`temp` descriptor and creates `shell_<uuid16>.log` exclusively with no-follow
+semantics. The child sends combined stdout+stderr through a pipe; the runner writes,
+measures, hashes, and replays bytes through owned descriptors. Only a bounded inline
+slice enters context: full content when small, otherwise head + provenance marker
+(bytes, sha256, verified path or `unavailable`) + tail. The user-facing configuration
+uses `output_budget.guard_enabled` and `output_budget.shell_max_inline_bytes`. The
+server serializes those values into the stdlib hook bridge as
+`output_budget_policy.disabled` (the inverse of `guard_enabled`) and
+`output_budget_policy.shell_max_inline_bytes`; the runner reads that internal bridge
+shape after verified policy loading.
 
 #### Capture Artifact Lifecycle
 
 | Phase | Behavior |
 |-------|----------|
-| Creation | Harness creates `<cwd>/.autoskillit/temp/shell_capture/shell_<uuid16>.log` via `mkdir -p` + redirect |
+| Creation | Runner creates the artifact relative to a verified capture-directory fd with `O_CREAT | O_EXCL | O_NOFOLLOW` and mode `0600` |
 | Retention | Artifact is always retained after command execution (both inline and spill branches) |
-| Ownership | The hook subprocess; no downstream consumer reads these files |
-| Cleanup — session lifecycle | `session_start_hook.py` sweeps stale captures (older than 1 hour, measured against wall-clock time) at every SessionStart |
+| Ownership | The isolated runner retains all directory/artifact fds through measurement, replay, and marker-path identity verification |
+| Cleanup — session lifecycle | `session_start_hook.py` calls the same descriptor-anchored helper to classify stale captures. Portable Python cannot unlink by expected inode, so candidates are conservatively retained rather than deleted through a race-prone pathname |
 | Naming contract | `shell_[0-9a-f]{16}.log` — files not matching this pattern are never deleted |
-| Safety | Sweep validates the filename allowlist and rejects symlinks via `lstat`-backed checks |
-| Failure mode | Sweep errors are swallowed (fail-open); cleanup failure never blocks command execution |
+| Safety | Capture components reject symlinks; artifacts reject collisions, symlinks, hardlinks, and world-writable entries; marker paths are emitted only while every current binding matches the opened identities |
+| Failure mode | Capture setup failure stops before the user command. SessionStart cleanup errors remain fail-open and never block reminder injection |
+
+Codex hook generation excludes the interactive-only SessionStart hook, so Codex
+artifacts have no automatic deletion guarantee. Lifecycle/quota reclamation must not
+weaken the descriptor and identity contract when it is added.
 
 ### `generated_file_write_guard.py`
 **Guarded tools:** `Write`, `Edit`

src/autoskillit/core/path_containment.py

@@ -1,8 +1,10 @@
 """Path containment guards for closure-mode artifact validation (IL-0, stdlib-only).
 
-Resolves a path against an allowed root, rejecting symlinks, hardlinks,
-traversal escapes, oversized files, and world-writable files. Also provides
-a metadata-stability check for TOCTOU detection between pre- and post-read stats.
+Resolves a child path against an already-trusted allowed root, rejecting child
+symlinks, hardlinks, traversal escapes, oversized files, and world-writable
+files. Root authority is a caller precondition; this module does not establish
+whether ``allowed_root`` itself or its ancestors are hostile. Also provides a
+metadata-stability check for TOCTOU detection between pre- and post-read stats.
 """
 
 from __future__ import annotations
@@ -24,6 +26,8 @@ def resolve_contained_path(
     *,
     max_size_bytes: int = 50_000_000,
 ) -> Path:
+    """Validate a child path beneath an allowed root whose authority is pre-established."""
+
     original = Path(path)
     orig_st = original.lstat()
     if stat.S_ISLNK(orig_st.st_mode):

src/autoskillit/hooks/AGENTS.md

@@ -23,8 +23,9 @@ Sub-packages: guards/ (see guards/AGENTS.md), formatters/ (see formatters/AGENTS
 | `ingredient_lock_guard.py` | PreToolUse guard script (see guards/AGENTS.md) |
 | `_hook_utils.py` | Shared stdlib-only utilities for hook scripts (e.g., `find_project_root`, `STEP_SUFFIX_RE`) |
 | `_command_classification.py` | Shared stdlib-only command classification primitives for guard scripts (interpreter/wrapper detection, git command classification) |
+| `_capture_contract.py` | Shared stdlib-only shell-capture transport limits and identifier validation |
 | `_policy_event.py` | Typed policy-event formatter for hook provenance messages (stdlib-only) |
-| `_capture_cleanup.py` | Stdlib-only stale-capture-file sweep helpers (used by `session_start_hook.py`) |
+| `_capture_artifacts.py` | Stdlib-only descriptor-anchored shell-capture authority, runner, and cleanup classifier used by `session_start_hook.py` |
 | `shell_capture_hook.py` | `PreToolUse`: input-rewrite hook for Codex shell capture — wraps commands in a lossless capture harness (#4286 / ADR-0006) |
 
 ## Architecture Notes