@zgeoff/atc 2.15.2 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.15.2",
+  "version": "2.16.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -43,7 +43,7 @@
     "@better-auth/oauth-provider": "1.7.6",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
-    "@zgeoff/imp-client": "0.24.0",
+    "@zgeoff/imp-client": "0.27.0",
     "better-auth": "1.7.6",
     "bun-pty": "0.4.10",
     "citty": "0.2.2",

package/src/agents/build-hook-settings.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { AgentID } from '../shared/agent-id';
+import { toShellArg } from '../shared/to-shell-arg';
 import { buildCLICommand } from './build-cli-command';
 
 /**
@@ -20,7 +21,9 @@ export interface HookSettingsProfile {
  * The settings object injected into wrangled sessions via
  * `claude --settings`. The user's own settings are untouched; these hooks
  * only exist in sessions atc spawns, and identify themselves via
- * ATC_SESSION_ID in the env.
+ * ATC_SESSION_ID in the env and the agent id on their command line. A
+ * nested harness inherits the env but not the command line, so the agent id
+ * keeps its reports from passing as the session's own.
  *
  * A settings-file env block outranks a shell export of the same variable, so
  * a session's backend is decided here rather than by whatever the terminal
@@ -37,7 +40,13 @@ export function buildHookSettings(
 ): Record<string, unknown> {
   const entry = [
     {
-      hooks: [{ type: 'command', command: buildCLICommand('hook-report', cliArgv), timeout: 5 }],
+      hooks: [
+        {
+          type: 'command',
+          command: buildCLICommand(`hook-report --agent ${toShellArg(profile.id)}`, cliArgv),
+          timeout: 5,
+        },
+      ],
     },
   ];
 
@@ -61,7 +70,7 @@ export function buildHookSettings(
     // padding.
     statusLine: {
       type: 'command',
-      command: buildCLICommand('statusline', cliArgv),
+      command: buildCLICommand(`statusline --agent ${toShellArg(profile.id)}`, cliArgv),
       padding: statuslinePadding,
     },
     ...(profile.env === undefined || Object.keys(profile.env).length === 0

package/src/agents/print-codex-hook-file.ts

@@ -17,7 +17,7 @@ export function printCodexHookFile(): void {
 }
 
 function buildCodexHookFile(): string {
-  const cmd = buildCLICommand('hook-report');
+  const cmd = buildCLICommand('hook-report --agent codex');
   const buildEntry = (timeout: number) => [{ hooks: [{ type: 'command', command: cmd, timeout }] }];
   const hooks = Object.fromEntries(CODEX_HOOK_EVENTS.map((event) => [event, buildEntry(5)]));
 

package/src/agents/print-grok-hook-file.ts

@@ -19,7 +19,7 @@ export function printGrokHookFile(): void {
 }
 
 function buildGrokHookFile(): string {
-  const cmd = buildCLICommand('hook-report');
+  const cmd = buildCLICommand('hook-report --agent grok');
   const entry = [{ hooks: [{ type: 'command', command: cmd, timeout: 5 }] }];
   const hooks = Object.fromEntries(GROK_HOOK_EVENTS.map((event) => [event, entry]));
 

package/src/cli.ts

@@ -291,10 +291,16 @@ const main = defineCommand({
           description: 'Forward a hook event from a wrangled session to the atc socket',
           hidden: true,
         },
-        async run() {
+
+        // No arg is required: a citty usage error exits nonzero, and
+        // reporters must always exit 0.
+        args: {
+          agent: { type: 'string', default: '' },
+        },
+        async run(ctx) {
           const reporter = await import('./hook-report');
 
-          await reporter.runHookReport();
+          await reporter.runHookReport(ctx.args.agent);
         },
       }),
     tap: () =>
@@ -352,10 +358,15 @@ const main = defineCommand({
           description: 'Render the chained statusline for a wrangled session',
           hidden: true,
         },
-        async run() {
+
+        // A statusline command must always exit 0 too, so no arg is required.
+        args: {
+          agent: { type: 'string', default: '' },
+        },
+        async run(ctx) {
           const statusline = await import('./statusline');
 
-          await statusline.runStatusline();
+          await statusline.runStatusline(ctx.args.agent);
         },
       }),
   },

package/src/daemon/broker-authority-error.ts

@@ -0,0 +1,41 @@
+/**
+ * Why impd's credential broker may not be used for a session, or why atc
+ * may not clean up after one:
+ *
+ * - `auth_impd_too_old`: impd lacks grantable tokens or secret rebinds.
+ * - `auth_token_scope`: the token's scope is below `manage`.
+ * - `auth_token_too_broad`: the token can reach imps outside atc's
+ *   namespace, through no imp patterns or a pattern whose literal text
+ *   before its first `*` does not start with the namespace prefix.
+ * - `auth_imp_out_of_scope`: an imp the call touches is outside the
+ *   token's patterns.
+ * - `auth_secret_not_grantable`: a bound secret is not on the token's
+ *   grantable list.
+ * - `auth_runtime_mismatch`: the imp under the recorded name has another
+ *   id than the one recorded.
+ */
+export type BrokerAuthorityCode =
+  | 'auth_impd_too_old'
+  | 'auth_token_scope'
+  | 'auth_token_too_broad'
+  | 'auth_imp_out_of_scope'
+  | 'auth_secret_not_grantable'
+  | 'auth_runtime_mismatch';
+
+/**
+ * A refusal to provision through impd's credential broker or to clean up
+ * after it, carrying its code and the detail the code defines.
+ */
+export class BrokerAuthorityError extends Error {
+  readonly code: BrokerAuthorityCode;
+
+  readonly data: Readonly<Record<string, unknown>>;
+
+  constructor(code: BrokerAuthorityCode, message: string, data: Readonly<Record<string, unknown>>) {
+    super(message);
+
+    this.code = code;
+    this.data = data;
+    this.name = 'BrokerAuthorityError';
+  }
+}

