@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.26

package/packages/agent-hooks/src/rules/impl/adl-git-credential-bypass.ts

@@ -1,8 +1,8 @@
 /**
- * `adl.git-credential-bypass` — H2 (STATUS.md 12p): deny, for agents, every
+ * `adl.git-credential-bypass` — deny, for agents, every
  * shell shape that reaches Azure DevOps credentials or bypasses
  * `bin/git-ado`'s routing entirely, without touching any of the specific
- * verbs `adl.session-required-for-writes`/`adl.git-identity` already police:
+ * verbs `adl.run-required-for-writes`/`adl.git-identity` already police:
  *
  *  - An absolute git binary other than the managed front controller
  *    `/usr/local/bin/git` (that IS the path `bin/git-ado` installs itself
@@ -13,7 +13,7 @@
  *    untouched.
  *  - `git remote update` — fetches every configured remote, the same
  *    network operation as `git fetch`, but not a verb
- *    `adl.session-required-for-writes`'s `NETWORK_GIT_VERBS` recognizes.
+ *    `adl.run-required-for-writes`'s `NETWORK_GIT_VERBS` recognizes.
  *  - `git submodule update/sync/foreach` — `update`/`sync` can fetch a
  *    submodule's own remote; `foreach` runs an arbitrary shell command once
  *    per submodule, unauditable by this hook.
@@ -21,7 +21,7 @@
  *    credential directly, sidestepping the front controller entirely.
  *
  * `security find-generic-password`/`find-internet-password` naming Azure
- * DevOps (the fifth H2 item — a macOS Keychain read, not a git operation at
+ * DevOps (a macOS Keychain read, not a git operation at
  * all) is `adl.security-keychain-ado` below, in the same file since it
  * shares `namesAzureDevops`, but registered as its own `category: 'tool'`
  * rule: `tests/unit/rules-git-deny-guidance.test.ts` requires every
@@ -33,14 +33,13 @@
  * an intentional, heavily-tested feature — `tests/unit/rules-git-worktree.
  * test.ts`'s dozens of `git -c alias.wt=worktree`-shaped corpus entries SEE
  * THROUGH a non-network inline alias on purpose). Two narrower, resolved
- * pieces of that space ARE covered, R9 correcting this header's stale
- * "BLOCKED" note (STATUS.md 12p):
+ * pieces of that space ARE covered:
  *  - a SELF-referential inline `-c alias.<verb>=<value>`/`--config-env`
  *    naming the LITERAL subcommand this invocation runs, where `<value>`'s
  *    own verb is network/credential — `adl.git-identity`'s own
  *    `network-alias-redefinition` reason (`../shell/git-identity.ts`), not
  *    this rule.
- *  - R4 (re-review 2026-09-28 night): a REPO-CONFIGURED alias (`.git/config`,
+ *  - a REPO-CONFIGURED alias (`.git/config`,
  *    invisible to the walker's own inline/env-var-only resolution) whose
  *    value's verb is network/credential — `repo-alias-network-verb` below,
  *    resolved via the injectable `ctx.index.configuredAlias` port
@@ -48,7 +47,7 @@
  *    stay hermetic. Still narrower than a blanket deny: a non-network
  *    repo-configured alias (`git st` → `alias.st=status`) is untouched.
  *
- * R4 also adds three more front-controller bypasses here, all sharing the
+ * Three more front-controller bypasses are denied here, all sharing the
  * same reasoning: `/usr/local/bin/git` (`bin/git-ado`) routes on the
  * LITERAL verb/binary an agent typed — it does not resolve `PATH`
  * overrides, `command -p`'s own default `$PATH`, or `xcrun`'s tool
@@ -130,7 +129,7 @@ const CREDENTIAL_HELPER_BINARY_PREFIX = 'credential-'
  * that holds a credential for a short-lived window and exits — `git
  * credential-cache exit` merely stops it); it never reads or writes a
  * platform secret store the way `credential-osxkeychain`/`credential-
- * manager`/… do, and this exact allow case predates R4 (H2's own corpus).
+ * manager`/… do, and this exact allow case is part of this rule's own corpus.
  * Excluded from the deny by name rather than widened into a blanket
  * "every credential-* helper", to avoid regressing that settled behaviour.
  */
