@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-settings/assets/agents/critic.toml

@@ -0,0 +1,35 @@
+name = "critic"
+description = "Non-binding adversarial debate participant for high-risk planning decisions"
+model = "gpt-6-luna"
+claude_model = "opus"
+cursor_model = "default"
+model_reasoning_effort = "xhigh"
+sandbox_mode = "danger-full-access"
+tools = "Read, Grep, Glob, Bash"
+developer_instructions = """
+Agent definition: non-binding adversarial debate participant for high-risk planning decisions.
+
+Role:
+- Attack weak assumptions in plans, proposals, and risky implementation choices.
+- Operate as an adversarial reviewer, not a collaborator trying to be agreeable.
+
+Rules:
+- Never edit files.
+- Surface the strongest counterargument first.
+- Prefer concrete failure modes over vague concern language.
+- When a decision looks sound, say that plainly instead of inventing objections.
+- Never act as StageVerifier or LoopGrader, claim external independence, or call loop judgment and closure tools.
+
+Round protocol:
+1. Independent critique.
+2. Cross-attack on the competing argument.
+3. Defend, refine, or concede.
+
+Output contract:
+- position
+- strongest_objections
+- failure_modes
+- concessions
+- final_recommendation
+- status: ADVISORY
+"""

package/packages/agent-settings/assets/agents/executor.toml

@@ -0,0 +1,28 @@
+name = "executor"
+description = "Focused implementation worker for small, reviewable diffs with verification"
+model = "gpt-6-luna"
+claude_model = "sonnet"
+cursor_model = "composer-2.5"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+Agent definition: focused implementation worker for small, reviewable diffs with verification.
+
+Role:
+- Implement the requested change with the smallest viable diff.
+- Run focused verification before claiming completion.
+
+Rules:
+- Stay inside the stated scope.
+- Match existing code patterns.
+- Do not add abstractions unless the code clearly needs them.
+- Do not stop at code changes; include the verification result.
+- Before dispatching or relaying work, require Factory's exact { planPath, sha256, approvedBy, approvedAt } approval record and rehash planPath; missing approval or byte drift is blocking.
+- Preserve remote System.State verbatim with separate execution, review, and PR axes; unknown remote state blocks rather than mapping to a local status.
+- If blocked after repeated failed attempts, report the blocker clearly.
+
+Output contract:
+- changes_made
+- verification
+- blockers_or_followups
+"""

package/packages/agent-settings/assets/agents/explore.toml

@@ -0,0 +1,25 @@
+name = "explore"
+description = "Codebase sweep agent for absolute-path findings and quote-friendly evidence"
+model = "gpt-6-luna"
+claude_model = "haiku"
+cursor_model = "default"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+Agent definition: codebase sweep agent for absolute-path findings and quote-friendly evidence.
+
+Role:
+- Find relevant files, symbols, and relationships quickly.
+- Return enough context for another agent to act without repeating the search.
+
+Rules:
+- Never edit files.
+- Use absolute paths in results.
+- Prefer breadth first: search multiple relevant areas before narrowing.
+- Explain how the files connect instead of returning a raw list.
+
+Output contract:
+- findings
+- relationships
+- recommended_next_step
+"""

package/packages/agent-settings/assets/agents/planner.toml