package/src/daemon/collect-secret-rule-mismatches.ts

@@ -0,0 +1,83 @@
+import type { ImpSecret, ImpSecretRule } from './imp-port';
+
+/**
+ * One secret as a resolved binding expects impd to hold it: its kind and
+ * the complete set of rules, one per host.
+ */
+export interface ExpectedSecret {
+  readonly secret: string;
+  readonly kind: ImpSecret['kind'];
+  readonly rules: readonly ImpSecretRule[];
+}
+
+export type SecretRuleMismatch =
+  | { readonly secret: string; readonly reason: 'missing' }
+  | {
+      readonly secret: string;
+      readonly reason: 'kind';
+      readonly expected: ImpSecret['kind'];
+      readonly actual: ImpSecret['kind'];
+    }
+  | {
+      readonly secret: string;
+      readonly reason: 'rules';
+      readonly expected: readonly ImpSecretRule[];
+      readonly actual: readonly ImpSecretRule[];
+    };
+
+/**
+ * Compares the secrets a resolved binding expects with the secrets impd
+ * lists, secret by secret. Each expected secret must exist with the same
+ * kind and exactly the same set of rules, in any order: a rule impd holds
+ * that the binding lacks is a mismatch as much as a missing one, since it
+ * sends the credential to a host the binding never approved. An empty
+ * result means every expected secret matches; secrets the binding does not
+ * expect are ignored.
+ */
+export function collectSecretRuleMismatches(
+  expected: readonly ExpectedSecret[],
+  secrets: readonly ImpSecret[],
+): SecretRuleMismatch[] {
+  const held = new Map(secrets.map((secret) => [secret.name, secret]));
+
+  const mismatches: SecretRuleMismatch[] = [];
+
+  for (const want of expected) {
+    const actual = held.get(want.secret);
+
+    if (actual === undefined) {
+      mismatches.push({ secret: want.secret, reason: 'missing' });
+    } else if (actual.kind !== want.kind) {
+      mismatches.push({
+        secret: want.secret,
+        reason: 'kind',
+        expected: want.kind,
+        actual: actual.kind,
+      });
+    } else if (!hasSameRules(want.rules, actual.rules)) {
+      mismatches.push({
+        secret: want.secret,
+        reason: 'rules',
+        expected: want.rules,
+        actual: actual.rules,
+      });
+    }
+  }
+
+  return mismatches;
+}
+
+function hasSameRules(left: readonly ImpSecretRule[], right: readonly ImpSecretRule[]): boolean {
+  const leftKeys = left.map((rule) => toRuleKey(rule)).toSorted();
+  const rightKeys = right.map((rule) => toRuleKey(rule)).toSorted();
+
+  return (
+    leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index])
+  );
+}
+
+// A rule as one comparable string; JSON keeps a missing user apart from
+// any user a basic rule can hold.
+function toRuleKey(rule: ImpSecretRule): string {
+  return JSON.stringify([rule.host, rule.header, rule.scheme, rule.user ?? null]);
+}

