dsh-permission-rules 0.4.2 → 0.5.2

package/src/client/section.ts

@@ -0,0 +1,201 @@
+/**
+ * The "Permission Rules" settings page: network-policy summary (mode
+ * mapping, proxy liveness), block counters, the recent interception list
+ * (source tool + target domain), and the rule editor over known rule
+ * sources. All data arrives through the `permissionRules` Remote
+ * namespace; the page holds no state beyond the selected file and the
+ * draft text. Written with `React.createElement` only — the client
+ * bundle is plain JavaScript.
+ * @module dsh-permission-rules/client/section
+ */
+
+import * as React from 'react'
+import type { ReactElement } from 'react'
+import type { PermissionRulesLocaleKey } from './locales.ts'
+import type { PermissionRulesSnapshot, RulesReadResult, RulesReloadResult, RulesSaveResult } from '../wire.ts'
+
+/** Functions the registration injects (wired to the Remote namespace in `./index.ts`). */
+export interface PermissionRulesSectionInjected {
+  /** Read the network-policy snapshot. */
+  status: () => Promise<PermissionRulesSnapshot>
+  /** Read one known rule file. */
+  rulesRead: (path: string) => Promise<RulesReadResult>
+  /** Validate and write one known rule file. */
+  rulesSave: (path: string, text: string) => Promise<RulesSaveResult>
+  /** Re-read every cached workspace chain. */
+  reload: () => Promise<RulesReloadResult>
+  /** The locale-bound translator. */
+  t: T
+}
+
+/** One bound dictionary. */
+export type T = (key: PermissionRulesLocaleKey, vars?: Record<string, string | number>) => string
+
+/** The shell supplies `close`; everything else arrives through the slot injection. */
+export type PermissionRulesSectionProps = PermissionRulesSectionInjected & {
+  close: () => void
+}
+
+/** One select option for the rule-file picker. */
+interface SourceOption {
+  path: string
+  label: string
+}
+
+const HEADER: React.CSSProperties = { fontSize: 14, fontWeight: 700, margin: '16px 0 8px' }
+const ROW: React.CSSProperties = { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }
+const LABEL: React.CSSProperties = { fontSize: 13, color: 'var(--dsh-color-text-secondary, #666)', minWidth: 110 }
+const VALUE: React.CSSProperties = { fontSize: 13 }
+const MONO: React.CSSProperties = { fontFamily: 'var(--dsh-font-mono, monospace)', fontSize: 12 }
+const TEXTAREA: React.CSSProperties = { width: '100%', minHeight: 260, fontFamily: 'var(--dsh-font-mono, monospace)', fontSize: 12, whiteSpace: 'pre', overflow: 'auto' }
+const NOTICE_OK: React.CSSProperties = { fontSize: 13, color: 'var(--dsh-color-success, #1a7f37)' }
+const NOTICE_ERR: React.CSSProperties = { fontSize: 13, color: 'var(--dsh-color-error, #c62828)' }
+const TABLE: React.CSSProperties = { width: '100%', borderCollapse: 'collapse', fontSize: 12 }
+const CELL: React.CSSProperties = { borderBottom: '1px solid var(--dsh-color-border, #ddd)', padding: '4px 6px', textAlign: 'left', verticalAlign: 'top' }
+
+/** The settings section component. */
+export function PermissionRulesSection({ close, t, ...injected }: PermissionRulesSectionProps): ReactElement {
+  void close
+  const [snapshot, setSnapshot] = React.useState<PermissionRulesSnapshot | undefined>(undefined)
+  const [loadError, setLoadError] = React.useState<string | undefined>(undefined)
+  const [sources, setSources] = React.useState<SourceOption[]>([])
+  const [selected, setSelected] = React.useState<string | undefined>(undefined)
+  const [text, setText] = React.useState('')
+  const [dirty, setDirty] = React.useState(false)
+  const [notice, setNotice] = React.useState<{ ok: boolean; text: string } | undefined>(undefined)
+
+  const refresh = React.useCallback(() => {
+    void injected.status().then(next => {
+      setSnapshot(next)
+      setLoadError(undefined)
+      setSources(next.sources.map(source => ({
+        path: source.path,
+        label: source.cwd === null ? source.path : source.path.replace(source.cwd, '.'),
+      })))
+      setSelected(current => current === undefined && next.sources.length > 0 ? next.sources[0]?.path : current)
+    }).catch(error => {
+      setLoadError(error instanceof Error ? error.message : String(error))
+    })
+  }, [injected.status])
+
+  React.useEffect(() => {
+    refresh()
+    const timer = setInterval(refresh, 5000)
+    return () => clearInterval(timer)
+  }, [refresh])
+
+  const loadFile = React.useCallback((path: string) => {
+    setSelected(path)
+    setDirty(false)
+    setNotice(undefined)
+    void injected.rulesRead(path).then(result => {
+      setText(result.error ?? result.text)
+      if (result.error !== null && result.error !== undefined) setNotice({ ok: false, text: result.error })
+    })
+  }, [injected])
+
+  const saveFile = React.useCallback(() => {
+    if (selected === undefined || !dirty) return
+    setNotice(undefined)
+    void injected.rulesSave(selected, text).then(result => {
+      setNotice(result.ok
+        ? { ok: true, text: t('editorSaved', { reloaded: result.reloaded ?? 0 }) }
+        : { ok: false, text: t('editorFailed', { error: result.error ?? t('unknown') }) })
+      if (result.ok) {
+        setDirty(false)
+        refresh()
+      }
+    })
+  }, [injected, selected, text, dirty, t, refresh])
+
+  const reloadAll = React.useCallback(() => {
+    setNotice(undefined)
+    void injected.reload().then(result => {
+      setNotice(result.ok
+        ? { ok: true, text: t('editorSaved', { reloaded: 0 }) }
+        : { ok: false, text: t('editorFailed', { error: result.error ?? t('unknown') }) })
+      refresh()
+    })
+  }, [injected, t, refresh])
+
+  const picker = React.createElement('select', {
+    style: { ...MONO, maxWidth: 420 },
+    value: selected ?? '',
+    onChange: (event: React.ChangeEvent<HTMLSelectElement>) => {
+      const path = event.target.value
+      if (path !== '') loadFile(path)
+    },
+  }, sources.map(source => React.createElement('option', { key: source.path, value: source.path }, source.label)))
+
+  const children: React.ReactNode[] = []
+
+  // Policy summary.
+  children.push(React.createElement('div', { key: 'policy-title', style: HEADER }, t('policyTitle')))
+  if (snapshot === undefined) {
+    children.push(React.createElement('div', { key: 'loading', style: VALUE }, loadError === undefined ? '…' : loadError))
+  } else {
+    const modeText = `${snapshot.mode}${snapshot.sandboxMode === null ? '' : ` (${t('preset')}: ${snapshot.sandboxMode})`}${snapshot.configuredMode === 'auto' ? '' : ` — ${t('configured')}: ${snapshot.configuredMode}`}`
+    children.push(React.createElement('div', { key: 'mode', style: ROW },
+      React.createElement('span', { style: LABEL }, t('mode')),
+      React.createElement('span', { style: VALUE }, modeText)))
+    const proxyText = snapshot.enabled
+      ? snapshot.proxyActive ? t('proxyActive', { port: snapshot.proxyPort }) : t('proxyInactive')
+      : t('proxyDisabled')
+    children.push(React.createElement('div', { key: 'proxy', style: ROW },
+      React.createElement('span', { style: LABEL }, t('proxy')),
+      React.createElement('span', { style: VALUE }, proxyText)))
+    children.push(React.createElement('div', { key: 'counters', style: ROW },
+      React.createElement('span', { style: LABEL }, t('counters')),
+      React.createElement('span', { style: VALUE }, `${snapshot.denied} ${t('denied')} · ${snapshot.askBlocked} ${t('askBlocked')}`)))
+  }
+
+  // Recent blocks.
+  children.push(React.createElement('div', { key: 'recent-title', style: HEADER }, t('recentTitle')))
+  if (snapshot === undefined || snapshot.recent.length === 0) {
+    children.push(React.createElement('div', { key: 'no-blocks', style: VALUE }, t('noBlocks')))
+  } else {
+    const rows = snapshot.recent.map(block => React.createElement('tr', { key: `${block.time}-${block.domain}` },
+      React.createElement('td', { style: CELL }, new Date(block.time).toLocaleTimeString()),
+      React.createElement('td', { style: CELL }, block.tool + (block.attributed ? '' : ` (${t('blockUnattributed')})`)),
+      React.createElement('td', { style: CELL }, `${block.scheme ?? '?'}://${block.domain}${block.port === null ? '' : `:${block.port}`}`),
+      React.createElement('td', { style: CELL }, block.matched
+        ? t('blockBy', { index: (block.ruleIndex ?? 0) + 1 })
+        : t('blockDefault')),
+      React.createElement('td', { style: CELL }, block.action),
+      React.createElement('td', { style: CELL }, block.reason ?? '')))
+    children.push(React.createElement('table', { key: 'recent-table', style: TABLE },
+      React.createElement('tbody', undefined, rows)))
+  }
+
+  // Rule editor.
+  children.push(React.createElement('div', { key: 'editor-title', style: HEADER }, t('editorTitle')))
+  children.push(React.createElement('div', { key: 'editor-picker', style: ROW },
+    React.createElement('span', { style: LABEL }, t('editorPath')),
+    picker,
+    React.createElement('button', { type: 'button', onClick: () => { if (selected !== undefined) loadFile(selected) } }, t('editorLoad')),
+    React.createElement('button', { type: 'button', onClick: reloadAll }, t('editorReload'))))
+  if (selected === undefined) {
+    children.push(React.createElement('div', { key: 'editor-empty', style: VALUE }, t('editorEmpty')))
+  } else {
+    children.push(React.createElement('textarea', {
+      key: 'editor-text',
+      style: TEXTAREA,
+      value: text,
+      spellCheck: false,
+      onChange: (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+        setText(event.target.value)
+        setDirty(true)
+        setNotice(undefined)
+      },
+    }))
+    children.push(React.createElement('div', { key: 'editor-actions', style: { ...ROW, marginTop: 8 } },
+      React.createElement('button', { type: 'button', disabled: !dirty, onClick: saveFile }, t('editorSave')),
+      dirty === true ? React.createElement('span', { style: VALUE }, '●') : null,
+      notice === undefined ? null : React.createElement('span', {
+        key: 'notice',
+        style: notice.ok ? NOTICE_OK : NOTICE_ERR,
+      }, notice.text)))
+  }
+
+  return React.createElement('div', { style: { padding: '0 4px 24px' } }, ...children)
+}

