[D][Security] Bind Claude subagents to attenuated child passports

[gnanirahulnutakki]

Part of #170 (Epic D, Phase 2). Depends on the reusable lifecycle contract in sibling issue #312.

Goal

Ensure Claude Code subagent tool calls are governed by a verified attenuated child passport rather than merely attributed to an observed child while continuing under parent authority.

Verified current gap

python/vibap/claude_code_hook.py records SubagentStart/SubagentStop receipts and labels a copy of the active parent policy as inherited_policy. It does not issue or bind a child passport.

The current official hook contract matters:

• PreToolUse can block the Agent tool before execution.
• SubagentStart runs after creation, cannot block the spawn, and exposes agent_id/agent_type but no parent Agent tool-use correlation ID.
• Therefore SubagentStart alone cannot provide a race-free dynamic per-prompt authority handoff, especially for parallel same-type spawns.

Observation or context injection is not authority adoption.

What to build

• Gate the Claude Agent tool at PreToolUse and atomically reserve/derive child authority before allowing spawn.
• Use an operator-authored agent-type policy registry as the safe correlation boundary for CLI hooks. Concurrent same-type spawns may be interchangeable only when their derived policies are byte-equivalent; otherwise fail closed rather than guess.
• At SubagentStart, bind the observed (session_id, agent_id, agent_type) to an eligible pending child reservation and inject only a bounded opaque child handle/context marker.
• Route subsequent PreToolUse events carrying that agent_id through the bound child session. Never fall back to parent authority when a child binding is missing, ambiguous, expired, closed, or mismatched.
• Settle/close the child on SubagentStop; quarantine reservations on missing stop, crash, or timeout for bounded reconciliation.
• Rename receipt fields so inherited_policy cannot overclaim enforcement before binding. Preserve explicit states such as observed-only, pending, bound, denied, closed, and unverified child receipt summary.
• If current hook inputs cannot safely support a requested dynamic policy mode, document it as unsupported and fail closed; do not infer identity from transcript paths or timing.
• Provide an Agent SDK integration path only if it exposes stronger correlation, and keep its claim boundary distinct from CLI hooks.

Acceptance criteria

• Agent spawn above parent/depth/budget/policy limits is denied at PreToolUse; a test proves no spawn follows.
• A bound subagent tool call is evaluated against its child passport, and a parent-only capability is denied before tool execution.
• Parallel different-type and same-type spawns have deterministic, race-tested binding behavior with no authority swap.
• Missing agent_id, missing pending reservation, ambiguous binding, replay, timeout, stop-before-start, duplicate stop, and process restart fail closed or quarantine safely.
• Lifecycle receipts truthfully distinguish observation from enforced binding and contain no prompts, transcripts, raw credentials, secrets, or host paths.
• Existing main-agent Claude Code governance remains compatible.
• Unit, concurrency, hook-contract, daemon/fallback, privacy, report, package, and relevant full-suite tests pass.
• Docs cite the exact supported Claude Code hook contract and limitations.
• PR targets dev from an isolated EXTENDED worktree with signed DCO commits and green CI.

Non-goals

• Do not claim SubagentStart can block a spawn.
• Do not dynamically derive policy from untrusted prompt text.
• Do not use transcript paths, timestamps, or child final text as authentication.
• Do not combine this platform-specific hook work with the reusable LangGraph adapter PR.

Primary sources

• Claude Code hooks reference: https://code.claude.com/docs/en/hooks
• Claude Code subagents: https://code.claude.com/docs/en/sub-agents

[gnanirahulnutakki]

Claimed for the autonomous backlog lane after a fresh collision and ownership audit.

• Planned worktree: /Volumes/EXTENDED/github/ardur-issue-313-claude-child-passports
• Branch: gnanirahulnutakki/issue-313-claude-child-passports
• Stacked exact base: 97d603d942a7c750aa5c206582849d9d74d74838 (PR [D][Integration] Ship reusable governed subagent delegation adapter #318 / issue [D][Integration] Ship reusable governed subagent delegation adapter #312 contract)
• Live origin/dev: eb63d22361c45621df7c04884ee978b9bf0195c3
• No [D][Security] Bind Claude subagents to attenuated child passports #313 assignee, comment, PR, local/remote branch, worktree, or journal collision exists.

Fresh official-contract verification:

• PreToolUse receives the Agent tool's tool_use_id, prompt, description, and subagent_type, and can deny before execution.
• SubagentStart receives session_id, agent_id, and agent_type, cannot block creation, and still exposes no parent Agent tool_use_id.
• SubagentStop is post-execution and its transcript/final text fields are evidence inputs, not identity or authority.

Design boundary: use an operator-authored agent-type registry, atomically reserve a derived child before allowing Agent, bind only an eligible byte-equivalent reservation at SubagentStart, and fail closed on missing/ambiguous/expired/mismatched state. Child tool calls must resolve the bound child session; no fallback to parent authority. No prompt-derived policy, timing inference, transcript-path authentication, raw credential exposure, or host-path evidence.

Plan: create the isolated stacked worktree and journal; write lifecycle/concurrency/restart/privacy failures first; implement durable reservation/binding around #312's adapter; update report/plugin/docs; then run focused suites, adversarial review, signed DCO publication, and exact CI. PR #318 remains separately parked on its external CodeRabbit queue and will be re-audited before #313 publication.

[gnanirahulnutakki]

Parked at the required native security-review startup gate; this does not block the wider autonomous backlog.

Verified implementation state:

• focused [D][Security] Bind Claude subagents to attenuated child passports #313 work remains isolated and uncommitted on gnanirahulnutakki/issue-313-claude-child-passports, stacked on PR [D][Integration] Ship reusable governed subagent delegation adapter #318 head 97d603d942a7c750aa5c206582849d9d74d74838;
• child reservation/binding, no-parent-fallback routing, concurrency/restart/expiry/failure handling, package mirrors, report semantics, ADR/docs, and privacy coverage are implemented;
• expanded relevant matrix after the latest durable-state hardening: 287 passed, 4 skipped;
• earlier fresh full Python regression: 1872 passed, 32 skipped, zero failures; a fresh full rerun remains required after security review;
• dependency PR [D][Integration] Ship reusable governed subagent delegation adapter #318 is now open, mergeable, and green at its exact head, including CodeRabbit.

Exact blocker: the native Codex Security diff workspace was opened against the stacked base, but no scan was launched before its setup wait expired because the workspace requires an explicit human Start scan action. Per the scan workflow, I did not substitute a weaker terminal scan or claim exhaustive review.

Exact unblock: open the existing Codex Security workspace, press Start scan (or Regenerate and continue), then resume this lane. The remaining sequence is: execute the native diff review, remediate/validate any findings, rerun the full relevant and Python suites, run hooks/privacy/package gates, create a signed DCO commit, publish the focused stacked PR, and capture exact-head hosted CI/reviewer evidence.

No commit, push, or #313 PR has been created, and dev/main remain untouched.