package/src/daemon/daemon.ts

@@ -58,6 +58,7 @@ import { EffectRemainsError } from './effect-remains-error';
 import { EventSignal } from './event-signal';
 import { startHookServer } from './hooks';
 import { IdempotencyLedger } from './idempotency-ledger';
+import { isOwnHookEvent } from './is-own-hook-event';
 import { isTreeInReach } from './is-tree-in-reach';
 import { loadTranscriptPage } from './load-transcript-page';
 import { makeHookRunner } from './make-hook-runner';
@@ -765,6 +766,22 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
 
     const before = mgr.sessions.find((s) => s.id === e.atcId);
+    const runtime = runtimes.get(e.atcId);
+
+    // A harness nested inside a session inherits its environment and reports
+    // under its id; only the harness atc started may change the session.
+    if (
+      before !== undefined &&
+      runtime !== undefined &&
+      !isOwnHookEvent(e.agent, before.agent, runtime.hasAgentHookLines)
+    ) {
+      return;
+    }
+
+    if (runtime !== undefined && e.agent !== undefined) {
+      runtime.hasAgentHookLines = true;
+    }
+
     const previousAgentSessionID = before?.agentSessionID;
     const ev = mgr.applyHook(e);
 
@@ -777,7 +794,6 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
 
     const kind = ev?.kind ?? null;