package/src/config.ts

@@ -9,6 +9,8 @@
 import { isAbsolute } from 'node:path'
 import z from '@deepseek-ai/schemastery'
 import type { PatternMode } from './rules.ts'
+import type { NetworkMode, UnlistedAction } from './network.ts'
+import { NETWORK_MODES } from './network.ts'
 import type { UiLanguage } from './prose.ts'
 
 /** What happens when a discovered rule file exists but cannot be parsed or compiled. */
@@ -17,6 +19,44 @@ export type BadFilePolicy = 'fail' | 'ignore-with-warning'
 /** Which decisions are audit-logged: every call, or only rule hits. */
 export type AuditGranularity = 'all' | 'hits'
 
+/** Loopback-target handling at the proxy layer. */
+export type LoopbackPolicy = 'allow' | 'policy'
+
+/** NO_PROXY handling for policy-injected subprocess environment. */
+export type NoProxyPolicy = 'clear' | 'preserve'
+
+/**
+ * The process-level network policy block. Every field is optional —
+ * {@link ResolvedConfig} supplies the defaults. `mode: 'auto'` maps the
+ * official sandbox preset onto the three network modes (read-only →
+ * deny-all, workspace-write → whitelist, danger-full-access → allow-all);
+ * on hosts without the sandbox-policy service `auto` resolves to
+ * `autoFallback` (`allow-all` by default, so pre-network hosts keep their
+ * permissive behavior until configured).
+ */
+export interface NetworkConfig {
+  /** Master switch: `false` disables the proxy, the env injection, and the web-tool mode defaults. */
+  enabled?: boolean
+  /** Policy mode: `auto` follows the sandbox preset, or an explicit mode. */
+  mode?: 'auto' | NetworkMode
+  /** Mode used when `mode: 'auto'` and the sandbox-policy service is absent or unknown. */
+  autoFallback?: NetworkMode
+  /** Whitelist-mode handling of targets no rule matched: `ask` (default) or `deny`. */
+  unlisted?: UnlistedAction
+  /** Local proxy bind address (loopback only — the proxy never listens publicly). */
+  proxyBind?: string
+  /** Local proxy port; `0` picks a free ephemeral port. */
+  proxyPort?: number
+  /** Cap on recent-block records kept for the settings page. */
+  proxyMaxRecent?: number
+  /** Loopback targets: `allow` (default, Codex parity) or `policy` (evaluated like any target). */
+  loopback?: LoopbackPolicy
+  /** Whether proxy environment variables are injected for subprocesses. */
+  injectEnv?: boolean
+  /** Subprocess NO_PROXY handling: `clear` enforces the policy (default) or `preserve` keeps ambient values. */
+  noProxy?: NoProxyPolicy
+}
+
 /** Raw plugin config — every field optional; {@link Config} supplies the defaults. */
 export interface Config {
   /**
@@ -75,6 +115,22 @@ export interface Config {
    * `scripts/repair-session-logs.mjs` before loading on a newer harness).
    */
   allowUnmarkedAudit?: boolean
+  /** Process-level network policy (all optional; defaults inside). */
+  network?: NetworkConfig
+}
+
+/** Network config after {@link resolveConfig}: every optional field has its explicit default. */
+export interface ResolvedNetworkConfig {
+  readonly enabled: boolean
+  readonly mode: 'auto' | NetworkMode
+  readonly autoFallback: NetworkMode
+  readonly unlisted: UnlistedAction
+  readonly proxyBind: string
+  readonly proxyPort: number
+  readonly proxyMaxRecent: number
+  readonly loopback: LoopbackPolicy
+  readonly injectEnv: boolean
+  readonly noProxy: NoProxyPolicy
 }
 
 /** Config after {@link resolveConfig}: every optional field has its explicit default. */
