LidGuard: Skill for Claude Code

LidGuard Session Runtime

Process Exit Watcher

Hook stop events may be missed, so LidGuard also watches the agent process.

• Prefer a provided parent process id when hooks can supply one.
• Managed Codex, Claude Code, GitHub Copilot CLI, and OpenCode hooks should resolve a watched process id from the hook process ancestry on their start events when WatchParentProcess is enabled.
• Working directory must not be used to auto-resolve watched processes. Keep it only for status, logs, transcript fallback, and webhook payload metadata.
• If neither an explicit parent process id nor a hook ancestry owner process id is available, start or update the session with process=none.
• On Windows, open the target process with synchronize/query rights and wait with WaitForSingleObject.
• On Windows, read hook process ancestry with CsWin32/WDK NtQueryInformationProcess(ProcessBasicInformation).
• On Linux, read hook process ancestry with /proc/<pid>/stat, /proc/<pid>/comm, and /proc/<pid>/cmdline.
• On macOS, read hook process ancestry from ps -axo pid=,ppid=,comm=,command=.
• On Linux and macOS, use Process.GetProcessById().WaitForExitAsync() for process exit watching.
• Treat the first cleanup signal as authoritative; later stop/watchdog events for the same session should be harmless.
• If a provider launches a short-lived wrapper that exits before the real agent, prefer provider-specific process selection rather than broadening the generic resolver.
• Watched parent process exit and orphan cleanup are cancel cleanup paths, not provider-reported normal session ends. They must suppress PostSessionEnd and any new PreSuspend webhook they would otherwise schedule, while preserving any pending suspend that was already scheduled or running.

Active Session Policy

• Keep session state ref-counted by active session.
• Attach provider name to AgentProvider.Mcp sessions so multiple MCP-backed providers can reuse the same session identifier without colliding.
• Track last activity timestamp, soft-lock state, soft-lock reason, and soft-lock timestamp per session.
• Keep shared platform keep-awake protection alive only while at least one active session is not soft-locked.
• When all remaining active sessions are soft-locked, treat the runtime as suspend-eligible even before those sessions emit stop events.
• Refresh a session's last activity timestamp on start/update and provider activity such as new tool execution.
• Clear that session's current soft-lock state on provider activity.
• Do not refresh last activity when setting a soft-lock; soft-locking represents waiting rather than autonomous work.
• Closed-lid PermissionRequest decision Ask marks the current provider session soft-locked with reason closed_lid_permission_request_ask; it is cleared by the same provider activity, transcript activity, start/update, stop/remove, or cleanup paths as other soft-locks.
• When a session reaches the configured inactive session timeout, transition it to soft-locked with reason metadata and apply the same suspend-eligibility handling as other soft-locked sessions.
• Pending provider work is not an unconditional exemption from the inactive session timeout. Deferred stops refresh the session's last activity, so still-live background work keeps renewing the timeout window. A session whose pending work shows no provider activity for the configured timeout is treated as abandoned: clear the pending work flag, log session-pending-provider-work-abandoned, and route the session through the same timeout soft-locking path. A soft-locked session with pending work must also stay in the timeout timer so a lost completion notification can be abandoned the same way. Later provider activity from work that was abandoned in error resumes the session through the normal activity paths. Turning the inactive session timeout off (SessionTimeoutMinutes = off) disables this abandonment entirely, since no timeout monitor runs.
• Do not auto-resolve watched processes from the working directory for any provider.
• Preserve an existing watched process for the same active session when a later start/update does not provide a new watched process id and WatchParentProcess is still enabled.
• Provider hook ancestry owner detection should accept Codex CLI, Codex App app-server, Claude Code CLI/wrappers, GitHub Copilot CLI, gh ... copilot, OpenCode CLI, and provider-specific bun/node/npm/npx wrappers.
• Back up optional lid action changes once to pending JSON, preserve any existing pending JSON, and restore only from that JSON after the last active session stops.
• While shared protection remains applied and the lid is closed, keep the Emergency Hibernation thermal monitor polling every 10 seconds and stop it automatically once protection is restored or disabled.
• Keep multiple stop signals for the same session from causing repeated cleanup side effects.
• Ask-before-sleep reply waiting reuses the pending suspend path: keep blocking-capable Stop hooks blocked only while the pending suspend cancellation token remains active. Wait through postStopSuspendDelaySeconds before sending the follow-up webhook so immediately-following prompts can arrive first, then wait up to closedLidStopFollowUpDelaySeconds for the initial reply deadline. The notification dashboard may extend that deadline up to 5 minutes beyond the initial deadline, and managed provider hook timeout must be postStopSuspendDelaySeconds + closedLidStopFollowUpDelaySeconds + 5 minutes so blocking-capable provider hooks remain alive for the whole supported extension window. Poll responses include the current expiresAtUtc; the runtime must trust that value and continue waiting up to it. When a reply arrives, restore the session as active instead of treating the provider stop as final cleanup. With RepeatClosedLidStopFollowUp=true, later Stop hooks from the continued work may ask again without a fixed repeat limit. With RepeatClosedLidStopFollowUp=false, the continued Stop must not wait through postStopSuspendDelaySeconds again; it should proceed as an immediate suspend attempt. When the notification server returns Canceled, stop waiting and reschedule the existing stop/suspend path with a 0 second delay.
• OpenCode differs from blocking-capable Stop hooks: the managed plugin waits after session.idle, consumes the continuation stdout, and sends the reply back into the same session with client.session.prompt(). This simulates the same user experience but depends on OpenCode still having the session available.
• If closedLidStopFollowUpSound is configured, play it once after the follow-up webhook start succeeds and the poll URL is valid, before polling starts. Log playback or volume override failures and keep waiting for replies.