-    const runtime = runtimes.get(e.atcId);
     const currentAgentSessionID = mgr.sessions.find((s) => s.id === e.atcId)?.agentSessionID;
 
     if (currentAgentSessionID !== undefined && currentAgentSessionID !== previousAgentSessionID) {

package/src/daemon/imp-client-port.ts

@@ -1,14 +1,17 @@
 import { createImpClient, openExecSession, openReverseForward } from '@zgeoff/imp-client';
 import type { ExecOutcome, ImpClient } from '@zgeoff/imp-client';
+import { isRecord } from '../shared/report';
 import type {
   ImpCommand,
   ImpCommandResult,
   ImpCreateSpec,
   ImpFeatures,
+  ImpIdentity,
   ImpLease,
   ImpPort,
   ImpRelayConnection,
   ImpReverseForward,
+  ImpSecret,
   ImpSessionConnection,
   ImpSessionHandlers,
   ImpSessionOutcome,
@@ -48,11 +51,79 @@ export class ImpClientPort implements ImpPort {
     this.readToken = options.readToken;
   }
 
-  // An impd from before the flags has neither.
+  // A flag counts only as a literal true: an impd from before a flag has
+  // it false, and so does one that sends anything else in its place.
   readonly readFeatures = async (): Promise<ImpFeatures> => {
     const info = await this.tryCall((client) => client.system.info());
 
-    return info.features ?? { sessionOffsets: false, leases: false };
+    const features: Readonly<Record<string, unknown>> | undefined = info.features;
+
+    return {
+      sessionOffsets: features?.['sessionOffsets'] === true,
+      leases: features?.['leases'] === true,
+      grantableTokens: features?.['grantableTokens'] === true,
+      secretRebind: features?.['secretRebind'] === true,
+    };
+  };
+
+  // An impd from before grantable lists sends none, which grants nothing.
+  readonly readIdentity = async (): Promise<ImpIdentity> => {
+    const identity = await this.tryCall((client) => client.tokens.whoami());
+
+    return {
+      kind: identity.kind,
+      name: identity.name,
+      scope: identity.scope,
+      imps: identity.imps === null ? null : [...identity.imps],
+      grantable: [...(identity.grantable ?? [])],
+    };
+  };
+
+  readonly readSecrets = async (): Promise<readonly ImpSecret[]> => {
+    const secrets = await this.tryCall((client) => client.secrets.list());
+
+    return secrets.map((secret) => ({
+      name: secret.name,
+      kind: secret.kind,
+      rules: secret.rules.map((rule) => ({
+        host: rule.host,
+        header: rule.header,
+        scheme: rule.scheme,
+        ...(rule.user === undefined ? {} : { user: rule.user }),
+      })),
+      imps: [...secret.imps],
+    }));
+  };
+
+  readonly readGrants = async (name: string): Promise<readonly string[]> => {
+    const grants = await this.tryCall((client) => client.grants.list({ name }));
+
+    return [...grants];
+  };
+
+  readonly createGrant = async (name: string, secret: string): Promise<void> => {
+    await this.tryCall((client) => client.grants.add({ name, secret }));
+  };
+
+  // A grant impd no longer holds is no grant to revoke; a missing imp or
+  // secret still rejects.
+  readonly removeGrant = async (name: string, secret: string): Promise<boolean> => {
+    try {
+      await this.tryCall((client) => client.grants.delete({ name, secret }));
+
+      return true;
+    } catch (error) {
+      if (
+        error instanceof ImpPortError &&
+        error.code === 'NOT_FOUND' &&
+        isRecord(error.data) &&
+        error.data['kind'] === 'grant'
+      ) {
+        return false;
+      }
+
+      throw error;
+    }
   };
 
   readonly readImp = async (name: string): Promise<ImpView | null> => {
@@ -60,6 +131,7 @@ export class ImpClientPort implements ImpPort {
       const imp = await this.tryCall((client) => client.imps.get({ name }));
 
       return {
+        id: imp.id,
         name: imp.name,
         state: imp.state,
         leases: (imp.leases?.leases ?? []).map((lease) => toLease(lease)),
@@ -83,7 +155,7 @@ export class ImpClientPort implements ImpPort {
       }),
     );
 
-    return { name: imp.name, state: imp.state, leases: [], otherLeaseCount: 0 };
+    return { id: imp.id, name: imp.name, state: imp.state, leases: [], otherLeaseCount: 0 };
   };
 
   readonly acquireLease = async (

package/src/daemon/imp-port.ts

@@ -9,6 +9,23 @@ export interface ImpPort {
   // impd's capability flags; an impd without them has neither.
   readonly readFeatures: () => Promise<ImpFeatures>;
 
+  // The caller's own identity: its scope, the imps it may reach, and the
+  // secrets it may grant.
+  readonly readIdentity: () => Promise<ImpIdentity>;
+
+  // Every secret impd holds, with its rules and never its value.
+  readonly readSecrets: () => Promise<readonly ImpSecret[]>;
+
+  // The names of the secrets granted to an imp.
+  readonly readGrants: (name: string) => Promise<readonly string[]>;
+
+  // Grants a secret to an imp; granting one it already holds changes
+  // nothing, and nothing in the result distinguishes the two.
+  readonly createGrant: (name: string, secret: string) => Promise<void>;
+
+  // Revokes a secret from an imp, and reports whether impd held the grant.
+  readonly removeGrant: (name: string, secret: string) => Promise<boolean>;
+
   // The imp under a name, or null when impd holds none.
   readonly readImp: (name: string) => Promise<ImpView | null>;
   readonly createImp: (spec: ImpCreateSpec) => Promise<ImpView>;
@@ -51,11 +68,54 @@ export interface ImpPort {
 export interface ImpFeatures {
   readonly sessionOffsets: boolean;
   readonly leases: boolean;
+
+  // Tokens limited to some imps may grant a list of secrets to them.
+  readonly grantableTokens: boolean;
+
+  // A rebound or recreated secret drops its grants and leaves a token's
+  // list of grantable secrets behind.
+  readonly secretRebind: boolean;
+}
+
+type ImpScope = 'read' | 'exec' | 'manage';
+
+export interface ImpIdentity {
+  readonly kind: 'token' | 'ssh' | 'tailnet' | 'dashboard';
+  readonly name: string;
+  readonly scope: ImpScope;
+
+  // Imp name patterns with `*` for any run of characters; null reaches
+  // every imp on the host.
+  readonly imps: readonly string[] | null;
+
+  // The secrets the caller may grant to the imps it reaches and revoke
+  // from them.
+  readonly grantable: readonly string[];
+}
+
+export interface ImpSecret {
+  readonly name: string;
+  readonly kind: 'anthropic' | 'custom' | 'github' | 'npm';
+  readonly rules: readonly ImpSecretRule[];
+
+  // The imps holding a grant of the secret.
+  readonly imps: readonly string[];
+}
+
+// How impd adds a secret to requests for one host.
+export interface ImpSecretRule {
+  readonly host: string;
+  readonly header: string;
+  readonly scheme: 'basic' | 'bearer' | 'raw';
+  readonly user?: string;
 }
 
 export type ImpState = 'creating' | 'running' | 'sleeping' | 'stopped' | 'error';
 
 export interface ImpView {
+  // impd's id for this imp, which a new imp made under the same name never
+  // shares.
+  readonly id: string;
   readonly name: string;
   readonly state: ImpState;
 

package/src/daemon/is-imp-name-allowed.ts

@@ -0,0 +1,38 @@
+/**
+ * Whether an imp name matches one of a token's imp patterns, as impd
+ * matches them: each pattern is an imp name with `*` for any run of
+ * characters, including none, so `dev-*` matches `dev-` and `dev-a1`, and
+ * a pattern without `*` matches only its own name.
+ */
+export function isImpNameAllowed(patterns: readonly string[], name: string): boolean {
+  return patterns.some((pattern) => isPatternMatch(pattern, name));
+}
+
+function isPatternMatch(pattern: string, name: string): boolean {
+  const [first = '', ...rest] = pattern.split('*');
+  const last = rest.pop();
+
+  if (last === undefined) {
+    return name === first;
+  }
+
+  if (name.length < first.length + last.length || !name.startsWith(first) || !name.endsWith(last)) {
+    return false;
+  }
+
+  // Each middle part in order, between the prefix and the suffix.
+  let at = first.length;
+  const end = name.length - last.length;
+
+  for (const part of rest) {
+    const found = name.indexOf(part, at);
+
+    if (found === -1 || found + part.length > end) {
+      return false;
+    }
+
+    at = found + part.length;
+  }
+
+  return true;
+}

package/src/daemon/is-own-hook-event.ts

@@ -0,0 +1,19 @@
+import type { AgentID } from '../shared/agent-id';
+
+/**
+ * Whether a hook line, judged by the agent it carries, comes from the
+ * harness atc started for its session rather than from a harness nested
+ * inside it, which inherits the session's environment and so reports under
+ * the same session. A line carrying an agent is the session's own when that
+ * agent is the session's. A line without one comes from a hook command that
+ * carries no agent flag, and stays the session's own until a line carrying
+ * the session's agent arrives from the same terminal: from then on the
+ * session's own hooks are known to carry it.
+ */
+export function isOwnHookEvent(
+  lineAgent: AgentID | undefined,
+  sessionAgent: AgentID,
+  hasAgentHookLines: boolean,
+): boolean {
+  return lineAgent === undefined ? !hasAgentHookLines : lineAgent === sessionAgent;
+}

package/src/daemon/parse-hook-line.ts

@@ -23,8 +23,11 @@ export function parseHookLine(line: string): HookEvent | null {
     return null;
   }
 
+  const agent = parsed['agent'];
+
   return {
     atcId: toSessionID(parsed['atcId']),
+    ...(typeof agent === 'string' && agent !== '' ? { agent } : {}),
     event: parsed['event'],
     payload: parsed['payload'],
   };

package/src/daemon/session-runtime.ts

@@ -46,6 +46,11 @@ export class SessionRuntime {
   // later dropped may be restarting, so it keeps the inbox open.
   tapAttached = false;
 
+  // Whether a hook line carrying the session's agent arrived since the
+  // terminal last booted. Once one has, the session's own hooks are known
+  // to carry it, and a line without one comes from another harness.
+  hasAgentHookLines = false;
+
   // Returns the boot-scoped state to how a fresh terminal starts, at the
   // dims it boots with: no SessionStart yet and no tap since. Every path
   // that boots a new terminal for an existing session runs it, so a revived
@@ -54,6 +59,7 @@ export class SessionRuntime {
     this.dims = dims;
     this.startedAt = null;
     this.tapAttached = false;
+    this.hasAgentHookLines = false;
   }
 
   dispose(): void {

package/src/daemon/verify-broker-authority.ts

@@ -0,0 +1,52 @@
+import { BrokerAuthorityError } from './broker-authority-error';
+import type { ImpPort } from './imp-port';
+import { verifyTokenImpAuthority } from './verify-token-imp-authority';
+
+/**
+ * What a provisioning call is about to touch: the imps under their actual
+ * names, as the target's runtime namespace builds them, and every secret
+ * the binding grants them.
+ */
+export interface BrokerActivation {
+  readonly impNames: readonly string[];
+  readonly secrets: readonly string[];
+}
+
+/**
+ * The gate before atc grants or relies on a brokered credential. It reads
+ * impd's features, then the token's identity, and writes nothing, so a
+ * refusal leaves impd as it was. It rejects unless impd has both grantable
+ * tokens and secret rebinds, the token may manage each imp and reaches no
+ * imp outside the namespace whose imp names start with the prefix, and the
+ * token may grant every bound secret.
+ * Whether each secret's rules match the binding is a separate comparison.
+ */
+export async function verifyBrokerAuthority(
+  port: Pick<ImpPort, 'readFeatures' | 'readIdentity'>,
+  activation: BrokerActivation,
+  impPrefix: string,
+): Promise<void> {
+  const features = await port.readFeatures();
+
+  if (!features.grantableTokens || !features.secretRebind) {
+    throw new BrokerAuthorityError(
+      'auth_impd_too_old',
+      'impd lacks grantable tokens or secret rebinds; it must be 0.27.0 or later',
+      { grantableTokens: features.grantableTokens, secretRebind: features.secretRebind },
+    );
+  }
+
+  const identity = await port.readIdentity();
+
+  verifyTokenImpAuthority(identity, activation.impNames, impPrefix);
+
+  const missing = activation.secrets.filter((secret) => !identity.grantable.includes(secret));
+
+  if (missing.length > 0) {
+    throw new BrokerAuthorityError(
+      'auth_secret_not_grantable',
+      `impd token ${identity.name} cannot grant ${missing.join(', ')}`,
+      { token: identity.name, grantable: identity.grantable, missing },
+    );
+  }
+}

package/src/daemon/verify-cleanup-authority.ts

@@ -0,0 +1,44 @@
+import { BrokerAuthorityError } from './broker-authority-error';
+import type { ImpPort, ImpView } from './imp-port';
+import { verifyTokenImpAuthority } from './verify-token-imp-authority';
+
+// The imp a binding recorded when atc made it.
+export interface RecordedImp {
+  readonly name: string;
+  readonly id: string;
+}
+
+/**
+ * The check before atc destroys a session's imp or revokes its grants.
+ * It asks that the token may manage the recorded imp, under imp patterns
+ * that stay inside the namespace whose imp names start with the prefix,
+ * and that the imp under that
+ * name is still the one recorded. It never asks that a secret's rules
+ * still match or that every grant is still in place, so a rotated, rebound
+ * or deleted secret never stops atc removing access. Resolves to the imp,
+ * or to null when impd confirms no imp holds the name, which needs no
+ * cleanup; an imp with another id rejects.
+ */
+export async function verifyCleanupAuthority(
+  port: Pick<ImpPort, 'readIdentity' | 'readImp'>,
+  recorded: RecordedImp,
+  impPrefix: string,
+): Promise<ImpView | null> {
+  const identity = await port.readIdentity();
+
+  // Checked first, so impd's answer for the name comes from a token that
+  // can see the imp, and a missing imp means it is gone.
+  verifyTokenImpAuthority(identity, [recorded.name], impPrefix);
+
+  const imp = await port.readImp(recorded.name);
+
+  if (imp !== null && imp.id !== recorded.id) {
+    throw new BrokerAuthorityError(
+      'auth_runtime_mismatch',
+      `imp ${recorded.name} is no longer the imp atc made`,
+      { imp: recorded.name, recordedID: recorded.id, actualID: imp.id },
+    );
+  }
+
+  return imp;
+}

package/src/daemon/verify-token-imp-authority.ts

@@ -0,0 +1,74 @@
+import { BrokerAuthorityError } from './broker-authority-error';
+import type { ImpIdentity } from './imp-port';
+import { isImpNameAllowed } from './is-imp-name-allowed';
+
+/**
+ * Rejects unless the token may manage every named imp and reaches no imp
+ * outside atc's namespace: scope `manage`, imp patterns rather than none,
+ * and each pattern contained in the namespace prefix, so the literal text
+ * before its first `*`, or the whole pattern when it has none, starts with
+ * the prefix. A token with any pattern beyond the prefix is refused
+ * outright, however few names that pattern reaches, never used in place of
+ * a contained one. Each name must then match a pattern. The prefix is the
+ * literal start of every imp name the target's runtime namespace builds,
+ * and the names are the imps the call touches under those built names.
+ */
+export function verifyTokenImpAuthority(
+  identity: ImpIdentity,
+  impNames: readonly string[],
+  impPrefix: string,
+): void {
+  assertImpPrefix(impPrefix);
+
+  if (identity.scope !== 'manage') {
+    throw new BrokerAuthorityError(
+      'auth_token_scope',
+      `impd token ${identity.name} cannot manage imps`,
+      {
+        token: identity.name,
+        scope: identity.scope,
+      },
+    );
+  }
+
+  const patterns = identity.imps;
+
+  if (patterns === null || !patterns.every((pattern) => isPatternContained(pattern, impPrefix))) {
+    throw new BrokerAuthorityError(
+      'auth_token_too_broad',
+      `impd token ${identity.name} can reach imps outside atc's namespace, whose imp names start with ${impPrefix}`,
+      {
+        token: identity.name,
+        imps: patterns,
+        offending:
+          patterns === null
+            ? null
+            : patterns.filter((pattern) => !isPatternContained(pattern, impPrefix)),
+      },
+    );
+  }
+
+  const outside = impNames.filter((name) => !isImpNameAllowed(patterns, name));
+
+  if (outside.length > 0) {
+    throw new BrokerAuthorityError(
+      'auth_imp_out_of_scope',
+      `impd token ${identity.name} cannot manage ${outside.join(', ')}`,
+      { token: identity.name, imps: patterns, outside },
+    );
+  }
+}
+
+// An empty prefix would contain every pattern, `*` included.
+function assertImpPrefix(impPrefix: string): void {
+  if (impPrefix === '') {
+    throw new Error('the imp name prefix of a runtime namespace must not be empty');
+  }
+}
+
+// Every name a pattern matches starts with the text before its first `*`.
+function isPatternContained(pattern: string, impPrefix: string): boolean {
+  const [literal = ''] = pattern.split('*');
+
+  return literal.startsWith(impPrefix);
+}

package/src/hook-report.ts

@@ -4,10 +4,12 @@ import { isRecord, sendReport } from './shared/report';
 /**
  * Runs as a hook inside wrangled sessions. Reads the hook event from stdin
  * (Claude snake_case keys or Grok camelCase keys) and forwards a PascalCase
- * event name to the atc unix socket. Always exits 0 so it never blocks the
- * session it reports on.
+ * event name to the atc unix socket, with the agent id the hook command
+ * gave it, so the daemon can tell a nested harness's report from the
+ * session's own. Always exits 0 so it never blocks the session it reports
+ * on.
  */
-export async function runHookReport(): Promise<void> {
+export async function runHookReport(agent: string): Promise<void> {
   const sock = process.env['ATC_SOCKET'];
   const atcId = process.env['ATC_SESSION_ID'];
 
@@ -26,7 +28,7 @@ export async function runHookReport(): Promise<void> {
 
     const rawName = payload['hook_event_name'] ?? payload['hookEventName'];
     const event = typeof rawName === 'string' ? normalizeHookEventName(rawName) : rawName;
-    const line = `${JSON.stringify({ atcId, event, payload })}\n`;
+    const line = `${JSON.stringify({ atcId, ...(agent === '' ? {} : { agent }), event, payload })}\n`;
 
     await sendReport(sock, line, 2000);
   }

package/src/protocol/hook-event.ts

@@ -1,11 +1,15 @@
+import type { AgentID } from '../shared/agent-id';
 import type { SessionID } from '../shared/session-id';
 
 /**
- * One line a hook reporter sends: the atc session it reports on, the agent's
- * hook event name, and the hook's payload as the agent gave it.
+ * One line a hook reporter sends: the atc session it reports on, the agent
+ * whose hook command sent it, the agent's hook event name, and the hook's
+ * payload as the agent gave it. The agent is absent on a line from a hook
+ * command that carries none.
  */
 export interface HookEvent {
   atcId: SessionID;
+  agent?: AgentID;
   event: string;
   payload: Record<string, unknown>;
 }

package/src/statusline.ts

@@ -8,10 +8,11 @@ import { isRecord, sendReport } from './shared/report';
 /**
  * Runs as the statusLine command injected into wrangled sessions. Chains the
  * user's own statusline (from ~/.claude/settings.json), appends the atc fleet
- * segment, and heartbeats the session id back to the atc socket. Always
- * exits 0 so it never breaks the session it renders for.
+ * segment, and heartbeats the session id back to the atc socket, with the
+ * agent id the command gave it. Always exits 0 so it never breaks the
+ * session it renders for.
  */
-export async function runStatusline(): Promise<void> {
+export async function runStatusline(agent: string): Promise<void> {
   const raw = await new Response(Bun.stdin.stream()).text();
 
   const sock = process.env['ATC_SOCKET'];
@@ -28,7 +29,7 @@ export async function runStatusline(): Promise<void> {
       }
     } catch {}
 
-    const line = `${JSON.stringify({ atcId, event: 'Statusline', payload })}\n`;
+    const line = `${JSON.stringify({ atcId, ...(agent === '' ? {} : { agent }), event: 'Statusline', payload })}\n`;
 
     await sendReport(sock, line, 500);
   }
@@ -128,7 +129,8 @@ async function readOwnSegment(sock: string): Promise<string> {
 }
 
 // A user statusline that is atc's own injected command would chain into
-// itself; the injected command always ends with the bare subcommand.
+// itself; the injected command ends with the bare subcommand, or with the
+// subcommand and its agent flag.
 function isSelfCommand(cmd: string): boolean {
-  return cmd.includes('statusline.ts') || cmd.trimEnd().endsWith(' statusline');
+  return cmd.includes('statusline.ts') || /\sstatusline(?:\s+--agent\s.*)?$/u.test(cmd);
 }