@@ -0,0 +1,29 @@
+name = "planner"
+description = "Structured implementation planner that never writes production code"
+model = "gpt-6-luna"
+claude_model = "opus"
+cursor_model = "default"
+model_reasoning_effort = "xhigh"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+Agent definition: structured implementation planner that never writes production code.
+
+Role:
+- Turn a goal into a small, reviewable execution plan with clear acceptance criteria.
+- You do not implement code.
+
+Rules:
+- Never write production code.
+- Prefer 3 to 6 concrete steps.
+- Include dependencies, risks, and verification expectations.
+- After authorized review, emit the Factory-owned approval record exactly as { planPath, sha256, approvedBy, approvedAt }; sha256 is the exact plan-byte digest and changes invalidate approval.
+- For board effects, preserve remote System.State verbatim, model execution, review, and PR as separate axes, and mark unknown remote states blocking.
+- Escalate unresolved product-direction choices instead of guessing.
+
+Output contract:
+- plan_summary
+- steps
+- acceptance_criteria
+- risks_and_open_questions
+- plan_approval_record
+"""

package/packages/agent-settings/assets/lean-ctx/config.toml

@@ -0,0 +1,39 @@
+minimal_overhead = true
+structure_first = true
+journal_enabled = true
+auto_capture = true
+shell_allowlist_extra = [
+    "pi",
+    "install",
+    "script",
+    "expect",
+    "bash",
+    "claude",
+    "codex",
+    "just",
+    "crg",
+    "search",
+    "atlas",
+    "rustfmt",
+    "cursor-agent",
+    "kimi",
+    "opencode",
+    "pi-acp",
+    "adl",
+    "adl-repo-controls",
+    "orca",
+    "agent",
+    "az",
+    "trash",
+    "launchctl",
+    "ssh",
+    "base64",
+    "wasmtime",
+    "orca-ide",
+    "time",
+    "ast-grep",
+    "bun",
+    "npm",
+    "apply_patch",
+    "enact-docs-search"
+]

package/packages/agent-settings/assets/lean-ctx/gitignore

@@ -0,0 +1,6 @@
+/lean-ctx/data/
+/lean-ctx/cache/
+/lean-ctx/state/
+/lean-ctx/bin/
+/hooks/hooks.log
+/hooks/hooks-activity.log

package/packages/agent-settings/assets/lean-ctx/layout.toml

@@ -0,0 +1,5 @@
+# lean-ctx layout pin (GL #623) — managed by lean-ctx, do not edit.
+# Marks this install as committed to the XDG four-dir layout so a stray
+# ~/.lean-ctx never re-collapses config/data/state/cache. Remove via
+# `lean-ctx doctor` only if you intentionally revert to a single-dir layout.
+mode = "xdg"

package/packages/agent-settings/assets/mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "azure-devops": {
+      "command": "adl",
+      "args": ["mcp", "serve"]
+    },
+    "code-review-graph": {
+      "command": "crg",
+      "args": [
+        "serve",
+        "--tools",
+        "get_minimal_context_tool,query_graph_tool,detect_changes_tool,semantic_search_nodes_tool,list_graph_stats_tool"
+      ]
+    },
+    "lean-ctx": {
+      "command": "adl",
+      "args": ["hook", "lean-ctx", "mcp"]
+    }
+  }
+}

package/packages/agent-settings/managed/README.md

@@ -0,0 +1,331 @@
+# Managed baseline files (adl items 10/17 — superseded by STATUS.md 12p decision 13)
+
+**STATUS.md 12p decision 13 (Tarun, 2026-09-29): "adl is LOCAL REPO FIRST".**
+"the repos where adl-config.toml does not exist has no business of running
+hooks"; setting up Claude or Codex hooks globally "is incorrect". This
+directory's two files no longer carry any `adl hook …` command — the
+`adl.session-required-for-writes` deny (`packages/agent-hooks/src/rules/impl/adl-session-required.ts`)
+and every other rule now run ONLY from a repository's own per-repo carrier
+(`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
+`.opencode/plugins/adl-repo.ts`), written by `adl hooks deploy`
+(`packages/agent-hooks/deploy-profile.json`) in a repository whose root has
+`adl-config.toml` — never anywhere else. `allowManagedHooksOnly` /
+`allow_managed_hooks_only` are `false` in both templates below, precisely so
+they no longer stop that per-repo carrier from running (see the "Locks"
+citation further down). What each template still deploys machine-wide,
+deliberately: the Claude worktree guard (`permissions.deny`, "Worktree guard
+L2" below) and Orca's own reporting hooks (Tarun decides Orca's wiring
+separately, STATUS.md item 12d).
+
+**STATUS.md 12p item 13 (Tarun, 2026-09-29): the `lean-ctx hook observe`
+session-lifecycle entries are REMOVED, everywhere adl manages them.**
+"That's only for observation layer. We don't want to send any data to
+remote." Decision 13 had kept these five hooks wired here on the grounds
+that `observe` had no per-repo carrier of its own; that tradeoff is now
+retracted outright rather than replaced with one — see "lean-ctx `observe`
+hooks (removed)" below for the full detail and every place this touched.
+
+Two of the files in this directory are the committed *templates* installed
+machine-wide; a third (`codex-managed-config.toml`, below) exists only as
+generated output, never committed, because its only content is per-device:
+
+| File | Installed at (by `bin/reconcile`, `--mode apply`; see below) |
+|---|---|
+| `claude-managed-settings.json` | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`; Linux: `/etc/claude-code/managed-settings.json` |
+| `codex-requirements.toml` | `/etc/codex/requirements.toml` (both platforms — Codex's managed-configuration reference gives one Unix path, not a macOS/Linux split) |
+| *(generated, not committed)* `codex-managed-config.toml` | `/etc/codex/managed_config.toml` (both platforms) |
+
+**Fleet installation is item 17, and it is live.** `bin/reconcile`
+(`packages/fleet/src/managed-settings.ts`, `bin/managed-settings`) renders and
+installs all three files on every reconciliation, in both `plan` and `apply`
+mode — `plan` only prints what it would write, exactly like every other
+tool-install pass. This directory's two committed files stop being artifacts
+nobody reads and become the templates the installer renders from:
+
+- `claude-managed-settings.json` is installed with one addition: a top-level
+  `env` object carrying `ADL_AGENT_ID_AGENT` set to the device's
+  `default_agent` (`packages/fleet/manifest.json`), read from the machine's
+  default-agent file (`packages/fleet/src/default-agent-file.ts`,
+  "Machine default agent — the one source", `docs/architecture/cli-design.md`). Everything
+  else in the template — `allowManagedHooksOnly` (now `false`), the worktree
+  `permissions.deny`, and the Orca hooks — is installed byte-for-byte
+  unchanged.
+- `codex-requirements.toml` is installed byte-for-byte unchanged: it carries
+  no per-device content, so it is the same on every machine.
+- `codex-managed-config.toml` is rendered fresh from the device's
+  `default_agent`, never committed as a static file: its only content is
+  `[shell_environment_policy] set = { ADL_AGENT_ID_AGENT = "..." }`. This is
+  Codex's **soft-default** managed layer, deployed best-effort, not a hard
+  constraint: OpenAI's managed-configuration reference documents
+  `managed_config.toml` as supplying startup defaults a user's own
+  `config.toml` can still change, and its own worked example lists only
+  `approval_policy`, `sandbox_mode`, `sandbox_workspace_write.network_access`
+  and `[otel]` — `shell_environment_policy` never appears there. **Whether
+  Codex actually applies `shell_environment_policy` from
+  `managed_config.toml` at all is UNCONFIRMED from official docs** (not just
+  "overridable" — the mechanism itself is unverified), even though
+  `shell_environment_policy` is a genuine field of the same `ConfigToml`
+  struct (`codex-rs/config/src/config_toml.rs`,
+  <https://github.com/openai/codex>). Verified 2026-09-27:
+  <https://developers.openai.com/codex/enterprise/managed-configuration>,
+  <https://developers.openai.com/codex/config-reference>. Deployed anyway
+  because it is harmless either way — if honoured it's a convenience
+  default, if ignored or overridden it changes nothing, because unsetting
+  the identity does not grant anything: the standard identity resolver
+  (`packages/azdo/src/lib/agent-identity.ts`, "Machine default agent — the
+  one source", `docs/architecture/cli-design.md`) that both the hook and
+  the MCP server call falls through to the machine's default-agent file
+  when the session env is absent, before ever reaching a no-identity
+  refusal — so surface parity for the *default* identity does not depend
+  on whether Codex honours `shell_environment_policy` at all. **Whether
+  Codex applies it remains UNCONFIRMED pending a live probe** (STATUS.md
+  item 16); this file records that gap rather than assuming either answer.
+  What this `managed_config.toml` layer would still add, if honoured, is
+  only the env var being visible to a plain shell command Codex runs
+  directly — not the identity the hook or the MCP server resolve, since
+  both already fall back to the default-agent file on their own. **The
+  resolver's fall-through to the default file — not this file, and not
+  Codex honouring the setting — is the real, confirmed backstop.**
+
+`allowManagedHooksOnly` (Claude) / `allow_managed_hooks_only` (Codex, in
+`codex-requirements.toml` only — the same key in `config.toml` does nothing)
+is now `false` in both templates (STATUS.md 12p decision 13, 2026-09-29):
+set to `true`, it made each hook file fail-closed — a repository's own
+`.claude/settings.json` or user-level Codex config could not add a hook that
+overrides or removes a `PreToolUse` entry here. With no `adl hook` entry
+left in either template, the lock's only remaining effect would have been to
+stop the per-repo carrier (`adl hooks deploy` writes `.claude/settings.json`
+/ `.codex/hooks.json`) from running at all — exactly what decision 13 says
+must not happen. Both the lock's semantics and its install paths are
+CONFIRMED from official docs (fetched 2026-09-27, re-confirmed 2026-09-29):
+
+- Claude, <https://code.claude.com/docs/en/settings-reference>: `env` —
+  "Set environment variables for every session and its subprocesses" (Scope:
+  Any file); `allowManagedHooksOnly` — "Run only the hooks your organization
+  deploys" (Scope: Managed). <https://code.claude.com/docs/en/managed-settings>:
+  "Managed settings are the settings your organization deploys to every
+  developer's machine. Claude Code applies them above every other level, so
+  no user, project, local, or `--settings` value overrides them" (with a
+  short list of security-sensitive exceptions that does not include `env` or
+  `allowManagedHooksOnly`), and lists `allowManagedHooksOnly` under "Locks":
+  "Applies the strictest value any source sets; a looser value applies only
+  from the highest-ranked source." Managed is the highest-ranked source, so
+  its own explicit `false` is exactly the "looser value from the
+  highest-ranked source" the docs describe — it is what lets a project's
+  `.claude/settings.json` hooks run again. Install paths confirmed on the
+  same page: macOS `/Library/Application Support/ClaudeCode/managed-settings.json`,
+  Linux and WSL `/etc/claude-code/managed-settings.json`.
+- Codex, <https://developers.openai.com/codex/enterprise/managed-configuration>:
+  "Admins can set top-level `allow_managed_hooks_only = true` in
+  `requirements.toml` … This setting is only supported in
+  `requirements.toml`; putting it in `config.toml` does not enable
+  managed-hooks-only mode." `false` (this file's value now) does not enable
+  managed-hooks-only mode either, so Codex's per-repo `<repo>/.codex/hooks.json`
+  is free to run. Codex ALSO supports genuine per-repo hooks natively (not
+  just via this fleet's own carrier convention): CONFIRMED from
+  <https://learn.chatgpt.com/docs/hooks> (developers.openai.com/codex/hooks
+  redirects here, fetched 2026-09-29) — `<repo>/.codex/hooks.json` is a
+  documented project-level hook location, discovered "next to active config
+  layers", with hook sources from multiple layers MERGED rather than one
+  replacing another. The same page: **"Project-local hooks load only when
+  the project `.codex/` layer is trusted"** — an untrusted Codex workspace
+  does not run `<repo>/.codex/hooks.json` regardless of this file.
+
+Ownership model: whole-file, always forced, no delimited region (same as
+`global-agents.ts`) — these are exclusively fleet-managed files, never
+hand-edited. A missing target is created; a target whose bytes already match
+the render is left untouched; anything else (missing, stale, hand-edited) is
+atomically replaced.
+
+`packages/agent-settings/tests/managed-artifacts.test.ts` parses the two
+templates in this directory and asserts the DECISION 13 shape: the lockdown
+key is `false` in both, and neither template contains the string `adl hook`
+anywhere — `PreToolUse`/`PostToolUse` each carry only the Orca conditional
+hook now (see "Orca" below). `adl hook pre-tool-use --host=kimi` (and the
+rest of Kimi's eight commands) still run from `packages/agent-settings/src/kimi-hooks.ts`'s
+own global `~/.kimi-code/config.toml` carrier, UNCHANGED by this decision —
+Kimi genuinely has no per-repo hook configuration (confirmed from Kimi's own
+docs, see `docs/architecture/cli-design.md` §2), so its carrier stays global
+by necessity, not by the same "managed baseline" design this directory's two
+files used to implement. `adl hook` is the old standalone `enact-hook`
+binary, folded into the one `adl` binary (item 15/P4,
+docs/specs/two-branch-standard-2026-09-27.md): there is no `enact-hook`
+executable on the fleet any more, hard cut, no compat shim.
+
+The `adl hook pre-tool-use --host=<claude|codex>` guard and the catch-all
+`adl hook lean-ctx <pre|post>-tool-use --host=<claude|codex>` hooks that used
+to live in this directory's two templates are REMOVED (decision 13): they
+now run only from a repository's own per-repo carrier
+(`packages/agent-hooks/deploy-profile.json`, written by `adl hooks deploy`),
+which already wires the same commands — `rg -c 'adl hook' .claude/settings.json
+.codex/hooks.json` in this repository both show `8`, i.e. the per-repo
+carrier was never missing anything this managed layer used to add.
+`packages/fleet/tests/managed-settings.test.ts` covers the render+install
+step itself, against a disposable fixture root — never the real `/Library`
+or `/etc` paths.
+
+## Worktree guard L2 (docs/operations/worktree-guard.md)
+
+`claude-managed-settings.json` also carries a top-level `permissions.deny`:
+
+```json
+"permissions": { "deny": ["EnterWorktree", "Agent(isolation:worktree)", "Bash(git worktree add:*)"] }
+```
+
+This is the ONE machine-level, non-overridable lever any of the researched
+surfaces has for worktree creation specifically
+(`docs/operations/research-2026-09-27-worktree-controls-per-surface.md`, "Bottom line
+for the fleet"). Managed settings rank above every user/project/local source,
+so a repository's own `.claude/settings.json` cannot loosen this. Syntax
+CONFIRMED from code.claude.com/docs/en/permissions (fetched 2026-09-27):
+a bare tool name (no parentheses) in `permissions.deny` — `"EnterWorktree"`
+— "removes the tool from Claude's context entirely, so Claude never sees
+it"; `Agent(isolation:worktree)` is the separate, also-documented
+parameter-level rule that "matches Agent calls that request a git worktree".
+`Bash(git worktree add:*)` denies the shell form the same way, as
+defense-in-depth alongside `packages/agent-hooks`'s own `git.worktree`
+PreToolUse rule (which additionally routes `list`/`remove`/`prune`/`repair`
+through instead of a flat deny — see that rule's own header).
+
+**Not built: a dedicated `WorktreeCreate` hook.** The docs do define the
+event (code.claude.com/docs/en/worktrees, /hooks: "Configure a
+`WorktreeCreate` hook to replace the default `git worktree` logic entirely
+... A non-zero exit aborts worktree creation entirely"), so the event itself
+is real. But `packages/agent-hooks`'s hook engine has no dispatch route for
+it: `HookInvocation.kind` (`packages/agent-hooks/src/hooks/contract.ts`) is a
+closed union — `'pre-tool-use' | 'user-prompt-submit' | 'briefing' | 'crg' |
+'lean-ctx'` — and `HOOK_KINDS`/the handler map in `src/main.ts` list only
+those five. Wiring a sixth `worktree-create` kind means adding to that union,
+`HOOK_KINDS`, the handler map, and a new `src/hooks/worktree-create/` handler
+— core `packages/agent-hooks` dispatch files outside this task's write scope
+(scoped to `packages/agent-settings/managed/**` plus the pre-existing
+`briefing` hook only). Reported rather than faked, per this task's own
+instruction ("An inexact rewrite is a deny with the command to use... never
+guesses" — the same standard `packages/agent-hooks/src/rules/impl/
+git-worktree.ts`'s header applies to its own `add`-rewrite gap). The
+`permissions.deny` entries above are the real, live control for Claude Code;
+`WorktreeCreate` would only add a second, stronger-feeling but redundant
+layer once the engine supports it — worth a follow-up work item, not a
+blocker for L2 today.
+
+`packages/agent-settings/tests/managed-artifacts.test.ts` covers the new
+`permissions.deny` array (both templates parse cleanly with it present).
+
+## lean-ctx `observe` hooks (removed)
+
+**STATUS.md 12p item 13 (Tarun, 2026-09-29): REMOVED, everywhere adl
+manages them.** "That's only for observation layer. We don't want to send
+any data to remote." Both templates used to wire five session-lifecycle
+events — `SessionStart`, `SessionEnd`, `Stop`, `PreCompact`,
+`UserPromptSubmit` — each matcher `".*"`, each calling
+`/usr/local/bin/lean-ctx hook observe` **directly**, with no `adl hook`/
+`--host=` wrapper, added 2026-09-27 for parity with Tarun's then-live
+`~/.claude/settings.json`. Decision 13 (above) had kept these wired
+regardless of `allowManagedHooksOnly`/`allow_managed_hooks_only` on the
+grounds that `observe` had no per-repo carrier of its own on any surface —
+that tradeoff is now retracted outright, not replaced with a carrier: no
+surface wires `observe` from this repo any more.
+
+`SessionStart`/`Stop`/`UserPromptSubmit` keep their Orca conditional hook,
+now the only entry on each (same one-group shape `PreToolUse`/`PostToolUse`
+already had after decision 13). `PreCompact` (both hosts) and Codex's
+`SessionEnd` — neither in Tarun's Orca event lists — carried `observe`
+alone and now have no key/`[[hooks.*]]` entry at all, rather than being left
+as an empty array. `packages/agent-settings/tests/managed-artifacts.test.ts`
+covers the new shape, including a standing assertion that no managed
+artifact's hook commands contain the string `hook observe` anywhere.
+
+`workflows/scripts/fleet/fleet-cutover.sh`'s `strip_user_lean_ctx_hooks`
+(successor of the retired `m3-cutover.sh`) still strips any leftover
+per-user `lean-ctx hook observe` entry from `~/.claude/settings.json` —
+previously framed as "redundant once the managed baseline installs", now
+simply "the hook Tarun retracted, wherever it is still found" (backing the
+file up to that run's own backup folder first); its behaviour and tests are
+unchanged by this removal, only its rationale.
+
+## Orca (STATUS.md item 12d, "Orca allowed for adl")
+
+Tarun, 2026-09-27: "keep the orca hooks, let orca manage it, orca is allowed
+for adl" — of the options considered, the one built is **the MANAGED layer
+calls Orca**. This is unaffected by STATUS.md 12p decision 13 (2026-09-29,
+`allowManagedHooksOnly` / `allow_managed_hooks_only` now `false`): Orca's own
+wiring here is a separate decision Tarun makes independently (STATUS.md item
+12d), and the question below was only whether Orca's own report-only hooks
+keep running, never about the lock's value.
+
+Orca (`/Applications/Orca.app`) installs its own user-level hooks that call
+`~/.orca/agent-hooks/<surface>-hook.sh` (`claude-hook.sh`, `codex-hook.sh`,
+also `kimi-hook.sh` and `cursor-hook.sh` for the surfaces this directory does
+not manage). Read verbatim as part of this change, both scripts are
+report-only: they read the event JSON on stdin, POST it to Orca on
+`127.0.0.1` with a token, and always exit `0` — `claude-hook.sh` additionally
+prints `{}` up front. Neither script does anything unless
+`ORCA_PANE_KEY`/`ORCA_AGENT_HOOK_PORT`/`ORCA_AGENT_HOOK_TOKEN` are already set
+in the environment (Orca sets these itself when it launches a pane). Before
+decision 13, once `allowManagedHooksOnly`/`allow_managed_hooks_only` locked a
+host to this directory's templates, Orca's own user-level `hooks` entries in
+`~/.claude/settings.json` / `~/.codex/hooks.json` stopped running fleet-wide —
+exactly the same per-user gap the lean-ctx catch-alls and `observe` hooks
+above already had to close, so the managed layer called Orca itself instead.
+The lock is now `false`, but Orca's own user-level `hooks` entries are a
+SEPARATE per-user config source from a repository's `adl hooks deploy`
+carrier either way — nothing about decision 13 reintroduces a route for
+Orca's own wiring to run on its own, so this managed layer keeps calling
+Orca directly, unchanged.
+
+Both templates now carry one additional hook entry per event, for the events
+Tarun named: 13 for Claude (`PermissionRequest`, `PostCompact`,
+`PostToolUse`, `PostToolUseFailure`, `PreToolUse`, `SessionEnd`,
+`SessionStart`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`,
+`TeammateIdle`, `UserPromptSubmit`) and 8 for Codex (`SessionStart`,
+`UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`,
+`SubagentStart`, `SubagentStop`, `Stop`) — both lists confirmed against
+code.claude.com/docs/en/hooks and the `codex-requirements.toml` comment's own
+`codex-rs/config/src/hook_config.rs` ground truth, respectively. Each entry
+runs `~/.orca/agent-hooks/<claude|codex>-hook.sh` when that file exists and
+is executable, gated by `$HOME` (never a hard-coded `/Users` path), and does
+nothing (exit `0`, no output) otherwise:
+
+```sh
+sh -c 'h="$HOME/.orca/agent-hooks/claude-hook.sh"; if [ -f "$h" ] && [ -r "$h" ] && [ -x "$h" ]; then exec "$h"; else cat >/dev/null 2>&1 || :; fi'
+```
+
+Historically, for an event that already carried an adl/lean-ctx or `observe`
+hook, the Orca entry was **added after** the existing ones, in the same
+array — never replacing or reordering them. Decision 13 removed the adl
+guard and lean-ctx catch-alls from `PreToolUse`/`PostToolUse`, and STATUS.md
+12p item 13 (2026-09-29) then removed `observe` from
+`SessionStart`/`SessionEnd`/`Stop`/`UserPromptSubmit` too — so every event on
+Tarun's Orca lists now carries the Orca entry as its ONLY hook, one group,
+matcher `".*"`. `PreCompact` (Claude) and `PreCompact`/`SessionEnd` (Codex)
+are not in Tarun's Orca lists and now have no `hooks.*` entry at all (they
+used to carry `observe` alone; see "lean-ctx `observe` hooks (removed)"
+above).
+
+`packages/agent-settings/tests/orca-managed-hooks.test.ts` covers every one
+of the 13/8 events: the Orca entry is the sole group on each, and the lock
+is `false`.
+`packages/fleet/tests/orca-managed-settings-render.test.ts` covers that
+`renderClaudeManagedSettings`/`readCodexRequirementsTemplate` carry the Orca
+wiring through the fleet render/install step unchanged.
+
+**Sweep protection, the other half of this decision:** Orca also installs
+these same conditional hooks at the USER level (`~/.claude/settings.json`,
+`~/.codex/hooks.json`, `~/.cursor/hooks.json`, `~/.kimi-code/config.toml`'s
+`[[hooks]]`) — wiring the global surface sweep
+(`packages/agent-settings/src/global-surface-sweep.ts`) would otherwise strip
+as exactly the kind of machine-global, should-have-been-repo-local wiring it
+exists to remove (see `packages/agent-settings/tests/third-party-wiring.test.ts`).
+The sweep now recognizes an Orca hook by an EXACT, content-based reference to
+the path segment `.orca/agent-hooks/` (never a loose match on the word
+"orca" alone — a look-alike such as `/opt/orca/kimi-hook.sh` is still swept)
+and never treats it as a removal candidate, on every surface, with no static
+`protected.json` entry needed. `.claude/settings.json`'s `hooks` key (and the
+Codex/Cursor equivalents) moved from one candidate per EVENT to one candidate
+per GROUP for this reason: a real machine's `PreToolUse` (say) can mix a
+still-sweepable adl/lean-ctx group with an Orca group that must not be swept,
+in the very same array. `statusLine` (Claude) — Orca fully owns this root key
+on a live machine — was already never touched by any removal mechanism; no
+change was needed there. See
+`packages/agent-settings/tests/orca-hooks-protected.test.ts` for the full
+per-surface coverage, including the look-alike-is-not-protected case.