@@ -94,6 +150,7 @@ export interface ResolvedConfig {
   readonly maxGlobStars: number
   readonly enforce: boolean
   readonly allowUnmarkedAudit: boolean
+  readonly network: ResolvedNetworkConfig
 }
 
 /** Schemastery schema: the loader validates and fills defaults before `apply`. */
@@ -113,6 +170,18 @@ export const Config: z<Config> = z.object({
   maxGlobStars: z.number().default(2),
   enforce: z.boolean().default(true),
   allowUnmarkedAudit: z.boolean().default(false),
+  network: z.object({
+    enabled: z.boolean().default(true),
+    mode: z.union(['auto', ...NETWORK_MODES] as const).default('auto'),
+    autoFallback: z.union(NETWORK_MODES as [NetworkMode, ...NetworkMode[]]).default('allow-all'),
+    unlisted: z.union(['ask', 'deny'] as const).default('ask'),
+    proxyBind: z.string().default('127.0.0.1'),
+    proxyPort: z.number().default(0),
+    proxyMaxRecent: z.number().default(100),
+    loopback: z.union(['allow', 'policy'] as const).default('allow'),
+    injectEnv: z.boolean().default(true),
+    noProxy: z.union(['clear', 'preserve'] as const).default('clear'),
+  }),
 })
 
 /**
@@ -156,6 +225,7 @@ export function resolveConfig(config: Config = {}): ResolvedConfig {
   assertBoolean('caseInsensitivePaths', config.caseInsensitivePaths ?? process.platform === 'win32')
   assertBoolean('enforce', config.enforce ?? true)
   assertBoolean('allowUnmarkedAudit', config.allowUnmarkedAudit ?? false)
+  const network = resolveNetworkConfig(config.network)
   return {
     rulesFile,
     fallbackPath: config.fallbackPath,
@@ -172,6 +242,47 @@ export function resolveConfig(config: Config = {}): ResolvedConfig {
     maxGlobStars,
     enforce: config.enforce ?? true,
     allowUnmarkedAudit: config.allowUnmarkedAudit ?? false,
+    network,
+  }
+}
+
+/** Validate and default the optional `network` block; bad values fail the mount loudly. */
+function resolveNetworkConfig(raw: NetworkConfig | undefined): ResolvedNetworkConfig {
+  const mode = raw?.mode ?? 'auto'
+  if (mode !== 'auto') assertEnum('network.mode', mode, NETWORK_MODES)
+  const autoFallback = raw?.autoFallback ?? 'allow-all'
+  assertEnum('network.autoFallback', autoFallback, NETWORK_MODES)
+  const unlisted = raw?.unlisted ?? 'ask'
+  assertEnum('network.unlisted', unlisted, ['ask', 'deny'])
+  const loopback = raw?.loopback ?? 'allow'
+  assertEnum('network.loopback', loopback, ['allow', 'policy'])
+  const noProxy = raw?.noProxy ?? 'clear'
+  assertEnum('network.noProxy', noProxy, ['clear', 'preserve'])
+  assertBoolean('network.enabled', raw?.enabled ?? true)
+  assertBoolean('network.injectEnv', raw?.injectEnv ?? true)
+  const proxyBind = raw?.proxyBind ?? '127.0.0.1'
+  if (typeof proxyBind !== 'string' || proxyBind.trim().length === 0) {
+    throw new TypeError(`network.proxyBind must be a non-empty string, got ${typeof proxyBind}`)
+  }
+  const proxyPort = raw?.proxyPort ?? 0
+  if (!Number.isSafeInteger(proxyPort) || proxyPort < 0 || proxyPort > 65535) {
+    throw new TypeError(`network.proxyPort must be an integer 0-65535, got ${String(raw?.proxyPort)}`)
+  }
+  const proxyMaxRecent = raw?.proxyMaxRecent ?? 100
+  if (!Number.isSafeInteger(proxyMaxRecent) || proxyMaxRecent <= 0) {
+    throw new TypeError(`network.proxyMaxRecent must be a positive safe integer, got ${String(raw?.proxyMaxRecent)}`)
+  }
+  return {
+    enabled: raw?.enabled ?? true,
+    mode: mode as 'auto' | NetworkMode,
+    autoFallback,
+    unlisted,
+    proxyBind: proxyBind.trim(),
+    proxyPort,
+    proxyMaxRecent,
+    loopback,
+    injectEnv: raw?.injectEnv ?? true,
+    noProxy,
   }
 }
 