@@ -143,9 +142,8 @@ function isDeniedCredentialHelper(subcommandOrName: string): boolean {
 
 /**
  * Git's own real subcommand vocabulary (porcelain and common plumbing),
- * lower-cased — R4 (STATUS.md 12p): gates the repo-
- * configured-alias lookup (`ctx.index.configuredAlias`) to an UNKNOWN verb
- * only, per this finding's own text ("resolve unknown git verbs"), so an
+ * lower-cased — gates the repo-configured-alias lookup
+ * (`ctx.index.configuredAlias`) to an UNKNOWN verb only, so an
  * ordinary `git status`/`git log`/… never pays for a `git config --get`
  * shell-out. Not exhaustive — an obscure real git verb missing here only
  * costs one harmless extra (correctness-preserving) lookup that resolves to
@@ -163,8 +161,8 @@ const KNOWN_GIT_VERBS: ReadonlySet<string> = new Set([
 /**
  * `PATH=`/`export PATH=` anywhere in `command`, co-occurring with a `git`
  * invocation this rule is already deciding — coarse (whole-command, not
- * piece-scoped) by design, matching R3's own precedent elsewhere in this
- * package: a PATH override ahead of `git` ANYWHERE on the line is suspicious
+ * piece-scoped) by design, matching the other coarse textual checks in this
+ * package (see `containsIdentityBearingToken` in `git-helpers.ts`): a PATH override ahead of `git` ANYWHERE on the line is suspicious
  * enough on its own that over-denial costs nothing legitimate.
  */
 function pathOverridePresent(command: string): boolean {

package/packages/agent-hooks/src/rules/impl/adl-git-identity.ts

@@ -8,8 +8,9 @@
  * `adl run -- codex` session ran `git push -u origin feat/adl-m3-finish`
  * through the lean-ctx MCP tool `mcp__lean_ctx__ctx_shell`; Codex gives
  * `ADL_AGENT_ID_AGENT` only to its own shell tool, so the push executed with
- * no identity and `bin/git-ado`'s HUMAN pass-through (bin/git-ado:191-194)
- * pushed with Tarun's own credential helper. The hook knew the session
+ * no identity and `bin/git-ado` (which then passed an unset identity through
+ * to the human's credential helper; it now fails closed unless a real TTY and
+ * `ADL_HUMAN_AZDO=1`) pushed with Tarun's own credential. The hook knew the session
  * identity — it is in the hook's own environment — but passed the command
  * through unchanged. This module is the fix: the command is REWRITTEN to
  * carry the identity (`git push …` → `ADL_AGENT_ID_AGENT=agent-tarun git
@@ -25,9 +26,9 @@
  *     into the human credential), or a `sudo`/`doas` wrapper, which strips
  *     the environment the identity travels in. Both are denies rather than
  *     rewrites: an inexact rewrite is a deny (cli-design.md §1a's rule). With
- *     no session identity at all this rule stays silent —
- *     `adl.session-required-for-writes` denies the write with the
- *     `adl run` hint first.
+ *     no agent identity at all this rule stays silent —
+ *     `adl.run-required-for-writes` denies the write with the
+ *     inline-prefix hint first.
  *
  *  2. The REWRITE stage, computed in `../engine.ts`'s `decideCommand` after
  *     every rule passed: `../shell/git-identity.ts` rewrites the command
@@ -67,7 +68,7 @@ import { NETWORK_GIT_VERBS, scanGitIdentityConflicts, type GitIdentityDenyReason
 
 export const RULE_ID = 'adl.git-identity'
 
-export type GitIdentityRuleReason = Extract<
+type GitIdentityRuleReason = Extract<
   GitIdentityDenyReason,
   'identity-mismatch' | 'unrewritable-wrapper' | 'network-alias-redefinition' | 'dynamic-agent'
 >
@@ -75,14 +76,13 @@ export type GitIdentityRuleReason = Extract<
 /** Messages for the rule's two deny reasons and for the engine rewrite-stage nets (unsafe identity). */
 export function gitIdentityDenyMessage(reason: GitIdentityDenyReason, ctx: MessageContext, identity: string | undefined): RuleMessage {
   if (reason === 'identity-mismatch') {
-    // L1 (STATUS.md 12p): the 2026-09-28 standard
-    // widened this reason to mean ONLY "empty or not a recognized agent" —
-    // a valid inline override that merely NAMES A DIFFERENT agent than the
-    // session's own is no longer a conflict at all (see
-    // applyIdentityOutcome's doc in ../shell/git-identity.ts): it is the
-    // override, and it wins. The old wording ("a different agent identity
-    // ... conflicts with this session") described that earlier, no-longer-
-    // true behavior and was actively misleading about what to actually fix.
+    // Under the one-agent-identity standard (Tarun, 2026-09-28) this reason
+    // means ONLY "empty or not a recognized agent": a valid inline override
+    // that merely NAMES A DIFFERENT agent than the session's own is not a
+    // conflict at all (see applyIdentityOutcome's doc in
+    // ../shell/git-identity.ts) — it is the override, and it wins. The
+    // message therefore says what to fix (an empty or unrecognized value),
+    // not that another agent "conflicts with this session".
     const user = 'the inline ADL_AGENT_ID_AGENT override on this command is empty or not a recognized agent'
     const hint = identity !== undefined ? ` Your session's own resolved identity is ${identity}; remove the override to use it,` : ' Remove the override,'
     return {
@@ -124,22 +124,22 @@ export function gitIdentityDenyMessage(reason: GitIdentityDenyReason, ctx: Messa
         `directly instead of aliasing it inline. Blocked: ${ctx.snippet}`,
     }
   }
-  const user = "the session's agent identity is not a safe shell word"
+  const user = 'the agent identity is not a safe shell word'
   return {
     user,
     agent:
-      `DENIED ${user}: this session's ${ADL_AGENT_ID_ENV_VAR} contains characters outside [A-Za-z0-9_-], ` +
-      'so the hook cannot place it on a command line. The session is misconfigured — start it with `adl run`. ' +
+      `DENIED ${user}: the ${ADL_AGENT_ID_ENV_VAR} value in this environment contains characters outside [A-Za-z0-9_-], ` +
+      `so the hook cannot place it on a command line. Prefix the command with ${ADL_AGENT_ID_ENV_VAR}=<agent-tarun|agent-vivek|agent-reviewer> instead. ` +
       `Blocked: ${ctx.snippet}`,
   }
 }
 
 /**
- * H3 (STATUS.md 12p): the deny rendered by
- * `../engine.ts`'s rewrite stage itself for a `needs-identity` outcome —
+ * The deny rendered by `../engine.ts`'s rewrite stage itself for a
+ * `needs-identity` outcome —
  * an identity-bearing command with no valid inline override and no
  * resolvable fallback (steps 2-3 of the standard). This is defense in
- * depth: `adl.session-required-for-writes` is expected to have already
+ * depth: `adl.run-required-for-writes` is expected to have already
  * denied the same command with this same standard message earlier in the
  * rule pass, but it is a SEPARATE classification that can be disabled per
  * repo or simply miss a shape this scanner recognizes — see engine.ts's own
@@ -159,14 +159,14 @@ export function gitIdentityNeedsIdentityMessage(ctx: MessageContext): RuleMessag
  * tool input, and the identity is not otherwise present in THIS invocation's
  * own environment: an MCP-class tool (Kimi has no `renderRewrite` at all),
  * or a native-shell tool whose identity resolved from the machine
- * default-agent file rather than the session env (C2 — the hook process
+ * default-agent file rather than the session env (the hook process
  * read that file itself; a child process this shell tool spawns never sees
  * `ADL_AGENT_ID_AGENT`, so it would reach Azure DevOps as the human, which
  * is the exact incident this module exists to close). `agent` is the
  * resolved fallback identity (steps 2-3 of the standard) when one resolved
  * — always the case at both call sites, since a `rewrite` decision only
  * exists once a fallback resolved — so the message can name the EXACT
- * prefix to add (M1), not just point at "an agent" in the abstract.
+ * prefix to add, not just point at "an agent" in the abstract.
  */
 export function hostCannotRewriteMessage(host: string, ctx: MessageContext, agent: string | undefined): RuleMessage {
   const prefix = `${ADL_AGENT_ID_ENV_VAR}=${agent ?? '<agent>'}`
@@ -174,7 +174,7 @@ export function hostCannotRewriteMessage(host: string, ctx: MessageContext, agen
   // OpenCode's fail-closed path) writes `message.user`, not `message.agent`,
   // to stderr (see ../../pre-tool-use/handler.ts's `denyHostCannotRewrite`),
   // and that stream is what the agent itself reads on those hosts.
-  const user = `this agent surface (${host}) cannot carry the session identity into this command; prefix it with \`${prefix}\` and retry`
+  const user = `this agent surface (${host}) cannot carry the agent identity into this command; prefix it with \`${prefix}\` and retry`
   return {
     user,
     agent:
@@ -193,16 +193,16 @@ export const adlGitIdentity: RuleSpec = {
   summary: 'Deny an identity-bearing command whose inline ADL_AGENT_ID_AGENT is invalid/empty, or that runs through sudo/doas.',
   params: noParams,
   match(inv, ctx): Finding | null {
-    // WIDENED 2026-09-28 (STATUS.md 12p, W2 build
-    // item 3): every identity-bearing command class, not only network git —
+    // Every identity-bearing command class, not only network git
+    // (widened 2026-09-28 by the one-agent-identity standard) —
     // `adl mcp cli`/`adl repo doctor`/`adl repo controls azdo-push`/`adl id
     // token`, `adl-agent-id exec`, and curl/wget/httpie/xh to
     // dev.azure.com/*.visualstudio.com. This rule no longer requires a
     // resolved fallback identity to run (`identity === null` used to skip
-    // straight to session-required) — an invalid/empty INLINE override is a
+    // straight to run-required) — an invalid/empty INLINE override is a
     // real problem independent of whether a fallback exists; the two rules
     // still cannot both win for the same invocation because the registry
-    // orders session-required first (`../registry.ts`) and the engine's
+    // orders run-required first (`../registry.ts`) and the engine's
     // `firstFinding` stops at the first rule that reports anything at all.
     let isIdentityBearing = false
     if (inv.kind === 'git') {
@@ -213,7 +213,7 @@ export const adlGitIdentity: RuleSpec = {
       if (ADL_BINARY_NAMES.has(inv.name)) {
         isIdentityBearing = !dynamic && matchesIdentityShape(values, ADL_IDENTITY_COMMAND_SHAPES)
       } else if (ADL_AGENT_ID_BINARY_NAMES.has(inv.name)) {
-        // M5 (STATUS.md 12p): leading dash-prefixed
+        // Leading dash-prefixed
         // global flags (`adl-agent-id --verbose exec …`) are skipped before
         // matching the `['exec']` shape — see skipLeadingDashFlags's doc.
         isIdentityBearing = !dynamic && matchesIdentityShape(skipLeadingDashFlags(values), ADL_AGENT_ID_COMMAND_SHAPES)

package/packages/agent-hooks/src/rules/impl/adl-git-push-policy.ts

@@ -4,13 +4,13 @@
  *
  * Scope: this rule only ever looks at a `git push` whose destination is
  * Azure DevOps or UNRESOLVED (the same fail-closed classification
- * `adl.session-required-for-writes` uses, via `classifyGitPushDestination` —
+ * `adl.run-required-for-writes` uses, via `classifyGitPushDestination` —
  * see git-helpers.ts). A push with a PROVEN non-Azure-DevOps destination
  * (e.g. an explicit `https://github.com/...` URL) is entirely outside this
  * table's scope and this rule never fires on it.
  *
  * Requires an identity to already be present (`ADL_AGENT_ID_AGENT`
- * non-blank). With no identity at all, `adl.session-required-for-writes` is
+ * non-blank). With no identity at all, `adl.run-required-for-writes` is
  * the rule that denies the push (a different problem: no session, not the
  * wrong branch or role) — this rule returns null immediately when the env
  * var is absent or blank, exactly like `adl.role-required`-style rules.
@@ -66,8 +66,7 @@ import { defaultGitMessage, detailString } from './messages.ts'
 const RULE_ID = 'adl.git-push-branch-policy'
 
 /**
- * The effective identity for THIS specific push invocation (M2/M3,
- * STATUS.md 12p) — not
+ * The effective identity for THIS specific push invocation — not
  * `effectiveIdentityForCommand`'s whole-command coarse value, which is set
  * from whichever piece on the line happens to carry a valid inline override
  * FIRST and would otherwise be applied to grading EVERY push on a compound
@@ -191,7 +190,7 @@ export const adlGitPushBranchPolicy: RuleSpec = {
     if (inv.kind !== 'git' || inv.subcommand !== 'push') return null
     if (isHelpOnlyInvocation(inv.rest)) return null
 
-    // WIDENED 2026-09-28 (W2 build item 2): grade the EFFECTIVE identity for
+    // Grade the EFFECTIVE identity for
     // THIS command — a valid inline ADL_AGENT_ID_AGENT= override on the push
     // itself wins over the session's own env/default-file resolution (the
     // override is a per-command identity switch: `agent-reviewer may not
@@ -199,9 +198,9 @@ export const adlGitPushBranchPolicy: RuleSpec = {
     // agent-tarun/agent-vivek but the command overrides to agent-reviewer).
     const resolution = resolveFromEnvOrFile(ctx.env)
     const fallback = resolution.ok ? resolution.agent : null
-    // M2/M3: THIS push's own piece, not the whole command's coarse value — see effectiveIdentityForPush's doc.
+    // THIS push's own piece, not the whole command's coarse value — see effectiveIdentityForPush's doc.
     const agent = effectiveIdentityForPush(inv, ctx.command ?? '', fallback)
-    if (agent === null) return null // no identity at all: adl.session-required-for-writes's job
+    if (agent === null) return null // no identity at all: adl.run-required-for-writes's job
 
     const destinationRisk = classifyGitPushDestination(inv.rest)
     if (destinationRisk === 'non-ado') return null // out of this table's scope entirely
@@ -245,11 +244,11 @@ export const adlGitPushBranchPolicy: RuleSpec = {
     // which the shared corpus fixture (tests/fixtures/decide.ts) cannot
     // supply — see tests/unit/rules-adl-git-push-policy.test.ts for the real
     // coverage, built the same way tests/unit/rules-tool-search.test.ts and
-    // rules-adl-session-required.test.ts's az-CLI split are (a custom
+    // rules-adl-run-required.test.ts's az-CLI split are (a custom
     // EngineContext per env value, decide() called directly).
     deny: [],
     // `git fetch origin main` itself is no longer end-to-end allowed without
-    // an identity (adl.session-required-for-writes now covers reads too,
+    // an identity (adl.run-required-for-writes now covers reads too,
     // 2026-09-28) — an explicit non-ADO destination stays provably safe
     // and still proves this rule (which only ever looks at `push`) does not
     // fire on a fetch.