package/src/events.ts

@@ -57,6 +57,34 @@ declare module '@deepseek-ai/dsh-session/types' {
       cwd: string
       dryRun?: true
     }
+    /**
+     * One process-level network block (proxy layer), appended when the
+     * block can be attributed to a session — log-only audit with the same
+     * `ignorable` marker discipline as `permissionRules/decision`. `tool`
+     * is the attributed shell tool (`bash`/`pwsh`) or `'subprocess'` when
+     * no in-flight shell execution could be named; `attributed` records
+     * which case. `domain`/`scheme`/`port` name the blocked target,
+     * `action` is `deny` or `ask` (an ask at the proxy cannot ride the
+     * approval seam — no session context — and blocks with a message),
+     * `mode` is the network policy mode in effect, and `ruleIndex`/`reason`
+     * appear only on rule hits.
+     */
+    'permissionRules/network': {
+      kind: 'block'
+      tool: string
+      attributed: boolean
+      callId?: CallId
+      domain: string
+      scheme?: 'http' | 'https'
+      port?: number
+      action: 'deny' | 'ask'
+      mode: string
+      matched: boolean
+      source: string
+      ruleIndex?: number
+      reason?: string
+      time: number
+    }
   }
 }
 
@@ -81,6 +109,24 @@ export interface AuditDecision {
   dryRun?: true
 }
 
+/** The payload of one `permissionRules/network` audit record. */
+export interface AuditNetworkBlock {
+  kind: 'block'
+  tool: string
+  attributed: boolean
+  callId?: CallId
+  domain: string
+  scheme?: 'http' | 'https'
+  port?: number
+  action: 'deny' | 'ask'
+  mode: string
+  matched: boolean
+  source: string
+  ruleIndex?: number
+  reason?: string
+  time: number
+}
+
 /**
  * `Session.append` narrowed to this plugin's audit event. The options bag
  * exists only on host builds that expose the `ignorable` envelope-marker

package/src/index.ts

@@ -27,3 +27,5 @@ export * from './config.ts'
 export * from './events.ts'
 export * from './rules.ts'
 export * from './glob.ts'
+export * from './network.ts'
+export * from './proxy.ts'

package/src/network.ts

@@ -0,0 +1,177 @@
+/**
+ * Pure network-policy orchestration shared by the `tools/pre-execute` gate
+ * and the local HTTP/CONNECT proxy: the three policy modes mapped onto the
+ * official sandbox presets, proxy-layer first-match evaluation over the
+ * loaded rule chains, and the mode-default fallback decision. No I/O, no
+ * process state — unit-testable and replayable.
+ * @module dsh-permission-rules/network
+ */
+
+import type { CompiledRule, CompiledRuleset, NetworkTarget } from './rules.ts'
+import { matchWhen, matchTools, targetMatchesNetwork } from './rules.ts'
+import type { MatchContext } from './rules.ts'
+
+/** The three network policy modes. */
+export type NetworkMode = 'deny-all' | 'whitelist' | 'allow-all'
+
+/** Closed mode list for runtime normalization of untrusted values. */
+export const NETWORK_MODES: readonly NetworkMode[] = ['deny-all', 'whitelist', 'allow-all']
+
+/** The official file-sandbox presets the `auto` mode maps onto. */
+export type SandboxModeName = 'read-only' | 'workspace-write' | 'danger-full-access'
+
+/** How a whitelist-mode unlisted target is handled: ask (blocked at the proxy, approval seam for web tools) or deny. */
+export type UnlistedAction = 'ask' | 'deny'
+
+/**
+ * Map one official sandbox preset onto its network mode, Codex-style:
+ * `read-only` defaults to no network (whitelist only), `workspace-write`
+ * keeps a whitelist with ask/deny for unlisted targets, and
+ * `danger-full-access` opens everything (rules can still narrow it). Any
+ * other value falls back to `fallback` — hosts without the sandbox-policy
+ * service therefore stay permissive, preserving pre-network behavior.
+ * @param sandbox - the resolved sandbox mode, or undefined.
+ * @param fallback - the mode used when the preset is unknown/absent.
+ * @returns the effective network mode.
+ */
+export function networkModeForSandbox(sandbox: string | undefined, fallback: NetworkMode): NetworkMode {
+  switch (sandbox) {
+    case 'read-only': return 'deny-all'
+    case 'workspace-write': return 'whitelist'
+    case 'danger-full-access': return 'allow-all'
+    default: return fallback
+  }
+}
+
+/** One rule chain the proxy evaluates (ruleset + its source-file paths for attribution). */
+export interface NetworkChain {
+  readonly ruleset: CompiledRuleset
+  readonly sources: readonly string[]
+}
+
+/** Proxy-layer evaluation options. */
+export interface NetworkDecisionOptions {
+  /** The policy mode in effect (already resolved by the runtime). */
+  readonly mode: NetworkMode
+  /** Whitelist-mode handling of unlisted targets. */
+  readonly unlisted: UnlistedAction
+  /** `allow` short-circuits loopback targets before rules; `policy` evaluates them normally. */
+  readonly loopback: 'allow' | 'policy'
+  /** Host facts for `when` evaluation (proxy has no agent identity). */
+  readonly context?: MatchContext
+}
+
+/** One network decision: a rule hit or the mode-default fallback. */
+export interface NetworkDecision {
+  readonly action: 'allow' | 'deny' | 'ask'
+  /** Whether a rule (true) or the mode default (false) produced the decision. */
+  readonly matched: boolean
+  /** The mode the fallback was computed from. */
+  readonly mode: NetworkMode
+  readonly ruleIndex?: number
+  readonly rule?: CompiledRule
+  /** Source file of the matched rule, for audit attribution. */
+  readonly source?: string
+}
+
+/** The default decision a mode yields for a target no rule matched. */
+export function defaultDecision(mode: NetworkMode, unlisted: UnlistedAction): NetworkDecision {
+  switch (mode) {
+    case 'deny-all':
+      return { action: 'deny', matched: false, mode }
+    case 'whitelist':
+      return { action: unlisted, matched: false, mode }
+    case 'allow-all':
+      return { action: 'allow', matched: false, mode }
+  }
+}
+
+/**
+ * Evaluate the network policy for one target across the loaded rule
+ * chains (nearest workspace first, first match wins). Proxy-layer tool
+ * attribution: a shell subprocess connection counts as `bash`/`pwsh`
+ * candidates, so a rule scoped to either shell tool can fire and one
+ * scoped to web tools never does. Agent identity is unknown at the proxy,
+ * so agent-scoped network rules fail closed there (the pre-execute path
+ * is where agents are known). Loopback targets short-circuit before any
+ * rule when `loopback: 'allow'` (Codex parity: local dev servers stay
+ * reachable in the read-only default).
+ * @param chains - the loaded chains, insertion (nearest) order first.
+ * @param target - the parsed connection/URL target.
+ * @param options - mode, unlisted handling, loopback policy, host facts.
+ * @returns the decision.
+ */
+export function decideNetworkTarget(chains: readonly NetworkChain[], target: NetworkTarget, options: NetworkDecisionOptions): NetworkDecision {
+  if (options.loopback === 'allow' && isLoopbackTarget(target)) {
+    return { action: 'allow', matched: false, mode: options.mode }
+  }
+  const context = options.context ?? {}
+  for (const chain of chains) {
+    for (const rule of chain.ruleset.rules) {
+      if (!rule.enabled) continue
+      if (rule.network === undefined) continue
+      if (!matchToolsProxy(rule)) continue
+      if (rule.when !== undefined && !matchWhen(rule, context)) continue
+      if (!targetMatchesNetwork(target, rule.network)) continue
+      return {
+        action: rule.action,
+        matched: true,
+        mode: options.mode,
+        ruleIndex: rule.index,
+        rule,
+        source: chain.sources[rule.sourceIndex] ?? '',
+      }
+    }
+  }
+  return defaultDecision(options.mode, options.unlisted)
+}
+
+/**
+ * Tool-scope check for proxy traffic: shell subprocess connections carry
+ * the `bash`/`pwsh` identity candidates (ANY match satisfies, like the
+ * agents dimension); rules scoped to other tools never fire here.
+ */
+function matchToolsProxy(rule: CompiledRule): boolean {
+  if (rule.tools.length === 0) return true
+  return matchTools(rule, 'bash') || matchTools(rule, 'pwsh')
+}
+
+/** Whether a target addresses the loopback range. */
+export function isLoopbackTarget(target: NetworkTarget): boolean {
+  const host = target.host
+  if (host === 'localhost' || host === '::1' || host === '0:0:0:0:0:0:0:1') return true
+  const parts = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)
+  if (parts === null) return false
+  return parts.slice(1).every(octet => Number(octet) <= 255) && parts[1] === '127'
+}
+
+/**
+ * The short structured message a blocked proxy connection receives (403
+ * body for plain HTTP, CONNECT error body for tunnels). Clients such as
+ * curl print it verbatim, so the model sees the reason through the shell
+ * tool output. An `ask` at the proxy layer is worded as a pending-approval
+ * block because the proxy has no session context for the interactive
+ * approval seam.
+ * @param decision - the decision that blocked the connection.
+ * @returns a short text/plain message.
+ */
+export function blockMessage(decision: NetworkDecision): string {
+  const reason = decision.rule?.reason ?? ''
+  if (decision.matched) {
+    const rulePart = decision.ruleIndex !== undefined ? ` by rule ${decision.ruleIndex + 1}` : ''
+    if (decision.action === 'ask') {
+      return `[network: blocked pending approval${rulePart}] ${reason}\n(subprocess connections cannot ride the interactive approval seam — ask your user or add an allow rule for this target)`
+    }
+    return `[network: denied${rulePart}] ${reason}`
+  }
+  switch (decision.mode) {
+    case 'deny-all':
+      return '[network: denied] network mode deny-all (read-only sandbox preset): only whitelisted targets are reachable'
+    case 'whitelist':
+      return decision.action === 'ask'
+        ? '[network: blocked pending approval] whitelist mode: the target is not matched by an allow rule'
+        : '[network: denied] whitelist mode: the target is not matched by an allow rule'
+    case 'allow-all':
+      return '[network: denied]'
+  }
+}